Обробка синхронних/асинхронних відповідей

Всі відповіді асинхронні та синхронні будуть підписані.

Структура відповіді

Усі відповіді сервісу передаються у форматі JWS (JSON Web Signature)

Це гарантує:

• цілісність даних — повідомлення не було змінено під час передачі;

• автентичність джерела — запит дійсно надійшов від авторизованого сервісу.

Повідомлення JWS має вигляд:

<base64Url(header)>.<base64Url(payload)>.<base64Url(signature)>

Кодування Header і Payload

Обидві частини (header, payload) не шифруються, а лише кодуються у формат Base64Url. Тобто, їх можна декодувати для перегляду змісту, але змінювати — ні (це зламає підпис).

Параметр Signature забезпечує гарантію, що навіть якщо хтось змінить одне поле у payload, підпис стане невалідним.

Приклад вигляду закодованих даних:

Закодована частина header

eyJhbGciOiJFUzI1NiIsImtpZCI6IjYwMjE3ZDU2LTJkMzYtNDhlMy1hYmU4LTVjMDBiNDJjYTg4NSJ9

Розкодована частина header

Закодована частина payload

eyJ0eXBlIjoiQUNDT1VOVF8yX0NBUkQiLCJycm4iOiI1MzE3MTU5MzczMDUiLCJwdXJwb3NlIjoi0LfQsCDRgtC-0LLQsNGAIiwiY29pbkFtb3VudCI6MTAsIm1lcmNoYW50SWQiOiIxMzdkOTMwNC0wMzY4LTExZWQtYjkzOS0wMjQyYWMxMjAwMDIiLCJvcGVyYXRpb25JZCI6IjE3NjMwNDY5NjQyODl5R2pEZDJ1RVBrWSIsImVjb21PcGVyYXRpb25JZCI6ImQ1Y2RlYzg0LWNkYzUtNDVjMi1hZmEyLWQ4MWJmZDc5ZmU2MSIsInN0YXR1cyI6IlNVQ0NFU1MiLCJ0cmFuc2FjdGlvblR5cGUiOjQ2LCJtZXJjaGFudFJlcXVlc3RJZCI6IjA0MDIyNjVkLWMwYzYtNDNlYi05NDhlLTAyMzEwYzMzMWEzMyIsInRyYW5zYWN0aW9uQ3VycmVuY3kiOiI5ODAiLCJtZXJjaGFudENvbW1pc3Npb24iOjAsImNyZWF0aW9uRGF0ZVRpbWUiOiIyMDI1LjExLjEzIDE3OjE2OjA0LjIyNyIsIm1vZGlmaWNhdGlvbkRhdGVUaW1lIjoiMjAyNS4xMS4xMyAxNzoxNjowNC4yMjciLCJ0cmFuc2FjdGlvblJlc3BvbnNlSW5mbyI6eyJhY3Rpb25Db2RlIjoiMCIsInJlc3BvbnNlQ29kZSI6IjAwIiwiZGVzY3JpcHRpb24iOiLQntC_0LXRgNCw0YbRltGPINGD0YHQv9GW0YjQvdCwIn0sInByb2R1Y3RUeXBlIjoiQTJDIiwibm90aWZpY2F0aW9uVXJsIjoiaHR0cHM6Ly93ZWJob29rLnNpdGUvNDExNjM0ZjQtNmMxNy00ODYyLTg4NTYtZDA2NGY3ZjIxMzVhIiwicGF5bWVudFNlcnZpY2VUeXBlIjoiQ0FSRCIsIm5vdGlmaWNhdGlvbkVuY3J5cHRpb24iOmZhbHNlLCJub3RpZmljYXRpb25TaWduYXR1cmUiOnRydWUsInByb2Nlc3NpbmdUZXJtaW5hbElkIjoiQUUwMDEwMDQiLCJwcm9jZXNzaW5nTWVyY2hhbnRJZCI6IkFFMDAxMDA0IiwiY3JlYXRvclN5c3RlbSI6IkgySCIsImJhbGFuY2VBbW91bnRBZnRlciI6OTkwMTAxOTY5NDQ5MTMsInNlbmRlckN1c3RvbWVySWQiOiIwMDAwMDAiLCJzZW5kZXJGaXJzdE5hbWUiOiJzZW5kZXJGaXJzdE5zZW5kZXJGaXJzdE5hbWVzZW4iLCJzZW5kZXJMYXN0TmFtZSI6InNlbmRlckxhc3ROYW1lc2VuZGVyTGFzdE5hbWVzZSIsInNlbmRlck1pZGRsZU5hbWUiOiJzZW5kZXJNaWRkbGVOYW1lc2VuZGVyTWlkZGxlTmEiLCJzZW5kZXJDb3VudHJ5IjoiODA0Iiwic2VuZGVyUmVnaW9uIjoic2VuZGVyX3JlZ2lvbiIsInNlbmRlckNpdHkiOiJzZW5kZXJfY2l0eSIsInNlbmRlclN0cmVldCI6InNlbmRlcl9zdHJlZXQiLCJzZW5kZXJBZGRpdGlvbmFsQWRkcmVzcyI6Ik4gNiIsInNlbmRlckl0biI6IjEyMzQ1Iiwic2VuZGVyUGFzc3BvcnQiOiIxMjM0NSIsInNlbmRlcklwIjoiMTY1LjIyMi44Ny4yMjQiLCJzZW5kZXJQaG9uZSI6IjM4MDk2NzU0MjM0NCIsInNlbmRlckJpcnRoZGF5IjoiMTIxMjIwMDAiLCJzZW5kZXJHZW5kZXIiOiJNYWxlIiwic2VuZGVyWmlwQ29kZSI6IjEyMzQ1IiwicmVjaXBpZW50Q3VzdG9tZXJJZCI6IjEyMzQ1NjciLCJyZWNpcGllbnRGaXJzdE5hbWUiOiJyZWNpcGllbnRGaXJzdE5yZWNpcGllbnRGaXJzdE4iLCJyZWNpcGllbnRMYXN0TmFtZSI6InJlY2lwaWVudExhc3N0TnJlY2lwaWVudExhc3N0TiIsInJlY2lwaWVudE1pZGRsZU5hbWUiOiJyZWNpcGllbnRNaWRkbGVOYW1lcmVjaXBpZW50TWkiLCJyZWNpcGllbnRFbWFpbCI6InLRhNGEQGdtYWlsLmNvbSIsInJlY2lwaWVudENvdW50cnkiOiI4MDQiLCJyZWNpcGllbnRSZWdpb24iOiJyZXNfcmVnIiwicmVjaXBpZW50Q2l0eSI6InJlc19kbmlwcm8iLCJyZWNpcGllbnRTdHJlZXQiOiJyZXNfc3RyZWV0IiwicmVjaXBpZW50QWRkaXRpb25hbEFkZHJlc3MiOiJyZXNfYWRkcmVzIiwicmVjaXBpZW50SXRuIjoiMTIzNDU2Nzg5MCIsInJlY2lwaWVudFBhc3Nwb3J0IjoicmVzX3Bhc3BvcnQiLCJyZWNpcGllbnRJcCI6IjE2NS4yMjIuODcuMjI0IiwicmVjaXBpZW50UGhvbmUiOiIzODA5Njc1NDIzNDQiLCJyZWNpcGllbnRCaXJ0aGRheSI6IjEyMTIyMDAwIiwicmVjaXBpZW50R2VuZGVyIjoiRmVtYWxlIiwicmVjaXBpZW50WmlwQ29kZSI6Ijc3Nzc3In0

Розкодована частина payload

Перевірка підпису

Параметр kid (Key ID) у JWS Header визначає, який саме публічний ключ слід використовувати для перевірки підпису.

У разі, якщо ключова пара оновлюється, сервер формує відповіді з новим kid. Клієнт має:

1. Отримати новий kid з header JWS;

2. Виконати запит на /ecom/keys/public_key/get_v1 для отримання відповідного публічного ключа;

3. Використати цей ключ для перевірки підпису наступних повідомлень.

Для перевірки підпису, потрібно розкодувати частину header де буде знаходитись параметр kid .

Отримати публічний ключ за kid

post

Повертає публічний ключ (JWK) для вказаного kid.

Body

application/json

kidstringRequired

Ідентифікатор ключа (Key ID)

Example: 60217d56-2d36-48e3-abe8-5c00b42ca885

Responses

200

Успішно. Повертає публічний ключ у форматі JWK.

application/json

ktystringOptional

Тип ключа (наприклад, EC)

Example: EC

usestringOptional

Призначення ключа (наприклад, sig)

Example: sig

crvstringOptional

Крива (наприклад, P-256)

Example: P-256

kidstringOptional

Ідентифікатор ключа

Example: 60217d56-2d36-48e3-abe8-5c00b42ca885

xstringOptional

X-координата публічного ключа (base64url)

Example: gwv2nKBulGGxTuAqcxBvWcvRweSErxw_jUgdl7Z_...

ystringOptional

Y-координата публічного ключа (base64url)

Example: NGWref0yNMQsmi-1u7ca1dASA4t_kpSPQTo6Wzhz...

algstringOptional

Алгоритм (наприклад, ES256)

Example: ES256

400

Некоректний запит (наприклад, відсутній kid)

404

Ключ не знайдено

500

Внутрішня помилка сервера

post

/ecom/keys/public_key/get_v1

HTTPcURLJavaScriptPython

POST /ecom/keys/public_key/get_v1 HTTP/1.1
Host: {{url}}
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "kid": "60217d56-2d36-48e3-abe8-5c00b42ca885"
}

{
  "kty": "EC",
  "use": "sig",
  "crv": "P-256",
  "kid": "60217d56-2d36-48e3-abe8-5c00b42ca885",
  "x": "gwv2nKBulGGxTuAqcxBvWcvRweSErxw_jUgdl7Z_...",
  "y": "NGWref0yNMQsmi-1u7ca1dASA4t_kpSPQTo6Wzhz...",
  "alg": "ES256"
}