How we use the JWE format

This section describes how we expect the JWE to be created as input to the devices, so that you can build your own tool to create the blobs from your certificates and keys.

Refer to JSON Web Encryption (JWE) https://datatracker.ietf.org/doc/html/rfc7516 and JSON Web Signature (JWS) https://datatracker.ietf.org/doc/html/rfc7515.

We use the Compact Serialization of a JSON document to create JWE blobs. The parameters you need to include when creating the JWE blobs are:

• JOSE Header (protected). In the JSON Object Signing and Encryption header, you MUST include the following key-value pairs:

  • "alg":"dir"

    The direct algorithm is the only one we support for encrypting the payload, and you must use the device's initial client secret.

  • "enc":"A128GCM" or "enc":"A256GCM"

    We support these two encryption algorithms.

  • "cisco-action": "add" or "cisco-action": "populate" or "cisco-action": "activate" or "cisco-action": "deactivate"

    This is a proprietary key and four values it can take. We introduced this key to signal the purpose of the encrypted data to the target device. The values are named after the xAPI commands on the device where you are using the encrypted data.

    We named it cisco-action to mitigate potential clashes with future JWE extensions.

  • "cisco-kdf": { "version": "1", "salt": "base64URLEncodedRandom4+Bytes" }

    Another proprietary key. We use the values you provide as inputs for key derivation on the device. The version must be 1 (the version of our key derivation function). The value of salt must be a base64 URL-encoded sequence of at least 4 bytes, which you must choose randomly.

• JWE Encrypted Key. This field is empty. The device derives it from the initial ClientSecret.

• JWE Initialization Vector. You must supply a base64url encoded initialization vector for decrypting the payload. The IV MUST be a random 12 byte value (we are using the AES-GCM cipher family, which requires the IV to be 12 bytes long).

• JWE AAD (additional authenticated data). You must omit this field because it is not supported in the Compact Serialization.

• JWE Ciphertext: This is the encrypted payload that you want to keep secret.

  The payload MAY be empty. For example, to reset the client secret, you need to overwrite it with an empty value.

  There are different types of payloads, depending on what you are trying to do on the device. Different xAPI commands expect different payloads, and you must specify the purpose of the payload with the cisco-action key, as follows:

  • With "cisco-action":"populate" the ciphertext is the new ClientSecret.

  • With ""cisco-action":"add" the ciphertext is a PEM blob carrying the certificate and its private key (concatenated).

  • With ""cisco-action":"activate" the ciphertext is the fingerprint (hexadecimal representation of sha-1) of the certificate we are activating for device identitiy verification.

  • With ""cisco-action":"deactivate" the ciphertext is the fingerprint (hexadecimal representation of sha-1) of the certificate we are deactivating from being used for device identity verification.

• JWE authentication tag: This field contains the authentication tag to ascertain the integrity of the entire JWE compactly serialized blob

How we derive the encryption key from the ClientSecret

After the first population of the secret, we do not accept or output the secret as plain text. This is to prevent potential dictionary attacks by someone who could access the device.

The device software uses the client secret as an input to a key derivation function (kdf) and then uses the derived key for content decryption/encryption on the device.

What this means for you is that your tool to produce JWE blobs must follow the same procedure to derive the same encryption/decryption key from the client secret.

The devices use scrypt for key derivation (see https://en.wikipedia.org/wiki/Scrypt), with the following parameters:

• CostFactor (N) is 32768

• BlockSizeFactor (r) is 8

• ParallelizationFactor (p) is 1

• Salt is a random sequence of at least 4 bytes; you must supply this same salt when specifying the cisco-kdf parameter.

• Key lengths are either 16 bytes (if you select the AES-GCM 128 algorithm), or 32 bytes (if you select the AES-GCM 256 algorithm)

• Max memory cap is 64MB

This set of parameters is the only configuration of scrypt that is compatible with the key derivation function on the devices. This kdf on the devices is called "version":"1", which is the only version currently taken by the cisco-kdf parameter.

Worked example

Here is an example that you can follow to verify that your JWE encryption process works the same as the process we created on the devices.

The example scenario is adding a PEM blob to the device (mimics adding a certificate, with a very short string instead of a full cert + key). The client secret in the example is ossifrage.

1. Choose an encryption cipher. This example uses A128GCM (AES with 128-bit keys in the Galois Counter Mode). Your tool could use A256GCM if you prefer.

2. Choose a salt (must be a random sequence of at least 4 bytes). This example uses (hex bytes)E5 E6 53 08 03 F8 33 F6. Base64url encode the sequence to get 5eZTCAP4M_Y (remove the base64 padding).

3. Here is a sample scrypt call to create the content encryption key (cek):

   cek=scrypt(password="ossifrage", salt=4-byte-sequence, N=32768, r=8, p=1, keylength=16)

   The derived key should be 16 bytes (hex) as follows:95 9e ba 6d d1 22 01 05 78 fe 6a 9d 22 78 ff ac which base64url encodes to lZ66bdEiAQV4_mqdInj_rA.

4. Choose a random sequence of 12 bytes to use as an initialization vector. This example uses (hex) 34 b3 5d dd 5f 53 7b af 2d 92 95 83 which base64url encodes to NLNd3V9Te68tkpWD.

5. Create the JOSE header with compact serialization (follow the same order of parameters we use here) and then base64url encode it:

   {"alg":"dir","cisco-action":"add","cisco-kdf":{"salt":"5eZTCAP4M_Y","version":"1"},"enc":"A128GCM"}

   The base64url encoded JOSE header is eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

   This will be the first element of the JWE blob.

6. The second element of the JWE blob is empty, because we are not supplying a JWE encryption key.

7. The third element of the JWE blob is the initialization vector NLNd3V9Te68tkpWD.

8. Use your JWE encryption tool to produce an encrypted payload and tag. For this example, the unencrypted payload is going to be the fake PEM blob this is a PEM file

   The encryption parameters you should use are:

   • Payload is this is a PEM file

   • Encryption cipher is AES 128 GCM

   • The base64url encoded JOSE header as Additional Authenticated Data (AAD)

   Base64url encode the encrypted payload, which should result in f5lLVuWNfKfmzYCo1YJfODhQ

   This is the fourth element (JWE Ciphertext) in the JWE blob.

9. Base64url encode the tag you produced in step 8, which should result in PE-wDFWGXFFBeo928cfZ1Q

   This is the fifth element in the JWE blob.

10. Concatenate the five elements of the JWE blob with dots (JOSEheader..IV.Ciphertext.Tag) to get:

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

11. If you derived the same base64url encoded values as we show here, using your own tools, you are ready to use them to secure the E2E encryption and verified identity of your devices.

12. This example won't actually work, but in principle your next step would be to use the JWE blob you created above as the input to the xcommand on the device that adds the certificate:

    xCommand Security Certificates Add eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q