Authenticated Diffie Hellman Key Exchange
Authenticated Diffie-Hellman uses the Web Crypto API generateKey and deriveKey functions for key exchange. The exchange proceeds as a standard Diffie-Hellman exchange but the key derivation operation requires an additional key as input and returns three keys instead of a single key: an AES-128-CBC session encryption key Kenc, an HMAC-SHA256 session HMAC key Khmac, and an AES-128-KeyWrap wrapping key Kwrap. The only purpose of Kwrap is to serve as the additional key in subsequent key exchanges.
The use of an additional key ensures that only the parties with access to the key bits can derive the session keys, and thus prevents man-in-the-middle attacks that would otherwise be possible with standard Diffie-Hellman. When coupled with the pre-shared keys Kpw or model group keys Kdw wrapping key, this scheme guarantees that key exchange is being performed for the requesting entity and also provides perfect forward secrecy.
The wrapping key Kwrap is used to limit use of a single key for all deriveKey operations in much the same way as the session keys are time-limited to restrict their usage. Use of a previously issued Kwrap instead of Kpw or Kdw is likely to be more efficient as the Kpw and Kdw keys require a higher level of security due to their permanent nature.
The master token entity is expected to persist the derivation key and derive data for use in the next key exchange.
This scheme is identified by the string AUTHENTICATED_DH.
N.B. The Diffie-Hellman public keys and computed shared secret must be converted into a byte array for transport over the wire and for use in the key derivation respectively. The byte array will be the minimum number of bytes required for the two’s complement representation in big-endian byte-order (the most significant byte is first) including at least one sign bit, with exactly one zero byte in the zeroth element. As a result, a shared secret value of zero will be represented by an array of length one containing a single byte with a value of zero. This representation is compatible with the Java BigInteger.toByteArray() function and BigInteger(byte[]) constructor.
keydata = {
"#mandatory" : [ "mechanism", "parametersid", "publickey" ],
"mechanism" : "enum(PSK|MGK|WRAP)",
"parametersid" : "string",
"publickey" : "binary",
"wrapdata" : "binary",
}| Field | Description |
|---|---|
| mechanism | mechanism for wrapping and unwrapping the new wrapping key |
| parametersid | Diffie-Hellman parameters identifier |
| publickey | Diffie-Hellman public key |
| wrapdata | wrapped previous Kwrap |
The PSK and MGK mechanisms indicate the key derivation should use Kpw or Kdw for the additional key. The WRAP mechanism indicates the key derivation should use the previous Kwrap for the additional key; Kwrap will be provided to the responding entity by including the wrap data.
The parameters ID identifies the Diffie-Hellman parameters to use for key generation.
The public key should contain exactly one zero byte in the zeroth element. When creating or upon receipt of key request data this zero byte must be prepended if missing.
When using the WRAP mechanism, the wrap data will be included and is the previously derived Kwrap wrapped using AESWrap with an AES-128-KeyWrap key Kissuer only known by the responding entity (or entities in a trusted services network). The responding entity is capable of unwrapping the wrap data to retrieve the previously issued key Kwrap and therefore does not need to remember all Kwrap keys it has derived.
Although access to Kissuer will not allow a third party access to previously or future generated session keys, it should be sufficiently protected and periodically rotated. Kissuer must not be available to the requesting entity.
See the response wrap data definition below.
keydata =
"#mandatory" : [ "wrapdata", "publickey", "parametersid" ],
"wrapdata" : "binary",
"publickey" : "binary",
"parametersid" : "string",
}| Field | Description |
|---|---|
| wrapdata | Kissuer wrapped new Kwrap |
| publickey | Diffie-Hellman public key |
| parametersid | Diffie-Hellman parameters identifier |
The wrap data contains the new wrapping key Kwrap wrapped using AESWrap with Kissuer only known by the responding entity (or entities in a trusted services network).
The public key should contain exactly one zero byte in the zeroth element. When creating or upon receipt of key response data this zero byte must be prepended if missing.
The parameters ID identifies the Diffie-Hellman parameters to use for key generation. This value should match the value in the key request data.
The key derivation function uses HMAC-SHA384 and SHA-384 to generate the raw keying material. The session encryption key Kenc and session HMAC key Khmac are created directly from the keying material. The session wrapping key Kwrap is derived from Kenc and Khmac using the wrapping key derivation algorithm described in the PSK and MGK entity authentication scheme above.
Since the computed shared secret is a numeric value (typically a BigInteger) it must be converted into a byte array when computing the HMAC-SHA384. To ensure both entities involved in the key exchange derive the same keys, the byte array must also obey the Diffie-Hellman public key encoding rule described above.
Key Derivation Pseudocode
switch (mechanism) { case PSK: Kd = Kpw; break; case MGK: Kd = Kdw; break; case WRAP: Kd = Kwrap; break; } bytes = HMAC-SHA384(SHA384(Kd), shared_secret); Kenc' = bytes[0...15] Khmac' = bytes[16...47] Kwrap' = derive(Kenc', Khmac')
The recognized name for this algorithm is NFLX-DH.
| Operation | Parameters | Result |
|---|---|---|
| generateKey | DhKeyGenParams | KeyPair |
| deriveKey | NflxDhKeyDeriveParams | NflxKeys |
dictionary NflxDhKeyDeriveParams : DhKeyDeriveParams {
// The additional derivation key Kd.
Key kd;
};dictionary NflxKeys {
// The session encryption key.
Key encryptionKey;
// The session HMAC key.
Key hmacKey;
// The wrapping key.
Key wrappingKey;
};The encryption key is an AES-CBC secret key limited to the encrypt and decrypt operations and must have its extractable attribute set to false.
The HMAC key is an HMAC-SHA256 secret key limited to the sign and verify operations and must have its extractable attribute set to false.
The wrapping key is an AES-KeyWrap secret key that is not allowed to be used with any operations and must have its extractable attribute set to false.
The following sequence diagram illustrates a sequence of key exchanges. Only the key request data and key response data is documented.
