Аутентификация при использовании mDAG

Все запросы и ответы API Gateway должны быть аутентифицированы.

Исключение составляют запросы:

Аутентификационные данные передаются в заголовке Authorization HTTP-запроса.

Формат заголовка:

Authorization: myDSS kid:Base64(HMAC):Base64(nonce),
где

kid – идентификатор ключа пользователя,
Base64(HMAC) – значение HMAC в кодировке BASE64,
Base64(nonce) - случайное значение размером 32 байта (см. далее) в кодировке BASE64.

Значение HMAC вычисляется от конкатенации следующих данных:

kid | deviceFingerprint | HTTP-Body | nonce | timeDelta,

где

kid – идентификатор ключа пользователя;
deviceFingerprint - отпечаток устройства (опциональный параметр);
HTTP-Body – тело HTTP запроса в UTF-8 кодировке;
nonce - случайное значение размером 32 байта;
timeDelta – число временных интервалов между начальным и текущим значением времени; вычисляется по следующей формуле: timeDelta = (T – T0) / myDssTimeStep, где (T – T0) – количество секунд между текущим временем и 1 января 1970 00:00:00 UTC (Unix-time), myDssTimeStep – интервал валидации кода подтверждения, полученный из политики myDSS API Gateway (в секундах).

Под kid понимается идентификатор набора ключей, состоящего из двух ключей Kauth и Kconf. Какой ключ из набора должен быть использован для вычисления HMAC, указано в описании соответствующего метода API.

Ошибки аутентификации

В случае невозможности выполнить процедуру аутентификации пользователя myDSS API Gateway вернет HTTP-ответ со статусом 401, в поле причина (Reason-Phrase) указывается код ошибки.

Код ошибки	Описание
`user_not_found`	Не удалось найти пользователя по идентификатору набора ключей `kid`
`user_blocked`	Учетная запись пользователя заблокирована
`invalid_authentication_scheme`	Пользователю не назначен способ аутентификации через мобильное приложение
`key_expired_or_not_yet_valid`	Срок действия ключей аутентификации истек или еще не наступил
`device_blocked`	Аутентификация на данном наборе ключей запрещена оператором
`invalid_hmac`	Неправильное значение HMAC
`assertion_replay`	Повторение запроса с неуникальным nonce
`invalid_license`	Отсутствует действительная лицензия на способ аутентификации через мобильное приложение
`invalid_grant`	Не удалось проверить заголовок аутентификации (подробности в журнале сервера)

Пример вычисления HMAC для аутентификации

Значение HMAC представляет из себя Base64-значение криптографической операции HMAC от конкатенации значений kid | deviceFingerprint | HTTP-Body | timeDelta каждое из которых представлено в виде массива байт в кодировке UTF-8, то есть:

hmac = Base64(
    HMACconf(
        Utf8GetBytes(kid)
        | Utf8GetBytes(deviceFingerprint)
        | Utf8GetBytes(HTTP-Body)
        | nonce
        | Utf8GetBytes(timeDelta)
    )
)

Исходные данные:

kid - идентификатор ключа аутентификации MyDss, string

64474817

kconf или kauth (в зависимости от типа операции) - значение ключа Kauth или Kconf. Какой ключ из набора должен быть использован для вычисления HMAC, указано в описании соответствующего метода API. В виде массива из байт, byte[32] (hex)

000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F

Ключевой блоб

012000001E660000FD514A371E660000A1E6470645C342CB80C5E76969A9882E9382F09CC58052B4F46AC5F973BAAFBA8864CA45D3BAA68223D15FE6300B06092A850307010205010100000000C10179A7

Для импорта ключевого блоба нужно использовать следующие параметры:

userId: 79f5c06f-8806-40b0-b4bb-13b82175216d
password: 11111111

deviceFingerprint - идентификатор (отпечаток) устройства, string

e28ef702-dee5-402f-a32e-981b3132740b

HTTP-Body - тело HTTP-запроса к REST API, string

{ "Id": "708a4546-5045-468e-89e9-6265f7363739", "TimeStamp": 12345 }

// Другие примеры тел HTTP-запросов:
// { "phone" : "79998887766", "email" : "test@cryptropro.ru" }
// { "cid": "8330", "friendlyName": "My main certificate" }
// { "kid" : "63101476" }

nonce - уникальное значение, byte[32] (hex)

B75E04EE13C0F50C9AEE6D97A28D7212C6D95C0B8D25174AAA0A198597A63E22

timeStamp - штамп Unix-времени, long

MyDssTimeStep - интервал валидации кода подтверждения, полученный из политики MyDss API Gateway, int

Шаг 1: Определение номера текущего интервала проверки HMAC

(timeStamp / MyDssTimeStep).ToString() - строковое представление целочисленного деления штампа Unix-времени на интервал валидации кода подтверждения, string

Входные данные:

// timeStamp = 
12345
// MyDssTimeStep =
180

Результат:

// (timeStamp / MyDssTimeStep).ToString() =
68

Шаг 2: Получение байтового представления исходных данных в кодировке UTF-8

Utf8GetBytes - функция получения массива байтов из строк в кодировке UTF8

Входные данные: Строки

// kid = 
64474817
// deviceFingerprint =
e28ef702-dee5-402f-a32e-981b3132740b
// HTTP-Body =
{ "Id": "708a4546-5045-468e-89e9-6265f7363739", "TimeStamp": 12345 }
// (timeStamp / MyDssTimeStep).ToString() =
68

Выходные данные: Массивы байт (hex)

// Utf8GetBytes(kid) = 
3634343734383137
// Utf8GetBytes(deviceFingerprint) =
65323865663730322D646565352D343032662D613332652D393831623331333237343062
// Utf8GetBytes(HTTP-Body) =
7B20224964223A202237303861343534362D353034352D343638652D383965392D363236356637333633373339222C202254696D655374616D70223A203132333435207D
// Utf8GetBytes((timeStamp / MyDssTimeStep).ToString()) =
3638

Примечание

Если не установлено требование задавать отпечаток устройства (deviceFingerprint), и это значение отсутствует, то результатом функции Utf8GetBytes(deviceFingerprint) должен быть пустой массив байт byte[0], таким образом deviceFingerprint не участвует в вычислении значения HMAC.

Шаг 3: HMACconf

HMACconf - функция вычисления HMAC на ключе kconf или kauth (в зависимости от типа операции).

Входные данные: Конкатенация массивов байт из предыдущего шага в том порядке, в котором они перечислены

// Utf8GetBytes(kid)
// | Utf8GetBytes(deviceFingerprint)
// | Utf8GetBytes(HTTP-Body)
// | nonce
// | Utf8GetBytes((timeStamp / MyDssTimeStep).ToString()) =
363434373438313765323865663730322D646565352D343032662D613332652D3938316233313332373430627B20224964223A202237303861343534362D353034352D343638652D383965392D363236356637333633373339222C202254696D655374616D70223A203132333435207DB75E04EE13C0F50C9AEE6D97A28D7212C6D95C0B8D25174AAA0A198597A63E223638

Выходные данные: Значение hmac в виде массива байт (hex)

CCF2562E3659F17B368B3F2AB963D5047418DADD783188EEED1E57D4DACD6025

Шаг 4: Base64

Base64 - функция преобразования массива байтов в строку в кодировке BASE64.

Входные данные: Значение hmac в виде массива байт из предыдущего шага (hex)

CCF2562E3659F17B368B3F2AB963D5047418DADD783188EEED1E57D4DACD6025

Выходные данные: Значение hmac в виде строки в формате Base64

zPJWLjZZ8Xs2iz8quWPVBHQY2t14MYju7R5X1NrNYCU=

Подтверждение операций

Для подтверждения операции необходимо на конечную точку /mydss/v1/operations/confirm отправить запрос, содержащий объект ApproveRequest, содержащий сведения о подтверждаемой операции (объект ApprovedOperation сериализованный в строку формата JSON), и значение hmac, подсчитанное на основе этих сведений, в формате Base64.

Значение HMAC вычисляется от конкатенации следующих данных:

kid | deviceFingerprint | approvedOperationJson,

где

kid – идентификатор ключа пользователя;
deviceFingerprint - отпечаток устройства (опциональный параметр);
approvedOperationJson – сериализованный в строку формата JSON объект ApprovedOperation, содержащий сведения о подтверждаемой операции.

Пример вычисления HMAC для подтверждения операции

Для подтверждения операции значение HMAC вычисляется практически аналогичным аутентификации образом, за исключением отсутствия параметра timeStamp и замены параметра HTTP-Body на параметр approvedOperationJson.

Значение HMAC представляет из себя Base64 значение криптографической операции HMAC (на ключе Kconf) от конкатенации значений kid | deviceFingerprint | approvedOperationJson каждое из которых представлено в виде массива байт в кодировке UTF-8, то есть:

hmac = Base64(
    HMACconf(
        Utf8GetBytes(kid)
        | Utf8GetBytes(deviceFingerprint)
        | Utf8GetBytes(approvedOperationJson)
    )
)