Благодарим вас за обратную связь.

Как мы используем формат 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 Object Signing and Encryption необходимо включить следующие пары ключ-значение:

  • «alg» :"dir»

    Мы поддерживаем только прямой алгоритм шифрования полезной нагрузки, и вы должны использовать исходный секрет клиента устройства.

  • «конец»: «A128GCM» или «конец»: «A256GCM»

    Мы поддерживаем эти два алгоритма шифрования.

  • «cisco-action»: «добавить» или «cisco-action»: «заполнить» или «cisco-action»: «активировать» или «cisco-action»: «деактивировать»

    Это собственный ключ и четыре значения, которые он может принимать. Мы ввели этот ключ, чтобы сообщить целевому устройству о назначении зашифрованных данных. Значения названы в честь команд xAPI на устройстве, на котором вы используете зашифрованные данные.

    Мы назвали его cisco-action, чтобы предотвратить потенциальные конфликты с будущими расширениями JWE.

  • «cisco-kdf»: {«версия»: «1», «соль»: «URL-адрес в базе 64, закодированный случайным образом, более 4 байтов»}

    Еще один проприетарный ключ. Мы используем предоставленные вами значения в качестве входных данных для получения ключа на устройстве. Версия должна быть равна 1 (версия нашей функции деривации ключей). Значение salt должно представлять собой последовательность в кодировке base64 длиной не менее 4 байт, которую вы должны выбрать случайным образом.

• Зашифрованный ключ JWE. Это поле пусто. Устройство получает его из исходного ClientSecret.

• Вектор инициализации JE. Для расшифровки полезной нагрузки необходимо предоставить вектор инициализации в кодировке base64url. IV ДОЛЖНО быть случайным 12-байтовым значением (мы используем семейство шифров AES-GCM, для которого длина IV должна составлять 12 байт).

• JWE AAD (дополнительные аутентифицированные данные). Это поле следует опустить, так как оно не поддерживается в компактной сериализации.

• JWE Ciphertext: это зашифрованная полезная информация, которую вы хотите сохранить в секрете.

  Полезная нагрузка МОЖЕТ быть пуста. Например, чтобы восстановить секретный ключ клиента, его нужно перезаписать пустым значением.

  Существуют разные типы полезной нагрузки в зависимости от того, что вы пытаетесь сделать на устройстве. Разные команды 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 должен следовать той же процедуре, чтобы получить тот же ключ шифрования/дешифрования из секрета клиента.

Устройства используют шифрование для получения ключей (см. https://en.wikipedia.org/wiki/Scrypt) со следующими параметрами:

• Коэффициент стоимости (N) равен 32768

• Коэффициент размера блока (r) равен 8

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

• Соль — это случайная последовательность длиной не менее 4 байт; вы должны указать ту же самую соль при указании параметра cisco-kdf.

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

• Максимальный объем памяти составляет 64 МБ

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

Проработанный пример

Вот пример, по которому вы можете убедиться, что ваш процесс шифрования JWE работает так же, как и процесс, созданный нами на устройствах.

В качестве примера можно привести добавление на устройство большого двоичного объекта PEM (имитирует добавление сертификата с использованием очень короткой строки вместо полного ключа 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», «версия» :"1"}, "enc» :"A128GCM "}

   Заголовок JOSE в кодировке 64 URL-адресов: eyjhbgcioijkaxiilcjaxnjby1h3rpb24ioijhzgqilcjaxnjby1rzgyionsic2fsdci6ijvlwlrdqva0tv9ziiwidmvyc2lvbii6ijeifswizw5jjjqteyoeddtsj9

   Это будет первый элемент блоба JWE.

6. Второй элемент большого двоичного объекта JWE пуст, поскольку мы не предоставляем ключ шифрования JWE.

7. Третий элемент большого двоичного объекта JWE — это вектор инициализации NlnD3v9Te68tkPwd.

8. Используйте свой инструмент шифрования JWE для создания зашифрованных данных и тегов. В этом примере незашифрованная полезная нагрузка будет поддельным блобом PEM, то есть файлом PEM

   Вам следует использовать следующие параметры шифрования:

   • Полезная нагрузка: это файл PEM

   • Шифр шифрования — AES 128 GCM

   • Заголовок JOSE закодирован в кодировке base64url как дополнительные аутентифицированные данные (AAD)

   Base64url кодирует зашифрованную полезную нагрузку, в результате чего должно получиться значение f5llvuwnfkfmzyco1yjfodhq

   Это четвертый элемент (шифрованный текст JWE) в блоке JWE.

9. Base64url закодирует тег, созданный на шаге 8, в результате чего должно получиться значение pe-wdfwgxffbeo928cfz1q

   Это пятый элемент в блоке JWE.

10. Объедините пять элементов блоба JWE точками (JoseHeader.IV.CipherText.tag), чтобы получить:

    Eyjhbgcioijkaxiilcjaxnjby 1hy3rpb24ioijhzgqilcjjaxnjbjyby1 rzgyionsic2fsdci6ijvldqva0tv9te68tkpwd.f5llwn fkfmzyco1yjfodhq.pe-wdfwgxffbeo928CFZ1Q

11. Если вы получили те же значения в кодировке base64url, которые приведены здесь, используя свои собственные инструменты, вы готовы использовать их для защиты шифрования E2E и подтверждения личности ваших устройств.

12. Этот пример на самом деле не сработает, но в принципе следующим шагом будет использование созданного выше большого двоичного объекта JWE в качестве входных данных для команды на устройстве, добавляющей сертификат:

    Сертификаты безопасности команд Добавьте eyhbgcioijkaxiilcjaxnjby1y3rpb24ioijhzgqilcjjaxnjby1rzgyionsic2fsdci6ijvlrdqva0tv9ziiwidmvyc2lvbii6ijeifswizw5jjjjjaxnjby2fsdci6ijvldqva0tv9te68tkpwd.F5llvuwnfkfmzyco1yjfodhq.pe-wdfwgxffbeo928cfz1q