KeyChain is the main class of the security library. More...

#include <key-chain.hpp>

Classes
class	Error
	A KeyChain::Error extends runtime_error and represents an error in KeyChain processing. More...

class	InvalidSigningInfoError
	A KeyChain::InvalidSigningInfoError extends KeyChain::Error to indicate that the supplied SigningInfo is invalid. More...

class	LocatorMismatchError
	A KeyChain::LocatorMismatchError extends KeyChain::Error to indicate that the supplied TPM locator does not match the locator stored in the PIB. More...

Public Types
typedef func_lib::function < ptr_lib::shared_ptr< PibImpl > const std::string &location)>	MakePibImpl

typedef func_lib::function < ptr_lib::shared_ptr < TpmBackEnd >const std::string &location)>	MakeTpmBackEnd

Public Member Functions
	KeyChain (const std::string &pibLocator, const std::string &tpmLocator, bool allowReset=false)
	Create a KeyChain to use the PIB and TPM defined by the given locators. More...

	KeyChain (const ptr_lib::shared_ptr< PibImpl > &pibImpl, const ptr_lib::shared_ptr< TpmBackEnd > &tpmBackEnd, const ptr_lib::shared_ptr< PolicyManager > &policyManager=ptr_lib::shared_ptr< PolicyManager >())
	Create a security v2 KeyChain with explicitly-created PIB and TPM objects, and that optionally still uses the v1 PolicyManager. More...

	KeyChain (const ptr_lib::shared_ptr< IdentityManager > &identityManager, const ptr_lib::shared_ptr< PolicyManager > &policyManager)
	Create a new security v1 KeyChain with the given IdentityManager and PolicyManager. More...

	KeyChain (const ptr_lib::shared_ptr< IdentityManager > &identityManager)
	Create a new security v1 KeyChain with the given IdentityManager and a NoVerifyPolicyManager. More...

	KeyChain ()
	Create a KeyChain with the default PIB and TPM, which are platform-dependent and can be overridden system-wide or individually by the user. More...

Pib &	getPib ()

Tpm &	getTpm ()

bool	getIsSecurityV1 () const
	Get the flag set by the constructor if this is a security v1 or v2 KeyChain. More...

ptr_lib::shared_ptr< PibIdentity >	createIdentityV2 (const Name &identityName, const KeyParams &params=getDefaultKeyParams())
	Create a security V2 identity for identityName. More...

void	deleteIdentity (PibIdentity &identity)
	Delete the identity. More...

void	setDefaultIdentity (PibIdentity &identity)
	Set the identity as the default identity. More...

ptr_lib::shared_ptr< PibKey >	createKey (PibIdentity &identity, const KeyParams &params=getDefaultKeyParams())
	Create a key for the identity according to params. More...

void	deleteKey (PibIdentity &identity, PibKey &key)
	Delete the given key of the given identity. More...

void	setDefaultKey (PibIdentity &identity, PibKey &key)
	Set the key as the default key of identity. More...

void	addCertificate (PibKey &key, const CertificateV2 &certificate)
	Add a certificate for the key. More...

void	deleteCertificate (PibKey &key, const Name &certificateName)
	Delete the certificate with the given name from the given key. More...

void	setDefaultCertificate (PibKey &key, const CertificateV2 &certificate)
	Set the certificate as the default certificate of the key. More...

void	sign (Data &data, const SigningInfo &params, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Wire encode the Data object, sign it according to the supplied signing parameters, and set its signature. More...

void	sign (Data &data, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Wire encode the Data object, sign it with the default key of the default identity, and set its signature. More...

void	sign (Interest &interest, const SigningInfo &params, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Sign Interest according to the supplied signing parameters. More...

void	sign (Interest &interest, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Sign the Interest with the default key of the default identity. More...

Blob	sign (const uint8_t *buffer, size_t bufferLength, const SigningInfo &params=getDefaultSigningInfo())
	Sign the byte array according to the supplied signing parameters. More...

ptr_lib::shared_ptr < CertificateV2 >	selfSign (ptr_lib::shared_ptr< PibKey > &key, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Generate a self-signed certificate for the public key and add it to the PIB. More...

void	importSafeBag (const SafeBag &safeBag, const uint8_t *password=0, size_t passwordLength=0)
	Import a certificate and its corresponding private key encapsulated in a SafeBag. More...

Name	createIdentityAndCertificate (const Name &identityName, const KeyParams &params=getDefaultKeyParams())
	Create a security v1 identity by creating a pair of Key-Signing-Key (KSK) for this identity and a self-signed certificate of the KSK. More...

Name DEPRECATED_IN_NDN_CPP	createIdentity (const Name &identityName, const KeyParams &params=getDefaultKeyParams())
	Create a security v1 identity by creating a pair of Key-Signing-Key (KSK) for this identity and a self-signed certificate of the KSK. More...

void	deleteIdentity (const Name &identityName)
	Delete the identity from the public and private key storage. More...

Name	getDefaultIdentity ()
	Get the default identity. More...

Name	getDefaultCertificateName ()
	Get the default certificate name of the default identity. More...

Name	generateRSAKeyPair (const Name &identityName, bool isKsk=false, int keySize=2048)
	Generate a pair of RSA keys for the specified identity. More...

Name	generateEcdsaKeyPair (const Name &identityName, bool isKsk=false, int keySize=256)
	Generate a pair of ECDSA keys for the specified identity. More...

void	setDefaultKeyForIdentity (const Name &keyName, const Name &identityNameCheck=Name())
	Set a key as the default key of an identity. More...

Name	generateRSAKeyPairAsDefault (const Name &identityName, bool isKsk=false, int keySize=2048)
	Generate a pair of RSA keys for the specified identity and set it as the default key for the identity. More...

Name	generateEcdsaKeyPairAsDefault (const Name &identityName, bool isKsk=false, int keySize=256)
	Generate a pair of ECDSA keys for the specified identity and set it as the default key for the identity. More...

Blob	createSigningRequest (const Name &keyName)
	Create a public key signing request. More...

void	installIdentityCertificate (const IdentityCertificate &certificate)
	Install an identity certificate into the public key identity storage. More...

void	setDefaultCertificateForKey (const IdentityCertificate &certificate)
	Set the certificate as the default for its corresponding key. More...

ptr_lib::shared_ptr < IdentityCertificate >	getCertificate (const Name &certificateName)
	Get a certificate with the specified name. More...

ptr_lib::shared_ptr < IdentityCertificate > DEPRECATED_IN_NDN_CPP	getIdentityCertificate (const Name &certificateName)

void	revokeKey (const Name &keyName)
	Revoke a key. More...

void	revokeCertificate (const Name &certificateName)
	Revoke a certificate. More...

const ptr_lib::shared_ptr < IdentityManager > &	getIdentityManager ()
	Get the identity manager given to or created by the constructor. More...

const ptr_lib::shared_ptr < PolicyManager > &	getPolicyManager ()
	Get the policy manager given to or created by the constructor. More...

void	sign (Data &data, const Name &certificateName, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Wire encode the Data object, sign it and set its signature. More...

void	sign (Interest &interest, const Name &certificateName, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Append a SignatureInfo to the Interest name, sign the name components and append a final name component with the signature bits. More...

ptr_lib::shared_ptr< Signature >	sign (const uint8_t *buffer, size_t bufferLength, const Name &certificateName)
	Sign the byte array using a certificate name and return a Signature object. More...

ptr_lib::shared_ptr< Signature >	sign (const std::vector< uint8_t > &buffer, const Name &certificateName)
	Sign the byte array using a certificate name and return a Signature object. More...

void	signByIdentity (Data &data, const Name &identityName=Name(), WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Wire encode the Data object, sign it and set its signature. More...

ptr_lib::shared_ptr< Signature >	signByIdentity (const uint8_t *buffer, size_t bufferLength, const Name &identityName)
	Sign the byte array using an identity name and return a Signature object. More...

ptr_lib::shared_ptr< Signature >	signByIdentity (const std::vector< uint8_t > &buffer, const Name &identityName)
	Sign the byte array using an identity name and return a Signature object. More...

void	signWithSha256 (Data &data, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Wire encode the Data object, digest it and set its SignatureInfo to a DigestSha256. More...

void	signWithSha256 (Interest &interest, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	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). More...

void	verifyData (const ptr_lib::shared_ptr< Data > &data, const OnVerified &onVerified, const OnDataValidationFailed &onValidationFailed, int stepCount=0)
	Check the signature on the Data object and call either onVerify or onValidationFailed. More...

void DEPRECATED_IN_NDN_CPP	verifyData (const ptr_lib::shared_ptr< Data > &data, const OnVerified &onVerified, const OnVerifyFailed &onVerifyFailed, int stepCount=0)
	Check the signature on the Data object and call either onVerify or onVerifyFailed. More...

void	verifyInterest (const ptr_lib::shared_ptr< Interest > &interest, const OnVerifiedInterest &onVerified, const OnInterestValidationFailed &onValidationFailed, int stepCount=0, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Check the signature on the signed interest and call either onVerify or onValidationFailed. More...

void DEPRECATED_IN_NDN_CPP	verifyInterest (const ptr_lib::shared_ptr< Interest > &interest, const OnVerifiedInterest &onVerified, const OnVerifyInterestFailed &onVerifyFailed, int stepCount=0, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Check the signature on the signed interest and call either onVerify or onVerifyFailed. More...

void	setFace (Face *face)
	Set the Face which will be used to fetch required certificates. More...

Static Public Member Functions
static void	registerPibBackend (const std::string &scheme, const MakePibImpl &makePibImpl)
	Add to the PIB factories map where scheme is the key and makePibImpl is the value. More...

static void	registerTpmBackend (const std::string &scheme, const MakeTpmBackEnd &makeTpmBackEnd)
	Add to the TPM factories map where scheme is the key and makeTpmBackEnd is the value. More...

static void	signWithHmacWithSha256 (Data &data, const Blob &key, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Wire encode the Data object, compute an HmacWithSha256 and update the signature value. More...

static void	signWithHmacWithSha256 (Interest &interest, const Blob &key, const Name &keyName, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	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. More...

static bool	verifyDataWithHmacWithSha256 (const Data &data, const Blob &key, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Compute a new HmacWithSha256 for the data packet and verify it against the signature value. More...

static bool	verifyInterestWithHmacWithSha256 (const Interest &interest, const Blob &key, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Compute a new HmacWithSha256 for all but the final name component and verify it against the signature value in the final name component. More...

static const KeyParams &	getDefaultKeyParams ()

Static Public Attributes
static const RsaKeyParams DEPRECATED_IN_NDN_CPP	DEFAULT_KEY_PARAMS

Friends
class	CommandInterestSigner

Detailed Description

KeyChain is the main class of the security library.

The KeyChain class 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 .

Constructor & Destructor Documentation

ndn::KeyChain::KeyChain	(	const std::string &	pibLocator,
		const std::string &	tpmLocator,
		bool	allowReset = `false`
	)

Create a KeyChain to use the PIB and TPM defined by the given locators.

This creates a security v2 KeyChain that uses CertificateV2, Pib, Tpm and Validator (instead of v1 Certificate, IdentityStorage, PrivateKeyStorage and PolicyManager).

Parameters

pibLocator	The PIB locator, e.g., "pib-sqlite3:/example/dir".
tpmLocator	The TPM locator, e.g., "tpm-memory:".
allowReset	(optional) If true, the PIB will be reset when the supplied tpmLocator mismatches the one in the PIB. If omitted, don't allow reset.

Exceptions

KeyChain::LocatorMismatchError if the supplied TPM locator does not match the locator stored in the PIB.

ndn::KeyChain::KeyChain	(	const ptr_lib::shared_ptr< PibImpl > &	pibImpl,
		const ptr_lib::shared_ptr< TpmBackEnd > &	tpmBackEnd,
		const ptr_lib::shared_ptr< PolicyManager > &	policyManager = `ptr_lib::shared_ptr<PolicyManager>()`
	)

Create a security v2 KeyChain with explicitly-created PIB and TPM objects, and that optionally still uses the v1 PolicyManager.

Parameters

pibImpl	An explicitly-created PIB object of a subclass of PibImpl.
tpmBackEnd	An explicitly-created TPM object of a subclass of TpmBackEnd.
policyManager	(optional) An object of a subclass of a security v1 PolicyManager. If omitted or null, use a new NoVerifyPolicyManager.

ndn::KeyChain::KeyChain	(	const ptr_lib::shared_ptr< IdentityManager > &	identityManager,
		const ptr_lib::shared_ptr< PolicyManager > &	policyManager
	)

Create a new security v1 KeyChain with the given IdentityManager and PolicyManager.

For security v2, use KeyChain(pibLocator, tpmLocator) or the default constructor if your .ndn folder is already initialized for v2.

Parameters

identityManager	An object of a subclass of IdentityManager.
policyManager	An object of a subclass of PolicyManager.

ndn::KeyChain::KeyChain ( const ptr_lib::shared_ptr< IdentityManager > & identityManager )

Create a new security v1 KeyChain with the given IdentityManager and a NoVerifyPolicyManager.

For security v2, use KeyChain(pibLocator, tpmLocator) or the default constructor if your .ndn folder is already initialized for v2.

Parameters

identityManager An object of a subclass of IdentityManager.

ndn::KeyChain::KeyChain ( )

Create a KeyChain with the default PIB and TPM, which are platform-dependent and can be overridden system-wide or individually by the user.

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

Member Function Documentation

void ndn::KeyChain::addCertificate	(	PibKey &	key,
		const CertificateV2 &	certificate
	)

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

key	A valid PibKey object.
certificate	The certificate to add. This copies the object.

Note: This method overwrites a certificate with the same name, without considering the implicit digest.

Exceptions

invalid_argument If the key does not match the certificate.

Name DEPRECATED_IN_NDN_CPP ndn::KeyChain::createIdentity	(	const Name &	identityName,
		const KeyParams &	params = `getDefaultKeyParams()`
	)

inline

Create a security v1 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.

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.

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 getDefaultKeyParams().

Returns: The key name of the auto-generated KSK of the identity.

Name ndn::KeyChain::createIdentityAndCertificate	(	const Name &	identityName,
		const KeyParams &	params = `getDefaultKeyParams()`
	)

inline

Create a security v1 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. However, if this is a security v2 KeyChain, use createIdentityV2.

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 getDefaultKeyParams().

Returns: The name of the default certificate of the identity.

ptr_lib::shared_ptr< PibIdentity > ndn::KeyChain::createIdentityV2	(	const Name &	identityName,
		const KeyParams &	params = `getDefaultKeyParams()`
	)

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

identityName	The name of the identity.
params	(optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().

Returns: The created PibIdentity instance.

ptr_lib::shared_ptr< PibKey > ndn::KeyChain::createKey	(	PibIdentity &	identity,
		const KeyParams &	params = `getDefaultKeyParams()`
	)

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

identity	A valid PibIdentity object.
params	(optional) The key parameters if a key needs to be generated for the identity. If omitted, use getDefaultKeyParams().

Returns: The new PibKey.

Blob ndn::KeyChain::createSigningRequest ( const Name & keyName )

inline

Create a public key signing request.

Parameters

keyName The name of the key.

Returns: The signing request data.

void ndn::KeyChain::deleteCertificate	(	PibKey &	key,
		const Name &	certificateName
	)

Delete the certificate with the given name from the given key.

If the certificate does not exist, this does nothing.

Parameters

key	A valid PibKey object.
certificateName	The name of the certificate to delete.

Exceptions

invalid_argument If certificateName does not follow certificate naming conventions.

void ndn::KeyChain::deleteIdentity ( PibIdentity & identity )

Delete the identity.

After this operation, the identity is invalid.

Parameters

identity The identity to delete.

void ndn::KeyChain::deleteIdentity ( const Name & identityName )

inline

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

identityName The name of the identity.

void ndn::KeyChain::deleteKey	(	PibIdentity &	identity,
		PibKey &	key
	)

Delete the given key of the given identity.

The key becomes invalid.

Parameters

identity	A valid PibIdentity object.
key	The key to delete.

Exceptions

invalid_argument If the key does not belong to the identity.

Name ndn::KeyChain::generateEcdsaKeyPair	(	const Name &	identityName,
		bool	isKsk = `false`,
		int	keySize = `256`
	)

inline

Generate a pair of ECDSA keys for the specified identity.

Parameters

identityName	The name of the identity.
isKsk	(optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
keySize	(optional) The size of the key. If omitted, use a default secure key size.

Returns: The generated key name.

Name ndn::KeyChain::generateEcdsaKeyPairAsDefault	(	const Name &	identityName,
		bool	isKsk = `false`,
		int	keySize = `256`
	)

inline

Generate a pair of ECDSA keys for the specified identity and set it as the default key for the identity.

Parameters

identityName	The name of the identity.
isKsk	(optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
keySize	(optional) The size of the key. If omitted, use a default secure key size.

Returns: The generated key name.

Name ndn::KeyChain::generateRSAKeyPair	(	const Name &	identityName,
		bool	isKsk = `false`,
		int	keySize = `2048`
	)

inline

Generate a pair of RSA keys for the specified identity.

Parameters

identityName	The name of the identity.
isKsk	(optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
keySize	(optional) The size of the key. If omitted, use a default secure key size.

Returns: The generated key name.

Name ndn::KeyChain::generateRSAKeyPairAsDefault	(	const Name &	identityName,
		bool	isKsk = `false`,
		int	keySize = `2048`
	)

inline

Generate a pair of RSA keys for the specified identity and set it as the default key for the identity.

Parameters

identityName	The name of the identity.
isKsk	(optional) true for generating a Key-Signing-Key (KSK), false for a Data-Signing-Key (DSK). If omitted, generate a Data-Signing-Key.
keySize	(optional) The size of the key. If omitted, use a default secure key size.

Returns: The generated key name.

ptr_lib::shared_ptr<IdentityCertificate> ndn::KeyChain::getCertificate ( const Name & certificateName )

inline

Get a certificate with the specified name.

Parameters

certificateName The name of the requested certificate.

Returns: The requested certificate.

Name ndn::KeyChain::getDefaultCertificateName ( )

inline

Get the default certificate name of the default identity.

Returns: The requested certificate name.

Exceptions

SecurityException (for security v1) or Pib::Error (for security v2) 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.

Name ndn::KeyChain::getDefaultIdentity ( )

inline

Get the default identity.

Returns: The name of default identity.

Exceptions

SecurityException (for security v1) or Pib::Error (for security v2) if the default identity is not set.

ptr_lib::shared_ptr<IdentityCertificate> DEPRECATED_IN_NDN_CPP ndn::KeyChain::getIdentityCertificate ( const Name & certificateName )

inline

Deprecated:: Use getCertificate.

const ptr_lib::shared_ptr<IdentityManager>& ndn::KeyChain::getIdentityManager ( )

inline

Get the identity manager given to or created by the constructor.

Returns: The identity manager.

bool ndn::KeyChain::getIsSecurityV1 ( ) const

inline

Get the flag set by the constructor if this is a security v1 or v2 KeyChain.

Returns: True if this is a security v1 KeyChain, false if this is a security v2 KeyChain.

const ptr_lib::shared_ptr<PolicyManager>& ndn::KeyChain::getPolicyManager ( )

inline

Get the policy manager given to or created by the constructor.

Returns: The policy manager.

void ndn::KeyChain::importSafeBag	(	const SafeBag &	safeBag,
		const uint8_t *	password = `0`,
		size_t	passwordLength = `0`
	)

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

safeBag	The SafeBag containing the certificate and private key. This copies the values from the SafeBag.
password	(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.
passwordLength	(optional) The length of the password. If password is omitted or null, this is ignored.

Exceptions

KeyChain.Error if the private key cannot be imported, or if a public key or private key of the same name already exists, or if a certificate of the same name already exists.

void ndn::KeyChain::installIdentityCertificate ( const IdentityCertificate & certificate )

inline

Install an identity certificate into the public key identity storage.

Parameters

certificate The certificate to to added.

static void ndn::KeyChain::registerPibBackend	(	const std::string &	scheme,
		const MakePibImpl &	makePibImpl
	)

inlinestatic

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

scheme	The PIB scheme.
makePibImpl	A callback which takes the PIB location and returns a new PibImpl instance.

static void ndn::KeyChain::registerTpmBackend	(	const std::string &	scheme,
		const MakeTpmBackEnd &	makeTpmBackEnd
	)

inlinestatic

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

scheme	The TPM scheme.
makeTpmBackEnd	A callback which takes the TPM location and returns a new TpmBackEnd instance.

void ndn::KeyChain::revokeCertificate ( const Name & certificateName )

inline

Revoke a certificate.

Parameters

certificateName The name of the certificate that will be revoked.

void ndn::KeyChain::revokeKey ( const Name & keyName )

inline

Revoke a key.

Parameters

keyName The name of the key that will be revoked.

ptr_lib::shared_ptr< CertificateV2 > ndn::KeyChain::selfSign	(	ptr_lib::shared_ptr< PibKey > &	key,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

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

key	The PibKey with the key name and public key.
wireFormat	(optional) A WireFormat object used to encode the certificate. If omitted, use WireFormat getDefaultWireFormat().

Returns: The new certificate.

void ndn::KeyChain::setDefaultCertificate	(	PibKey &	key,
		const CertificateV2 &	certificate
	)

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

key	A valid PibKey object.
certificate	The certificate to become the default. This copies the object.

void ndn::KeyChain::setDefaultCertificateForKey ( const IdentityCertificate & certificate )

inline

Set the certificate as the default for its corresponding key.

Parameters

certificate The certificate.

void ndn::KeyChain::setDefaultIdentity ( PibIdentity & identity )

Set the identity as the default identity.

Parameters

identity The identity to make the default.

void ndn::KeyChain::setDefaultKey	(	PibIdentity &	identity,
		PibKey &	key
	)

Set the key as the default key of identity.

Parameters

identity	A valid PibIdentity object.
key	The key to become the default.

Exceptions

invalid_argument If the key does not belong to the identity.

void ndn::KeyChain::setDefaultKeyForIdentity	(	const Name &	keyName,
		const Name &	identityNameCheck = `Name()`
	)

inline

Set a key as the default key of an identity.

The identity name is inferred from keyName.

Parameters

keyName	The name of the key.
identityNameCheck	(optional) The identity name to check that the keyName contains the same identity name. If an empty name, it is ignored.

void ndn::KeyChain::setFace ( Face * face )

inline

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

Parameters

face	A pointer to the Face object.

void ndn::KeyChain::sign	(	Data &	data,
		const SigningInfo &	params,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

Wire encode the Data object, sign it according to the supplied signing parameters, and set its signature.

Parameters

data	The Data object to be signed. This replaces its Signature object based on the type of key and other info in the SigningInfo params, and updates the wireEncoding.
params	The signing parameters.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

Exceptions

KeyChain::Error	if signing fails.
KeyChain::InvalidSigningInfoError	if params is invalid, or if the identity, key or certificate specified in params does not exist.

void ndn::KeyChain::sign	(	Data &	data,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

Wire encode the Data object, sign it with the default key of the default identity, and set its signature.

If this is a security v1 KeyChain then use the IdentityManager to get the default identity. Otherwise use the PIB.

Parameters

data	The Data object to be signed. This replaces its Signature object based on the type of key of the default identity, and updates the wireEncoding.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

void ndn::KeyChain::sign	(	Interest &	interest,
		const SigningInfo &	params,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

Sign Interest according to the supplied signing parameters.

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

Parameters

interest	The Interest object to be signed. This appends name components of SignatureInfo and the signature bits.
params	The signing parameters.
wireFormat	(optional) A WireFormat object used to encode the input and encode the appended components. If omitted, use WireFormat getDefaultWireFormat().

Exceptions

KeyChain::Error	if signing fails.
KeyChain::InvalidSigningInfoError	if params is invalid, or if the identity, key or certificate specified in params does not exist.

void ndn::KeyChain::sign	(	Interest &	interest,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

Sign the Interest with the default key of the default identity.

Append a SignatureInfo to the Interest name, sign the encoded name components and append a final name component with the signature bits. If this is a security v1 KeyChain then use the IdentityManager to get the default identity. Otherwise use the PIB.

Parameters

interest	The Interest object to be signed. This appends name components of SignatureInfo and the signature bits.
wireFormat	(optional) A WireFormat object used to encode the input and encode the appended components. If omitted, use WireFormat getDefaultWireFormat().

Blob ndn::KeyChain::sign	(	const uint8_t *	buffer,
		size_t	bufferLength,
		const SigningInfo &	params = `getDefaultSigningInfo()`
	)

Sign the byte array according to the supplied signing parameters.

Parameters

buffer	The byte array to be signed.
bufferLength	the length of buffer.
params	(optional) The signing parameters. If params refers to an identity, this selects the default key of the identity. If params refers to a key or certificate, this selects the corresponding key. If params is omitted, this selects the default key of the default identity.

Returns: The signature Blob, or an isNull Blob if params.getDigestAlgorithm() is unrecognized.

void ndn::KeyChain::sign	(	Data &	data,
		const Name &	certificateName,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

Wire encode the Data object, sign it and set its signature.

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.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

void ndn::KeyChain::sign	(	Interest &	interest,
		const Name &	certificateName,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

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

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.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

ptr_lib::shared_ptr<Signature> ndn::KeyChain::sign	(	const uint8_t *	buffer,
		size_t	bufferLength,
		const Name &	certificateName
	)

inline

Sign the byte array using a certificate name and return a Signature object.

Parameters

buffer	The byte array to be signed.
bufferLength	the length of buffer.
certificateName	The certificate name used to get the signing key and which will be put into KeyLocator.

Returns: The Signature.

ptr_lib::shared_ptr<Signature> ndn::KeyChain::sign	(	const std::vector< uint8_t > &	buffer,
		const Name &	certificateName
	)

inline

Sign the byte array using a certificate name and return a Signature object.

Parameters

buffer	The byte array to be signed.
certificateName	The certificate name used to get the signing key and which will be put into KeyLocator.

Returns: The Signature.

void ndn::KeyChain::signByIdentity	(	Data &	data,
		const Name &	identityName = `Name()`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

Wire encode the Data object, sign it and set its signature.

Parameters

data	The Data object to be signed. This updates its signature and key locator field and wireEncoding.
identityName	(optional) The identity name for the key to use for signing. If omitted, infer the signing identity from the data packet name.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

ptr_lib::shared_ptr< Signature > ndn::KeyChain::signByIdentity	(	const uint8_t *	buffer,
		size_t	bufferLength,
		const Name &	identityName
	)

Sign the byte array using an identity name and return a Signature object.

Parameters

buffer	The byte array to be signed.
bufferLength	the length of buffer.
identityName	The identity name.

Returns: The Signature.

ptr_lib::shared_ptr<Signature> ndn::KeyChain::signByIdentity	(	const std::vector< uint8_t > &	buffer,
		const Name &	identityName
	)

inline

Sign the byte array using an identity name and return a Signature object.

Parameters

buffer	The byte array to be signed.
identityName	The identity name.

Returns: The Signature.

static void ndn::KeyChain::signWithHmacWithSha256	(	Data &	data,
		const Blob &	key,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

static

Wire encode the Data object, compute an HmacWithSha256 and update the signature value.

Parameters

data	The Data object to be signed. It should already have an HmacWithSha256Signature with a KeyLocator for the key name. This updates its signature and wireEncoding.
key	The key for the HmacWithSha256.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

Note: This method is an experimental feature. The API may change.

static void ndn::KeyChain::signWithHmacWithSha256	(	Interest &	interest,
		const Blob &	key,
		const Name &	keyName,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

static

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.

Parameters

interest	The Interest object to be signed. This appends name components of SignatureInfo and the signature bits.
key	The key for the HmacWithSha256.
keyName	The name of the key for the KeyLocator in the SignatureInfo.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

Note: This method is an experimental feature. The API may change.

void ndn::KeyChain::signWithSha256	(	Data &	data,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

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

Parameters

data	The Data object to be signed. This updates its signature and wireEncoding.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

void ndn::KeyChain::signWithSha256	(	Interest &	interest,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

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

Parameters

interest	The Interest object to be signed. This appends name components of SignatureInfo and the signature bits.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

void ndn::KeyChain::verifyData	(	const ptr_lib::shared_ptr< Data > &	data,
		const OnVerified &	onVerified,
		const OnDataValidationFailed &	onValidationFailed,
		int	stepCount = `0`
	)

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

data	The Data object with the signature to check.
onVerified	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	If the signature check fails, this calls onValidationFailed(data, reason). 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.

void ndn::KeyChain::verifyData	(	const ptr_lib::shared_ptr< Data > &	data,
		const OnVerified &	onVerified,
		const OnVerifyFailed &	onVerifyFailed,
		int	stepCount = `0`
	)

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.

Deprecated:

Use verifyData with OnDataValidationFailed.

Parameters

data	The Data object with the signature to check.
onVerified	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	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.

static bool ndn::KeyChain::verifyDataWithHmacWithSha256	(	const Data &	data,
		const Blob &	key,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

static

Compute a new HmacWithSha256 for the data packet and verify it against the signature value.

Parameters

data	The Data object to verify.
key	The key for the HmacWithSha256.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

Returns: True if the signature verifies, otherwise false.

Note: This method is an experimental feature. The API may change.

void ndn::KeyChain::verifyInterest	(	const ptr_lib::shared_ptr< Interest > &	interest,
		const OnVerifiedInterest &	onVerified,
		const OnInterestValidationFailed &	onValidationFailed,
		int	stepCount = `0`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

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

interest	The interest with the signature to check.
onVerified	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	If the signature check fails, this calls onValidationFailed(data, reason). 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.

void ndn::KeyChain::verifyInterest	(	const ptr_lib::shared_ptr< Interest > &	interest,
		const OnVerifiedInterest &	onVerified,
		const OnVerifyInterestFailed &	onVerifyFailed,
		int	stepCount = `0`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

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.

Deprecated:

Use verifyInterest with OnInterestValidationFailed.

Parameters

interest	The interest with the signature to check.
onVerified	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	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.

static bool ndn::KeyChain::verifyInterestWithHmacWithSha256	(	const Interest &	interest,
		const Blob &	key,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

static

Compute a new HmacWithSha256 for all but the final name component and verify it against the signature value in the final name component.

Parameters

interest	The Interest object to verify.
key	The key for the HmacWithSha256.
wireFormat	(optional) A WireFormat object used to encode the input. If omitted, use WireFormat getDefaultWireFormat().

Returns: True if the signature verifies, otherwise false.

Note: This method is an experimental feature. The API may change.

Member Data Documentation

const RsaKeyParams ndn::KeyChain::DEFAULT_KEY_PARAMS

static

Deprecated:: Use getDefaultKeyParams().

The documentation for this class was generated from the following files:

include/ndn-cpp/security/key-chain.hpp
src/security/key-chain.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation