ndn::security::v2::KeyChain Class Reference

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 ()
 
void addCertificate (const Key &key, const Certificate &certificate)
 Add a certificate certificate for 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 key for identity according to params. More...
 
void deleteCertificate (const Key &key, const Name &certificateName)
 delete a certificate with name certificateName of key. More...
 
void deleteIdentity (const Identity &identity)
 delete identity. More...
 
void deleteKey (const Identity &identity, const Key &key)
 Delete a key key of identity. More...
 
shared_ptr< SafeBagexportSafeBag (const Certificate &certificate, const char *pw, size_t pwLen)
 Export a certificate and its corresponding private key. More...
 
const Pib & getPib () const
 
const Tpm & getTpm () const
 
void importSafeBag (const SafeBag &safeBag, const char *pw, size_t pwLen)
 Import a pair of certificate and its corresponding private key encapsulated in a SafeBag. More...
 
void setDefaultCertificate (const Key &key, const Certificate &certificate)
 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=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...
 

Static Public Member Functions

static const KeyParamsgetDefaultKeyParams ()
 
static const SigningInfogetDefaultSigningInfo ()
 
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...
 

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 v2/key-chain.hpp.

Constructor & Destructor Documentation

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.

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

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

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

Member Function Documentation

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_argumentkey does not match certificate

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

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
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 221 of file key-chain.cpp.

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

Create a key for identity according to params.

Parameters
identityreference to a valid Identity object
paramsThe key parameters if a key needs to be created for the identity (default: EC key with random key id)

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.

Precondition
identity must be valid.

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

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_argumentcertificateName does not follow certificate naming convention.

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

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.

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_argumentkey does not belong to identity

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

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
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 349 of file key-chain.cpp.

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

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

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

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

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

Definition at line 104 of file v2/key-chain.hpp.

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

Definition at line 110 of file v2/key-chain.hpp.

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

Import a pair of 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 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 366 of file key-chain.cpp.

template<class PibType >
void ndn::security::v2::KeyChain::registerPibBackend ( const std::string &  scheme)
inlinestatic

Register a new PIB backend.

Parameters
schemeName for the registered PIB backend scheme
Note
This interface is implementation detail and may change without notice.

Definition at line 445 of file v2/key-chain.hpp.

template<class TpmType >
void ndn::security::v2::KeyChain::registerTpmBackend ( const std::string &  scheme)
inlinestatic

Register a new TPM backend.

Parameters
schemeName for the registered TPM backend scheme
Note
This interface is implementation detail and may change without notice.

Definition at line 454 of file v2/key-chain.hpp.

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_argumentkey does not match certificate

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

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.

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_argumentkey does not belong to identity

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

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
dataThe data to sign
paramsThe signing parameters.
Exceptions
Errorsigning fails
InvalidSigningInfoErrorinvalid params is specified or specified identity, key, or certificate does not exist
See also
SigningInfo

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

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
interestThe interest to sign
paramsThe signing parameters.
Exceptions
Errorsigning fails
InvalidSigningInfoErrorinvalid params is specified or specified identity, key, or certificate does not exist
See also
SigningInfo
docs/specs/signed-interest.rst

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

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
bufferThe buffer to sign
bufferLengthThe buffer size
paramsThe signing parameters.
Returns
a SignatureValue TLV block
Exceptions
Errorsigning fails
See also
SigningInfo

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