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

#include <key-chain.hpp>

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

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

	KeyChain ()
	Create a new KeyChain with the the default IdentityManager and a NoVerifyPolicyManager.

Name	createIdentityAndCertificate (const Name &identityName, const KeyParams &params=DEFAULT_KEY_PARAMS)
	Create an 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=DEFAULT_KEY_PARAMS)
	Create an 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 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 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 (Data &data, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Wire encode the Data object, sign it with the default identity 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...

void	sign (Interest &interest, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Append a SignatureInfo to the Interest name, sign the name components with the default identity 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 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 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	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 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 Public Attributes
static const RsaKeyParams	DEFAULT_KEY_PARAMS

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 ptr_lib::shared_ptr< IdentityManager > &	identityManager,
		const ptr_lib::shared_ptr< PolicyManager > &	policyManager
	)

Create a new KeyChain with the given IdentityManager and PolicyManager.

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 KeyChain with the given IdentityManager and a NoVerifyPolicyManager.

Parameters

identityManager An object of a subclass of IdentityManager.

Member Function Documentation

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

inline

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.

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

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

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

inline

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

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

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

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

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

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::installIdentityCertificate ( const IdentityCertificate & certificate )

inline

Install an identity certificate into the public key identity storage.

Parameters

certificate The certificate to to added.

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.

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::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 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	(	Data &	data,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

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

Parameters

data	The Data object to be signed. This updates its signature and key locator field and wireEncoding.
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().

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

inline

Append a SignatureInfo to the Interest name, sign the name components with the default identity 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.
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. 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.

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

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

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.

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

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation