From 88b414fb15759341710bc29d110abe09934032d7 Mon Sep 17 00:00:00 2001 From: Dana Morris Date: Mon, 14 Oct 2024 16:51:28 -0400 Subject: [PATCH] minor readme updates (#45) changes nanoTDF to NanoTDF, updates intro text to be cleaner 'read' as it's pulled into docusaurus site --- schema/nanotdf/README.md | 97 +++++++++++++++++++--------------------- 1 file changed, 47 insertions(+), 50 deletions(-) diff --git a/schema/nanotdf/README.md b/schema/nanotdf/README.md index 0f826a9..e063850 100644 --- a/schema/nanotdf/README.md +++ b/schema/nanotdf/README.md @@ -1,25 +1,25 @@ -# nanotdf - a compact binary TDF format +# NanoTDF -This document describes nanotdf version v1. +This document describes NanoTDF version v1, a compact binary data encoding format. ## 1. Problem -The [tdf3] allows for the description of sophisticated encryption processes. -However, the descriptive and sometimes verbose nature of the [tdf3] prevents +The Base TDF allows for the description of sophisticated encryption processes. +However, the descriptive and sometimes verbose nature of the Base TDF prevents it's use in environments with constrained storage or bandwidth requirements. In -order to support these use-cases we have designed the nanotdf as a binary format +order to support these use-cases, NanoTDF has been designed as a binary format with strict constraints and without sacrificing many of the descriptive -capabilities of the [tdf3]. The minimum overhead of this format is less than 200 -bytes. With the nanotdf encryption of very granular information. +capabilities of the Base TDF. The minimum overhead of this format is less than 200 +bytes. ## 2. Background ### 2.1 ECC Encryption/Decryption -All of the encryption methods used in the nanotdf involve Elliptic Curve +All of the encryption methods used in the NanoTDF involve Elliptic Curve Cryptography (ECC). Unlike when using RSA, ECC public/private key pairs are only used to create signatures or to handle key exchange. The ECC property in use -by the nanotdf is the support of a secure key exchange scheme, ECDH. Given +by the NanoTDF is the support of a secure key exchange scheme, ECDH. Given either the recipients private key and the sender's public key or the sender's private key and the recipient public key, the same key can be generated and used securely. The combination of public/private key allows derivation of a @@ -36,31 +36,28 @@ For reference please see the following resources: ## 3. Design -The nanotdf is a binary structure that allows for offline creation of small +NanoTDF is a binary structure that allows for offline creation of small encrypted payloads. Where possible, the design attempts to provide quickly deserializable chunks of data. However, the design is mostly concerned with maintaining the smallest possible size. ### 3.1 Assumptions -The following design assumptions/restrictions were used to create the nanotdf: - * Elliptic Curve Cryptography is used with ECDH + HKDF to derive a key * No Elliptic Curves less than 256-bits are supported * All numbers are big endian ### 3.2 Features -The initial version of the `nanotdf`, was designed to accomodate the following -requirements: +The initial version was designed to accomodate the following requirements: -* Support a single policy -* Support a small payload that can fit within 240 Bytes -* Support offline creation +* A single policy +* A small payload that can fit within 240 Bytes +* Offline creation -### 3.3 nanotdf Structure +### 3.3 Structure -The nanotdf is composed of 3 main sections: the Header, the Payload, and the +NanoTDF is composed of 3 main sections: the Header, the Payload, and the Signature. The following table describes the overall binary structure of the nanotdf. Each section is described in greater detail in the subsequent sections and a high level diagram is present after the table below. @@ -71,14 +68,14 @@ and a high level diagram is present after the table below. | Payload | 14 | 16,777,218 | | Signature (Optional) | 97 | 133 | -The following diagram is the general overview of the nanotdf structure: +The following diagram is the general overview of the NanoTDF structure: ![nanotdf 1.0 diagram](../../diagrams/nanotdf.svg) #### 3.3.1 Header The header section is intended to be sent to a KAS and is used by the KAS to -derive the decryption key that can decrypts the nanotdf's payload. The Header is +derive the decryption key that can decrypts the NanoTDF payload. The Header is structured as follows: | Section | Minimum Length (B) | Maximum Length (B) | @@ -93,7 +90,7 @@ structured as follows: ##### 3.3.1.1 Magic Number + Version The Magic Number + Version is a 3 byte artifact that can be used to aid in the -discovery of a nanotdf. The Magic Number is the first 18 bits of this section. +discovery of a NanoTDF. The Magic Number is the first 18 bits of this section. The remaining 6 bits are used for the version number. The 18 bits of the magic number are (`x`'s represent the space for the version number): @@ -102,8 +99,8 @@ number are (`x`'s represent the space for the version number): ``` However, as part of an easter egg of the design, we have started the version -count at 12, all versions before that should be considered invalid. So the first -version of the nanotdf has a Magic Number + Version value of `L1L` which, +count at 12, all versions before that should be considered invalid. The first +version of the NanoTDF has a Magic Number + Version value of `L1L` which, consequently, is `TDFM` (think TDF mini/micro/etc) when base64 encoded. ##### 3.3.1.2 KAS @@ -123,7 +120,7 @@ Refer to the Resource Locator object's definition in [Section 3.4.1]. This section contains a 1-byte bitfield describing the ECC Params and Policy binding strategy to use. The Policy Binding strategy is either using a 64-bit GMAC (using AES-256-GCM) tag or an ECDSA signature. The signature size depends -on the size of ECC Params used. The nanotdf at this time only supports methods +on the size of ECC Params used. NanoTDF at this time only supports methods that involve Elliptic Curve Cryptography. The fields are structured as follows: | Section | Bit Length | Bit start index | @@ -143,7 +140,7 @@ to `1` an ECDSA signature is used. ###### 3.3.1.3.2 Ephemeral ECC Params Enum This 7-bit length enum describes the possible ECC Parameters to use. By design, -the nanotdf does not allow choosing arbitrary ECC params. The following table +NanoTDF does not allow choosing arbitrary ECC params. The following table describes the valid values and the associated ECC Params. | Value | Params | @@ -160,7 +157,7 @@ describes the valid values and the associated ECC Params. This section contains a 1 byte data structure composed of bitfields that describe the symmetric ciphers for encrypted payloads. This cipher applies to -both the Payload and the Policy of the nanotdf. The fields are as follows: +both the Payload and the Policy of the NanoTDF. The fields are as follows: | Section | Bit Length | Bit start index | |-----------------------|-------------|-----------------| @@ -180,8 +177,8 @@ zero otherwise. [Section 3.3.1.4.2]: #33142-signature-ecc-mode The Signature ECC Mode is used to determine the length of the signature at the -end of a nanotdf. This, in combination with the previous `HAS_SIGNATURE` -section, describe the signature of the nanotdf. The following table +end of a NanoTDF. This, in combination with the previous `HAS_SIGNATURE` +section, describe the signature of the NanoTDF. The following table describes the valid values and the associated ECC Params. | Value | Params | @@ -222,7 +219,7 @@ Encryption Method Section. This section contains an ephemeral public key. #### 3.3.2 Payload -The payload section of the nanotdf contains the ciphertext that is protected by +The payload section of contains the ciphertext that is protected by the policy defined in the Header. The structure of the Payload is as follows: | Section | Minimum Length (B) | Maximum Length (B) | @@ -253,12 +250,12 @@ structure: The IV used for encryption. This value is a byte array containing the IV. This IV must never be reused with the same symmetric key. Also, to support an -extremely compacted version of the `nanotdf` the IV value `00 00 00` is reserved +extremely compact version the IV value `00 00 00` is reserved for use with an encrypted policy. ###### 3.3.2.2.2 Ciphertext -The byte array of the ciphertext that is protected in the `nanotdf`. The +The byte array of the ciphertext that is protected in the NanoTDF. The encryption method used to create or decrypt the ciphertext is defined in the Key Access object in the header. @@ -271,11 +268,12 @@ Method Enum used in the [Symmetric and Payload Config] object in the header. The signature section is an optional section that contains an ECDSA signature used to cryptographically bind the Header and Payload to a creator of the -nanotdf. The key used for signing is the private key of the creator of the -nanotdf. The ECC Params used for the signature are described in [Section 3.3.1.4.2]. The private key used for this signature is distinctly different than +NanoTDF file. The key used for signing is the private key of the creator. +The ECC Params used for the signature are described in [Section 3.3.1.4.2]. +The private key used for this signature is distinctly different than the ephemeral private key. This is a persistent key belonging to an individual, -entity, or device that creates nanotdfs. The signature is used to authenticate -the entire nanotdf and contains both the public key related to the creators +entity, or device. The signature is used to authenticate +the entire NanoTDF and contains both the public key related to the creators private key and the resulting signature. The structure of this section: | Section | Minimum Length (B) | Maximum Length (B) | @@ -293,17 +291,17 @@ the message. This section contains the encoded `r` and `s` values of the ECDSA signature. They are encoded as described in [Section 5.2]. -### 3.4 nanotdf Types +### 3.4 Types This section describes embedded types that are used in multiple places in a -`nanotdf`. +NanoTDF file. #### 3.4.1 Resource Locator [Resource Locator]: #341-resource-locator [Section 3.4.1]: #341-resource-locator -The Resource Locator is a way for the nanotdf to represent references to +The Resource Locator is a way for the NanoTDF to represent references to external resources in as succinct a format as possible. | Section | Minimum Length (B) | Maximum Length (B) | @@ -343,10 +341,10 @@ an erroneous condition._ ###### 3.4.1.1.1 The Shared Resource Directory One special thing to note about the protocol enum is the Shared Directory -version. This actually allows users of a shared directory to have reduced sizes -of their nanotdf. The shared resource directory at this time is still an -experimental part of the nanotdf and is included in the documentation to support -a minor update to the nanotdf in a subsequent specification. +version. This allows users of a shared directory to have reduced sizes +of their NanoTDF. The shared resource directory at this time is still an +experimental part of the NanoTDF specification and is included in the documentation to support +a minor update to the NanoTDF in a subsequent update to the specification. Note is this specification version ( > `opentdf/spec` 4.3.0) the "Shared Resource Directory" flag has moved. @@ -426,8 +424,7 @@ reused. This section allows for an ephemeral key other than the Payload key to encrypt the policy. However, for speed's sake, it is suggested that this only be used if -the nanotdf's encrypted payload is encrypted for a KAS's HSM (formerly called a -CKS). +the file's encrypted payload is encrypted for a KAS's HSM. The structure of this section is as follows: @@ -471,7 +468,7 @@ and payload together and generate the GMAC tag. For key derivation details see [Section 4]: #4-ecc-encryption-key-derivation -Encrypting information with the nanotdf is done by using ECDH to derive a key. +Encrypting information with NanoTDF is done by using ECDH to derive a key. However, once the shared key is derived, we must generate a key of the appropriate size as the ECDH bytes may derive a key with a length longer (or shorter) than the symmetric encryption algorithm expects. To decouple the @@ -481,7 +478,7 @@ Derivation Function with the following parameters: * `size` - Depends on the key size used for symmetric encryption * `hash method` - This should use `SHA256` * `salt` - This is a non-random value tied to the magic number and version - `SHA256(MAGIC_NUMBER + VERSION)`. So for this version of the nanotdf the value + `SHA256(MAGIC_NUMBER + VERSION)`. For this version of NanoTDF the value of the salt is `3de3ca1e50cf62d8b6aba603a96fca6761387a7ac86c3d3afe85ae2d1812edfc` in hex. * `info` - This should be an empty value. @@ -536,7 +533,7 @@ This example that has the following parameters: Gmail._ -#### 6.1.2 nanotdf Creator's DER encoded Private Key (base64) +#### 6.1.2 Creator's DER encoded Private Key (base64) _This is included to allow verification of the example._ @@ -566,7 +563,7 @@ A2ifhGOpE0DjR4R0FPXvZ6YBOrcjayIpxwtxeXTudOts ``` -#### 6.1.5 nanotdf +#### 6.1.5 NanoTDF (Base64) @@ -764,7 +761,7 @@ AjCYWytxXIomlJAExVWshnS/RciKf4FJ1L8Q29zIhzZg ``` -#### 6.2.5 nanotdf +#### 6.2.5 NanoTDF (Base64)