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: