Skip to content

Commit

Permalink
minor readme updates (#45)
Browse files Browse the repository at this point in the history 
changes nanoTDF to NanoTDF, updates intro text to be cleaner 'read' as it's pulled into docusaurus site
  • Loading branch information
@damorris25
damorris25 authored Oct 14, 2024
1 parent f7b8dd0 commit 88b414f
Showing 1 changed file with 47 additions and 50 deletions.
97 changes: 47 additions & 50 deletions schema/nanotdf/README.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
Expand All @@ -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) |
Expand All @@ -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):

Expand All @@ -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
Expand All @@ -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 |
Expand All @@ -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 |
Expand All @@ -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 |
|-----------------------|-------------|-----------------|
Expand All @@ -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 |
Expand Down Expand Up @@ -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) |
Expand Down Expand Up @@ -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.

Expand All @@ -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) |
Expand All @@ -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) |
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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._

Expand Down Expand Up @@ -566,7 +563,7 @@ A2ifhGOpE0DjR4R0FPXvZ6YBOrcjayIpxwtxeXTudOts
```


#### 6.1.5 nanotdf
#### 6.1.5 NanoTDF

(Base64)

Expand Down Expand Up @@ -764,7 +761,7 @@ AjCYWytxXIomlJAExVWshnS/RciKf4FJ1L8Q29zIhzZg
```


#### 6.2.5 nanotdf
#### 6.2.5 NanoTDF

(Base64)

Expand Down

0 comments on commit 88b414f

Please sign in to comment.