Формирование электронной подписи с помощью USB токена

Обновлено 20 декабря 2023

Запросы необходимо отправлять на http://localhost:28016/vpnkeylocal/<SID2>/, где SID2-идентификатор сессии, получаемый после перехода в бизнес-систему.

Подробнее о форматах запроса для:

• Инфокрипт токена смотрите в документе VPNKEYTLS_API_2.47.doc,

• Рутокена смотрите в документе Rutoken_API.pdf.

Для того чтобы получить ЭП VPNKeyTLS в формате CMS необходимо:

1. Cформировать строковую последовательность (ключевой буфер или дайджест), включающий все значимые данные документа.

2. Определить список сертификатов, находящихся на VPNKeyTLS, методом GET_OBJ_LIST_ID (см. 7. Получить список объектов (сертификаты ЭП, TLS, корневые и УЦ)).

Параметры запроса

Параметры запроса	Ограничение	Назначение
id (ID_FORMAT)	GET_OBJ_LIST_ID	id функции
obj_type (ENUM)	1 байт	0 - сертификаты ЭП, 1 - сертификаты TLS, 2 - корневые сертификаты, 3 - запрос ЭП, 4 - запрос TLS,5 - сертификаты УЦ, 6 - первичные ТЛС, 7 - транспортные ЭП

Пример запроса

POST http://localhost:28016/vpnkeylocal/
KEE2hUurVfiUBVrLaDyinXQF687Vz7OiVz/
POST data:
id=GET_OBJ_LIST_ID&obj_type=0

Параметры ответа

Параметры запроса	Ограничение	Назначение
data (STRING_A)	4096 байт	список id, сепаратор
retcode (ENUM)	2 байт	код возврата функции

Пример ответа

data="GFZ0tcwv"&retcode="1"

3. Определить handle сертификата методом INIT_SIGN_H_ID (см. 16.1. Инициализация ЭП).

Для работы по ГОСТ 2011 и выше необходимо указать хендл сертификата на этапе вызова команды INIT_SIGN_H_ID, т.к. параметры криптооперации берутся из сертификата. если сертификат не будет указан при вызове INIT_SIGN_H_ID, то его будет необходимо указать в конце, однако, в этом случае подписание будет произведено по ГОСТ-3411_1994_256, и если указанный в конце сертификат содержит другие параметры подписания, то операция будет завершена с ошибкой.

Параметры запроса

Параметры запроса	Ограничение	Назначение
id (ID_FORMAT)	INIT_SIGN_H_ID	id функции
datasize (NUMBER)	2^32 - 1	размер данных для ЭП
hascert (NUMBER)	1 байт	максимальное количество сертификатов из цепочки доверия, которое вложить в CMS ("-1" - вложить все сертификаты, в т.ч. корневой)
hasdata (ENUM)	1 байт	«0» - не вкладывать в CMS подписанные данные, проверка подписи с подписанными данными не поддерживается
mode (ENUM)	1, 2	стандарт криптооперации: 1 - КС1 - хеш данных считается "стартом.ехе", токен только генерирует подпись хеша, 2 - КС2 - хеш данных считается токеном, подпись генерируется им же (по умолчанию) (500+, опционально)
obj_id (HANDLE)	8 байт	id сертификата для подписи (500+, опционально)
name (BASE64)	128 символов UTF8 (размер BASE64 для их кодировки не регламентирован)	для экранных токенов. Имя подписываемого документа для отображения на экран. (500+, опционально)

Пример запроса

POST http://localhost:28016/vpnkeylocal/
KEE2hUurVfiUBVrLaDyinXQF687Vz7OiVz/
POST data:
id=INIT_SIGN_H_ID&obj_id=GFZ0tcwv&
datasize=654&hascert=-1&hasdata=0&mode=1

Параметры ответа

Параметры ответа	Ограничение	Назначение
retcode (ENUM)	2 байт	код возврата функции
(HANDLE)	8 байт	кхендл контекста операции

Пример ответа

ctx_handle="HzWQ6aUL"&retcode="1"

4. Передать методу SET_SIGN_DATA_H_ID дайджест в формате base64 и handle сертификата (см. 16.2. Загрузить порцию данных для ЭП).

Параметры запроса

Параметры запроса	Ограничение	Назначение
id (ID_FORMAT)	SET_SIGN_DATA_H_ID	id функции
data (BASE64)	Для прошивок 399+: 6144 URL-encoded байтов base64; Для прошивок 500+: 15360 байтов бинарных данных (размер base64, требуемый для их кодировки, не регламентирован) Для режима КС1: 16777216 байтов бинарных данных (размер base64, требуемый для их кодировки, не регламентирован)	данные для подписи в base64; размер декодированных данных должен быть кратен 8
blocknum (NUMBER)	2^32 - 1	номер посылки (опционально, если присутствует, то проверяется. Нумерация начинается с 1)
ctx_handle (HANDLE)	8 байт	хендл контекста операции

Пример запроса

POST http://localhost:28016/vpnkeylocal/KEE2hUurVfiUBVrLaDyinXQF687Vz7OiVz/
POST data:
id=SET_SIGN_DATA_H_ID&blocknum=1&data=YWNjZXB0YW5jZVRlcm09NQphbW91b
nQ9MzM3LjUyCmRhdGU9MjAxOS0wOS0xMQpleHRlcm5hbElkPTg2NzI2MjYwLTg3M
mYtNDczYS1hY2I3LTM0MmU1ODcxYmZiMgpvcGVyYXRpb25Db2RlPTAyCnBheWVlQ
WNjb3VudD00MDcwMjgxMDcwMjE1MDAwMDAyOQpwYXllZUJhbmtCaWM9MDQwM
TczNjA0CnBheWVlQmFua0NvcnJBY2NvdW50PTMwMTAxODEwMjAwMDAwMDAwNj
A0CnBheWVlSW5uPTIyMDUwMDE3NTMKcGF5ZWVOYW1lPdCe0YLQutGA0YvRgtC+
0LUg0LDQutGG0LjQvtC90LXRgNC90L7QtSDQvtCx0YnQtdGB0YLQstC+ICLQkNC70Y
LQsNC5LdCa0L7QutGBIgpwYXllckFjY291bnQ9NDA3MDI4MTA2MzgwMDAwMDQwOD
AKcGF5ZXJCYW5rQmljPTA0NDUyNTIyNQpwYXllckJhbmtDb3JyQWNjb3VudD0zMDE
wMTgxMDQwMDAwMDAwMDIyNQpwYXllcklubj0xNDgyNzQ2NTcwCnBheWVyTmFtZT
3QntCx0YnQtdGB0YLQstC+INGBINC+0LPRgNCw0L3QuNGH0LXQvdC90L7QuSDQvt
GC0LLQtdGC0YHRgtCy0LXQvdC90L7RgdGC0YzRjiAi0JzQsNGI0LAg0Lgg0JzQtdC00
LLQtdC00YwiCnBheW1lbnRDb25kaXRpb249Mgpwcmlvcml0eT01CnB1cnBvc2U9MTI2
NiDQn9C+INC00L7Qs9C+0LLQvtGA0YMgMTI2NiDQvtGCIDEwLjAxLjIwMTgKdm9Db2R
lPTYxMTUw&ctx_handle=HzWQ6aUL

Параметры ответа

Параметры ответа	Ограничение	Назначение
data_length (NUMBER)	2^32 - 1	суммарное количество данных, переданных для подписи (включая переданное данным вызовом)
retcode (ENUM)	2 байт	код возврата функции

Пример ответа

data_length="654"&retcode="1"

5. Вычислить подпись методом CALC_SIGN_H_ID (см. 16.3. Вычисление ЭП).

Поле obj_id не рекомендуется использовать с командой CALC_SIGN_H_ID, т.к. рекомендуется использовать его на этапе вызова команды INIT_SIGN_H_ID. Подробнее смотрите примечание к INIT_SIGN_H_ID.

Параметры запроса

Параметры запроса	Ограничение	Назначение
id (ID_FORMAT)	CALC_SIGN_H_ID	id функции
obj_type (HANDLE)	8 байт	id сертификата для подписи (НАСЛеДНОе ! Не рекомендуется к использованию! Опционально с 500+)
ctx_handle (HANDLE)	8 байт	хендл контекста операции

Пример запроса

POST http://localhost:28016/vpnkeylocal/KEE2hUurVfiUBVrLaDyinXQF687Vz7OiVz/
POST data:
id=CALC_SIGN_H_ID&obj_id=GFZ0tcwv&ctx_handle=HzWQ6aUL

Параметры ответа

Параметры запроса	Ограничение	Назначение
retcode (ENUM)	2 байт	код возврата ф-ии

Пример ответа

retcode="1"

6. Получить ЭП в формате CMS методом GET_SIGN_CMS_H_ID (см. 16.4. Получить ЭП в формате CMS).

Параметры запроса

Параметры запроса	Ограничение	Назначение
id (ID_FORMAT)	GET_SIGN_CMS_H_ID	id функции
ctx_handle (HANDLE)	8 байт	хендл контекста операции

Пример запроса

POST
http://localhost:28016/vpnkeylocal/KEE2hUurVfiUBVrLaDyinXQF687Vz7OiVz/
POST data:
id=GET_SIGN_CMS_H_ID&ctx_handle=HzWQ6aUL

Параметры ответа

Параметры запроса	Ограничение	Назначение
head (BASE64)	16384 байт декодированных данных	данные начала CMS в base64
suffix (BASE64)	16384 байт декодированных данных	данные начала CMS в base64
retcode (ENUM)	2 байт	код возврата функциии

Пример ответа

head="MIIMuAYJKoZIhvcNAQcCoIIMqTCCDKUCAQ
ExDjAMBggqhQMHAQECAgUAMAsGCSqGSIb3DQEHAQ=="
&suffix="oIIJkTCCBHAwggQdoAMCAQICCndONrct2UNmYqE...............
++4XWBJmrjrohy7NA=="&retcode="1"