security: clean up KeyChain and SigningInfo APIs
refs #4804
Change-Id: I55ad2b61f05aec8c75d5f6bafc4eea8e1e1100e9
diff --git a/ndn-cxx/metadata-object.hpp b/ndn-cxx/metadata-object.hpp
index 0403d3e..7946e7f 100644
--- a/ndn-cxx/metadata-object.hpp
+++ b/ndn-cxx/metadata-object.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2019 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -79,7 +79,7 @@
NDN_CXX_NODISCARD Data
makeData(Name discoveryInterestName,
KeyChain& keyChain,
- const ndn::security::SigningInfo& si = KeyChain::getDefaultSigningInfo(),
+ const ndn::security::SigningInfo& si = security::SigningInfo(),
optional<uint64_t> version = nullopt,
time::milliseconds freshnessPeriod = 10_ms) const;
diff --git a/ndn-cxx/prefix-announcement.hpp b/ndn-cxx/prefix-announcement.hpp
index 7f6168f..4ff1291 100644
--- a/ndn-cxx/prefix-announcement.hpp
+++ b/ndn-cxx/prefix-announcement.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2018 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -70,7 +70,7 @@
*/
const Data&
toData(KeyChain& keyChain,
- const ndn::security::SigningInfo& si = KeyChain::getDefaultSigningInfo(),
+ const ndn::security::SigningInfo& si = security::SigningInfo(),
optional<uint64_t> version = nullopt) const;
/** \brief Return announced name.
diff --git a/ndn-cxx/security/command-interest-signer.hpp b/ndn-cxx/security/command-interest-signer.hpp
index ab719ec..f6cb644 100644
--- a/ndn-cxx/security/command-interest-signer.hpp
+++ b/ndn-cxx/security/command-interest-signer.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2018 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -82,7 +82,7 @@
* @sa https://redmine.named-data.net/projects/ndn-cxx/wiki/CommandInterest
*/
Interest
- makeCommandInterest(const Name& name, const SigningInfo& params = KeyChain::getDefaultSigningInfo());
+ makeCommandInterest(const Name& name, const SigningInfo& params = SigningInfo());
private:
KeyChain& m_keyChain;
diff --git a/ndn-cxx/security/signing-info.hpp b/ndn-cxx/security/signing-info.hpp
index 9089429..847978c 100644
--- a/ndn-cxx/security/signing-info.hpp
+++ b/ndn-cxx/security/signing-info.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2019 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -67,15 +67,15 @@
* @brief Constructor.
*
* @param signerType The type of signer
- * @param signerName The name of signer; interpretation differs per signerType
- * @param signatureInfo A semi-prepared SignatureInfo which contains other information except
- * SignatureType and KeyLocator. If SignatureType and KeyLocator are
- * specified, they may be overwritten by KeyChain.
+ * @param signerName The name of the signer; interpretation differs with the type of signer
+ * @param signatureInfo A semi-prepared SignatureInfo that contains all necessary information
+ * except SignatureType and KeyLocator. If SignatureType and/or KeyLocator
+ * is set, they will be overwritten by KeyChain::sign().
*/
explicit
SigningInfo(SignerType signerType = SIGNER_TYPE_NULL,
- const Name& signerName = getEmptyName(),
- const SignatureInfo& signatureInfo = getEmptySignatureInfo());
+ const Name& signerName = Name(),
+ const SignatureInfo& signatureInfo = SignatureInfo());
/**
* @brief Construct from a PIB identity.
@@ -222,7 +222,7 @@
}
/**
- * @brief Set a semi-prepared SignatureInfo;
+ * @brief Set a semi-prepared SignatureInfo
*/
SigningInfo&
setSignatureInfo(const SignatureInfo& signatureInfo);
@@ -237,9 +237,18 @@
}
public:
+ /**
+ * @deprecated Use default constructor for Name
+ */
+ [[deprecated("use default constructor for Name")]]
static const Name&
getEmptyName();
+ /**
+ * @brief Get a SignatureInfo constructed with default values.
+ * @deprecated Use default constructor for SignatureInfo
+ */
+ [[deprecated("use default constructor for SignatureInfo")]]
static const SignatureInfo&
getEmptySignatureInfo();
diff --git a/ndn-cxx/security/v2/key-chain.hpp b/ndn-cxx/security/v2/key-chain.hpp
index 1021e8b..1524a1b 100644
--- a/ndn-cxx/security/v2/key-chain.hpp
+++ b/ndn-cxx/security/v2/key-chain.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2019 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -237,71 +237,69 @@
public: // signing
/**
- * @brief Sign data according to the supplied signing information.
+ * @brief Sign a Data packet according to the supplied signing information
*
- * This method uses the supplied signing information @p 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.
+ * This method uses the supplied signing information in @p params to sign @p data as follows:
+ * - It selects a private key and its associated certificate to sign the packet.
+ * - It generates a KeyLocator based upon the certificate name.
+ * - Using the SignatureInfo in @p params as a base, it generates the final SignatureInfo block
+ * for @p data.
+ * - It adds the generated SignatureInfo block to @p data.
+ * - It generates a signature for @p data and adds it as the SignatureValue block of @p data.
*
* @param data The data to sign
- * @param params The signing parameters.
- * @throw Error signing fails
- * @throw InvalidSigningInfoError invalid @p params is specified or specified identity, key,
+ * @param params The signing parameters
+ * @throw Error Signing failed
+ * @throw InvalidSigningInfoError Invalid @p params was specified or the specified identity, key,
* or certificate does not exist
* @see SigningInfo
+ * @see SignatureInfo
*/
void
- sign(Data& data, const SigningInfo& params = getDefaultSigningInfo());
+ sign(Data& data, const SigningInfo& params = SigningInfo());
/**
- * @brief Sign interest according to the supplied signing information
+ * @brief Sign an Interest according to the supplied signing information
*
- * This method uses the supplied signing information @p 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.
+ * This method uses the supplied signing information in @p params to sign @p interest as follows:
+ * - It selects a private key and its associated certificate to sign the packet.
+ * - It generates a KeyLocator based upon the certificate name.
+ * - Using the SignatureInfo in @p params as a base, it generates the final SignatureInfo block
+ * for @p interest.
+ * - It appends the generated SignatureInfo block to the end of the Name of @p interest.
+ * - It generates a signature for @p interest and appends it to the end of the Name of
+ * @p interest as a SignatureValue block.
*
* @param interest The interest to sign
- * @param params The signing parameters.
- * @throw Error signing fails
- * @throw InvalidSigningInfoError invalid @p params is specified or specified identity, key,
+ * @param params The signing parameters
+ * @throw Error Signing failed
+ * @throw InvalidSigningInfoError Invalid @p params was specified or the specified identity, key,
* or certificate does not exist
* @see SigningInfo
+ * @see SignatureInfo
* @see docs/specs/signed-interest.rst
*/
void
- sign(Interest& interest, const SigningInfo& params = getDefaultSigningInfo());
+ sign(Interest& interest, const SigningInfo& params = SigningInfo());
/**
* @brief Sign buffer according to the supplied signing information @p params
+ * @deprecated Sign Interests and Data directly
*
* If @p params refers to an identity, the method selects the default key of the identity.
* If @p params refers to a key or certificate, the method select the corresponding key.
*
* @param buffer The buffer to sign
* @param bufferLength The buffer size
- * @param params The signing parameters.
- * @return a SignatureValue TLV block
- * @throw Error signing fails
+ * @param params The signing parameters
+ * @return SignatureValue TLV block
+ * @throw Error Signing failed
* @see SigningInfo
+ * @see SignatureInfo
*/
+ [[deprecated("sign Interests and Data directly")]]
Block
- sign(const uint8_t* buffer, size_t bufferLength, const SigningInfo& params = getDefaultSigningInfo());
+ sign(const uint8_t* buffer, size_t bufferLength, const SigningInfo& params = SigningInfo());
public: // export & import
/**
@@ -422,9 +420,9 @@
* @brief Prepare a SignatureInfo TLV according to signing information and return the signing
* key name.
*
- * @param params The signing parameters.
- * @return The signing key name and prepared SignatureInfo.
- * @throw InvalidSigningInfoError when the requested signing method cannot be satisfied.
+ * @param params The signing parameters
+ * @return The signing key name and prepared SignatureInfo
+ * @throw InvalidSigningInfoError The requested signing method cannot be satisfied
*/
std::tuple<Name, SignatureInfo>
prepareSignatureInfo(const SigningInfo& params);
@@ -437,6 +435,10 @@
sign(const uint8_t* buf, size_t size, const Name& keyName, DigestAlgorithm digestAlgorithm) const;
public:
+ /**
+ * @deprecated Use default constructor for SigningInfo
+ */
+ [[deprecated("use default constructor for SigningInfo")]]
static const SigningInfo&
getDefaultSigningInfo();
diff --git a/tests/unit/metadata-object.t.cpp b/tests/unit/metadata-object.t.cpp
index 6074c59..364600e 100644
--- a/tests/unit/metadata-object.t.cpp
+++ b/tests/unit/metadata-object.t.cpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2019 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -62,7 +62,7 @@
// pass metadata version number
const Data data1 = metadata1.makeData(metadataFullName.getPrefix(-2), m_keyChain,
- KeyChain::getDefaultSigningInfo(), metadataVerNo);
+ security::SigningInfo(), metadataVerNo);
BOOST_CHECK_EQUAL(metadata1.getVersionedName(), versionedContentName);
BOOST_CHECK_EQUAL(data1.getName(), metadataFullName);
diff --git a/tests/unit/security/signing-helpers.t.cpp b/tests/unit/security/signing-helpers.t.cpp
index f9a51b2..f4493fe 100644
--- a/tests/unit/security/signing-helpers.t.cpp
+++ b/tests/unit/security/signing-helpers.t.cpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2018 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -60,7 +60,7 @@
{
SigningInfo info = signingWithSha256();
BOOST_CHECK_EQUAL(info.getSignerType(), SigningInfo::SIGNER_TYPE_SHA256);
- BOOST_CHECK_EQUAL(info.getSignerName(), SigningInfo::getEmptyName());
+ BOOST_CHECK_EQUAL(info.getSignerName(), Name());
}
BOOST_AUTO_TEST_SUITE_END() // TestSigningHelpers
diff --git a/tests/unit/security/signing-info.t.cpp b/tests/unit/security/signing-info.t.cpp
index e32d5b1..9b59a13 100644
--- a/tests/unit/security/signing-info.t.cpp
+++ b/tests/unit/security/signing-info.t.cpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2019 Regents of the University of California.
+ * Copyright (c) 2013-2020 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -42,7 +42,7 @@
SigningInfo info;
BOOST_CHECK_EQUAL(info.getSignerType(), SigningInfo::SIGNER_TYPE_NULL);
- BOOST_CHECK_EQUAL(info.getSignerName(), SigningInfo::getEmptyName());
+ BOOST_CHECK_EQUAL(info.getSignerName(), Name());
BOOST_CHECK_EQUAL(info.getDigestAlgorithm(), DigestAlgorithm::SHA256);
const SignatureInfo& sigInfo = info.getSignatureInfo();
@@ -81,12 +81,12 @@
info.setSha256Signing();
BOOST_CHECK_EQUAL(info.getSignerType(), SigningInfo::SIGNER_TYPE_SHA256);
- BOOST_CHECK_EQUAL(info.getSignerName(), SigningInfo::getEmptyName());
+ BOOST_CHECK_EQUAL(info.getSignerName(), Name());
BOOST_CHECK_EQUAL(info.getDigestAlgorithm(), DigestAlgorithm::SHA256);
SigningInfo infoSha(SigningInfo::SIGNER_TYPE_SHA256);
BOOST_CHECK_EQUAL(infoSha.getSignerType(), SigningInfo::SIGNER_TYPE_SHA256);
- BOOST_CHECK_EQUAL(infoSha.getSignerName(), SigningInfo::getEmptyName());
+ BOOST_CHECK_EQUAL(infoSha.getSignerName(), Name());
BOOST_CHECK_EQUAL(infoSha.getDigestAlgorithm(), DigestAlgorithm::SHA256);
std::string encodedKey("QjM3NEEyNkE3MTQ5MDQzN0FBMDI0RTRGQURENUI0OTdGRE"
@@ -111,7 +111,7 @@
BOOST_CHECK_EQUAL(info1.getSignatureInfo(), si);
- SigningInfo info2(SigningInfo::SIGNER_TYPE_NULL, SigningInfo::getEmptyName(), si);
+ SigningInfo info2(SigningInfo::SIGNER_TYPE_NULL, Name(), si);
BOOST_CHECK_EQUAL(info2.getSignatureInfo(), si);
}
@@ -119,7 +119,7 @@
{
SigningInfo infoDefault("");
BOOST_CHECK_EQUAL(infoDefault.getSignerType(), SigningInfo::SIGNER_TYPE_NULL);
- BOOST_CHECK_EQUAL(infoDefault.getSignerName(), SigningInfo::getEmptyName());
+ BOOST_CHECK_EQUAL(infoDefault.getSignerName(), Name());
BOOST_CHECK_EQUAL(infoDefault.getDigestAlgorithm(), DigestAlgorithm::SHA256);
SigningInfo infoId("id:/my-identity");
@@ -145,7 +145,7 @@
SigningInfo infoSha("id:/localhost/identity/digest-sha256");
BOOST_CHECK_EQUAL(infoSha.getSignerType(), SigningInfo::SIGNER_TYPE_SHA256);
- BOOST_CHECK_EQUAL(infoSha.getSignerName(), SigningInfo::getEmptyName());
+ BOOST_CHECK_EQUAL(infoSha.getSignerName(), Name());
BOOST_CHECK_EQUAL(infoSha.getDigestAlgorithm(), DigestAlgorithm::SHA256);
}