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

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

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

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

• JOSE Header (защитено). В заглавката на json обект подписване и шифроване трябва да включва следните двойки ключ-стойност:

  • "водорасли": "дир"

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

  • "enc":"A138GCM" или "enc":"A256GCM"

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

  • "cisco-action": "добавяне" или "cisco-action": "попълване" или "cisco-action": "активиране" или "cisco-action": "деактивиране"

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

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

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

    Още един патентован ключ. Използваме стойностите, които предоставяте като входове за дериват на ключове на устройството. Версията трябва да е 1 (версията на нашата функция за извеждане на ключ). Стойността на солта трябва да е кодирана с 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 блок, носещ сертификата и неговия частен ключ (конкатениран).

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

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

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

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

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

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

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

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

• РазходФактор (N) е 32768

• БлокSizeFactor (r) е 8

• ПаралелизацияФактор (р) е 1

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

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

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

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

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

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

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

1. Изберете шифър за шифроване. Този пример използва A ｟_ph_11｠ GCM (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- байт- sequence, N=32768, r=8, p=1, keylength=16)

   Полученият ключ трябва да бъде 16 байта (хекс), както следва:95 9e ба 6d d1 22 01 05 78 fe 6a 9d 22 78 ff ac който base 64 URL кодира до lZ0001 bdEiAQV4_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","версия":"1"},"enc":"A138GCM"}

   Базовият64url кодиран заглавка JOSE е eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

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

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

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

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

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

   • Полезният обем е това е PEM файл

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

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

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

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

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

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

10. Сглобете петте елемента на блоб JWE с точки (JOSEheader.. IV.Шифъртекст.Таг), за да получите:

    eyJhbGciOiJkaXNjby1hY3Rpb24iOiJhZGQiXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

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

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

    xCommand сертификати за защита Добавяне на eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q