The interface of signing key management. More...
#include <ndn-cxx/security/key-chain.hpp>
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... | |
Name | createHmacKey (const Name &prefix=SigningInfo::getHmacIdentity(), const HmacKeyParams ¶ms=HmacKeyParams()) |
Create a new HMAC key. More... | |
Identity | createIdentity (const Name &identityName, const KeyParams ¶ms=getDefaultKeyParams()) |
Create an identity identityName . More... | |
Key | createKey (const Identity &identity, const KeyParams ¶ms=getDefaultKeyParams()) |
Create a new key for identity . 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< SafeBag > | exportSafeBag (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 | 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... | |
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 ¶ms=SigningInfo()) |
Sign a Data packet according to the supplied signing information. More... | |
void | sign (Interest &interest, const SigningInfo ¶ms=SigningInfo()) |
Sign an Interest according to the supplied signing information. More... | |
Block | sign (const uint8_t *buffer, size_t bufferLength, const SigningInfo ¶ms=SigningInfo()) |
Sign buffer according to the supplied signing information params . More... | |
Static Public Member Functions | |
static const KeyParams & | getDefaultKeyParams () |
static const SigningInfo & | getDefaultSigningInfo () |
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... | |
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 45 of file key-chain.hpp.
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.
Definition at line 165 of file key-chain.cpp.
ndn::security::v2::KeyChain::KeyChain | ( | const std::string & | pibLocator, |
const std::string & | tpmLocator, | ||
bool | allowReset = false |
||
) |
KeyChain constructor.
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 170 of file key-chain.cpp.
|
default |
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.
key
must be valid. std::invalid_argument | key does not match certificate |
Definition at line 321 of file key-chain.cpp.
Name ndn::security::v2::KeyChain::createHmacKey | ( | const Name & | prefix = SigningInfo::getHmacIdentity() , |
const HmacKeyParams & | params = HmacKeyParams() |
||
) |
Create a new HMAC key.
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 |
The newly created key will be inserted in the TPM. HMAC keys don't have any PIB entries.
Definition at line 286 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
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) |
Definition at line 222 of file key-chain.cpp.
Key ndn::security::v2::KeyChain::createKey | ( | const Identity & | identity, |
const KeyParams & | params = getDefaultKeyParams() |
||
) |
Create a new key for identity
.
identity | Reference to a valid Identity object |
params | Key creation parameters (default: EC key with random key id) |
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 268 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.
key
must be valid. std::invalid_argument | certificateName does not follow certificate naming convention. |
Definition at line 340 of file key-chain.cpp.
void ndn::security::v2::KeyChain::deleteIdentity | ( | const Identity & | identity | ) |
delete identity
.
identity
must be valid. identity
becomes invalid. Definition at line 246 of file key-chain.cpp.
Delete a key key
of identity
.
identity
must be valid. key
must be valid. key
becomes invalid. std::invalid_argument | key does not belong to identity |
Definition at line 292 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.
certificate | The certificate to export. |
pw | The password to secure the private key. |
pwLen | The length of password. |
Error | the certificate or private key does not exist |
Definition at line 361 of file key-chain.cpp.
|
static |
Definition at line 157 of file key-chain.cpp.
|
static |
Definition at line 150 of file key-chain.cpp.
|
inline |
Definition at line 99 of file key-chain.hpp.
|
inline |
Definition at line 105 of file key-chain.hpp.
void ndn::security::v2::KeyChain::importPrivateKey | ( | const Name & | keyName, |
shared_ptr< transform::PrivateKey > | key | ||
) |
Import a private key into the TPM.
Definition at line 439 of file key-chain.cpp.
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.
safeBag | The encoded data to import. |
pw | The password to secure the private key. |
pwLen | The length of password. |
Error | any of following conditions:
|
Definition at line 378 of file key-chain.cpp.
|
inlinestatic |
Register a new PIB backend.
scheme | Name for the registered PIB backend scheme |
Definition at line 463 of file key-chain.hpp.
|
inlinestatic |
Register a new TPM backend.
scheme | Name for the registered TPM backend scheme |
Definition at line 472 of file 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).
key
must be valid. std::invalid_argument | key does not match certificate |
Definition at line 352 of file key-chain.cpp.
void ndn::security::v2::KeyChain::setDefaultIdentity | ( | const Identity & | identity | ) |
Set identity
as the default identity.
identity
must be valid. Definition at line 260 of file key-chain.cpp.
Set key
as the default key of identity
.
identity
must be valid. key
must be valid. std::invalid_argument | key does not belong to identity |
Definition at line 308 of file key-chain.cpp.
void ndn::security::v2::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:
params
as a base, it generates the final SignatureInfo block for data
.data
.data
and adds it as the SignatureValue block of data
.data | The data to sign |
params | The signing parameters |
Error | Signing failed |
InvalidSigningInfoError | Invalid params was specified or the specified identity, key, or certificate does not exist |
Definition at line 456 of file key-chain.cpp.
void ndn::security::v2::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:
params
as a base, it generates the final SignatureInfo block for interest
.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.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.interest | The interest to sign |
params | The signing parameters |
Error | Signing failed |
InvalidSigningInfoError | Invalid params was specified or the specified identity, key, or certificate does not exist |
Definition at line 474 of file key-chain.cpp.
Block ndn::security::v2::KeyChain::sign | ( | const uint8_t * | buffer, |
size_t | bufferLength, | ||
const SigningInfo & | params = SigningInfo() |
||
) |
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.
buffer | The buffer to sign |
bufferLength | The buffer size |
params | The signing parameters |
Error | Signing failed |
Definition at line 501 of file key-chain.cpp.