Использование формата JWE

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

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

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

• Заголовок JOSE (защищенный). В заголовке "Подпись и шифрование объекта 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, содержащей не менее 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 должен следовать той же процедуре, чтобы получить тот же ключ шифрования/дешифрования из секретного кода клиента.

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

• CostFactor (N) — 32768

• BlockSizeFactor (r) — 8

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

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

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

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

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

Рабочий пример

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

Пример сценария заключается в добавлении двоичного объекта PEM на устройство (имитирует добавление сертификата с очень короткой строкой вместо полного сертификата + ключа). Секретный код клиента в примере: 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"}

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

   Это будет первый элемент двоичного объекта JWE.

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

7. Третьим элементом двоичного объекта JWE является вектор инициализации NLNd3V9Te68tkpWD.

8. Используйте инструмент шифрования JWE для создания зашифрованной полезной нагрузки и тега. В этом примере незашифрованная полезная нагрузка будет поддельным двоичным объектом PEM this is a PEM file

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

   • Полезная нагрузка this is a PEM file

   • Шифр AES 128 GCM

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

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

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

9. В Base64url закодируйте тег, созданный в шаге 8, который должен привести к PE-wDFWGXFFBeo928cfZ1Q

   Это пятый элемент двоичного объекта JWE.

10. Объедините пять элементов двоичного объекта 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