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

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

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

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

• 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" }

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

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

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

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

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

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

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

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

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

• БлокSizeFactor (r) е 8

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

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

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

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

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

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

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

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

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

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

8. Използвайте инструмента си за криптиране на JWE, за да произвеждате криптиран полезен товар и маркер. За този пример нешифрованият полезен товар ще бъде фалшивият PEM blob 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. Сглобете петте елемента на блоб JWE с точки (JOSEheader.. IV.Шифъртекст.Таг), за да получите:

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

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

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

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