The interface of signing key management. More...

#include <key-chain.hpp>

Inheritance diagram for ndn::security::v2::KeyChain:

Collaboration diagram for ndn::security::v2::KeyChain:

Classes
class	Error

class	InvalidSigningInfoError
	Error indicating that the supplied SigningInfo is invalid. More...

class	LocatorMismatchError
	Error indicating that the supplied TPM locator does not match the locator stored in PIB. More...

Public Member Functions
	KeyChain ()
	Constructor to create KeyChain with default PIB and TPM. More...

	KeyChain (const std::string &pibLocator, const std::string &tpmLocator, bool allowReset=false)
	KeyChain constructor. More...

	~KeyChain ()

const Pib &	getPib () const

const Tpm &	getTpm () const

Identity	createIdentity (const Name &identityName, const KeyParams &params=getDefaultKeyParams())
	Create an identity `identityName`. More...

void	deleteIdentity (const Identity &identity)
	delete `identity`. More...

void	setDefaultIdentity (const Identity &identity)
	Set `identity` as the default identity. More...

Key	createKey (const Identity &identity, const KeyParams &params=getDefaultKeyParams())
	Create a new key for `identity`. More...

Name	createHmacKey (const Name &prefix=SigningInfo::getHmacIdentity(), const HmacKeyParams &params=HmacKeyParams())
	Create a new HMAC key. More...

void	deleteKey (const Identity &identity, const Key &key)
	Delete a key `key` of `identity`. More...

void	setDefaultKey (const Identity &identity, const Key &key)
	Set `key` as the default key of `identity`. More...

void	addCertificate (const Key &key, const Certificate &certificate)
	Add a certificate `certificate` for `key`. More...

void	deleteCertificate (const Key &key, const Name &certificateName)
	delete a certificate with name `certificateName` of `key`. More...

void	setDefaultCertificate (const Key &key, const Certificate &certificate)
	Set `cert` as the default certificate of `key`. More...

void	sign (Data &data, const SigningInfo &params=getDefaultSigningInfo())
	Sign data according to the supplied signing information. More...

void	sign (Interest &interest, const SigningInfo &params=getDefaultSigningInfo())
	Sign interest according to the supplied signing information. More...

Block	sign (const uint8_t *buffer, size_t bufferLength, const SigningInfo &params=getDefaultSigningInfo())
	Sign buffer according to the supplied signing information `params`. More...

shared_ptr< SafeBag >	exportSafeBag (const Certificate &certificate, const char *pw, size_t pwLen)
	Export a certificate and its corresponding private key. More...

void	importSafeBag (const SafeBag &safeBag, const char *pw, size_t pwLen)
	Import a certificate and its corresponding private key from a SafeBag. More...

void	importPrivateKey (const Name &keyName, shared_ptr< transform::PrivateKey > key)
	Import a private key into the TPM. More...

Static Public Member Functions
template<class PibBackendType >
static void	registerPibBackend (const std::string &scheme)
	Register a new PIB backend. More...

template<class TpmBackendType >
static void	registerTpmBackend (const std::string &scheme)
	Register a new TPM backend. More...

static const SigningInfo &	getDefaultSigningInfo ()

static const KeyParams &	getDefaultKeyParams ()

Public Attributes
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE	__pad0__: static tlv::SignatureTypeValue getSignatureType(KeyType keyType

NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE DigestAlgorithm	digestAlgorithm

Detailed Description

The interface of signing key management.

The KeyChain class provides an interface to manage entities related to packet signing, such as Identity, Key, and Certificates. It consists of two parts: a private key module (TPM) and a public key information base (PIB). Managing signing key and its related entities through KeyChain interface guarantees the consistency between TPM and PIB.

Definition at line 46 of file key-chain.hpp.

Constructor & Destructor Documentation

◆ KeyChain() [1/2]

ndn::security::v2::KeyChain::KeyChain ( )

Constructor to create KeyChain with default PIB and TPM.

Default PIB and TPM are platform-dependent and can be overriden system-wide or individually for the user.

See also: manpage ndn-client.conf

Todo:: Add detailed description about config file behavior here

Definition at line 164 of file key-chain.cpp.

◆ KeyChain() [2/2]

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

KeyChain constructor.

See also: manpage ndn-client.conf

Parameters

pibLocator	PIB locator, e.g., `pib-sqlite3:/example/dir`
tpmLocator	TPM locator, e.g., `tpm-memory:`
allowReset	if true, the PIB will be reset when the supplied `tpmLocator` does not match the one in the PIB

Definition at line 169 of file key-chain.cpp.

References NDN_THROW.

◆ ~KeyChain()

ndn::security::v2::KeyChain::~KeyChain ( )

default

Member Function Documentation

◆ getPib()

const Pib& ndn::security::v2::KeyChain::getPib ( ) const

inline

Definition at line 100 of file key-chain.hpp.

Referenced by nfd::rib::HostToGatewayReadvertisePolicy::handleNewRoute().

◆ getTpm()

const Tpm& ndn::security::v2::KeyChain::getTpm ( ) const

inline

Definition at line 106 of file key-chain.hpp.

◆ createIdentity()

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

Create an identity 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	The key parameters if a key needs to be created for the identity (default: EC key with random key id)

Returns: The created Identity instance.

Definition at line 221 of file key-chain.cpp.

References createKey(), ndn::security::pib::Key::getDefaultCertificate(), ndn::security::pib::Key::getName(), and NDN_LOG_DEBUG.

◆ deleteIdentity()

void ndn::security::v2::KeyChain::deleteIdentity ( const Identity & identity )

delete identity.

Precondition: identity must be valid.

Postcondition: identity becomes invalid.

Definition at line 245 of file key-chain.cpp.

References ndn::security::pib::Identity::getKeys(), and ndn::security::pib::Identity::getName().

◆ setDefaultIdentity()

void ndn::security::v2::KeyChain::setDefaultIdentity ( const Identity & identity )

Set identity as the default identity.

Precondition: identity must be valid.

Definition at line 259 of file key-chain.cpp.

References ndn::security::pib::Identity::getName().

◆ createKey()

Key ndn::security::v2::KeyChain::createKey	(	const Identity &	identity,
		const KeyParams &	params = `getDefaultKeyParams()`
	)

Create a new key for identity.

Parameters

identity	Reference to a valid Identity object
params	Key creation parameters (default: EC key with random key id)

Precondition: identity must be valid.

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

Definition at line 267 of file key-chain.cpp.

References ndn::security::pib::Identity::getName(), ndn::security::pib::Key::getName(), and NDN_LOG_DEBUG.

Referenced by createIdentity().

◆ createHmacKey()

Name ndn::security::v2::KeyChain::createHmacKey	(	const Name &	prefix = `SigningInfo::getHmacIdentity()`,
		const HmacKeyParams &	params = `HmacKeyParams()`
	)

Create a new HMAC key.

Parameters

prefix	Prefix used to construct the key name (default: `/localhost/identity/hmac`); the full key name will include additional components according to `params`
params	Key creation parameters

Returns: A name that can be subsequently used to reference the created key.

The newly created key will be inserted in the TPM. HMAC keys don't have any PIB entries.

Definition at line 285 of file key-chain.cpp.

◆ deleteKey()

void ndn::security::v2::KeyChain::deleteKey	(	const Identity &	identity,
		const Key &	key
	)

Delete a key key of identity.

Precondition: identity must be valid.; key must be valid.

Postcondition: key becomes invalid.

Exceptions

std::invalid_argument key does not belong to identity

Definition at line 291 of file key-chain.cpp.

References ndn::security::pib::Key::getIdentity(), ndn::security::pib::Identity::getName(), ndn::security::pib::Key::getName(), NDN_THROW, ndn::security::pib::Identity::removeKey(), and ndn::Name::toUri().

◆ setDefaultKey()

void ndn::security::v2::KeyChain::setDefaultKey	(	const Identity &	identity,
		const Key &	key
	)

Set key as the default key of identity.

Precondition: identity must be valid.; key must be valid.

Exceptions

std::invalid_argument key does not belong to identity

Definition at line 307 of file key-chain.cpp.

References ndn::security::pib::Key::getIdentity(), ndn::security::pib::Identity::getName(), ndn::security::pib::Key::getName(), NDN_THROW, ndn::security::pib::Identity::setDefaultKey(), and ndn::Name::toUri().

◆ addCertificate()

void ndn::security::v2::KeyChain::addCertificate	(	const Key &	key,
		const Certificate &	certificate
	)

Add a certificate certificate for key.

If key had no default certificate selected, the added certificate will be set as the default certificate for this key.

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

Precondition: key must be valid.

Exceptions

std::invalid_argument key does not match certificate

Definition at line 320 of file key-chain.cpp.

References ndn::Data::getContent(), ndn::security::v2::Certificate::getKeyName(), ndn::security::pib::Key::getName(), ndn::Data::getName(), ndn::security::pib::Key::getPublicKey(), NDN_THROW, ndn::Name::toUri(), ndn::Block::value_begin(), and ndn::Block::value_end().

Referenced by setDefaultCertificate().

◆ deleteCertificate()

void ndn::security::v2::KeyChain::deleteCertificate	(	const Key &	key,
		const Name &	certificateName
	)

delete a certificate with name certificateName of key.

If the certificate certificateName does not exist, this method has no effect.

Precondition: key must be valid.

Exceptions

std::invalid_argument certificateName does not follow certificate naming convention.

Definition at line 334 of file key-chain.cpp.

References ndn::security::v2::Certificate::isValidName(), NDN_THROW, ndn::security::pib::Key::removeCertificate(), and ndn::Name::toUri().

◆ setDefaultCertificate()

void ndn::security::v2::KeyChain::setDefaultCertificate	(	const Key &	key,
		const Certificate &	certificate
	)

Set cert as the default certificate of key.

The certificate cert will be added to the key, potentially overriding existing certificate if it has the same name (without considering implicit digest).

Precondition: key must be valid.

Exceptions

std::invalid_argument key does not match certificate

Definition at line 346 of file key-chain.cpp.

References addCertificate(), ndn::Data::getName(), and ndn::security::pib::Key::setDefaultCertificate().

◆ sign() [1/3]

void ndn::security::v2::KeyChain::sign	(	Data &	data,
		const SigningInfo &	params = `getDefaultSigningInfo()`
	)

Sign data according to the supplied signing information.

This method uses the supplied signing information params to create the SignatureInfo block:

it selects a private key and its certificate to sign the packet
sets the KeyLocator field with the certificate name, and
adds other requested information to the SignatureInfo block.

After that, the method assigns the created SignatureInfo to the data packets, generate a signature and sets as part of the SignatureValue block.

Note: The exception throwing semantics has changed from v1::KeyChain. If the requested identity/key/certificate does not exist, it will not be created and exception will be thrown.

Parameters

data	The data to sign
params	The signing parameters.

Exceptions

Error	signing fails
InvalidSigningInfoError	invalid `params` is specified or specified identity, key, or certificate does not exist

See also: SigningInfo

Definition at line 450 of file key-chain.cpp.

References ndn::security::SigningInfo::getDigestAlgorithm(), ndn::Data::setSignature(), and ndn::Data::wireEncode().

Referenced by ndn::security::CommandInterestSigner::makeCommandInterest(), ndn::MetadataObject::makeData(), ndn::util::NotificationStream< Notification >::postNotification(), sign(), and ndn::PrefixAnnouncement::toData().

◆ sign() [2/3]

void ndn::security::v2::KeyChain::sign	(	Interest &	interest,
		const SigningInfo &	params = `getDefaultSigningInfo()`
	)

Sign interest according to the supplied signing information.

This method uses the supplied signing information params to create the SignatureInfo block:

it selects a private key and its certificate to sign the packet
sets the KeyLocator field with the certificate name, and
adds other requested information to the SignatureInfo block.

After that, the method appends the created SignatureInfo to the interest name, generate a signature and appends it as part of the SignatureValue block to the interest name.

Note: The exception throwing semantics has changed from v1::KeyChain. If the requested identity/key/certificate does not exist, it will not be created and exception will be thrown.

Parameters

interest	The interest to sign
params	The signing parameters.

Exceptions

Error	signing fails
InvalidSigningInfoError	invalid `params` is specified or specified identity, key, or certificate does not exist

See also: SigningInfo; docs/specs/signed-interest.rst

Definition at line 467 of file key-chain.cpp.

References ndn::Name::append(), ndn::Block::encode(), ndn::security::SigningInfo::getDigestAlgorithm(), ndn::Interest::getName(), ndn::Interest::setName(), sign(), ndn::SignatureInfo::wireEncode(), and ndn::Name::wireEncode().

◆ sign() [3/3]

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

Sign buffer according to the supplied signing information params.

If params refers to an identity, the method selects the default key of the identity. If params refers to a key or certificate, the method select the corresponding key.

Parameters

buffer	The buffer to sign
bufferLength	The buffer size
params	The signing parameters.

Returns: a SignatureValue TLV block

Exceptions

Error signing fails

See also: SigningInfo

Definition at line 485 of file key-chain.cpp.

References ndn::security::SigningInfo::getDigestAlgorithm(), and sign().

◆ exportSafeBag()

shared_ptr< SafeBag > ndn::security::v2::KeyChain::exportSafeBag	(	const Certificate &	certificate,
		const char *	pw,
		size_t	pwLen
	)

Export a certificate and its corresponding private key.

Parameters

certificate	The certificate to export.
pw	The password to secure the private key.
pwLen	The length of password.

Returns: A SafeBag carrying the certificate and encrypted private key.

Exceptions

Error the certificate or private key does not exist

Definition at line 355 of file key-chain.cpp.

References ndn::security::v2::Certificate::getIdentity(), ndn::security::v2::Certificate::getKeyName(), NDN_THROW_NESTED, and ndn::Name::toUri().

◆ importSafeBag()

void ndn::security::v2::KeyChain::importSafeBag	(	const SafeBag &	safeBag,
		const char *	pw,
		size_t	pwLen
	)

Import a certificate and its corresponding private key from 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 KeyChain.

Parameters

safeBag	The encoded data to import.
pw	The password to secure the private key.
pwLen	The length of password.

Exceptions

Error

any of following conditions:

the safebag cannot be decoded or its content does not match;
private key cannot be imported;
a private/public key of the same name already exists;
a certificate of the same name already exists.

Definition at line 372 of file key-chain.cpp.

References ndn::security::transform::boolSink(), ndn::security::SafeBag::getCertificate(), ndn::security::SafeBag::getEncryptedKeyBag(), ndn::security::v2::Certificate::getIdentity(), ndn::security::pib::Identity::getKey(), ndn::security::v2::Certificate::getKeyName(), ndn::Data::getName(), ndn::security::v2::Certificate::getPublicKey(), nonstd::optional_lite::std11::move(), NDN_THROW, NDN_THROW_NESTED, ndn::SHA256, ndn::Name::toUri(), and ndn::security::transform::verifierFilter().

◆ importPrivateKey()

void ndn::security::v2::KeyChain::importPrivateKey	(	const Name &	keyName,
		shared_ptr< transform::PrivateKey >	key
	)

Import a private key into the TPM.

Definition at line 433 of file key-chain.cpp.

References nonstd::optional_lite::std11::move(), NDN_THROW, NDN_THROW_NESTED, and ndn::Name::toUri().

◆ registerPibBackend()

template<class PibType >

void ndn::security::v2::KeyChain::registerPibBackend ( const std::string & scheme )

inlinestatic

Register a new PIB backend.

Parameters

scheme Name for the registered PIB backend scheme

Note: This interface is implementation detail and may change without notice.

Definition at line 456 of file key-chain.hpp.

◆ registerTpmBackend()

template<class TpmType >

void ndn::security::v2::KeyChain::registerTpmBackend ( const std::string & scheme )

inlinestatic

Register a new TPM backend.

Parameters

scheme Name for the registered TPM backend scheme

Note: This interface is implementation detail and may change without notice.

Definition at line 465 of file key-chain.hpp.

◆ getDefaultSigningInfo()

const SigningInfo & ndn::security::v2::KeyChain::getDefaultSigningInfo ( )

static

Definition at line 149 of file key-chain.cpp.

◆ getDefaultKeyParams()

const KeyParams & ndn::security::v2::KeyChain::getDefaultKeyParams ( )

static

Definition at line 156 of file key-chain.cpp.

Member Data Documentation

◆ pad0

NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE ndn::security::v2::KeyChain::__pad0__

Definition at line 343 of file key-chain.hpp.

◆ digestAlgorithm

NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE DigestAlgorithm ndn::security::v2::KeyChain::digestAlgorithm

Definition at line 348 of file key-chain.hpp.

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

ndnSIM/ndn-cxx/ndn-cxx/security/v2/key-chain.hpp
ndnSIM/ndn-cxx/ndn-cxx/security/v2/key-chain.cpp

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ KeyChain() [1/2]

◆ KeyChain() [2/2]

◆ ~KeyChain()

Member Function Documentation

◆ getPib()

◆ getTpm()

◆ createIdentity()

◆ deleteIdentity()

◆ setDefaultIdentity()

◆ createKey()

◆ createHmacKey()

◆ deleteKey()

◆ setDefaultKey()

◆ addCertificate()

◆ deleteCertificate()

◆ setDefaultCertificate()

◆ sign() [1/3]

◆ sign() [2/3]

◆ sign() [3/3]

◆ exportSafeBag()

◆ importSafeBag()

◆ importPrivateKey()

◆ registerPibBackend()

◆ registerTpmBackend()

◆ getDefaultSigningInfo()

◆ getDefaultKeyParams()

Member Data Documentation

◆ __pad0__

◆ digestAlgorithm

◆ pad0