TLS Key Record Formats

Sensors use a REST API to send keys to key depots. The rest API uses a JSON object. The object is a key:value pair, where the key is a ‘client random’ and the value is a set of key fields and a meta-data structure. Meta-data data is not required for decryption.

The structure is the same for TLS 1.2 and TLS 1.3 keys. Fields are populated based on the TLS protocol type. The names of the fields match the NSS key log format specification. The JSON object uses the following abbreviations:

  • MS: master key - this field is populated when the type is “TLS 1.2”

  • CETS: client early traffic secret - TLS 1.3

  • CHTS: client handshake traffic secret - TLS 1.3

  • SHTS: server handshake traffic secret - TLS 1.3

  • CTS0: client traffic secret 0 - TLS 1.3

  • STS0: server traffic secret 0 - TLS 1.3

  • XS: exported secret - TLS 1.3

The figure below depicts a TLS 1.2 key object

{
"07ad5a5d9745c73e599e2147c7bb471249ed427a209dae6b77a807e898b9e5ec": {
  "CETS": "",
  "CHTS": "",
  "CR": "07ad5a5d9745c73e599e2147c7bb471249ed427a209dae6b77a807e898b9e5ec",
  "CTS0": "",
  "LastUsed": "2020-06-10T23:59:58",
  "MD": {
        "command": "curl",
        "hostname": "ip-172-31-5-150.ec2.internal",
        "instance": "i-05f1e99c1cd9e3b28",
        "lib": "osl",
        "pid": 22909
  },
  "MK": "8b48f8a3f80ee7bbf26166d20913ce5ff068924d23b79199adc1babc4385c084c9cccc143ffa19963db60e010157fe33",
  "SHTS": "",
  "STS0": "",
  "Type": "1.2",
  "XS": ""
 }
}

The following figure depicts a TLS 1.3 key object

{
"01fc0baa6eca082096d69f047e232ed762ba317b1e7392178ca8c2579c73c464": {
 "CETS": "",
 "CHTS": "34110bb15d8fad38f0e2cda16cebe43e5f30cf60066ab04bf6cabf9553b175c6e2d1a3005b1d1c5527d9d1ad9a750679",
 "CR": "01fc0baa6eca082096d69f047e232ed762ba317b1e7392178ca8c2579c73c464",
 "CTS0": "1bfa4c5d2351a746fb4472f5ca0276c81864ac613f994b06570431c1751f3aa88a4a67a66375a403dc9792e913b830b8",
 "LastUsed": "2020-06-11T00:01:43",
 "MD": {"command": "curl",
     "hostname": "ip-172-31-5-150.ec2.internal",
     "instance": "i-05f1e99c1cd9e3b28",
     "lib": "osl",
     "pid": 23311},
 "MK": "",
 "SHTS": "a86ae64b0fe1bd9e065125768251fd279089d0e544e2200f2d3df87edc2692d45befce649fac006d0fab153f2365a41a",
 "STS0": "4c84bdae94562490dc2371cf32a48489fe03e89f7c464efae93afdc1df522d774b875ffabf95ce8e35cdf9b89773855a",
 "Type": "1.3",
 "XS": "7dce5eec25e6e48a4f0a6bad9ece783fe7ef208d2508a1112b9a074d000e8cc9425ff2d59ac99b33715c2bdf98547510"
 }
}

Two communication channels are used when sensors send keys to a DTLS key target. A control channel uses a REST API to send keys. A low latency protocol uses DTLS to send a binary representation of key records. The structure of the binary format is the following:

  • Byte 0: Version: a running counter of Nubeva’s low latency protocol version. The current version can be 0x1. This is the same number returned with the bearer token.

  • Byte 1: Type indicates what function is requested. 0xC8 (200) = putkey

  • Bytes 2-3: Protocol Version: 0303 = TLS 1.2, 0304 = TLS 1.3

  • Bytes 4-5: Length: indicates the length of the keys + the length of the bearer token (64 + 32 + 48 + 384 = 528).

  • Bytes 6-69: Bearer-token (64 bytes)

  • Bytes 70-101: Client random (32 bytes)

  • Bytes 102-149: Master key (48 bytes). 0’s if ‘protocol version’ is 0304

  • Bytes 150-213: CETS (client early traffic secret) 0’s if ‘protocol version’ is 0303

  • Bytes 214-277: CHTS (client handshake traffic secret) 0’s if ‘protocol version’ is 0303

  • Bytes 278-341: SHTS (server handshake traffic secret) 0’s if ‘protocol version’ is 0303

  • Bytes 342-405: CTSZ (client traffic secret 0) 0’s if ‘protocol version’ is 0303

  • Bytes 406-469: STSZ (server traffic secret 0) 0’s if ‘protocol version’ is 0303

  • Bytes 470-533: XS (exported secret) 0’s if ‘protocol version’ is 0303

Sample code that shows how to receive REST API and UDP messages for storing keys is available at https://nubevalabs.s3.amazonaws.com/dtlskeydb/dtlskeydb.py. Instructions to run the script are provided in the DTLS Key DB section at the bottom of the previous page.

Note

Since the client random value is used as the unique key for looking up session master keys, it is possible to store the same master key more than once. This assures that TLS session renewals are supported as well.