NS-3 based Named Data Networking (NDN) simulator
ndnSIM 2.5: NDN, CCN, CCNx, content centric networks
API Documentation
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 
123  KeyChain();
124 
135  KeyChain(const std::string& pibLocator, const std::string& tpmLocator, bool allowReset = false);
136 
137  ~KeyChain();
138 
139  const Pib&
140  getPib() const noexcept
141  {
142  return *m_pib;
143  }
144 
145  const Tpm&
146  getTpm() const noexcept
147  {
148  return *m_tpm;
149  }
150 
151  static const KeyParams&
152  getDefaultKeyParams();
153 
154 public: // Identity management
172  Identity
173  createIdentity(const Name& identityName, const KeyParams& params = getDefaultKeyParams());
174 
181  void
182  deleteIdentity(const Identity& identity);
183 
188  void
189  setDefaultIdentity(const Identity& identity);
190 
191 public: // Key management
204  Key
205  createKey(const Identity& identity, const KeyParams& params = getDefaultKeyParams());
206 
217  Name
218  createHmacKey(const Name& prefix = SigningInfo::getHmacIdentity(),
219  const HmacKeyParams& params = HmacKeyParams());
220 
229  void
230  deleteKey(const Identity& identity, const Key& key);
231 
239  void
240  setDefaultKey(const Identity& identity, const Key& key);
241 
242 public: // Certificate management
255  void
256  addCertificate(const Key& key, const Certificate& certificate);
257 
266  void
267  deleteCertificate(const Key& key, const Name& certificateName);
268 
278  void
279  setDefaultCertificate(const Key& key, const Certificate& certificate);
280 
281 public: // signing
301  void
302  sign(Data& data, const SigningInfo& params = SigningInfo());
303 
330  void
331  sign(Interest& interest, const SigningInfo& params = SigningInfo());
332 
345  makeCertificate(const pib::Key& publicKey, const SigningInfo& params = SigningInfo(),
346  const MakeCertificateOptions& opts = {});
347 
363  makeCertificate(const Certificate& certRequest, const SigningInfo& params = SigningInfo(),
364  const MakeCertificateOptions& opts = {});
365 
366 public: // export & import
376  shared_ptr<SafeBag>
377  exportSafeBag(const Certificate& certificate, const char* pw, size_t pwLen);
378 
394  void
395  importSafeBag(const SafeBag& safeBag, const char* pw, size_t pwLen);
396 
400  void
401  importPrivateKey(const Name& keyName, shared_ptr<transform::PrivateKey> key);
402 
403 public: // PIB & TPM backend registry
410  template<class PibBackendType>
411  static void
412  registerPibBackend(const std::string& scheme)
413  {
414  getPibFactories().emplace(scheme, [] (const std::string& locator) {
415  return shared_ptr<pib::PibImpl>(new PibBackendType(locator));
416  });
417  }
418 
425  template<class TpmBackendType>
426  static void
427  registerTpmBackend(const std::string& scheme)
428  {
429  getTpmFactories().emplace(scheme, [] (const std::string& locator) {
430  return unique_ptr<tpm::BackEnd>(new TpmBackendType(locator));
431  });
432  }
433 
434 private:
435  using PibFactories = std::map<std::string, std::function<shared_ptr<pib::PibImpl>(const std::string&)>>;
436  using TpmFactories = std::map<std::string, std::function<unique_ptr<tpm::BackEnd>(const std::string&)>>;
437 
438  static PibFactories&
439  getPibFactories();
440 
441  static TpmFactories&
442  getTpmFactories();
443 
444  static std::tuple<std::string/*type*/, std::string/*location*/>
445  parseAndCheckPibLocator(const std::string& pibLocator);
446 
447  static std::tuple<std::string/*type*/, std::string/*location*/>
448  parseAndCheckTpmLocator(const std::string& tpmLocator);
449 
450  static const std::string&
451  getDefaultPibScheme();
452 
453  static const std::string&
454  getDefaultTpmScheme();
455 
459  static unique_ptr<Pib>
460  createPib(const std::string& pibLocator);
461 
465  static unique_ptr<Tpm>
466  createTpm(const std::string& tpmLocator);
467 
469  static const std::string&
470  getDefaultPibLocator();
471 
472  static const std::string&
473  getDefaultTpmLocator();
474 
479  getSignatureType(KeyType keyType, DigestAlgorithm digestAlgorithm);
480 
481 private: // signing
483  makeCertificate(const Name& keyName, span<const uint8_t> publicKey, SigningInfo params,
484  const MakeCertificateOptions& opts);
485 
492  selfSign(Key& key);
493 
502  std::tuple<Name, SignatureInfo>
503  prepareSignatureInfo(const SigningInfo& params);
504 
505  std::tuple<Name, SignatureInfo>
506  prepareSignatureInfoSha256(const SigningInfo& params);
507 
508  std::tuple<Name, SignatureInfo>
509  prepareSignatureInfoHmac(const SigningInfo& params);
510 
511  std::tuple<Name, SignatureInfo>
512  prepareSignatureInfoWithIdentity(const SigningInfo& params, const pib::Identity& identity);
513 
514  std::tuple<Name, SignatureInfo>
515  prepareSignatureInfoWithKey(const SigningInfo& params, const pib::Key& key,
516  optional<Name> certName = nullopt);
517 
523  sign(const InputBuffers& bufs, const Name& keyName, DigestAlgorithm digestAlgorithm) const;
524 
525 private:
526  unique_ptr<Pib> m_pib;
527  unique_ptr<Tpm> m_tpm;
528 
529  static std::string s_defaultPibLocator;
530  static std::string s_defaultTpmLocator;
531 };
532 
541 #define NDN_CXX_KEYCHAIN_REGISTER_PIB_BACKEND(PibType) \
542 static class NdnCxxAuto ## PibType ## PibRegistrationClass \
543 { \
544 public: \
545  NdnCxxAuto ## PibType ## PibRegistrationClass() \
546  { \
547  ::ndn::security::KeyChain::registerPibBackend<PibType>(PibType::getScheme()); \
548  } \
549 } ndnCxxAuto ## PibType ## PibRegistrationVariable
550 
559 #define NDN_CXX_KEYCHAIN_REGISTER_TPM_BACKEND(TpmType) \
560 static class NdnCxxAuto ## TpmType ## TpmRegistrationClass \
561 { \
562 public: \
563  NdnCxxAuto ## TpmType ## TpmRegistrationClass() \
564  { \
565  ::ndn::security::KeyChain::registerTpmBackend<TpmType>(TpmType::getScheme()); \
566  } \
567 } ndnCxxAuto ## TpmType ## TpmRegistrationVariable
568 
569 } // inline namespace v2
570 } // namespace security
571 
572 using security::KeyChain;
573 
574 } // namespace ndn
575 
576 #endif // NDN_CXX_SECURITY_KEY_CHAIN_HPP
Copyright (c) 2011-2015 Regents of the University of California.
static void registerTpmBackend(const std::string &scheme)
Register a new TPM backend.
Definition: key-chain.hpp:427
Represents an NDN certificate following the version 2.0 format.
Definition: certificate.hpp:60
The interface of signing key management.
Definition: key-chain.hpp:86
SimpleSymmetricKeyParams is a template for symmetric keys with only one parameter: size...
Definition: key-params.hpp:256
optional< uint64_t > version
Certificate name version component.
Definition: key-chain.hpp:53
static void registerPibBackend(const std::string &scheme)
Register a new PIB backend.
Definition: key-chain.hpp:412
ndn security KeyChain
Definition: key-chain.cpp:70
const Pib & getPib() const noexcept
Definition: key-chain.hpp:140
Error indicating that the supplied TPM locator does not match the locator stored in PIB...
Definition: key-chain.hpp:98
Represents an Interest packet.
Definition: interest.hpp:48
Signing parameters passed to KeyChain.
TPM front-end class.
Definition: tpm.hpp:65
SimpleSymmetricKeyParams< detail::HmacKeyParamsInfo > HmacKeyParams
HmacKeyParams carries parameters for HMAC key.
Definition: key-params.hpp:309
KeyType
The type of a cryptographic key.
A frontend handle of a key instance.
Definition: key.hpp:49
optional< ValidityPeriod > validity
Certificate ValidityPeriod.
Definition: key-chain.hpp:73
#define NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE
Definition: common.hpp:48
Represents an absolute name.
Definition: name.hpp:41
Error indicating that the supplied SigningInfo is invalid.
Definition: key-chain.hpp:107
SignatureTypeValue
SignatureType values.
Definition: tlv.hpp:132
Options to KeyChain::makeCertificate() .
Definition: key-chain.hpp:39
const Tpm & getTpm() const noexcept
Definition: key-chain.hpp:146
Represents a name component.
A secured container for sensitive information (certificate, private key)
Definition: safe-bag.hpp:38
Base class for key parameters.
Definition: key-params.hpp:35
A frontend handle of an Identity.
Definition: identity.hpp:47
InputBuffers bufs
Represents a Data packet.
Definition: data.hpp:37
time::milliseconds freshnessPeriod
Certificate packet FreshnessPeriod.
Definition: key-chain.hpp:63
name::Component issuerId
Certificate name IssuerId component.
Definition: key-chain.hpp:46
const nullopt_t nullopt((nullopt_t::init()))
static const Name & getHmacIdentity()
A localhost identity to indicate that the signature is generated using an HMAC key.
represents the PIB
Definition: pib.hpp:52
shared_ptr< const Buffer > ConstBufferPtr
Definition: buffer.hpp:139
boost::chrono::milliseconds milliseconds
Definition: time.hpp:48