Comment nous utilisons le format JWE

Cette section décrit comment nous attendons que le JWE soit créé en tant qu’entrée sur les périphériques, afin que vous pouvez créer votre propre outil pour créer les objets de vos certificats et clés.

Reportez-vous à JSON Web Encryption (JWE) https://datatracker.ietf.org/doc/html/rfc7516 et JSON Web Signature (JWS) https://datatracker.ietf.org/doc/html/rfc7515.

Nous utilisons la Sérialisation compacte d'un document JSON pour créer des blobs JWE. Les paramètres que vous devez inclure lors de la création des blobs JWE sont :

• En-tête JOSE (protégé). Dans l’en-tête De signature et chiffrement de l’objet JSON, vous DEVEZ inclure les paires de valeurs de clés suivantes :

  • "alg":"dir"

    L’algorithme direct est le seul que nous ons en charge pour chiffrer la charge utile et vous devez utiliser le secret initial du client du périphérique.

  • "enc":"A128GCM" ou "enc":"A256GCM"

    Nous ons en charge ces deux algorithmes de chiffrement.

  • "cisco-action": "ajouter" ou "cisco-action": "remplir" ou "cisco-action": "activer" ou "cisco-action": "désactiver"

    Il s’agit d’une clé propriétaire et de quatre valeurs qu’elle peut prendre. Nous avons introduit cette clé pour signaler l’objet des données chiffrées au périphérique cible. Les valeurs sont nommées d’après les commandes xAPI sur le périphérique sur lequel vous utilisez les données chiffrées.

    Nous l'avons nommé cisco-action pour atténuer les conflits potentiels avec les futures extensions JWE.

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

    Une autre clé propriétaire. Nous utilisons les valeurs que vous fournissez comme entrées pour le dérision de clés sur le périphérique. La version doit être 1 (la version de notre fonction de dérivation des clés). La valeur de salt doit être une séquence codée en base64 par URL d'au moins 4 octets, que vous devez choisir au hasard.

• Clé chiffrée JWE. Ce champ est vide. L’appareil le dérive du ClientSecret initial.

• Vecteur d'initialisation JWE. Vous devez fournir un vectoriel d’initialisation chiffré de base64url pour déchiffrer la charge utile. L’IV DOIT être une valeur aléatoire à 12 octets (nous utilisons la famille AES-GCM cipher, qui nécessite que l’IV d’être longue de 12 octets).

• JWE AAD (données supplémentaires authentifiées). Vous devez omettre ce champ car il n’est pas pris en charge dans la série compacte.

• Texte de chiffrement JWE : Ceci est la charge utile chiffrée que vous souhaitez secret.

  La charge utile PEUT être vide. Par exemple, pour réinitialiser le secret client, vous devez l'écraser avec une valeur vide.

  Il existe différents types de charges utiles, en fonction de ce que vous essayez de faire sur le périphérique. Différentes commandes xAPI s'attendent à des charges utiles différentes, et vous devez spécifier l'objet de la charge utile avec la touche cisco-action , comme suit :

  • Avec "cisco-action":"populate" , le texte chiffré est le nouveau ClientSecret.

  • Avec ""cisco-action":"add" le texte chiffré est un blob PEM portant le certificat et sa clé privée (concaténée).

  • Avec ""cisco-action":"activate" , le texte chiffré est l'empreinte digitale (représentation hexadécimale de sha-1) du certificat que nous activons pour la vérification de l'identité du périphérique.

  • Avec ""cisco-action":"désactiver" , le texte chiffré est l'empreinte digitale (représentation hexadécimale de sha-1) du certificat que nous désactivons pour la vérification de l'identité du périphérique.

• Balise d’authentification JWE : Ce champ contient la balise d’authentification pour vérifier l’intégrité de l’intégralité de la marque JWE compactée en série

Comment obtenir la clé de chiffrement à partir du ClientSecret

Après la première population de ce secret, nous n’acceptons pas et ne sortieons pas le secret en tant que texte simple. Ceci permet d’empêcher les attaques potentielles du dictionnaire par quelqu’un qui pourrait accéder au périphérique.

Le logiciel du périphérique utilise le secret du client comme entrée à une fonction de dérision de clé (kdf) puis utilise la clé obtenue pour le déchiffrage/chiffrement du contenu sur le périphérique.

Ce que cela signifie pour vous, c’est que votre outil de production JWEobs doit suivre la même procédure pour tirer la même clé de chiffrement/déchiffrement du secret du client.

Les périphériques utilisent scrypt pour le derivation de clés (voir https://en.wikipedia.org/wiki/Scrypt), avec les paramètres suivants :

• Le coût (N) est 32768

• BlockSizeRe (r) est 8

• Parallelization (p) est 1

• Salt est une séquence aléatoire d’au moins 4 octets ; vous devez fournir ce même salt lorsque vous spécifiez le paramètre cisco-kdf .

• Les longueurs des touches sont soit de 16 octets (si vous sélectionnez l’algorithme AES-GCM 128) ou de 32 octets (si vous sélectionnez l’algorithme AES-GCM 256)

• La mémoire maximale est de 64 Mo.

Cet ensemble de paramètres est la seule configuration de chiffrement compatible avec la fonction derivation de clé sur les périphériques. Ce kdf sur les périphériques est appelé "version":"1", qui est la seule version actuellement prise par le paramètre cisco-kdf .

Exemple de travail

Voici un exemple que vous pouvez suivre pour vérifier que votre processus de chiffrement JWE fonctionne de la même façon que le processus que nous avons créé sur les périphériques.

L’exemple de scénario est l’ajout d’unob PEM au périphérique (imite l’ajout d’un certificat, avec une chaîne très courte au lieu d’une touche +cert complet). Le secret client dans l’exemple est ossifrage.

1. Choisissez un chiffrement chiffrement. Cet exemple utilise A128GCM (AES avec des clés 128 bits en mode compteur Galois). Votre outil peut utiliser A256GCM si vous préférez.

2. Choisissez un juin (doit être une suite aléatoire d’au moins 4 octets). Cet exemple utilise (octets hexadécimaux)E5 E6 53 08 03 F8 33 F6. Base64url codent la séquence pour obtenir 5eZTCAP4M_Y (retirez le rembourrage base64).

3. Voici un exemple d'appel scrypt pour créer la clé de chiffrement de contenu (cek) :

   cek=scrypt(password="ossifrage", salt=séquence de 4 octets, N=32768, r=8, p=1, keylength=16)

   La clé obtenue doit être de 16 octets (hex) comme suit :95 9e ba 6d d1 22 01 05 78 fe 6a 9d 22 78 ff ac qui base64url code à lZ66bdEiAQV4_mqdInj_rA.

4. Choisissez une séquence aléatoire de 12 octets à utiliser comme vectoriel d’initialisation. Cet exemple utilise (hex) 34 b3 5d dd 5f 53 7b af 2d 92 95 83 que la base64url code pour NLNd3V9Te68tkpWD.

5. Créez l’en-tête JOSE avec une série compacte (suivez le même ordre de paramètres que celui que nous utilisons ici) puis encodez-le à l’encodage base64url :

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

   L'en-tête JOSE codé à l'url de base64url est eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

   Ce sera le premier élément duob JWEob.

6. Le second élément duob JWE est vide, car nous ne fournissons pas de clé JWE algorithme de chiffrement.

7. Le troisième élément du blob JWE est le vecteur d'initialisation NLNd3V9Te68tkpWD.

8. Utilisez votre outil de chiffrement JWE pour produire une charge utile cryptée et une balise. Dans cet exemple, la charge utile non chiffrée sera le faux blob PEM il s'agit d'un fichier PEM

   Les paramètres de chiffrement que vous devez utiliser sont :

   • La charge utile est un fichier PEM

   • Le chiffrement cipher est AES 128 GCM

   • L’en-tête encodée base64url JOSE en tant que Données authentifiées supplémentaires (AAD)

   Base64url codent la charge utile chiffrée, ce qui devrait entraîner f5lLVuWNfKfmzYCo1YJfODhQ

   Ceci est le quatrième élément (JWE Ciphertext) dans l’objet JWE.

9. Base64url codent la balise que vous avez produite à l'étape 8, ce qui devrait conduire à PE-wDFWGXFFBeo928cfZ1Q

   Ceci est le cinquième élément duob JWE.

10. Concaténer les cinq éléments du jWE blob avec des points (JOSEheader.. IV.Ciphertext.Tag) pour obtenir :

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

11. Si vous avez obtenu les mêmes valeurs encodées base64url que nous le montrons ici, en utilisant vos propres outils, vous êtes prêt à les utiliser pour sécuriser le chiffrement E2E et l’identité vérifiée de vos périphériques.

12. Cet exemple ne fonctionne pas réellement, mais en fait votre prochaine étape serait d’utiliser le but JWE que vous avez créé ci-dessus comme entrée de la comand x sur le périphérique qui ajoute le certificat :

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