key-chain.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2024 Regents of the University of California.
 *
 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
 *
 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later version.
 *
 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 *
 * You should have received copies of the GNU General Public License and GNU Lesser
 * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
 * <http://www.gnu.org/licenses/>.
 *
 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
 */
 
#ifndef NDN_CXX_SECURITY_KEY_CHAIN_HPP
#define NDN_CXX_SECURITY_KEY_CHAIN_HPP
 
#include "ndn-cxx/interest.hpp"
#include "ndn-cxx/security/certificate.hpp"
#include "ndn-cxx/security/key-params.hpp"
#include "ndn-cxx/security/pib/pib.hpp"
#include "ndn-cxx/security/safe-bag.hpp"
#include "ndn-cxx/security/signing-info.hpp"
#include "ndn-cxx/security/tpm/tpm.hpp"
 
namespace ndn::security {
 
struct MakeCertificateOptions
{
  name::Component issuerId = Certificate::DEFAULT_ISSUER_ID;
 
  std::optional<uint64_t> version;
 
  time::milliseconds freshnessPeriod = 1_h;
 
  std::optional<ValidityPeriod> validity;
};
 
class KeyChain : noncopyable
{
public:
  class Error : public std::runtime_error
  {
  public:
    using std::runtime_error::runtime_error;
  };
 
  class LocatorMismatchError : public Error
  {
  public:
    using Error::Error;
  };
 
  class InvalidSigningInfoError : public Error
  {
  public:
    using Error::Error;
  };
 
  KeyChain();
 
  KeyChain(const std::string& pibLocator, const std::string& tpmLocator, bool allowReset = false);
 
  ~KeyChain();
 
  const Pib&
  getPib() const noexcept
  {
    return *m_pib;
  }
 
  const Tpm&
  getTpm() const noexcept
  {
    return *m_tpm;
  }
 
  static const KeyParams&
  getDefaultKeyParams();
 
public: // Identity management
  Identity
  createIdentity(const Name& identityName, const KeyParams& params = getDefaultKeyParams());
 
  void
  deleteIdentity(const Identity& identity);
 
  void
  setDefaultIdentity(const Identity& identity);
 
public: // Key management
  Key
  createKey(const Identity& identity, const KeyParams& params = getDefaultKeyParams());
 
  Name
  createHmacKey(const Name& prefix = SigningInfo::getHmacIdentity(),
                const HmacKeyParams& params = HmacKeyParams());
 
  void
  deleteKey(const Identity& identity, const Key& key);
 
  void
  setDefaultKey(const Identity& identity, const Key& key);
 
public: // Certificate management
  void
  addCertificate(const Key& key, const Certificate& cert);
 
  void
  deleteCertificate(const Key& key, const Name& certName);
 
  void
  setDefaultCertificate(const Key& key, const Certificate& cert);
 
public: // signing
  void
  sign(Data& data, const SigningInfo& params = SigningInfo());
 
  void
  sign(Interest& interest, const SigningInfo& params = SigningInfo());
 
  Certificate
  makeCertificate(const pib::Key& publicKey, const SigningInfo& params = SigningInfo(),
                  const MakeCertificateOptions& opts = {});
 
  Certificate
  makeCertificate(const Certificate& certRequest, const SigningInfo& params = SigningInfo(),
                  const MakeCertificateOptions& opts = {});
 
public: // export & import
  shared_ptr<SafeBag>
  exportSafeBag(const Certificate& certificate, const char* pw, size_t pwLen);
 
  void
  importSafeBag(const SafeBag& safeBag, const char* pw, size_t pwLen);
 
  void
  importPrivateKey(const Name& keyName, shared_ptr<transform::PrivateKey> key);
 
public: // PIB & TPM backend registry
  template<class PibBackendType>
  static void
  registerPibBackend(const std::string& scheme)
  {
    getPibFactories().emplace(scheme, [] (const std::string& location) {
      return shared_ptr<pib::PibImpl>(new PibBackendType(location));
    });
  }
 
  template<class TpmBackendType>
  static void
  registerTpmBackend(const std::string& scheme)
  {
    getTpmFactories().emplace(scheme, [] (const std::string& location) {
      return unique_ptr<tpm::BackEnd>(new TpmBackendType(location));
    });
  }
 
private:
  class Locator;
 
  KeyChain(Locator pibLocator, Locator tpmLocator, bool allowReset);
 
  using PibFactories = std::map<std::string, std::function<shared_ptr<pib::PibImpl>(const std::string&)>>;
  using TpmFactories = std::map<std::string, std::function<unique_ptr<tpm::BackEnd>(const std::string&)>>;
 
  static PibFactories&
  getPibFactories();
 
  static TpmFactories&
  getTpmFactories();
 
  static Locator
  parseAndCheckPibLocator(const std::string& pibLocator);
 
  static Locator
  parseAndCheckTpmLocator(const std::string& tpmLocator);
 
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE:
  static const Locator&
  getDefaultPibLocator();
 
  static const Locator&
  getDefaultTpmLocator();
 
#ifdef NDN_CXX_WITH_TESTS
  static void
  resetDefaultLocators();
#endif
 
  static tlv::SignatureTypeValue
  getSignatureType(KeyType keyType, DigestAlgorithm digestAlgorithm);
 
private: // signing
  Certificate
  makeCertificate(const Name& keyName, span<const uint8_t> publicKey, SigningInfo params,
                  const MakeCertificateOptions& opts);
 
  Certificate
  selfSign(Key& key);
 
  std::tuple<Name, SignatureInfo>
  prepareSignatureInfo(const SigningInfo& params);
 
  static std::tuple<Name, SignatureInfo>
  prepareSignatureInfoSha256(const SigningInfo& params);
 
  static std::tuple<Name, SignatureInfo>
  prepareSignatureInfoHmac(const SigningInfo& params, Tpm& tpm);
 
  static std::tuple<Name, SignatureInfo>
  prepareSignatureInfoWithIdentity(const SigningInfo& params, const pib::Identity& identity);
 
  static std::tuple<Name, SignatureInfo>
  prepareSignatureInfoWithKey(const SigningInfo& params, const pib::Key& key,
                              const std::optional<Name>& certName = std::nullopt);
 
  ConstBufferPtr
  sign(const InputBuffers& bufs, const Name& keyName, DigestAlgorithm digestAlgorithm) const;
 
private:
  unique_ptr<Pib> m_pib;
  unique_ptr<Tpm> m_tpm;
 
  static Locator s_defaultPibLocator;
  static Locator s_defaultTpmLocator;
};
 
} // namespace ndn::security
 
namespace ndn {
using security::KeyChain;
} // namespace ndn
 
#define NDN_CXX_KEYCHAIN_REGISTER_PIB_BACKEND(PibType)     \
static class NdnCxxAuto ## PibType ## PibRegistrationClass    \
{                                                             \
public:                                                       \
  NdnCxxAuto ## PibType ## PibRegistrationClass()             \
  {                                                           \
    ::ndn::security::KeyChain::registerPibBackend<PibType>(PibType::getScheme()); \
  }                                                           \
} ndnCxxAuto ## PibType ## PibRegistrationVariable
 
#define NDN_CXX_KEYCHAIN_REGISTER_TPM_BACKEND(TpmType)     \
static class NdnCxxAuto ## TpmType ## TpmRegistrationClass    \
{                                                             \
public:                                                       \
  NdnCxxAuto ## TpmType ## TpmRegistrationClass()             \
  {                                                           \
    ::ndn::security::KeyChain::registerTpmBackend<TpmType>(TpmType::getScheme()); \
  }                                                           \
} ndnCxxAuto ## TpmType ## TpmRegistrationVariable
 
#endif // NDN_CXX_SECURITY_KEY_CHAIN_HPP