Class: KeyChain

KeyChain(pibLocator, tpmLocator, allowReset, identityManager, policyManager:, pibImpl, tpmBackEnd:)

new KeyChain(pibLocator, tpmLocator, allowReset, identityManager, policyManager:, pibImpl, tpmBackEnd:)

A KeyChain provides a set of interfaces to the security library such as identity management, policy configuration and packet signing and verification. Note: This class is an experimental feature. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/key-chain.html . There are four forms to create a KeyChain: KeyChain(pibLocator, tpmLocator, allowReset = false) - Create a KeyChain to use the PIB and TPM defined by the given locators, which creates a security v2 KeyChain that uses CertificateV2, Pib, Tpm and Validator (instead of v1 Certificate, IdentityStorage, PrivateKeyStorage and PolicyManager). KeyChain(identityManager = null, policyManager = null) - Create a security v1 KeyChain to use the optional identityManager and policyManager. KeyChain(pibImpl, tpmBackEnd, policyManager) - Create a KeyChain using this temporary constructor for the transition to security v2, which creates a security v2 KeyChain but still uses the v1 PolicyManager. Finally, the default constructor KeyChain() creates a KeyChain with the default PIB and TPM, which are platform-dependent and can be overridden system-wide or individually by the user. The default constructor creates a security v2 KeyChain that uses CertificateV2, Pib, Tpm and Validator. However, if the default security v1 database file still exists, and the default security v2 database file does not yet exists, then assume that the system is running an older NFD and create a security v1 KeyChain with the default IdentityManager and a NoVerifyPolicyManager.
Parameters:
Name Type Description
pibLocator string The PIB locator, e.g., "pib-sqlite3:/example/dir".
tpmLocator string The TPM locator, e.g., "tpm-memory:".
allowReset boolean (optional) If True, the PIB will be reset when the supplied tpmLocator mismatches the one in the PIB. If omitted, don't allow reset.
identityManager IdentityManager (optional) The identity manager as a subclass of IdentityManager. If omitted, use the default IdentityManager constructor.
policyManager: PolicyManager (optional) The policy manager as a subclass of PolicyManager. If omitted, use NoVerifyPolicyManager.
pibImpl PibImpl The PibImpl when using the constructor form KeyChain(pibImpl, tpmBackEnd, policyManager).
tpmBackEnd: TpmBackEnd The TpmBackEnd when using the constructor form KeyChain(pibImpl, tpmBackEnd, policyManager).
Source:
Throws:
SecurityException if this is not in Node.js and this uses the default IdentityManager constructor. (See IdentityManager for details.)

Classes

Error

Members

(static) DEFAULT_KEY_PARAMS

Deprecated:
  • Use getDefaultKeyParams().
Source:

Methods

(static) createPib_(pibLocator) → {Pib}

Create a Pib according to the pibLocator.
Parameters:
Name Type Description
pibLocator string The PIB locator, e.g., "pib-sqlite3:/example/dir".
Source:
Returns:
A new Pib object.
Type
Pib

(static) getDefaultPibLocator_(config) → {string}

Parameters:
Name Type Description
config ConfigFile
Source:
Returns:
Type
string

(static) getDefaultPibScheme_() → {string}

Source:
Returns:
Type
string

(static) getDefaultTpmLocator_(config) → {string}

Parameters:
Name Type Description
config ConfigFile
Source:
Returns:
Type
string

(static) getDefaultTpmScheme_() → {string}

Source:
Returns:
Type
string

(static) getPibFactories_() → {object}

Get the PIB factories map. On the first call, this initializes the map with factories for standard PibImpl implementations.
Source:
Returns:
A map where the key is the scheme string and the value is a function makePibImpl(location) which takes a string location and returns a new PibImpl object.
Type
object

(static) getTpmFactories_() → {object}

Get the TPM factories map. On the first call, this initializes the map with factories for standard TpmBackEnd implementations.
Source:
Returns:
A map where the key is the scheme string and the value is a function makeTpmBackEnd(location) which takes a string location and returns a new TpmBackEnd object.
Type
object

(static) parseAndCheckPibLocator_(pibLocator, pibScheme, pibLocation)

Parse the pibLocator and set the pibScheme and pibLocation.
Parameters:
Name Type Description
pibLocator string The PIB locator to parse.
pibScheme Array.<string> Set pibScheme[0] to the PIB scheme.
pibLocation Array.<string> Set pibLocation[0] to the PIB location.
Source:

(static) parseAndCheckTpmLocator_(tpmLocator, tpmScheme, tpmLocation)

Parse the tpmLocator and set the tpmScheme and tpmLocation.
Parameters:
Name Type Description
tpmLocator string The TPM locator to parse.
tpmScheme Array.<string> Set tpmScheme[0] to the TPM scheme.
tpmLocation Array.<string> Set tpmLocation[0] to the TPM location.
Source:

(static) parseLocatorUri_(uri, scheme, location)

Parse the uri and set the scheme and location.
Parameters:
Name Type Description
uri string The URI to parse.
scheme Array.<string> Set scheme[0] to the scheme.
location Array.<string> Set location[0] to the location.
Source:

(static) registerPibBackend(scheme, makePibImpl)

Add to the PIB factories map where scheme is the key and makePibImpl is the value. If your application has its own PIB implementations, this must be called before creating a KeyChain instance which uses your PIB scheme.
Parameters:
Name Type Description
scheme string The PIB scheme.
makePibImpl function A callback which takes the PIB location and returns a new PibImpl instance.
Source:

(static) registerTpmBackend(scheme, makeTpmBackEnd)

Add to the TPM factories map where scheme is the key and makeTpmBackEnd is the value. If your application has its own TPM implementations, this must be called before creating a KeyChain instance which uses your TPM scheme.
Parameters:
Name Type Description
scheme string The TPM scheme.
makeTpmBackEnd function A callback which takes the TPM location and returns a new TpmBackEnd instance.
Source:

(static) setUpTpm_(tpm, tpmLocator) → {Tpm}

Set up tpm according to the tpmLocator. This is called by Pib.initializePromise_ after determining the correct tpmLocator.
Parameters:
Name Type Description
tpm Tpm The Tpm to set up.
tpmLocator string The TPM locator, e.g., "tpm-memory:".
Source:
Returns:
A new Tpm object.
Type
Tpm

(static) signWithHmacWithSha256(target, key, wireFormat)

Wire encode the target, compute an HmacWithSha256 and update the object. Note: This method is an experimental feature. The API may change.
Parameters:
Name Type Description
target Data | Interest If the target is a Data object (which should already have an HmacWithSha256Signature with a KeyLocator for the key name), then update its signature and wire encoding. If the target is an Interest, then append a SignatureInfo to the Interest name, compute an HmacWithSha256 signature for the name components and append a final name component with the signature bits.
key Blob The key for the HmacWithSha256. param {Name} keyName (needed if target is an Interest) The name of the key for the KeyLocator in the SignatureInfo which is added to the Interest name.
wireFormat WireFormat (optional) A WireFormat object used to encode the target. If omitted, use WireFormat getDefaultWireFormat().
Source:

(static) verifyDataWithHmacWithSha256(data, key, wireFormat) → {boolean}

Compute a new HmacWithSha256 for the target and verify it against the signature value. Note: This method is an experimental feature. The API may change.
Parameters:
Name Type Description
data Data The Data object to verify.
key Blob The key for the HmacWithSha256.
wireFormat WireFormat (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
Source:
Returns:
True if the signature verifies, otherwise false.
Type
boolean

(static) verifyInterestWithHmacWithSha256(interest, key, wireFormat) → {boolean}

Compute a new HmacWithSha256 for all but the final name component and verify it against the signature value in the final name component. Note: This method is an experimental feature. The API may change.
Parameters:
Name Type Description
interest Interest The Interest object to verify.
key Blob The key for the HmacWithSha256.
wireFormat WireFormat (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
Source:
Returns:
True if the signature verifies, otherwise false.
Type
boolean

addCertificate(key, certificate, onComplete, onError)

Add a certificate for the key. If the key had no default certificate selected, the added certificate will be set as the default certificate for this key.
Parameters:
Name Type Description
key PibKey A valid PibKey object.
certificate CertificateV2 The certificate to add. This copies the object.
onComplete function (optional) This calls onComplete() when the operation is complete. If omitted, do not use it. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Throws:
Error if the key does not match the certificate. However, if onComplete and onError are defined, then if there is an exception return undefined and call onError(exception).

addCertificatePromise(key, certificate, useSync) → {Promise|SyncPromise}

Add a certificate for the key. If the key had no default certificate selected, the added certificate will be set as the default certificate for this key.
Parameters:
Name Type Description
key PibKey A valid PibKey object.
certificate CertificateV2 The certificate to add. This copies the object.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that fulfills when the operation is complete, or a promise rejected with Error if the key does not match the certificate.
Type
Promise | SyncPromise

createIdentity(identityName, params) → {Name}

Create an identity by creating a pair of Key-Signing-Key (KSK) for this identity and a self-signed certificate of the KSK. If a key pair or certificate for the identity already exists, use it.
Parameters:
Name Type Description
identityName Name The name of the identity.
params KeyParams (optional) The key parameters if a key needs to be generated for the identity. If omitted, use KeyChain.getDefaultKeyParams().
Deprecated:
  • Use createIdentityAndCertificate which returns the certificate name instead of the key name. You can use IdentityCertificate.certificateNameToPublicKeyName to convert the certificate name to the key name.
Source:
Returns:
The key name of the auto-generated KSK of the identity.
Type
Name

createIdentityAndCertificate(identityName, params, onComplete, onError) → {Name}

Create an identity by creating a pair of Key-Signing-Key (KSK) for this identity and a self-signed certificate of the KSK. If a key pair or certificate for the identity already exists, use it.
Parameters:
Name Type Description
identityName Name The name of the identity.
params KeyParams (optional) The key parameters if a key needs to be generated for the identity. If omitted, use KeyChain.getDefaultKeyParams().
onComplete function (optional) This calls onComplete(certificateName) with name of the default certificate of the identity. If omitted, the return value is described below. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Returns:
If onComplete is omitted, return the name of the default certificate of the identity. Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
Name

createIdentityV2(identityName, params, onComplete, onError) → {PibIdentity}

Create a security V2 identity for identityName. This method will check if the identity exists in PIB and whether the identity has a default key and default certificate. If the identity does not exist, this method will create the identity in PIB. If the identity's default key does not exist, this method will create a key pair and set it as the identity's default key. If the key's default certificate is missing, this method will create a self-signed certificate for the key. If identityName did not exist and no default identity was selected before, the created identity will be set as the default identity.
Parameters:
Name Type Description
identityName Name The name of the identity.
params KeyParams (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
onComplete function (optional) This calls onComplete(identity) with the created PibIdentity instance. If omitted, the return value is described below. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Returns:
If onComplete is omitted, return the created PibIdentity instance. Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
PibIdentity

createIdentityV2Promise(identityName, params, useSync) → {Promise|SyncPromise}

Create a security V2 identity for identityName. This method will check if the identity exists in PIB and whether the identity has a default key and default certificate. If the identity does not exist, this method will create the identity in PIB. If the identity's default key does not exist, this method will create a key pair and set it as the identity's default key. If the key's default certificate is missing, this method will create a self-signed certificate for the key. If identityName did not exist and no default identity was selected before, the created identity will be set as the default identity.
Parameters:
Name Type Description
identityName Name The name of the identity.
params KeyParams (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that returns the created PibIdentity instance.
Type
Promise | SyncPromise

createKey(identity, params, onComplete, onError) → {PibKey}

Create a key for the identity according to params. If the identity had no default key selected, the created key will be set as the default for this identity. This method will also create a self-signed certificate for the created key.
Parameters:
Name Type Description
identity PibIdentity A valid PibIdentity object.
params KeyParams (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
onComplete function (optional) This calls onComplete(key) with the new PibKey. If omitted, the return value is described below. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Returns:
If onComplete is omitted, return the new PibKey. Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
PibKey

createKeyPromise(identity, params, useSync) → {Promise|SyncPromise}

Create a key for the identity according to params. If the identity had no default key selected, the created key will be set as the default for this identity. This method will also create a self-signed certificate for the created key.
Parameters:
Name Type Description
identity PibIdentity A valid PibIdentity object.
params KeyParams (optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that returns the new PibKey.
Type
Promise | SyncPromise

createSigningRequest(keyName) → {Blob}

Create a public key signing request.
Parameters:
Name Type Description
keyName Name The name of the key.
Source:
Returns:
The signing request data.
Type
Blob

deleteCertificate(key, certificateName, onComplete, onError)

Delete the certificate with the given name from the given key. If the certificate does not exist, this does nothing.
Parameters:
Name Type Description
key PibKey A valid PibKey object.
certificateName Name The name of the certificate to delete.
onComplete function (optional) This calls onComplete() when the operation is complete. If omitted, do not use it. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Throws:
Error if certificateName does not follow certificate naming conventions. However, if onComplete and onError are defined, then if there is an exception return undefined and call onError(exception).

deleteCertificatePromise(key, certificateName, useSync) → {Promise|SyncPromise}

Delete the certificate with the given name from the given key. If the certificate does not exist, this does nothing.
Parameters:
Name Type Description
key PibKey A valid PibKey object.
certificateName Name The name of the certificate to delete.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that fulfills when the operation is complete, or a promise rejected with Error if certificateName does not follow certificate naming conventions.
Type
Promise | SyncPromise

deleteIdentity(identity, identityName, onComplete, onError)

This method has two forms: deleteIdentity(identity, onComplete, onError) - Delete the PibIdentity identity (optionally using onComplete and onError callbacks). After this operation, the identity is invalid. deleteIdentity(identityName, onComplete, onError) - Delete the identity from the public and private key storage (optionally using onComplete and onError callbacks). If the identity to be deleted is the current default system default, the method will not delete the identity and will return immediately.
Parameters:
Name Type Description
identity PibIdentity The identity to delete.
identityName Name The name of the identity to delete.
onComplete function (optional) This calls onComplete() when the operation is complete. If omitted, do not use it. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:

deleteIdentityPromise(identity, identityName, useSync) → {Promise|SyncPromise}

This method has two forms: deleteIdentity(identity, useSync) - Delete the PibIdentity identity. After this operation, the identity is invalid. deleteIdentity(identityName, useSync) - Delete the identity from the public and private key storage. If the identity to be deleted is the current default s system default, the method will not delete the identity and will return immediately.
Parameters:
Name Type Description
identity PibIdentity The identity to delete.
identityName Name The name of the identity to delete.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that fulfills when the operation is complete.
Type
Promise | SyncPromise

deleteKey(identity, key, onComplete, onError)

Delete the given key of the given identity. The key becomes invalid.
Parameters:
Name Type Description
identity PibIdentity A valid PibIdentity object.
key PibKey The key to delete.
onComplete function (optional) This calls onComplete() when the operation is complete. If omitted, do not use it. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Throws:
Error if the key does not belong to the identity. However, if onComplete and onError are defined, then if there is an exception return undefined and call onError(exception).

deleteKeyPromise(identity, key, useSync) → {Promise|SyncPromise}

Delete the given key of the given identity. The key becomes invalid.
Parameters:
Name Type Description
identity PibIdentity A valid PibIdentity object.
key PibKey The key to delete.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that fulfills when the operation is complete, or a promise rejected with Error if the key does not belong to the identity.
Type
Promise | SyncPromise

generateRSAKeyPair(identityName, isKsk, keySize) → {Name}

Generate a pair of RSA keys for the specified identity.
Parameters:
Name Type Description
identityName Name The name of the identity.
isKsk boolean (optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
keySize number (optional) The size of the key. If omitted, use a default secure key size.
Source:
Returns:
The generated key name.
Type
Name

generateRSAKeyPairAsDefault(identityName, isKsk, keySize) → {Name}

Generate a pair of RSA keys for the specified identity and set it as the default key for the identity.
Parameters:
Name Type Description
identityName Name The name of the identity.
isKsk boolean (optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
keySize number (optional) The size of the key. If omitted, use a default secure key size.
Source:
Returns:
The generated key name.
Type
Name

getCertificate(certificateName, onComplete, onError) → {IdentityCertificate}

Get a certificate which is still valid with the specified name.
Parameters:
Name Type Description
certificateName Name The name of the requested certificate.
onComplete function (optional) This calls onComplete(certificate) with the requested IdentityCertificate. If omitted, the return value is described below. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Returns:
If onComplete is omitted, return the requested certificate. Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
IdentityCertificate

getDefaultCertificateName(onComplete, onError) → {Name}

Get the default certificate name of the default identity, which will be used when signing is based on identity and the identity is not specified.
Parameters:
Name Type Description
onComplete function (optional) This calls onComplete(certificateName) with name of the default certificate. If omitted, the return value is described below. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Throws:
SecurityException if the default identity is not set or the default key name for the identity is not set or the default certificate name for the key name is not set. However, if onComplete and onError are defined, then if there is an exception return undefined and call onError(exception).
Returns:
If onComplete is omitted, return the default certificate name. Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
Name

getDefaultIdentity(onComplete, onError) → {Name}

Get the default identity.
Parameters:
Name Type Description
onComplete function (optional) This calls onComplete(identityName) with name of the default identity. If omitted, the return value is described below. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.)
Source:
Throws:
SecurityException if the default identity is not set. However, if onComplete and onError are defined, then if there is an exception return undefined and call onError(exception).
Returns:
If onComplete is omitted, return the name of the default identity. Otherwise, if onComplete is supplied then return undefined and use onComplete as described above. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Type
Name

getIdentityCertificate()

Deprecated:
  • Use getCertificate.
Source:

getIdentityManager() → {IdentityManager}

Get the identity manager given to or created by the constructor.
Source:
Returns:
The identity manager.
Type
IdentityManager

getIsSecurityV1()

Get the flag set by the constructor if this is a security v1 or v2 KeyChain.
Source:
Returns:
(boolean} True if this is a security v1 KeyChain, false if this is a security v2 KeyChain.

getPib() → {Pib}

Source:
Returns:
Type
Pib

getPolicyManager() → {PolicyManager}

Get the policy manager given to or created by the constructor.
Source:
Returns:
The policy manager.
Type
PolicyManager

getTpm() → {Tpm}

Source:
Returns:
Type
Tpm

importSafeBag(safeBag, password, onComplete, onError)

Import a certificate and its corresponding private key encapsulated in a SafeBag. If the certificate and key are imported properly, the default setting will be updated as if a new key and certificate is added into this KeyChain.
Parameters:
Name Type Description
safeBag SafeBag The SafeBag containing the certificate and private key. This copies the values from the SafeBag.
password Buffer (optional) The password for decrypting the private key. If the password is supplied, use it to decrypt the PKCS #8 EncryptedPrivateKeyInfo. If the password is omitted or null, import an unencrypted PKCS #8 PrivateKeyInfo.
onComplete function (optional) This calls onComplete() when finished. If omitted, just return when finished. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some crypto libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:

importSafeBagPromise(safeBag, password, useSync) → {Promise|SyncPromise}

Import a certificate and its corresponding private key encapsulated in a SafeBag. If the certificate and key are imported properly, the default setting will be updated as if a new key and certificate is added into this KeyChain.
Parameters:
Name Type Description
safeBag SafeBag The SafeBag containing the certificate and private key. This copies the values from the SafeBag.
password Buffer (optional) The password for decrypting the private key. If the password is supplied, use it to decrypt the PKCS #8 EncryptedPrivateKeyInfo. If the password is omitted or null, import an unencrypted PKCS #8 PrivateKeyInfo.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise which fulfills when finished.
Type
Promise | SyncPromise

installIdentityCertificate(certificate, onComplete, onError)

Install an identity certificate into the public key identity storage.
Parameters:
Name Type Description
certificate IdentityCertificate The certificate to to added.
onComplete function (optional) This calls onComplete() when complete. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:

prepareDefaultCertificateNamePromise_(useSync) → {Promise|SyncPromise}

Get the default certificate from the identity storage and return its name. If there is no default identity or default certificate, then create one.
Parameters:
Name Type Description
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that returns the default certificate name.
Type
Promise | SyncPromise

prepareSignatureInfoPromise_(params, keyName, useSync) → {Promise|SyncPromise}

Prepare a Signature object according to signingInfo and get the signing key name.
Parameters:
Name Type Description
params SigningInfo The signing parameters.
keyName Array.<Name> Set keyName[0] to the signing key name.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise which returns a new Signature object with the SignatureInfo, or a promise rejected with InvalidSigningInfoError when the requested signing method cannot be satisfied.
Type
Promise | SyncPromise

revokeCertificate(certificateName)

Revoke a certificate.
Parameters:
Name Type Description
certificateName Name The name of the certificate that will be revoked.
Source:

revokeKey(keyName)

Revoke a key.
Parameters:
Name Type Description
keyName Name The name of the key that will be revoked.
Source:

selfSign(key, wireFormat, onComplete, onError) → {CertificateV2}

Generate a self-signed certificate for the public key and add it to the PIB. This creates the certificate name from the key name by appending "self" and a version based on the current time. If no default certificate for the key has been set, then set the certificate as the default for the key.
Parameters:
Name Type Description
key PibKey The PibKey with the key name and public key.
wireFormat WireFormat (optional) A WireFormat object used to encode the certificate. If omitted, use WireFormat getDefaultWireFormat().
onComplete function (optional) This calls onComplete(certificate) with the new CertificateV2. If omitted, the return value is described below. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Returns:
If onComplete is omitted, return the new certificate. Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
CertificateV2

selfSignPromise(key, wireFormat, useSync) → {Promise|SyncPromise}

Generate a self-signed certificate for the public key and add it to the PIB. This creates the certificate name from the key name by appending "self" and a version based on the current time. If no default certificate for the key has been set, then set the certificate as the default for the key.
Parameters:
Name Type Description
key PibKey The PibKey with the key name and public key.
wireFormat WireFormat (optional) A WireFormat object used to encode the certificate. If omitted, use WireFormat getDefaultWireFormat().
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that returns the new CertificateV2.
Type
Promise | SyncPromise

setDefaultCertificate(key, certificate, onComplete, onError)

Set the certificate as the default certificate of the key. The certificate will be added to the key, potentially overriding an existing certificate if it has the same name (without considering implicit digest).
Parameters:
Name Type Description
key PibKey A valid PibKey object.
certificate CertificateV2 The certificate to become the default. This copies the object.
onComplete function (optional) This calls onComplete() when the operation is complete. If omitted, do not use it. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:

setDefaultCertificateForKey(certificate, onComplete, onError)

Set the certificate as the default for its corresponding key.
Parameters:
Name Type Description
certificate IdentityCertificate The certificate.
onComplete function (optional) This calls onComplete() when complete. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:

setDefaultCertificatePromise(key, certificate, useSync) → {Promise|SyncPromise}

Set the certificate as the default certificate of the key. The certificate will be added to the key, potentially overriding an existing certificate if it has the same name (without considering implicit digest).
Parameters:
Name Type Description
key PibKey A valid PibKey object.
certificate CertificateV2 The certificate to become the default. This copies the object.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that fulfills when the operation is complete.
Type
Promise | SyncPromise

setDefaultCertificatePromise_(useSync) → {Promise|SyncPromise}

Create the default certificate if it is not initialized. If there is no default identity yet, creating a new tmp-identity.
Parameters:
Name Type Description
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that resolves when the default certificate is set.
Type
Promise | SyncPromise

setDefaultIdentity(identity, onComplete, onError)

Set the identity as the default identity.
Parameters:
Name Type Description
identity PibIdentity The identity to make the default.
onComplete function (optional) This calls onComplete() when the operation is complete. If omitted, do not use it. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:

setDefaultIdentityPromise(identity, useSync) → {Promise|SyncPromise}

Set the identity as the default identity.
Parameters:
Name Type Description
identity PibIdentity The identity to make the default.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that fulfills when the operation is complete.
Type
Promise | SyncPromise

setDefaultKey(identity, key, onComplete, onError)

Set the key as the default key of identity.
Parameters:
Name Type Description
identity type A valid PibIdentity object.
key type The key to become the default.
onComplete function (optional) This calls onComplete() when the operation is complete. If omitted, do not use it. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Throws:
Error if the key does not belong to the identity. However, if onComplete and onError are defined, then if there is an exception return undefined and call onError(exception).

setDefaultKeyForIdentity(keyName, identityNameCheck, onComplete, onError)

Set a key as the default key of an identity. The identity name is inferred from keyName.
Parameters:
Name Type Description
keyName Name The name of the key.
identityNameCheck Name (optional) The identity name to check that the keyName contains the same identity name. If an empty name, it is ignored.
onComplete function (optional) This calls onComplete() when complete. (Some database libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:

setDefaultKeyPromise(identity, key, useSync) → {Promise|SyncPromise}

Set the key as the default key of identity.
Parameters:
Name Type Description
identity type A valid PibIdentity object.
key type The key to become the default.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that fulfills when the operation is complete, or a promise rejected with Error if the key does not belong to the identity.
Type
Promise | SyncPromise

setFace(face)

Set the Face which will be used to fetch required certificates.
Parameters:
Name Type Description
face Face A pointer to the Face object.
Source:

sign(target, paramsOrCertificateName, wireFormat, onComplete, onError) → {Signature}

Sign the target. If it is a Data or Interest object, set its signature. If it is a Buffer, produce a Signature object.
Parameters:
Name Type Description
target Data | Interest | Buffer If this is a Data object, wire encode for signing, replace its Signature object based on the type of key and other info in the SigningInfo params or default identity, and update the wireEncoding. If this is an Interest object, wire encode for signing, append a SignatureInfo to the Interest name, sign the name components and append a final name component with the signature bits. If it is a buffer, sign it and return a Signature object.
paramsOrCertificateName SigningInfo | Name (optional) If a SigningInfo, it is the signing parameters. If a Name, it is the certificate name of the key to use for signing. If omitted and this is a security v1 KeyChain then use the IdentityManager to get the default identity. Otherwise, use the PIB to get the default key of the default identity.
wireFormat WireFormat (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
onComplete function (optional) If target is a Data object, this calls onComplete(data) with the supplied Data object which has been modified to set its signature. If target is an Interest object, this calls onComplete(interest) with the supplied Interest object which has been modified to set its signature. If target is a Buffer, this calls onComplete(signature) where signature is the produced Signature object. If omitted, the return value is described below. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Returns:
If onComplete is omitted, return the generated Signature object (if target is a Buffer) or the target (if target is Data or Interest). Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
Signature

signBufferPromise_(buffer, keyName, digestAlgorithm, useSync) → {Promise|SyncPromise}

Sign the byte buffer using the key with name keyName.
Parameters:
Name Type Description
buffer Buffer The input byte buffer.
keyName Name The name of the key.
digestAlgorithm number The digest algorithm as an int from the DigestAlgorithm enum.
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise which returns the signature Blob (or an isNull Blob if the key does not exist), or a promise rejected with TpmBackEnd.Error for an error in signing.
Type
Promise | SyncPromise

signByIdentity(target, identityName, wireFormat, onComplete, onError) → {Signature}

Sign the target. If it is a Data object, set its signature. If it is an array, produce a signature object.
Parameters:
Name Type Description
target Data | Buffer If this is a Data object, wire encode for signing, update its signature and key locator field and wireEncoding. If it is an array, sign it and return a Signature object.
identityName Name (optional) The identity name for the key to use for signing. If omitted, infer the signing identity from the data packet name.
wireFormat WireFormat (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
onComplete function (optional) If target is a Data object, this calls onComplete(data) with the supplied Data object which has been modified to set its signature. If target is a Buffer, this calls onComplete(signature) where signature is the produced Signature object. If omitted, the return value is described below. (Some crypto libraries only use a callback, so onComplete is required to use these.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onError function (optional) If defined, then onComplete must be defined and if there is an exception, then this calls onError(exception) with the exception. If onComplete is defined but onError is undefined, then this will log any thrown exception. (Some database libraries only use a callback, so onError is required to be notified of an exception.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source:
Returns:
If onComplete is omitted, return the generated Signature object (if target is a Buffer) or undefined (if target is Data). Otherwise, if onComplete is supplied then return undefined and use onComplete as described above.
Type
Signature

signPromise(target, paramsOrCertificateName, wireFormat, useSync) → {Promise|SyncPromise}

Sign the target. If it is a Data or Interest object, set its signature. If it is a Buffer, produce a Signature object.
Parameters:
Name Type Description
target Data | Interest | Buffer If this is a Data object, wire encode for signing, replace its Signature object based on the type of key and other info in the SigningInfo params or default identity, and update the wireEncoding. If this is an Interest object, wire encode for signing, append a SignatureInfo to the Interest name, sign the name components and append a final name component with the signature bits. If it is a buffer, sign it and return a Signature object.
paramsOrCertificateName SigningInfo | Name (optional) If a SigningInfo, it is the signing parameters. If a Name, it is the certificate name of the key to use for signing. If omitted and this is a security v1 KeyChain then use the IdentityManager to get the default identity. Otherwise, use the PIB to get the default key of the default identity.
wireFormat WireFormat (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
useSync boolean (optional) If true then return a SyncPromise which is already fulfilled. If omitted or false, this may return a SyncPromise or an async Promise.
Source:
Returns:
A promise that returns the target (if target is Data or Interest), or returns the generated Signature object (if target is a Buffer).
Type
Promise | SyncPromise

signWithSha256(target, wireFormat)

Sign the target using DigestSha256.
Parameters:
Name Type Description
target Data | Interest If this is a Data object, wire encode for signing, digest it and set its SignatureInfo to a DigestSha256, updating its signature and wireEncoding. If this is an Interest object, wire encode for signing, append a SignatureInfo for DigestSha256 to the Interest name, digest the name components and append a final name component with the signature bits.
wireFormat WireFormat (optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().
Source:

verifyData(data, onVerified, onValidationFailed, stepCount)

Check the signature on the Data object and call either onVerify or onValidationFailed. We use callback functions because verify may fetch information to check the signature.
Parameters:
Name Type Description
data Data The Data object with the signature to check.
onVerified function If the signature is verified, this calls onVerified(data). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onValidationFailed function If the signature check fails, this calls onValidationFailed(data, reason) with the Data object and reason string. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
stepCount number
Source:

verifyInterest(interest, onVerified, onValidationFailed)

Check the signature on the signed interest and call either onVerify or onValidationFailed. We use callback functions because verify may fetch information to check the signature.
Parameters:
Name Type Description
interest Interest The interest with the signature to check.
onVerified function If the signature is verified, this calls onVerified(interest). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onValidationFailed function If the signature check fails, this calls onValidationFailed(interest, reason) with the Interest object and reason string. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
Source: