JSON Web Key (JWK) – это структура данных в формате JSON, представляющая криптографический ключ. Параметры этой структуры представляют свойства ключа, в том числе и значение ключа. Ниже приведена типовая структура ключа, независимо от его типа. Кроме того, в состав структуры JWK могут входить параметры, специфические для конкретных криптографических алгоритмов, использующих ключ.
В состав JWK входят следующие параметры:
<kty>: (обязательный) тип ключа; определены следующие значения:
“EC”: ключ для криптографического алгоритма на базе эллиптической кривой,“oct”: последовательность октетов, используемая для представления симметричного ключа;<use>: (опциональный) предполагаемое использование открытого ключа; определены следующие значения:
“sig” – подпись,“enc” – шифрование;<key_ops>: (опциональный) идентифицирует операции, для которых предполагается использовать ключ; определены следующие значения этого параметра:
“sign” – вычисление цифровой подписи или кода аутентификации сообщений,“verify” – проверка цифровой подписи или кода аутентификации сообщений,“encrypt” – шифрование контента,“decrypt” – расшифрование контента и проверка расшифрованного, если возможно,“wrapKey” – шифрование ключа,“unwrapKey” – расшифрование ключа и проверка расшифрованного, если возможно,“deriveKey” – вычисление производного ключа,“deriveBits” – вычисление производных битов не для использования в качестве ключа;<alg>: (опциональный) идентифицирует криптографический алгоритм, в котором предполагается использование ключа;
<kid>: (опциональный) идентификатор ключа; используется для того, чтобы выбрать нужный ключ в документе JWK Set;
<x5u>: (опциональный) URI, который ссылается на ресурс сертификата формата X.509 или цепочки сертификатов ключа проверки цифровой подписи JWS; данный ресурс должен содержать представление сертификата или цепочки сертификатов в соответствии с [RFC 5280] в PEM кодировании; сертификат ключа проверки цифровой подписи JWS должен быть первым сертификатом; в цепочке сертификатов каждый последующий сертификат должен использоваться для сертификации предыдущего; получатель должен проверить цепочку сертификатов в соответствии с [RFC 5280], считать сертификат или цепочку сертификатов и подпись JWS недействительными в случае отрицательного результата проверки; для получения ресурса должен использоваться HTTP-запрос GET и протокол TLS;
<x5c>: (опциональный) сертификат формата X.509 или цепочка сертификатов проверки цифровой подписи JWS; сертификат или цепочка сертификатов представлены в виде JSON-массива строк значений сертификата; каждая строка массива содержит кодировку Base64 (раздел 4 [RFC 4648], не Base64url кодирование) значения DER-представления сертификата формата X.509; сертификат ключа проверки цифровой подписи JWS должен быть первым сертификатом; в цепочке сертификатов каждый последующий сертификат должен использоваться для сертификации предыдущего; получатель должен проверить цепочку сертификатов в соответствии с [RFC 5280], считать сертификат или цепочку сертификатов и подпись JWS недействительными в случае отрицательного результата проверки;<x5c> в JWK, значение открытого ключа также должно присутствовать в составе JWK и совпадать со значением в сертификате.Одино из следующих представлений отпечаток сертификатов:
<x5t>: (опциональный) отпечаток SHA1 сертификата формата X.509; сертификат или цепочка сертификатов представлены в виде JSON-массива строк значений сертификата; каждая строка массива содержит отпечаток SHA-1 в кодировке base64url DER-представления сертификата формата X.509; сертификат ключа проверки цифровой подписи JWS должен быть первым сертификатом; в цепочке сертификатов каждый последующий сертификат должен использоваться для сертификации предыдущего; получатель должен проверить цепочку сертификатов в соответствии с [RFC 5280], считать сертификат или цепочку сертификатов и подпись JWS недействительными в случае отрицательного результата проверки;
<x5t#S256> (опциональный) отпечаток SHA-256 сертификата формата X.509; сертификат или цепочка сертификатов представлены в виде JSON-массива строк значений сертификата; каждая строка массива содержит отпечаток SHA-256 в кодировке base64url DER-представления сертификата формата X.509; сертификат ключа проверки цифровой подписи JWS должен быть первым сертификатом; в цепочке сертификатов каждый последующий сертификат должен использоваться для сертификации предыдущего; получатель должен проверить цепочку сертификатов в соответствии с [RFC 5280], считать сертификат или цепочку сертификатов и подпись JWS недействительными в случае отрицательного результата проверки;
<x5t#St256>: (опциональный) отпечаток сертификата ключа проверки подписи отправителя; представляет собой Base64url представление 256-битного значения хэш-функции ГОСТ Р 34.112012, вычисленной для DER-кодирования X.509 сертификата Cers ключа проверки цифровой подписи отправителя JWS: <x5t#St256> = BASE64URL(HASH256(DER(Cers)));
В зависимости от типа ключа <kty> в состав структуры JWK включаются также другие специфические параметры.
JSON-структура набора ключей JWK Set состоит из одного параметра <keys>, который является JSON-массивом ключей в формате JWK.
Документ Key Set, на который указывает значение параметра <jwks_uri> документа Discovery сервера авторизации, содержит ключ(и) проверки подписи сервера авторизации. Он также может содержать открытые ключи, для которых вырабатывается общий ключ шифрования запросов к серверу авторизации.
Набор Key Set, на который указывает значение параметра <jwks_uri> метаданных клиента, содержит ключ(и) проверки подписи клиента. Он также может содержать открытые ключи, для которых вырабатывается общий ключ шифрования запросов к клиенту.
Если в наборе Key Set присутствуют как ключи проверки подписи, так и ключи шифрования, в структуре JWK каждого ключа должно быть указано значение параметра
<use>.
Не допускается использование одного и того же ключа как для целей подписи, так и для шифрования.
Общие требования к структурам JWK и JWK Set приведены в [RFC 7517].
Структуры JWK и JWK Set определяются на этапе разработки сервера авторизации и клиента.
Пример документа JSON Web Key Set
{
"keys": [
{
"kid": "0A12E2001ARUUH76GHD567E669AF8A30",
"x5c": [
"MIIGkTCCBXmgAwIBAgIQChLiABqu5otO1Wfmaa+KMDANBgkqhkiG9w0BAQsFADCBhTE..."
],
"use": "sig",
"validFrom": 1641907986,
"validUntil": 1673444586,
"certificateOID": [
"1.2.643.6.57.42.21.3.2.1"
],
"kty": "RSA",
"e": "AQAB",
"n": "uGeu01Jmc_YrURmkos71It1O51H7hVQYIb8Fmk2L3wq9HdAP-BTnKx-isPtE-hugS_ybWnCd6CzTEPCde0rbUev7E5uH07EwD-wcwEazt0lkjdfsefjnsadfgjsdfljkvdfgkhuF4BVHW9Zo36gzcOY2j4M1lHU02p1-JgvV8Q2ce0hWmfSllgD9p5nYCM5qN0jhLCF5XOvWlswbTrX03zPol2uqFbKs4AZbDbAyF12wT_YiKtAw4u-Ptn_64SIymIFxj11THrrCl2ni5i_lM25UAf7sCmIVi7quyj6LaS2pwytsqXGwipKOd3xr981WZ354zPR2dbrDUrNTpgy0giYM5-tFQ"
},
{
"kid": "3148E2001A%rHyuHJGE437B99BAE9F",
"x5c": [
"MIIGkDCCBXigAwIBAgIQMUjiABquzJBIROQ3uZuunzANBgkqhkiG9w0BAQsFADCBhTEg..."
],
"use": "sig",
"validFrom": 1641908033,
"validUntil": 1673444633,
"certificateOID": [
"1.2.643.6.57.42.21.3.3.1"
],
"kty": "RSA",
"e": "AQAB",
"n": "4d01-uLSByfmguCpIhqpG7ETWsefd5kSWYVM_SadYBwomKJz6jEZby3dL0CrEBFnMU3JYTcPHElSJC2DFZ0SKlikfsdfljkdfgdlkldgfd7oSDcZ900KwwAENxm1SUDxK9hJFZsgnWeRSqHu6akAqE9TbYTqxUXpYlvy46hpMWhiAYXB7S;lkpiosdfsaldgjoaiusdfalksfsdfgikoF-RR-7lyC0x94rdZsVrhSeZ-_yA_nX3RP58sxTAO9FqbMIHEWXmO_OQQUUj2oHhwZITUlgcqXe8w"
}
]
}