Select Default Language Display:

  • C++
  • Python
  • JavaScript
  • Java
  • All Languages

KeyChain Class

Experimental

The NDN security library is experimental and the API is not finalized.

The Keychain class provides a set of interfaces to the security library such as identity management, policy configuration and packet signing and verification.

[C++]:
#include <ndn-cpp/security/key-chain.hpp>
Namespace: ndn
[Python]:Module: pyndn.security
[Java]:Package: net.named_data.jndn.security

KeyChain Constructor

Experimental

The NDN security library is experimental and the API is not finalized.

Create a new KeyChain with the the default IdentityManager and a NoVerifyPolicyManager. This is sufficient for signing command interests.

[C++]:
KeyChain();
[Python]:
def __init__(self)

KeyChain.createIdentityAndCertificate Method

Experimental

The NDN security library is experimental and the API is not finalized.

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.

[C++]:
Name createIdentityAndCertificate(
    const Name& identityName
    [, const KeyParams& params]
);
[Python]:
# Returns Name
def createIdentityAndCertificate(self,
    identityName  # Name
    [, params     # KeyParams]
)
[JavaScript]:
// Returns Name
KeyChain.prototype.createIdentityAndCertificate = function(
    identityName   // Name
    [, params      // KeyParams]
    [, onComplete  // function]
    [, onError     // function]
)
[Java]:
public final Name createIdentityAndCertificate(
    Name identityName
    [, KeyParams params]
)
Parameters:
  • identityName

    The name of the identity.

  • params

    (optional) The key parameters if a key needs to be generated for the identity. If omitted, use default parameters for RSA.

  • onComplete

    [JavaScript only] (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.)

  • onError

    [JavaScript only] (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.)

Returns:

The name of the default certificate of the identity. [JavaScript only: However, if onComplete is supplied then return undefined and use onComplete as described above.]

KeyChain.getDefaultCertificateName Method

Experimental

The NDN security library is experimental and the API is not finalized.

Get the default certificate name of the default identity.

[C++]:
Name getDefaultCertificateName();
[Python]:
# Returns Name
def getDefaultCertificateName(self)
[JavaScript]:
// Returns Name
KeyChain.prototype.getDefaultCertificateName = function()
[Java]:
public final Name getDefaultCertificateName() throws SecurityException
Returns:

The requested certificate name.

Throw:

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.

KeyChain.setFace Method

Experimental

The NDN security library is experimental and the API is not finalized.

Set the Face which will be used to fetch required certificates.

[C++]:
void setFace(
    Face* face
);
[Python]:
def setFace(self,
    face  # Face
)
[JavaScript]:
KeyChain.prototype.setFace = function(
    face  // Face
)
[Java]:
public final void setFace(
    Face face
)
Parameters:
  • face

    The Face object.

KeyChain.sign Methods

KeyChain.sign (Data) Method

Experimental

The NDN security library is experimental and the API is not finalized.

Wire encode the Data object, sign it and set its signature. Note: the caller must make sure the timestamp is correct, if necessary calling data.getMetaInfo().setTimestampMilliseconds.

[C++]:
void sign(
    Data& data,
    const Name& certificateName
);
[Python]:
def sign(self,
    data,            # Data
    certificateName  # Name
)
[JavaScript]:
KeyChain.prototype.sign = function(
    data,            // Data
    certificateName  // Name
)
[Java]:
public final void sign(
    Data data,
    Name certificateName
)
Parameters:
  • data

    The Data object to be signed. This updates its signature and key locator field and wireEncoding.

  • certificateName

    The certificate name of the key to use for signing.

KeyChain.sign (Interest) Method

Experimental

The NDN security library is experimental and the API is not finalized.

Append a SignatureInfo to the Interest name, sign the name components and append a final name component with the signature bits.

[C++]:
void sign(
    Interest& interest,
    const Name& certificateName
);
[Python]:
def sign(self,
    interest,        # Interest
    certificateName  # Name
)
[JavaScript]:
KeyChain.prototype.sign = function(
    interest,        // Interest
    certificateName  // Name
)
[Java]:
public final void sign(
    Interest interest,
    Name certificateName
)
Parameters:
  • interest

    The Interest object to be signed. This appends name components of SignatureInfo and the signature bits.

  • certificateName

    The certificate name of the key to use for signing.

KeyChain.signWithSha256 Methods

KeyChain.signWithSha256 (Data) Method

Experimental

The NDN security library is experimental and the API is not finalized.

Wire encode the Data object, digest it and set its SignatureInfo to a DigestSha256.

[C++]:
void signWithSha256(
    Data& data
);
[Python]:
def signWithSha256(self,
    data  # Data
)
[JavaScript]:
KeyChain.prototype.signWithSha256 = function(
    data  // Data
)
[Java]:
public final void signWithSha256(
    Data data
)
Parameters:
  • data

    The Data object to be signed. This updates its signature.

KeyChain.signWithSha256 (Interest) Method

Experimental

The NDN security library is experimental and the API is not finalized.

Append a SignatureInfo for DigestSha256 to the Interest name, digest the name components and append a final name component with the signature bits (which is the digest).

[C++]:
void signWithSha256(
    Interest& interest
);
[Python]:
def signWithSha256(self,
    interest  # Interest
)
[JavaScript]:
KeyChain.prototype.signWithSha256 = function(
    interest  // Interest
)
[Java]:
public final void signWithSha256(
    Interest interest
)
Parameters:
  • interest

    The Interest object to be signed. This appends name components of SignatureInfo and the signature bits.

KeyChain.verifyData Method

Experimental

The NDN security library is experimental and the API is not finalized.

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.

[C++]:
void verifyData(
    const ptr_lib::shared_ptr<Data>& data,
    const OnVerified& onVerified,
    const OnDataValidationFailed& onValidationFailed
);
[Python]:
def verifyData(self,
    data,               # Data
    onVerified,         # function object
    onValidationFailed  # function object
)
[JavaScript]:
KeyChain.prototype.verifyData = function(
    data,               // Data
    onVerified,         // function object
    onValidationFailed  // function object
)
[Java]:
public final void verifyData(
    Data data,
    OnVerified onVerified,
    OnDataValidationFailed onValidationFailed
)
Parameters:
  • data

    The Data object with the signature to check.

  • onVerified
    If the signature is verified, this calls onVerified(data) where:
    • data is the given Data object.

    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
    If the signature check fails, this calls onValidationFailed(data, reason) where:
    • data is the given Data object.
    • reason is the 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.

KeyChain.verifyInterest Method

Experimental

The NDN security library is experimental and the API is not finalized.

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.

[C++]:
void verifyInterest(
    const ptr_lib::shared_ptr<Interest>& interest,
    const OnVerifiedInterest& onVerified,
    const OnInterestValidationFailed& onValidationFailed
);
[Python]:
def verifyInterest(self,
    interest,           # Interest
    onVerified,         # function object
    onValidationFailed  # function object
)
[JavaScript]:
KeyChain.prototype.verifyInterest = function(
    interest,           // Interest
    onVerified,         // function object
    onValidationFailed  // function object
)
[Java]:
public final void verifyInterest(
    Interest interest,
    OnVerifiedInterest onVerified,
    OnInterestValidationFailed onValidationFailed
)
Parameters:
  • interest

    The interest with the signature to check.

  • onVerified
    If the signature is verified, this calls onVerified(interest) where:
    • interest is the given Interest object.

    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
    If the signature check fails, this calls onValidationFailed(interest, reason) where:
    • interest is the given Interest object.
    • reason is the 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.