Использование формата 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":"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 для расшифровки полезной нагрузки. Вектор инициализации ДОЛЖЕН быть случайным значением длиной 12 байт (используется семейство шифров AES-GCM, которое требует, чтобы вектор инициализации имел длину 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

• ParallelizationFactor (p) – 1

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

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

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

Этот набор параметров является единственной конфигурацией scrypt, совместимой с функцией формирования ключей на устройствах. Эта функция формирования ключа на устройствах называется "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 Ciphertext) в двоичном объекте BWE.

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