Как използваме формата JWE

Този раздел описва как очакваме JWE да бъде създаден като вход към устройствата, така че да можете да създадете свой собствен инструмент за създаване на блобове от вашите сертификати и ключове.

Отнесете се към JSON интернет криптиране (JWE)https://datatracker.ietf.org/doc/html/rfc7516и JSON интернет подпис (JWS)https://datatracker.ietf.org/doc/html/rfc7515.

Ние използваме Компактна сериализация на JSON документ за създаване на JWE блобове. Параметрите, които трябва да включите при създаването на JWE blobs са:

• JOSE Заглавка (защитен). В заглавката за подписване и шифроване на JSON обект ТРЯБВА да включите следните двойки ключ-стойност:

  • "alg":"dir"

    Директният алгоритъм е единственият, който поддържаме за криптиране на полезния товар и трябва да използвате първоначалната клиентска тайна на устройството.

  • "enc":"A128GCM" или "enc":"A256GCM"

    Ние поддържаме тези два алгоритма за криптиране.

  • "cisco-action": "add" или "cisco-action": "populate" или "cisco-action": "activate" или "cisco-action": "deactivate"

    Това е собствен ключ и четири стойности, които може да приеме. Въведохме този ключ, за да сигнализираме за целта на криптираните данни към целевото устройство. Стойностите са наименувани на xAPI командите на устройството, където използвате криптираните данни.

    Нарекохме го cisco-action за смекчаване на потенциални сблъсъци с бъдещи разширения на JWE.

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

    Още един собствен ключ. Ние използваме стойностите, които предоставяте, като входни данни за извличане на ключ на устройството. На version трябва да бъде 1(версията на нашата функция за извличане на ключ). Стойността на salt трябва да бъде base64 URL-кодирана последователност от поне 4 байта, която вие трябва изберете произволно.

• JWE криптиран ключ . Това поле е празно. Устройството го извлича от първоначалното ClientSecret.

• Вектор за инициализация на JWE . Трябва да предоставите base64url кодиран вектор за инициализация за декриптиране на полезния товар. IV ТРЯБВА бъде произволна стойност от 12 байта (използваме семейството на шифри AES-GCM, което изисква IV да е с дължина 12 байта).

• JWE AAD (допълнителни удостоверени данни). Трябва да пропуснете това поле, защото не се поддържа в компактната сериализация.

• Шифрен текст на JWE : Това е криптираният полезен товар, който искате да запазите в тайна.

  Полезният товар МОЖЕ да е празен. Например, за да нулирате тайната на клиента, трябва да я презапишете с празна стойност.

  Има различни видове полезни товари, в зависимост от това какво се опитвате да правите на устройството. Различните xAPI команди очакват различни полезни товари и трябва да посочите целта на полезния товар с cisco-action ключ, както следва:

  • С "cisco-action":"populate" шифротекстът е новият ClientSecret.

  • с " "cisco-action":"add" шифротекстът е PEM blob, носещ сертификата и неговия частен ключ (свързан).

  • с " "cisco-action":"activate" шифротекстът е пръстовият отпечатък (шестнадесетично представяне на sha-1) на сертификата, който активираме за проверка на самоличността на устройството.

  • с " "cisco-action":"deactivate" шифротекстът е пръстовият отпечатък (шестнадесетично представяне на sha-1) на сертификата, който деактивираме, за да не се използва за проверка на самоличността на устройството.

• Маркер за удостоверяване на JWE: Това поле съдържа маркера за удостоверяване, за да се установи целостта на целия JWE компактно сериализиран blob

Как извличаме ключ за шифроване от ClientSecret

След първото попълване на тайната, ние не приемаме или извеждаме тайната като обикновен текст. Това е за предотвратяване на потенциални атаки на речник от някой, който може да получи достъп до устройството.

Софтуерът на устройството използва тайната на клиента като вход за функция за извличане на ключ (kdf) и след това използва извлечения ключ за декриптиране/криптиране на съдържание на устройството.

Това означава за вас, че вашият инструмент за производство на JWE blobs трябва да следва същата процедура, за да извлече същия ключ за криптиране/декриптиране от тайната на клиента.

Устройствата използват scrypt за извличане на ключове (вжhttps://en.wikipedia.org/wiki/Scrypt ), със следните параметри:

• Разходният фактор (N) е 32768

• BlockSizeFactor (r) е 8

• Коефициентът на паралелизация (p) е 1

• Salt е произволна последователност от най-малко 4 байта; трябва да предоставите същото salt при уточняване на cisco-kdf параметър.

• Дължините на ключовете са или 16 байта (ако изберете алгоритъма AES-GCM 128), или 32 байта (ако изберете алгоритъма AES-GCM 256)

• Максималният капацитет на паметта е 64MB

Този набор от параметри е единствената конфигурация на scrypt който е съвместим с функцията за извличане на ключ на устройствата. Този kdf на устройствата се нарича "version":"1", което е единствената версия, взета в момента от cisco-kdf параметър.

Работен пример

Ето пример, който можете да следвате, за да се уверите, че вашият процес на криптиране на JWE работи по същия начин като процеса, който създадохме на устройствата.

Примерният сценарий е добавяне на PEM blob към устройството (имитира добавяне на сертификат, с много кратък низ вместо пълен сертификат + ключ). Тайната на клиента в примера е ossifrage.

1. Изберете шифър за криптиране. Този пример използва A128GCM(AES със 128-битови ключове в режим Galois Counter). Вашият инструмент може да се възползва A256GCM ако предпочитате.

2. Изберете сол (трябва да е произволна последователност от поне 4 байта). Този пример използва (шестнадесетични байтове) E5 E6 53 08 03 F8 33 F6. Base64url кодира последователността за получаване 5eZTCAP4M_Y(премахнете подложката base64).

3. Ето една извадка scrypt извикване, за да създадете ключ за шифроване на съдържанието (cek):

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

   Извлеченият ключ трябва да бъде 16 байта (шестнадесетичен), както следва: 95 9e ba 6d d1 22 01 05 78 fe 6a 9d 22 78 ff ac към който base64url кодира lZ66bdEiAQV4_mqdInj_rA.

4. Изберете произволна последователност от 12 байта, която да използвате като вектор за инициализация. Този пример използва (шестнадесетичен) 34 b3 5d dd 5f 53 7b af 2d 92 95 83 към който base64url кодира NLNd3V9Te68tkpWD.

5. Създайте заглавката JOSE с компактна сериализация (следвайте същия ред на параметри, който използваме тук) и след това го кодирайте base64url:

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

   Заглавката на JOSE, кодирана в base64url, е eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

   Това ще бъде първият елемент от JWE blob.

6. Вторият елемент на JWE blob е празен, защото не предоставяме ключ за шифроване на JWE.

7. Третият елемент на JWE blob е векторът за инициализация NLNd3V9Te68tkpWD.

8. Използвайте вашия инструмент за криптиране на JWE, за да създадете криптиран полезен товар и етикет. За този пример некриптираният полезен товар ще бъде фалшивото PEM петно this is a PEM file

   Параметрите за криптиране, които трябва да използвате, са:

   • Полезният товар е this is a PEM file

   • Шифърът за криптиране е AES 128 GCM

   • Заглавката на JOSE, кодирана в base64url като допълнителни удостоверени данни (AAD)

   Base64url кодира криптирания полезен товар, което трябва да доведе до f5lLVuWNfKfmzYCo1YJfODhQ

   Това е четвъртият елемент (JWE Ciphertext) в JWE blob.

9. Base64url кодира маркера, който сте създали в стъпка 8, което трябва да доведе до PE-wDFWGXFFBeo928cfZ1Q

   Това е петият елемент в JWE blob.

10. Свържете петте елемента на JWE blob с точки (JOSEheader..IV.Ciphertext.Tag), за да получите:

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

11. Ако сте извели същите base64url кодирани стойности, както показваме тук, с помощта на вашите собствени инструменти, вие сте готови да ги използвате, за да защитите E2E криптирането и проверената самоличност на вашите устройства.

12. Този пример всъщност няма да работи, но по принцип следващата ви стъпка би била да използвате JWE blob, който сте създали по-горе, като вход за командата x на устройството, което добавя сертификата:

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