key-chain.hpp
Go to the documentation of this file.
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3  * Copyright (c) 2013-2022 Regents of the University of California.
4  *
5  * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
6  *
7  * ndn-cxx library is free software: you can redistribute it and/or modify it under the
8  * terms of the GNU Lesser General Public License as published by the Free Software
9  * Foundation, either version 3 of the License, or (at your option) any later version.
10  *
11  * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
12  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
13  * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
14  *
15  * You should have received copies of the GNU General Public License and GNU Lesser
16  * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
17  * <http://www.gnu.org/licenses/>.
18  *
19  * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
20  */
21 
22 #ifndef NDN_CXX_SECURITY_KEY_CHAIN_HPP
23 #define NDN_CXX_SECURITY_KEY_CHAIN_HPP
24 
25 #include "ndn-cxx/interest.hpp"
32 
33 namespace ndn {
34 namespace security {
35 
40 {
46  name::Component issuerId = Certificate::DEFAULT_ISSUER_ID;
47 
53  optional<uint64_t> version;
54 
64 
73  optional<ValidityPeriod> validity;
74 };
75 
76 inline namespace v2 {
77 
86 class KeyChain : noncopyable
87 {
88 public:
89  class Error : public std::runtime_error
90  {
91  public:
92  using std::runtime_error::runtime_error;
93  };
94 
98  class LocatorMismatchError : public Error
99  {
100  public:
101  using Error::Error;
102  };
103 
108  {
109  public:
110  using Error::Error;
111  };
112 
121  KeyChain();
122 
133  KeyChain(const std::string& pibLocator, const std::string& tpmLocator, bool allowReset = false);
134 
136 
137  const Pib&
138  getPib() const noexcept
139  {
140  return *m_pib;
141  }
142 
143  const Tpm&
144  getTpm() const noexcept
145  {
146  return *m_tpm;
147  }
148 
149  static const KeyParams&
151 
152 public: // Identity management
170  Identity
171  createIdentity(const Name& identityName, const KeyParams& params = getDefaultKeyParams());
172 
178  void
179  deleteIdentity(const Identity& identity);
180 
186  void
187  setDefaultIdentity(const Identity& identity);
188 
189 public: // Key management
202  Key
203  createKey(const Identity& identity, const KeyParams& params = getDefaultKeyParams());
204 
215  Name
217  const HmacKeyParams& params = HmacKeyParams());
218 
227  void
228  deleteKey(const Identity& identity, const Key& key);
229 
237  void
238  setDefaultKey(const Identity& identity, const Key& key);
239 
240 public: // Certificate management
253  void
254  addCertificate(const Key& key, const Certificate& cert);
255 
264  void
265  deleteCertificate(const Key& key, const Name& certName);
266 
276  void
277  setDefaultCertificate(const Key& key, const Certificate& cert);
278 
279 public: // signing
299  void
300  sign(Data& data, const SigningInfo& params = SigningInfo());
301 
328  void
329  sign(Interest& interest, const SigningInfo& params = SigningInfo());
330 
343  makeCertificate(const pib::Key& publicKey, const SigningInfo& params = SigningInfo(),
344  const MakeCertificateOptions& opts = {});
345 
361  makeCertificate(const Certificate& certRequest, const SigningInfo& params = SigningInfo(),
362  const MakeCertificateOptions& opts = {});
363 
364 public: // export & import
374  shared_ptr<SafeBag>
375  exportSafeBag(const Certificate& certificate, const char* pw, size_t pwLen);
376 
392  void
393  importSafeBag(const SafeBag& safeBag, const char* pw, size_t pwLen);
394 
398  void
399  importPrivateKey(const Name& keyName, shared_ptr<transform::PrivateKey> key);
400 
401 public: // PIB & TPM backend registry
406  template<class PibBackendType>
407  static void
408  registerPibBackend(const std::string& scheme)
409  {
410  getPibFactories().emplace(scheme, [] (const std::string& location) {
411  return shared_ptr<pib::PibImpl>(new PibBackendType(location));
412  });
413  }
414 
419  template<class TpmBackendType>
420  static void
421  registerTpmBackend(const std::string& scheme)
422  {
423  getTpmFactories().emplace(scheme, [] (const std::string& location) {
424  return unique_ptr<tpm::BackEnd>(new TpmBackendType(location));
425  });
426  }
427 
428 private:
429  class Locator;
430 
431  KeyChain(Locator pibLocator, Locator tpmLocator, bool allowReset);
432 
433  using PibFactories = std::map<std::string, std::function<shared_ptr<pib::PibImpl>(const std::string&)>>;
434  using TpmFactories = std::map<std::string, std::function<unique_ptr<tpm::BackEnd>(const std::string&)>>;
435 
436  static PibFactories&
437  getPibFactories();
438 
439  static TpmFactories&
440  getTpmFactories();
441 
442  static Locator
443  parseAndCheckPibLocator(const std::string& pibLocator);
444 
445  static Locator
446  parseAndCheckTpmLocator(const std::string& tpmLocator);
447 
449  static const Locator&
450  getDefaultPibLocator();
451 
452  static const Locator&
453  getDefaultTpmLocator();
454 
455 #ifdef NDN_CXX_HAVE_TESTS
456  static void
457  resetDefaultLocators();
458 #endif
459 
464  getSignatureType(KeyType keyType, DigestAlgorithm digestAlgorithm);
465 
466 private: // signing
468  makeCertificate(const Name& keyName, span<const uint8_t> publicKey, SigningInfo params,
469  const MakeCertificateOptions& opts);
470 
477  selfSign(Key& key);
478 
487  std::tuple<Name, SignatureInfo>
488  prepareSignatureInfo(const SigningInfo& params);
489 
490  static std::tuple<Name, SignatureInfo>
491  prepareSignatureInfoSha256(const SigningInfo& params);
492 
493  static std::tuple<Name, SignatureInfo>
494  prepareSignatureInfoHmac(const SigningInfo& params, Tpm& tpm);
495 
496  static std::tuple<Name, SignatureInfo>
497  prepareSignatureInfoWithIdentity(const SigningInfo& params, const pib::Identity& identity);
498 
499  static std::tuple<Name, SignatureInfo>
500  prepareSignatureInfoWithKey(const SigningInfo& params, const pib::Key& key,
501  const optional<Name>& certName = nullopt);
502 
508  sign(const InputBuffers& bufs, const Name& keyName, DigestAlgorithm digestAlgorithm) const;
509 
510 private:
511  unique_ptr<Pib> m_pib;
512  unique_ptr<Tpm> m_tpm;
513 
514  static Locator s_defaultPibLocator;
515  static Locator s_defaultTpmLocator;
516 };
517 
524 #define NDN_CXX_KEYCHAIN_REGISTER_PIB_BACKEND(PibType) \
525 static class NdnCxxAuto ## PibType ## PibRegistrationClass \
526 { \
527 public: \
528  NdnCxxAuto ## PibType ## PibRegistrationClass() \
529  { \
530  ::ndn::security::KeyChain::registerPibBackend<PibType>(PibType::getScheme()); \
531  } \
532 } ndnCxxAuto ## PibType ## PibRegistrationVariable
533 
540 #define NDN_CXX_KEYCHAIN_REGISTER_TPM_BACKEND(TpmType) \
541 static class NdnCxxAuto ## TpmType ## TpmRegistrationClass \
542 { \
543 public: \
544  NdnCxxAuto ## TpmType ## TpmRegistrationClass() \
545  { \
546  ::ndn::security::KeyChain::registerTpmBackend<TpmType>(TpmType::getScheme()); \
547  } \
548 } ndnCxxAuto ## TpmType ## TpmRegistrationVariable
549 
550 } // inline namespace v2
551 } // namespace security
552 
553 using security::KeyChain;
554 
555 } // namespace ndn
556 
557 #endif // NDN_CXX_SECURITY_KEY_CHAIN_HPP
Represents a Data packet.
Definition: data.hpp:39
Represents an Interest packet.
Definition: interest.hpp:50
Base class for key parameters.
Definition: key-params.hpp:36
Represents an absolute name.
Definition: name.hpp:44
SimpleSymmetricKeyParams is a template for symmetric keys with only one parameter: size.
Definition: key-params.hpp:257
Represents a name component.
Signing parameters passed to KeyChain.
static const Name & getHmacIdentity()
A localhost identity to indicate that the signature is generated using an HMAC key.
Frontend handle for an identity in the PIB.
Definition: identity.hpp:50
Frontend handle for a key in the PIB.
Definition: key.hpp:51
Frontend to the Public Information Base.
Definition: pib.hpp:53
TPM front-end class.
Definition: tpm.hpp:66
Represents an NDN certificate.
Definition: certificate.hpp:60
Error indicating that the supplied SigningInfo is invalid.
Definition: key-chain.hpp:108
Error indicating that the supplied TPM locator does not match the locator stored in PIB.
Definition: key-chain.hpp:99
The main interface for signing key management.
Definition: key-chain.hpp:87
void setDefaultIdentity(const Identity &identity)
Set identity as the default identity.
Definition: key-chain.cpp:243
void deleteKey(const Identity &identity, const Key &key)
Delete key from identity.
Definition: key-chain.cpp:274
const Tpm & getTpm() const noexcept
Definition: key-chain.hpp:144
void deleteCertificate(const Key &key, const Name &certName)
Delete a certificate with name certName from key.
Definition: key-chain.cpp:304
Identity createIdentity(const Name &identityName, const KeyParams &params=getDefaultKeyParams())
Create an identity identityName.
Definition: key-chain.cpp:201
Key createKey(const Identity &identity, const KeyParams &params=getDefaultKeyParams())
Create a new key for identity.
Definition: key-chain.cpp:251
void setDefaultCertificate(const Key &key, const Certificate &cert)
Set cert as the default certificate of key.
Definition: key-chain.cpp:312
void deleteIdentity(const Identity &identity)
Delete identity from this KeyChain.
Definition: key-chain.cpp:226
static const KeyParams & getDefaultKeyParams()
Definition: key-chain.cpp:106
void sign(Data &data, const SigningInfo &params=SigningInfo())
Sign a Data packet according to the supplied signing information.
Definition: key-chain.cpp:403
void setDefaultKey(const Identity &identity, const Key &key)
Set key as the default key of identity.
Definition: key-chain.cpp:287
void importSafeBag(const SafeBag &safeBag, const char *pw, size_t pwLen)
Import a certificate and its corresponding private key from a SafeBag.
Definition: key-chain.cpp:336
const Pib & getPib() const noexcept
Definition: key-chain.hpp:138
Name createHmacKey(const Name &prefix=SigningInfo::getHmacIdentity(), const HmacKeyParams &params=HmacKeyParams())
Create a new HMAC key.
Definition: key-chain.cpp:268
Certificate makeCertificate(const pib::Key &publicKey, const SigningInfo &params=SigningInfo(), const MakeCertificateOptions &opts={})
Create and sign a certificate packet.
Definition: key-chain.cpp:449
void importPrivateKey(const Name &keyName, shared_ptr< transform::PrivateKey > key)
Import a private key into the TPM.
Definition: key-chain.cpp:386
void addCertificate(const Key &key, const Certificate &cert)
Add a certificate cert for key.
Definition: key-chain.cpp:296
KeyChain()
Constructor to create KeyChain with default PIB and TPM.
Definition: key-chain.cpp:145
static void registerTpmBackend(const std::string &scheme)
Register a new TPM backend type.
Definition: key-chain.hpp:421
static void registerPibBackend(const std::string &scheme)
Register a new PIB backend type.
Definition: key-chain.hpp:408
shared_ptr< SafeBag > exportSafeBag(const Certificate &certificate, const char *pw, size_t pwLen)
Export a certificate and its corresponding private key.
Definition: key-chain.cpp:320
#define NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE
Definition: common.hpp:48
boost::chrono::milliseconds milliseconds
Definition: time.hpp:48
SignatureTypeValue
SignatureType values.
Definition: tlv.hpp:127
Definition: data.cpp:25
SimpleSymmetricKeyParams< detail::HmacKeyParamsInfo > HmacKeyParams
HmacKeyParams carries parameters for HMAC key.
Definition: key-params.hpp:309
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:139
KeyType
The type of a cryptographic key.
Options to KeyChain::makeCertificate() .
Definition: key-chain.hpp:40
name::Component issuerId
Certificate name IssuerId component.
Definition: key-chain.hpp:46
time::milliseconds freshnessPeriod
Certificate packet FreshnessPeriod.
Definition: key-chain.hpp:63
optional< uint64_t > version
Certificate name version component.
Definition: key-chain.hpp:53
optional< ValidityPeriod > validity
Certificate ValidityPeriod.
Definition: key-chain.hpp:73
InputBuffers bufs