docs: rewrite spec using IETF ABNF
refs #4951
Change-Id: I26cce376cb8ef1e0163675106f11966f5c3b152e
diff --git a/docs/spec.rst b/docs/spec.rst
index 2de5aa1..659cde5 100644
--- a/docs/spec.rst
+++ b/docs/spec.rst
@@ -29,20 +29,20 @@
EncryptedContent
----------------
-The ``EncryptedContent`` element contains encrypted blob, optional Initial Vector (for AES CBC encryption),
+The ``EncryptedContent`` element contains encrypted blob, optional Initialization Vector (for AES CBC encryption),
optional EncryptedPayloadKey, and Name elements.
-::
+.. code-block:: abnf
- EncryptedContent ::= ENCRYPTED-CONTENT-TYPE TLV-LENGTH
- EncryptedPayload
- InitializationVector?
- EncryptedPayloadKey?
- Name?
+ EncryptedContent = ENCRYPTED-CONTENT-TYPE TLV-LENGTH
+ EncryptedPayload
+ [InitializationVector]
+ [EncryptedPayloadKey]
+ [Name]
- EncryptedPayload ::= ENCRYPTED-PAYLOAD-TYPE TLV-LENGTH(=N) BYTE{N}
- InitializationVector ::= INITIALIZATION-VECTOR-TYPE TLV-LENGTH(=N) BYTE{N}
- EncryptedPayloadKey ::= ENCRYPTED-PAYLOAD-KEY-TYPE TLV-LENGTH(=N) BYTE{N}
+ EncryptedPayload = ENCRYPTED-PAYLOAD-TYPE TLV-LENGTH *OCTET
+ InitializationVector = INITIALIZATION-VECTOR-TYPE TLV-LENGTH *OCTET
+ EncryptedPayloadKey = ENCRYPTED-PAYLOAD-KEY-TYPE TLV-LENGTH *OCTET
Access Manager
@@ -56,36 +56,36 @@
KEK is published as a single data packet with name ``/[access-namespace]/NAC/[dataset]/KEK/[key-id]``, following the following format:
-::
+.. code-block:: abnf
- Kek ::= DATA-TYPE TLV-LENGTH
- Name (= /[access-namespace]/NAC/[dataset]/KEK/[key-id])
- MetaInfo (= .ContentType = KEY, .FreshnessPeriod = 1 hour default value)
- KekContent
- SignatureInfo
- SignatureValue
+ Kek = DATA-TYPE TLV-LENGTH
+ Name ; /[access-namespace]/NAC/[dataset]/KEK/[key-id]
+ MetaInfo ; ContentType = KEY, FreshnessPeriod = 1 hour default value
+ KekContent
+ DataSignature
- KekContent ::= CONTENT-TYPE-TLV TLV-LENGTH
- BYTE* (= BER of public key /[access-namespace]/NAC/[dataset]/KEY/[key-id])
+ KekContent = CONTENT-TYPE-TLV TLV-LENGTH
+ *OCTET ; = BER of public key /[access-namespace]/NAC/[dataset]/KEY/[key-id]
Different versions of KDK are published, encrypted by the public key of the individual authorized member, following naming convention: ``/[access-namespace]/NAC/[dataset]/KDK/[key-id]/ENCRYPTED-BY/<authorized-member>/KEY/[member-key-id]``. KDK is published in the following format:
-::
+.. code-block:: abnf
- Kdk ::= DATA-TYPE TLV-LENGTH
- Name (= /[access-namespace]/NAC/[dataset]/KDK/[key-id]/ENCRYPTED-BY/<authorized-member>/KEY/[member-key-id])
- MetaInfo (= .ContentType = BLOB, .FreshnessPeriod = 1 hour default value)
- KdkContent
- SignatureInfo
- SignatureValue
+ Kdk = DATA-TYPE TLV-LENGTH
+ Name ; /[access-namespace]/NAC/[dataset]/KDK/[key-id]/ENCRYPTED-BY/<authorized-member>/KEY/[member-key-id]
+ MetaInfo ; ContentType = BLOB, FreshnessPeriod = 1 hour default value
+ KdkContent
+ DataSignature
- KdkContent ::= CONTENT-TYPE-TLV TLV-LENGTH
- EncryptedContent (=
- .EncryptedPayload = SafeBag with private key /[access-namespace]/NAC/[dataset]/KEY/[key-id]
- .EncryptedPayloadKey = password for SafeBag, encrypted by public key /<authorized-member>/KEY/[member-key-id]
- // .InitializationVector and .Name are not set
- )
+ KdkContent = CONTENT-TYPE-TLV TLV-LENGTH
+ EncryptedContent
+
+Within the ``EncryptedContent`` element,
+
+* ``EncryptedPayload`` contains `SafeBag <https://named-data.net/doc/ndn-cxx/0.7.0/specs/safe-bag.html>`__ of private key ``/[access-namespace]/NAC/[dataset]/KEY/[key-id]``
+* ``EncryptedPayloadKey`` contains password for SafeBag, encrypted by public key ``/<authorized-member>/KEY/[member-key-id]``
+* ``InitializationVector`` and ``Name`` must be omitted
Encryptor
---------
@@ -99,27 +99,29 @@
::
EncryptedPayload = AES CBC encrypted blob
- InitializationVector = Random initial vector for AES CBC encryption
+ InitializationVector = Random initial vector for AES CBC encryption
EncryptedPayloadKey (not set)
- Name = Prefix of ContentKey (CK) data packet [ck-prefix]/CK/[ck-id]
+ Name = Prefix of ContentKey (CK) data packet /[ck-prefix]/CK/[ck-id]
During initialization or when requested by the application, the Encryptor (re-)generates a random key for AES CBC encryption.
The encrypted version of this key is published (asynchronous operation, contingent on successful retrieval and validation of KEK) as a data packet, following the naming convention: ``/[ck-prefix]/CK/[ck-id]/ENCRYPTED-BY/[access-namespace]/NAC/[dataset]/KEK/[key-id]``. CK data is published in the following format:
-::
+.. code-block:: abnf
- CkData ::= DATA-TYPE TLV-LENGTH
- Name (= /[ck-prefix]/CK/[ck-id]/ENCRYPTED-BY/[access-namespace]/NAC/[dataset]/KEK/[key-id])
- MetaInfo (= .ContentType = BLOB, .FreshnessPeriod = 1 hour default value)
- CkContent
- SignatureInfo
- SignatureValue
+ CkData = DATA-TYPE TLV-LENGTH
+ Name ; /[ck-prefix]/CK/[ck-id]/ENCRYPTED-BY/[access-namespace]/NAC/[dataset]/KEK/[key-id]
+ MetaInfo ; ContentType = BLOB, FreshnessPeriod = 1 hour default value
+ CkContent
+ DataSignature
- CkContent ::= CONTENT-TYPE-TLV TLV-LENGTH
- EncryptedContent (=
- .EncryptedPayload = ContentKey encrypted by public key /[access-namespace]/NAC/[dataset]/KEK/[key-id]
- // .InitializationVector, .EncryptedPayloadKey, and .Name are not set
- )
+ CkContent = CONTENT-TYPE-TLV TLV-LENGTH
+ EncryptedContent
+
+Within the ``EncryptedContent`` element,
+
+* ``EncryptedPayload`` contains ContentKey encrypted by public key ``/[access-namespace]/NAC/[dataset]/KEK/[key-id]``
+* ``EncryptedPayloadKey``, ``InitializationVector``, and ``Name`` must be omitted
+
Decryptor
---------
@@ -129,3 +131,19 @@
:align: center
Encryptor decrypts (asynchronous operation, contingent on successful retrieval of CK data, KDK, and decryption of both) the supplied ``EncryptedContent`` element.
+
+TLV-TYPE number assignments
+---------------------------
+
++---------------------------------------------+------------------+-----------------+
+| Type | Assigned number | Assigned number |
+| | (decimal) | (hexadecimal) |
++=============================================+==================+=================+
+| EncryptedContent | 130 | 0x82 |
++---------------------------------------------+------------------+-----------------+
+| EncryptedPayload | 132 | 0x84 |
++---------------------------------------------+------------------+-----------------+
+| InitializationVector | 133 | 0x85 |
++---------------------------------------------+------------------+-----------------+
+| EncryptedPayloadKey | 134 | 0x86 |
++---------------------------------------------+------------------+-----------------+