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

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

Вижте JSON уеб шифроване (JWE) https://datatracker.ietf.org/doc/html/rfc7516 и JSON уеб подпис (JWS) https://datatracker.ietf.org/doc/html/rfc7515.

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

• JOSE Header (защитено). В заглавката за подписване и шифроване на 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: Това е шифрования полезен обем, който искате да запазите в тайна.

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

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

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

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

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

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

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

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

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

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

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

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

• CostFactor (N) е 32768

• BlockSizeFactor (r) е 8

• ParallelizationFactor (p) е 1

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

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

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

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

Пример за работа

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

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

1. Изберете шифър за шифроване. Този пример използва A128GCM (AES с 128-битови ключове в режим на брояч на Galois). Вашият инструмент може да използва 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"}

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

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

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

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

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

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

   • Полезният обем е this is a PEM file

   • Шифърът за шифроване е AES 128 GCM

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

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

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

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

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

10. Concatenate петте елемента на блока JWE с точки (JOSEheader.. IV.Ciphertext.Tag), за да получите:

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

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

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

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