ndn::security::KeyChain Class Reference

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< SafeBagexportSafeBag (const Certificate &certificate, const char *pw, size_t pwLen)
 Export a certificate and its corresponding private key. More...
 
const PibgetPib () const noexcept
 
const TpmgetTpm () 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 KeyParamsgetDefaultKeyParams ()
 
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
pibLocatorPIB locator, e.g., pib-sqlite3:/example/dir
tpmLocatorTPM locator, e.g., tpm-memory:
allowResetif 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_argumentThe 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
prefixPrefix used to construct the key name (default: /localhost/identity/hmac); the full key name will include additional components according to params.
paramsKey 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
identityNameThe name of the identity.
paramsThe 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
identityThe identity that will own the created key; must be valid.
paramsKey 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_argumentThe 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_argumentkey 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
certificateThe certificate to export.
pwThe password to secure the private key.
pwLenThe length of password.
Returns
A SafeBag carrying the certificate and encrypted private key.
Exceptions
Errorthe 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
safeBagThe encoded data to import.
pwThe password to secure the private key.
pwLenThe length of password.
Exceptions
Errorany 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
certRequestCertificate request enclosing the public key being certified. It does not need to exist in this KeyChain.
paramsSigning 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.
optsOptional arguments.
Returns
A certificate of the public key enclosed in certRequest signed by a key from this KeyChain found by params .
Exceptions
std::invalid_argumentopts.freshnessPeriod is not positive.
std::invalid_argumentcertRequest contains invalid public key.
ErrorCertificate 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
publicKeyPublic key being certified. It does not need to exist in this KeyChain.
paramsSigning 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.
optsOptional arguments.
Returns
A certificate of publicKey signed by a key from this KeyChain found by params .
Exceptions
std::invalid_argumentopts.freshnessPeriod is not positive.
ErrorCertificate 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
schemeUnique 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
schemeUnique 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_argumentThe 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_argumentkey 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
dataThe data to sign
paramsThe signing parameters
Exceptions
ErrorSigning failed
InvalidSigningInfoErrorInvalid 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
interestThe interest to sign
paramsThe signing parameters
Exceptions
ErrorSigning failed
InvalidSigningInfoErrorInvalid 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.