docs+security: clarify the SafeBag format specification
Rename CertificateV2 => Certificate and EncryptedKeyBag => EncryptedKey
Change-Id: I47dca47ddd4542b5548061373e469bb386fa20bf
diff --git a/docs/specs/certificate.rst b/docs/specs/certificate.rst
index 9233b75..2808bc8 100644
--- a/docs/specs/certificate.rst
+++ b/docs/specs/certificate.rst
@@ -45,20 +45,20 @@
.. code-block:: abnf
- CertificateV2 = DATA-TYPE TLV-LENGTH
- Name ; /<IdentityName>/KEY/<KeyId>/<IssuerId>/<Version>
- MetaInfo ; ContentType == KEY, FreshnessPeriod required
- CertificateV2Content
- CertificateV2SignatureInfo
- SignatureValue
+ Certificate = DATA-TYPE TLV-LENGTH
+ Name ; /<IdentityName>/KEY/<KeyId>/<IssuerId>/<Version>
+ MetaInfo ; ContentType == KEY, FreshnessPeriod required
+ CertificateContent
+ CertificateSignatureInfo
+ SignatureValue
- CertificateV2Content = CONTENT-TYPE TLV-LENGTH SubjectPublicKeyInfo
+ CertificateContent = CONTENT-TYPE TLV-LENGTH SubjectPublicKeyInfo
- CertificateV2SignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
+ CertificateSignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
SignatureType
KeyLocator
ValidityPeriod
- *CertificateV2Extension
+ *CertificateExtension
Name
@@ -103,8 +103,8 @@
Content
-------
-The ``Content`` element of a certificate contains the actual bits of the public key, formatted
-as a DER-encoded `SubjectPublicKeyInfo <https://tools.ietf.org/html/rfc5280#section-4.1.2.7>`__
+The ``Content`` element of a certificate contains the actual bits of the public key, formatted as
+a DER-encoded `SubjectPublicKeyInfo <https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.7>`__
structure.
SignatureInfo
@@ -176,7 +176,7 @@
.. code-block:: abnf
- CertificateV2Extension = AdditionalDescription
+ CertificateExtension = AdditionalDescription
AdditionalDescription = ADDITIONAL-DESCRIPTION-TYPE TLV-LENGTH
1*DescriptionEntry
diff --git a/docs/specs/safe-bag.rst b/docs/specs/safe-bag.rst
index 6cc6773..04e3c4e 100644
--- a/docs/specs/safe-bag.rst
+++ b/docs/specs/safe-bag.rst
@@ -1,24 +1,24 @@
SafeBag Format for Exported Credentials
=======================================
-Sometimes, one may need to export credentials (e.g., certificate and private key) from
-one machine, and import them into another machine. This requires a secured container for
-sensitive information. We define **SafeBag**, which contains both an NDN certificate
-(:doc:`version 2.0 <certificate>`) and the corresponding private key, which is encrypted
-in `PKCS #8 format <https://tools.ietf.org/html/rfc5208>`_.
+Sometimes it may be necessary to export an identity's credentials (i.e., private key and
+associated certificate) from one machine and import them into another. This requires a
+secure container to carry the sensitive information. We define **SafeBag**, which contains
+an :doc:`NDN certificate </specs/certificate>` and the corresponding private key in encrypted
+form. The private key is formatted as a DER-encoded
+`EncryptedPrivateKeyInfo <https://datatracker.ietf.org/doc/html/rfc5208#section-6>`__
+structure as described in PKCS #8.
-The format of **SafeBag** is defined as:
+The TLV-based format of ``SafeBag`` is defined as follows:
.. code-block:: abnf
SafeBag = SAFE-BAG-TYPE TLV-LENGTH
- CertificateV2
- EncryptedKeyBag
+ Certificate
+ EncryptedKey
- EncryptedKeyBag = ENCRYPTED-KEY-BAG-TYPE TLV-LENGTH
- *OCTET ; private key encrypted in PKCS #8 format
-
-All TLV-TYPE numbers are application specific:
+ EncryptedKey = ENCRYPTED-KEY-TYPE TLV-LENGTH
+ *OCTET ; PKCS #8 EncryptedPrivateKeyInfo
+---------------------------------------------+------------------+-----------------+
| Type | Assigned number | Assigned number |
@@ -26,5 +26,5 @@
+=============================================+==================+=================+
| SafeBag | 128 | 0x80 |
+---------------------------------------------+------------------+-----------------+
-| EncryptedKeyBag | 129 | 0x81 |
+| EncryptedKey | 129 | 0x81 |
+---------------------------------------------+------------------+-----------------+
diff --git a/ndn-cxx/encoding/tlv-security.hpp b/ndn-cxx/encoding/tlv-security.hpp
index c2f170d..3446bd6 100644
--- a/ndn-cxx/encoding/tlv-security.hpp
+++ b/ndn-cxx/encoding/tlv-security.hpp
@@ -28,9 +28,13 @@
namespace tlv {
namespace security {
-enum {
+/**
+ * @brief TLV-TYPE numbers for SafeBag and related elements
+ * @sa <a href="../specs/safe-bag.html">SafeBag Format</a>
+ */
+enum : uint32_t {
SafeBag = 128,
- EncryptedKeyBag = 129
+ EncryptedKey = 129,
};
} // namespace security
diff --git a/ndn-cxx/encoding/tlv.hpp b/ndn-cxx/encoding/tlv.hpp
index c87f2b1..4194c19 100644
--- a/ndn-cxx/encoding/tlv.hpp
+++ b/ndn-cxx/encoding/tlv.hpp
@@ -33,9 +33,10 @@
namespace ndn {
-/** @brief practical limit of network layer packet size
+/**
+ * @brief Practical size limit of a network-layer packet.
*
- * If a packet is longer than this size, library and application MAY drop it.
+ * If a packet is longer than this size, library and application MAY drop it.
*/
const size_t MAX_NDN_PACKET_SIZE = 8800;
@@ -140,9 +141,9 @@
operator<<(std::ostream& os, SignatureTypeValue st);
/** @brief TLV-TYPE numbers for SignatureInfo extensions
- * @sa docs/specs/certificate.rst
+ * @sa <a href="../specs/certificate.html">NDN Certificate Format</a>
*/
-enum {
+enum : uint32_t {
ValidityPeriod = 253,
NotBefore = 254,
NotAfter = 255,
diff --git a/ndn-cxx/security/additional-description.hpp b/ndn-cxx/security/additional-description.hpp
index b58aa8f..ae10987 100644
--- a/ndn-cxx/security/additional-description.hpp
+++ b/ndn-cxx/security/additional-description.hpp
@@ -34,7 +34,7 @@
/**
* @brief Represents an %AdditionalDescription TLV element.
- * @sa docs/specs/certificate.rst
+ * @sa <a href="../specs/certificate.html">NDN Certificate Format</a>
*/
class AdditionalDescription
{
diff --git a/ndn-cxx/security/key-chain.cpp b/ndn-cxx/security/key-chain.cpp
index c6ec639..63a37fb 100644
--- a/ndn-cxx/security/key-chain.cpp
+++ b/ndn-cxx/security/key-chain.cpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2020 Regents of the University of California.
+ * Copyright (c) 2013-2021 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -388,7 +388,7 @@
try {
m_tpm->importPrivateKey(keyName,
- safeBag.getEncryptedKeyBag().data(), safeBag.getEncryptedKeyBag().size(),
+ safeBag.getEncryptedKey().data(), safeBag.getEncryptedKey().size(),
pw, pwLen);
}
catch (const Tpm::Error&) {
diff --git a/ndn-cxx/security/safe-bag.cpp b/ndn-cxx/security/safe-bag.cpp
index af7067c..3502c5d 100644
--- a/ndn-cxx/security/safe-bag.cpp
+++ b/ndn-cxx/security/safe-bag.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-2021 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -40,9 +40,9 @@
}
SafeBag::SafeBag(const Data& certificate,
- const Buffer& encryptedKeyBag)
+ const Buffer& encryptedKey)
: m_certificate(certificate)
- , m_encryptedKeyBag(encryptedKeyBag)
+ , m_encryptedKey(encryptedKey)
{
}
@@ -50,22 +50,20 @@
const uint8_t* encryptedKey,
size_t encryptedKeyLen)
: m_certificate(certificate)
- , m_encryptedKeyBag(encryptedKey, encryptedKeyLen)
+ , m_encryptedKey(encryptedKey, encryptedKeyLen)
{
}
-///////////////////////////////////////////////////// encode & decode
-
template<encoding::Tag TAG>
size_t
SafeBag::wireEncode(EncodingImpl<TAG>& encoder) const
{
size_t totalLength = 0;
- // EncryptedKeyBag
- totalLength += encoder.prependByteArrayBlock(tlv::security::EncryptedKeyBag,
- m_encryptedKeyBag.data(),
- m_encryptedKeyBag.size());
+ // EncryptedKey
+ totalLength += encoder.prependByteArrayBlock(tlv::security::EncryptedKey,
+ m_encryptedKey.data(),
+ m_encryptedKey.size());
// Certificate
totalLength += this->m_certificate.wireEncode(encoder);
@@ -111,13 +109,13 @@
NDN_THROW(tlv::Error("Unexpected TLV structure when decoding Certificate"));
}
- // EncryptedKeyBag
- if (it != m_wire.elements_end() && it->type() == tlv::security::EncryptedKeyBag) {
- m_encryptedKeyBag = Buffer(it->value(), it->value_size());
+ // EncryptedKey
+ if (it != m_wire.elements_end() && it->type() == tlv::security::EncryptedKey) {
+ m_encryptedKey = Buffer(it->value(), it->value_size());
it++;
}
else {
- NDN_THROW(tlv::Error("Unexpected TLV structure when decoding EncryptedKeyBag"));
+ NDN_THROW(tlv::Error("Unexpected TLV structure when decoding EncryptedKey"));
}
// Check if end
diff --git a/ndn-cxx/security/safe-bag.hpp b/ndn-cxx/security/safe-bag.hpp
index 71877d9..acc7813 100644
--- a/ndn-cxx/security/safe-bag.hpp
+++ b/ndn-cxx/security/safe-bag.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-2021 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -27,12 +27,13 @@
#include "ndn-cxx/data.hpp"
#include "ndn-cxx/encoding/block.hpp"
#include "ndn-cxx/encoding/buffer.hpp"
-#include "ndn-cxx/security/security-common.hpp"
namespace ndn {
namespace security {
-/** @brief a secured container for sensitive information(certificate, private key)
+/**
+ * @brief A secured container for sensitive information (certificate, private key)
+ * @sa <a href="../specs/safe-bag.html">SafeBag Format</a>
*/
class SafeBag
{
@@ -49,20 +50,20 @@
SafeBag(const Block& wire);
/**
- * @brief Create a new Safe object with the given certificate and private key
+ * @brief Create a new SafeBag object with the given certificate and private key
*
* @param certificate A reference to the certificate data packet
- * @param encryptedKeyBag A reference to the Buffer of private key in PKCS#8
+ * @param encryptedKey A reference to a Buffer with the private key in PKCS #8 format
*/
SafeBag(const Data& certificate,
- const Buffer& encryptedKeyBag);
+ const Buffer& encryptedKey);
/**
- * @brief Create a new Safe object with the given certificate and private key
+ * @brief Create a new SafeBag object with the given certificate and private key
*
* @param certificate A reference to the certificate data packet
- * @param encryptedKey A reference to the uint8_t* of private key in PKCS#8
- * @param encryptedKeyLen The length of the encryptedKey
+ * @param encryptedKey A pointer to the private key in PKCS #8 format
+ * @param encryptedKeyLen The length of @p encryptedKey
*/
SafeBag(const Data& certificate,
const uint8_t* encryptedKey,
@@ -99,17 +100,17 @@
}
/**
- * @brief Get the private key in PKCS#8 from safe bag
+ * @brief Get the private key in PKCS #8 format from safe bag
*/
const Buffer&
- getEncryptedKeyBag() const
+ getEncryptedKey() const
{
- return m_encryptedKeyBag;
+ return m_encryptedKey;
}
private:
Data m_certificate;
- Buffer m_encryptedKeyBag;
+ Buffer m_encryptedKey;
mutable Block m_wire;
};
diff --git a/ndn-cxx/security/validation-error.hpp b/ndn-cxx/security/validation-error.hpp
index 2f8495e..5c0c3ae 100644
--- a/ndn-cxx/security/validation-error.hpp
+++ b/ndn-cxx/security/validation-error.hpp
@@ -35,8 +35,8 @@
{
public:
/**
- * @brief Known validation error code
- * @sa specs/validation-error-code.rst
+ * @brief Known validation error codes
+ * @sa <a href="../specs/validation-error-code.html">Validation Error Codes</a>
*/
enum Code : uint32_t {
NO_ERROR = 0,
diff --git a/ndn-cxx/security/validity-period.hpp b/ndn-cxx/security/validity-period.hpp
index 115c19e..c36ceec 100644
--- a/ndn-cxx/security/validity-period.hpp
+++ b/ndn-cxx/security/validity-period.hpp
@@ -32,7 +32,7 @@
/**
* @brief Represents a %ValidityPeriod TLV element.
- * @sa docs/specs/certificate.rst
+ * @sa <a href="../specs/certificate.html">NDN Certificate Format</a>
*/
class ValidityPeriod
{
diff --git a/tests/unit/security/safe-bag.t.cpp b/tests/unit/security/safe-bag.t.cpp
index d59cdef..53f28cf 100644
--- a/tests/unit/security/safe-bag.t.cpp
+++ b/tests/unit/security/safe-bag.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-2021 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -115,7 +115,7 @@
0x55, 0xf6, 0x1c, 0x19, 0x0b, 0xef, 0x99, 0x25, 0x1e, 0xdc, 0x78, 0xb3, 0xa7,
0xaa, 0x0d, 0x14, 0x58, 0x30, 0xe5, 0x37, 0x6a, 0x6d, 0xdb, 0x56, 0xac, 0xa3,
0xfc, 0x90, 0x7a, 0xb8, 0x66, 0x9c, 0x0e, 0xf6, 0xb7, 0x64, 0xd1,
- 0x81, 0x08, // EncryptedKeyBag
+ 0x81, 0x08, // EncryptedKey
0x2f, 0xd6, 0xf1, 0x6e, 0x80, 0x6f, 0x10, 0xbe
};
@@ -132,11 +132,11 @@
SafeBag safeBag3(data, buffer);
BOOST_CHECK(safeBag1.getCertificate() == data);
- BOOST_CHECK(safeBag1.getEncryptedKeyBag() == buffer);
+ BOOST_CHECK(safeBag1.getEncryptedKey() == buffer);
BOOST_CHECK(safeBag2.getCertificate() == data);
- BOOST_CHECK(safeBag2.getEncryptedKeyBag() == buffer);
+ BOOST_CHECK(safeBag2.getEncryptedKey() == buffer);
BOOST_CHECK(safeBag3.getCertificate() == data);
- BOOST_CHECK(safeBag3.getEncryptedKeyBag() == buffer);
+ BOOST_CHECK(safeBag3.getEncryptedKey() == buffer);
}
BOOST_AUTO_TEST_CASE(EncoderAndDecoder)
@@ -157,7 +157,7 @@
safeBag2.wireDecode(wireBlock);
// check equal
- Buffer buffer1 = safeBag2.getEncryptedKeyBag();
+ Buffer buffer1 = safeBag2.getEncryptedKey();
Buffer buffer2(ENCRYPTED_KEY_BAG, sizeof(ENCRYPTED_KEY_BAG));
BOOST_CHECK(buffer1 == buffer2);
}
diff --git a/tests/unit/security/transform/signer-filter.t.cpp b/tests/unit/security/transform/signer-filter.t.cpp
index 4f84582..b2145e6 100644
--- a/tests/unit/security/transform/signer-filter.t.cpp
+++ b/tests/unit/security/transform/signer-filter.t.cpp
@@ -134,7 +134,7 @@
BOOST_AUTO_TEST_SUITE(Hmac)
// Test vectors from RFC 4231
-// https://tools.ietf.org/html/rfc4231#section-4
+// https://datatracker.ietf.org/doc/html/rfc4231#section-4
BOOST_AUTO_TEST_CASE(Rfc4231Test1)
{
// Test case 1