Class: KeyChain

KeyChain

new KeyChain(identityManager, policyManager)

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 . Create a new KeyChain with the identityManager and policyManager.
Parameters:
Name Type Description
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.
Source:
Throws:
SecurityException if this is not in Node.js and this uses the default IdentityManager constructor. (See IdentityManager for details.)

Methods

(static) signWithHmacWithSha256(target, key, wireFormat)

Wire encode the target, compute an HmacWithSha256 and update the signature value. Note: This method is an experimental feature. The API may change.
Parameters:
Name Type Description
target Data If this is a Data object, update its signature and wire encoding.
key Blob The key for the HmacWithSha256.
wireFormat WireFormat (optional) A WireFormat object used to encode the target. If omitted, use WireFormat getDefaultWireFormat().
Source:

(static) verifyDataWithHmacWithSha256(target, 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
target Data The Data object to verify.
key Blob The key for the HmacWithSha256.
wireFormat WireFormat (optional) A WireFormat object used to encode the target. If omitted, use WireFormat getDefaultWireFormat().
Source:
Returns:
True if the signature verifies, otherwise false.
Type
boolean

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.DEFAULT_KEY_PARAMS.
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.DEFAULT_KEY_PARAMS.
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

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

deleteIdentity(identityName, onComplete, onError)

Delete the identity from the public and private key storage. If the identity to be deleted is the current default system default, this will not delete the identity and will return immediately.
Parameters:
Name Type Description
identityName Name The name of the identity.
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:

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 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

getPolicyManager() → {PolicyManager}

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

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

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:

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_(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

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:

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, certificateName, wireFormat, onComplete, onError) → {Signature}

Sign the target. If it is a Data or Interest object, set its signature. If it is an array, produce a Signature object. There are two forms of sign: sign(target, certificateName [, wireFormat] [, onComplete] [, onError]). sign(target [, wireFormat] [, onComplete] [, onError]).
Parameters:
Name Type Description
target Data | Interest | Buffer If this is a Data object, wire encode for signing, update its signature and key locator field and 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 an array, sign it and produce a Signature object.
certificateName Name (optional) The certificate name of the key to use for signing. If omitted, use the default identity in the identity storage.
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

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, certificateName, wireFormat, useSync) → {Promise|SyncPromise}

Sign the target. If it is a Data or Interest object, set its signature. If it is an array, produce a Signature object. There are two forms of signPromise: signPromise(target, certificateName [, wireFormat] [, useSync]). sign(target [, wireFormat] [, useSync]).
Parameters:
Name Type Description
target Data | Interest | Buffer If this is a Data object, wire encode for signing, update its signature and key locator field and 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 an array, sign it and produce a Signature object.
certificateName Name (optional) The certificate name of the key to use for signing. If omitted, use the default identity in the identity storage.
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 generated Signature object (if target is a Buffer) or the target (if target is Data or Interest).
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, onVerifyFailed, stepCount)

Check the signature on the Data object and call either onVerify or onVerifyFailed. 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.
onVerifyFailed function If the signature check fails, this calls onVerifyFailed(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.
stepCount number
Source:

verifyInterest(interest, onVerified, onVerifyFailed)

Check the signature on the signed interest and call either onVerify or onVerifyFailed. 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.
onVerifyFailed function If the signature check fails, this calls onVerifyFailed(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.
Source: