The main interface for signing key management. More...

#include <ndn-cxx/security/key-chain.hpp>

Inheritance diagram for ndn::security::KeyChain:

Collaboration diagram for ndn::security::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 ()

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

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

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

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

void	deleteCertificate (const Key &key, const Name &certName)
	Delete a certificate with name `certName` from `key`. More...

void	deleteIdentity (const Identity &identity)
	Delete `identity` from this KeyChain. More...

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

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

const Pib &	getPib () const noexcept

const Tpm &	getTpm () const noexcept

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

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

Certificate	makeCertificate (const Certificate &certRequest, const SigningInfo &params=SigningInfo(), const MakeCertificateOptions &opts={})
	Create and sign a certificate packet. More...

Certificate	makeCertificate (const pib::Key &publicKey, const SigningInfo &params=SigningInfo(), const MakeCertificateOptions &opts={})
	Create and sign a certificate packet. More...

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

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

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

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

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

Static Public Member Functions
static const KeyParams &	getDefaultKeyParams ()

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

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

Detailed Description

The main interface for 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 keys and their related entities through the KeyChain interface guarantees the consistency between TPM and PIB.

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

Constructor & Destructor Documentation

◆ KeyChain() [1/2]

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

Constructor to create KeyChain with default PIB and TPM.

The default PIB and TPM are platform-dependent and can be overridden system-wide or on a per-user or even per-application basis.

See also: man ndn-client.conf(5)

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

◆ KeyChain() [2/2]

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

KeyChain constructor.

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

See also: man ndn-client.conf(5)

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

◆ ~KeyChain()

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

default

Member Function Documentation

◆ addCertificate()

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

Add a certificate cert for key.

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

This method will overwrite a certificate with the same name (without considering the implicit digest).

Precondition: key must be valid.

Exceptions

std::invalid_argument The certificate does not match the key.

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

◆ createHmacKey()

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

Create a new HMAC key.

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

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.

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

◆ createIdentity()

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

Create an identity identityName.

This method will check if the identity exists in the PIB and whether the identity has a default key and default certificate. If the identity does not exist, this method will create it. 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 198 of file key-chain.cpp.

◆ createKey()

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

Create a new key for identity.

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.

Parameters

identity	The identity that will own the created key; must be valid.
params	Key creation parameters (default: EC key with random key id).

Returns: The created Key instance.

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

◆ deleteCertificate()

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

Delete a certificate with name certName from key.

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

Precondition: key must be valid.

Exceptions

std::invalid_argument The certificate name is invalid or does not match the key name.

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

◆ deleteIdentity()

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

Delete identity from this KeyChain.

Attempting to delete an invalid identity has no effect.

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

◆ deleteKey()

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

Delete key from identity.

Attempting to delete an invalid key has no effect.

Precondition: identity must be valid.

Exceptions

std::invalid_argument key does not belong to identity.

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

◆ exportSafeBag()

shared_ptr< SafeBag > ndn::security::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 317 of file key-chain.cpp.

◆ getDefaultKeyParams()

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

static

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

◆ getPib()

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

inlinenoexcept

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

◆ getTpm()

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

inlinenoexcept

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

◆ importPrivateKey()

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

Import a private key into the TPM.

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

◆ importSafeBag()

void ndn::security::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 333 of file key-chain.cpp.

◆ makeCertificate() [1/2]

Certificate ndn::security::KeyChain::makeCertificate	(	const Certificate &	certRequest,
		const SigningInfo &	params = `SigningInfo()`,
		const MakeCertificateOptions &	opts = `{}`
	)

Create and sign a certificate packet.

Parameters

certRequest	Certificate request enclosing the public key being certified. It does not need to exist in this KeyChain.
params	Signing parameters. The referenced key must exist in this KeyChain. It may contain SignatureInfo for customizing KeyLocator and CustomTlv (including AdditionalDescription), but ValidityPeriod will be overwritten.
opts	Optional arguments.

Returns: A certificate of the public key enclosed in certRequest signed by a key from this KeyChain found by params .

Exceptions

std::invalid_argument	`opts.freshnessPeriod` is not positive.
std::invalid_argument	`certRequest` contains invalid public key.
Error	Certificate signing failure.

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

◆ makeCertificate() [2/2]

Certificate ndn::security::KeyChain::makeCertificate	(	const pib::Key &	publicKey,
		const SigningInfo &	params = `SigningInfo()`,
		const MakeCertificateOptions &	opts = `{}`
	)

Create and sign a certificate packet.

Parameters

publicKey	Public key being certified. It does not need to exist in this KeyChain.
params	Signing parameters. The referenced key must exist in this KeyChain. It may contain SignatureInfo for customizing KeyLocator and CustomTlv (including AdditionalDescription), but ValidityPeriod will be overwritten.
opts	Optional arguments.

Returns: A certificate of publicKey signed by a key from this KeyChain found by params .

Exceptions

std::invalid_argument	`opts.freshnessPeriod` is not positive.
Error	Certificate signing failure.

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

◆ registerPibBackend()

template<class PibBackendType >

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

inlinestatic

Register a new PIB backend type.

Parameters

scheme Unique identifier for the registered PIB backend type.

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

◆ registerTpmBackend()

template<class TpmBackendType >

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

inlinestatic

Register a new TPM backend type.

Parameters

scheme Unique identifier for the registered TPM backend type.

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

◆ setDefaultCertificate()

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

Set cert as the default certificate of key.

The certificate cert will be added to key, potentially overwriting an existing certificate with the same name (without considering the implicit digest).

Precondition: key must be valid.

Exceptions

std::invalid_argument The certificate does not match the key.

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

◆ setDefaultIdentity()

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

Set identity as the default identity.

Precondition: identity must be valid.

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

◆ setDefaultKey()

void ndn::security::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 284 of file key-chain.cpp.

◆ sign() [1/2]

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

Sign a Data packet according to the supplied signing information.

This method uses the supplied signing information in params to sign data as follows:

It selects a private key and its associated certificate to sign the packet.
It generates a KeyLocator based upon the certificate name.
Using the SignatureInfo in params as a base, it generates the final SignatureInfo block for data.
It adds the generated SignatureInfo block to data.
It generates a signature for data and adds it as the SignatureValue block of data.

Parameters

data	The data to sign
params	The signing parameters

Exceptions

Error	Signing failed
InvalidSigningInfoError	Invalid `params` was specified or the specified identity, key, or certificate does not exist

See also: SigningInfo; SignatureInfo

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

◆ sign() [2/2]

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

Sign an Interest according to the supplied signing information.

This method uses the supplied signing information in params to sign interest as follows:

It selects a private key and its associated certificate to sign the packet.
It generates a KeyLocator based upon the certificate name.
Using the SignatureInfo in params as a base, it generates the final SignatureInfo block for interest.
It adds the generated SignatureInfo element to interest. If Packet Specification v0.3 formatting is desired, this block will be appended to interest as a separate InterestSignatureInfo element. Otherwise, it will be appended to the end of the name of interest as a SignatureInfo block.
It generates a signature for interest. If Packet Specification v0.3 formatting is desired, this block will be added to interest as a separate InterestSignatureValue element. Otherwise, it will be appended to the end of the name of interest as a SignatureValue block.

Parameters

interest	The interest to sign
params	The signing parameters

Exceptions

Error	Signing failed
InvalidSigningInfoError	Invalid `params` was specified or the specified identity, key, or certificate does not exist

See also: SigningInfo; SignatureInfo; https://docs.named-data.net/NDN-packet-spec/0.3/signed-interest.html

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

ndn-cxx: NDN C++ library with eXperimental eXtensions 0.9.0-4-g51974f6b documentation

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ KeyChain() [1/2]

◆ KeyChain() [2/2]

◆ ~KeyChain()

Member Function Documentation

◆ addCertificate()

◆ createHmacKey()

◆ createIdentity()

◆ createKey()

◆ deleteCertificate()

◆ deleteIdentity()

◆ deleteKey()

◆ exportSafeBag()

◆ getDefaultKeyParams()

◆ getPib()

◆ getTpm()

◆ importPrivateKey()

◆ importSafeBag()

◆ makeCertificate() [1/2]

◆ makeCertificate() [2/2]

◆ registerPibBackend()

◆ registerTpmBackend()

◆ setDefaultCertificate()

◆ setDefaultIdentity()

◆ setDefaultKey()

◆ sign() [1/2]

◆ sign() [2/2]