FastKey Protocol

FastKey combines a binary protocol over DTLS and a REST API to send keys to key targets. 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:

  • MK: 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

{
  "CETS": "",
  "CHTS": "",
  "CR": "07ad5a5d9745c73e599e2147c7bb471249ed427a209dae6b77a807e898b9e5ec",
  "CTS0": "",
  "LastUsed": "2020-06-10T23:59:58",
  "MK": "8b48f8a3f80ee7bbf26166d20913ce5ff068924d23b79199adc1babc4385c084c9cccc143ffa19963db60e010157fe33",
  "SHTS": "",
  "STS0": "",
  "Type": "1.2",
  "XS": ""
}

The following figure depicts a TLS 1.3 key object

{
 "CETS": "",
 "CHTS": "34110bb15d8fad38f0e2cda16cebe43e5f30cf60066ab04bf6cabf9553b175c6e2d1a3005b1d1c5527d9d1ad9a750679",
 "CR": "01fc0baa6eca082096d69f047e232ed762ba317b1e7392178ca8c2579c73c464",
 "CTS0": "1bfa4c5d2351a746fb4472f5ca0276c81864ac613f994b06570431c1751f3aa88a4a67a66375a403dc9792e913b830b8",
 "LastUsed": "2020-06-11T00:01:43",
 "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 is 0x2. This is the same number returned with the bearer token.
  • Byte 1: Type: indicates what function is requested:
    • 0xC8 (200) = putkey TLS 1.2
    • 0xCB (203) = putkey TLS 1.3 32B key
    • 0xCC (204) = putkey TLS 1.3 48B key
  • 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

Note

If the Byte 0 (version) is 0x1 then the Byte 1 (function) is 0xC0 (putkey). Key length indication was added in version 2.

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.

Tip

Nubeva provides a Python implementation of a DTLS key target and buffer for receiving and storing keys in memory. For details please refer to Key Buffer Example.