Благодарим за обратната връзка.

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

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

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

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

• Хедър JOSE (защитен). В заглавката за подписване и криптиране на обекти JSON, трябва да включите следните двойки ключ-стойност:

  • „alg“ :"дир“

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

  • „enc“ :"А128ГСМ“ или „enc“ :"А256ГСМ“

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

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

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

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

  • „cisco-kdf“: {„версия“: „1", „сол“: „Base64URLENcodeDrandom4+байтове“}

    Друг собствен ключ. Използваме стойностите, които предоставяте като входове за извеждане на ключове на устройството. Вер сията трябва да бъде 1 (версията на нашата функция за извеждане на ключове). Стойността на солта трябва да бъде бази64 URL кодирана последователност от поне 4 байта, която трябва да изберете на случаен принцип.

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

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

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

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

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

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

  • С „cisco-action“ :"попълване“ шифровият текст е новият Client Secret.

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

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

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

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

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

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

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

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

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

• Коефициентът на разходите (N) е 32768

• Факторът на блокиране (r) е 8

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

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

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

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

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

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

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

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

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

2. Изберете сол (трябва да бъде случайна последователност от поне 4 байта). Този пример използва (шестостенни байтове) E5 E6 53 08 03 F8 33 F 6. Base64URL кодира последователността, за да получите 5eztcap4 m_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“ :"добавяне“, "cisco-kdf“: {"salt“ :"5EZTCAP4M_Y“, "версия“ :"1"}, "enc“ :"A128GCM "}

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

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

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

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

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

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

   • Полезният товар е, че това е PEM файл

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

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

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

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

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

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

10. Свържете петте елемента на JWE блоб с точки (JoseHeader.. iv.CipherText.tag), за да получите:

    EYJHBGCIOIJKAXIILcJJAxNJbY1HY3rpb24ioijhzgqilcJjaxnJby1rZgyionsic2fSDCI6IJvlwlrdqva0tv9ziiwidmvyc2lvbii6ijeifswizw5jijoiqteyoeddtsj.. 9nlnd3v9te68tkpwd.f5llvUVuUD.f5llvUVu5lVuUD.f5llvUVuUD.f5llvUVuUD.FKFmZyCO1yJFODHQ.PE-WDFWGXFFBEO928CFZ1Q

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

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

    XCommand Сертификати за сигурност Добавяне на EyjHBGCioIJkaXiilCjJAxNjBy1HY3RPB24IOiJhZgQiLcJjaXnjBy1rZgYionsiC2FSDCI6IJvVLwlRdQVA0tv9ziiwidmvyc2lvbii6IJeifswizw5jiJoiqTeYoeddtsJ.. 9nLnd3v9te68pwtkd.tKpWd.F 5LLvUWnFKfmZYCO1yJfodHq.PE-WdfWG xFFBEO928CFz1Q