Class: CryptoPlugin

Методы

authenticate(deviceId, certId, salt) → {string}

Аутентификация по сертификату.

Предупреждение

С версии Рутокен Плагин 2.8.5 метод считается устаревшим и не рекомендуется к применению. В будущих обновлениях он может быть удален из состава продукта. Используйте метод rawSign.

changePin(deviceId, authPin, newPin, options)

Изменение PIN-кода Пользователя.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	authPin	string	Текущий PIN-код Пользователя или PIN-код Администратора
3	newPin	string	Новый PIN-код Пользователя
4	options	object	Объект, содержащий дополнительные параметры в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	useAdminPin	bool	false	Если true – параметр authPin должен содержать PIN-код Администратора. Если false – параметр authPin должен содержать текущий PIN-код Пользователя

cmsDecrypt(deviceId, keyId, cmsData, options) → {string}

Расшифрование данных в формате CMS.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор ключа для расшифрования
3	cmsData	string	CMS-сообщение в формате PEM или Base64, содержащее зашифрованные данные
4	options	object	Объект, содержащий параметры расшифрования в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	base64	bool	false	Если true – получить расшифрованные данные в Base64. Если false – получить расшифрованные данные в PEM-формате

Возвращает:

Расшифрованные данные

cmsEncrypt(deviceId, certId, recipientCerts, data, options) → {string}

Шифрование данных в формате CMS.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата. Зарезервировано для будущего использования
3	recipientCerts	object	Массив, содержащий сертификаты получателей в PEM-формате
4	data	string	Данные для шифрования (текстовая строка или Base64-encoded бинарные данные)
5	options	object	Объект, содержащий параметры шифрования в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	base64	bool	false	Если true – в параметр data передаются данные в Base64. Если false – в параметр data передается текстовая строка
2	cipherAlgorithm	enum	–	Алгоритм шифрования
3	outputFormat	enum	DATA_FORMAT_BASE64	Формат вывода подписанного сообщения

Возвращает:

Зашифрованные данные в формате CMS

createBinaryFile(deviceId, fileName, fileBuffer, isPrivate) → {string}

Создание бинарного файла на устройстве.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Примечание

При создании бинарных файлов альтернативными способами (например, через библиотеку rtPKCS11ECP) необходимо придерживаться ограничений.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	fileName	string	Имя (идентификатор) создаваемого файла
3	fileBuffer	string	Тело создаваемого файла в Base64
4	isPrivate	bool	Идентификатор доступа (доступен ли файл только из приватной сессии)

Возвращает:

Строка с идентификатором созданного бинарного файла

createPkcs10(deviceId, keyId, subject, extensions, options) → {string}

Формирование самоподписанного PKCS#10 запроса.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор ключа
3	subject	object	Массив, содержащий объекты вида: {rdn: "commonName", value: "значение"}
4	extensions	object	Ассоциативный массив, содержащий массивы расширений: keyUsage: ["digitalSignature",...]; extKeyUsage: ["oid", "longName" ]; certificatePolicies: ["OID", ...]; privateKeyUsagePeriod: { notBefore: number, notAfter: number} – объект, содержащий опциональные поля в формате Unix-время (целое число секунд, прошедших с 1970.01.01.00:00:00): notBefore – дата начала валидности закрытого ключа; notAfter – дата окончания валидности закрытого ключа; требования к полям privateKeyUsagePeriod (несоблюдение хотя бы одного приведет к ошибке): дата начала/окончания валидности закрытого ключа должна принадлежать диапазону от 1970.01.01.00:00:00 до 9999.12.31.23:59:59 включительно; если поля notBefore и notAfter заданы одновремено, то значение в поле notBefore должно быть меньше значения в поле notAfter; атрибуты закрытого ключа CKA_START_DATE/CKA_END_DATE должны быть не заданы. В случае, если атрибуты закрытого ключа CKA_START_DATE/CKA_END_DATE заданы, privateKeyUsagePeriod заполнится автоматически с проверкой инвариантов полей notBefore/notAfter метода getKeyInfo(KEY_INFO_USAGE_PERIOD) и перечисленных выше требований
5	options	object	Дополнительные опции

Параметры (опции) аргумента options:

	Название	Тип	Описание
1	subjectSignTool	string	Значение соответствующего расширения
2	hashAlgorithm	enum	Алгоритм хеширования
3	customExtensions	object	Массив, содержащий объекты вида: {oid: "1.2.3", value: "MA0GCCqFAwICLgAIAgEB", criticality: false}. Если задать более одного расширения с одинаковым oid через customExtensions, запишется первое созданное. Попытка создания более одного расширения с одинаковым oid через extensions и customExtensions приведет к ошибке. Значения расширений, заданные через customExtensions, используются as-is (без проверок на соответствие спецификациям расширений)

Возвращает:

PKCS#10 запрос

Пример:

   var subject = [
           {
               rdn:    "countryName",
               value:  "RU"
           }
           ,{
               rdn:    "stateOrProvinceName",
               value:  "moscow"
           }
           ,{
               rdn:    "localityName",
               value:  "locality"
           }
           ,{
               rdn:    "streetAddress",
               value:  "street"
           }
           ,{
               rdn:    "organizationName",
               value:  "Aktiv"
           }
           ,{
               rdn:    "organizationalUnitName",
               value:  "IT"
           }
           ,{
               rdn:    "title",
               value:  "должность"
           }
           ,{
               rdn:    "commonName",
               value:  "Фамилия Имя Отчество"
           }
           ,{
               rdn:    "postalAddress",
               value:  "postal address"
           }
           ,{
               rdn:    "pseudonym",
               value:  "pseudonym"
           }
           ,{
               rdn:    "surname",
               value:  "surname"
           }
           ,{
               rdn:    "givenName",
               value:  "given name"
           }
           ,{
               rdn:    "emailAddress",
               value:  "example@example.com"
           }
       ];
       var keyUsageVal = [
           "digitalSignature"
           ,"nonRepudiation"
           ,"keyEncipherment"
           ,"dataEncipherment"
           ,"keyAgreement"
           ,"keyCertSign"
           ,"cRLSign"
           ,"encipherOnly"
           ,"decipherOnly"
       ];
       var extKeyUsageVal = [
           "emailProtection"
           ,"clientAuth"
           ,"serverAuth"
           ,"codeSigning"
           ,"timeStamping"
           ,"msCodeInd"
           ,"msCodeCom"
           ,"msCTLSign"
           ,"1.3.6.1.5.5.7.3.9" // OSCP
           ,"1.2.643.2.2.34.6" // CryptoPro RA user
            // ,"anyExtendedKeyUsage"

       ];
       var certificatePolicies = [
           "1.2.643.100.113.1", // КС1
           "1.2.643.100.113.2", // КС2
           "1.2.643.100.113.3", // КС3
           "1.2.643.100.113.4", // КВ1
           "1.2.643.100.113.5", // КВ2
           "1.2.643.100.113.6"  // КА1
       ];
       var privateKeyUsagePeriod = {
           notBefore: 1714510800, // 2024.04.30 21:00:00
           notAfter: 1809118800, // 2027.04.30 21:00:00
       };
       var extensions = {
           "keyUsage":            keyUsageVal,
           "extKeyUsage":         extKeyUsageVal,
           "certificatePolicies": certificatePolicies
           "privateKeyUsagePeriod": privateKeyUsagePeriod
       };
       var options = {
           "subjectSignTool":     'СКЗИ "РУТОКЕН ЭП"',
           "hashAlgorithm":       plugin.HASH_TYPE_GOST3411_12_256,
           "customExtensions":    [
               {
                   oid: "1.3.6.1.4.1.311.21.7",
                   value: "MA0GCCqFAwICLgAIAgEB",
                   criticality: false
               }
           ]
       };
       plugin.createPkcs10(deviceID, keyID, subject, extensions, options);
   }


 

createTsRequest(data, dataFormat, hashType, options) → {string}

Создание запроса на метку времени.

Параметры:

	Название	Тип	Описание
1	data	string	Данные, для которых нужно создать метку времени
2	dataFormat	number	Формат данных. Если формат данных – DATA_FORMAT_HASH, то в параметр data передается посчитанный хеш от данных (hex-строка)
3	hashType	number	Алгоритм хеширования
4	options	object	Дополнительные опции

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	policy	string	empty	Политика, по которой ожидается создание метки времени
2	cert	bool	false	Если true – серверу требуется включить сертификат подписи в ответ. Если false – серверу не требуется включить сертификат подписи в ответ
3	nonce	bool	true	Если true – включить псевдослучайное 64-битное число в запрос. Если false – не включать псевдослучайное число в запрос
4	extensions	object	–	Массив, содержащий расширения в виде: {oid: "1.2.3", value: "MA0GCCqFAwICLgAIAgEB", criticality: false}

Возвращает:

Запрос (Base64)

deleteBinaryFile(deviceId, fileName)

Удаление бинарного файла с устройства.
Шаблон поиска аналогичен шаблону поиска бинарного файла с добавлением CKA_LABEL = <имя файла>.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	fileName	string	Имя (идентификатор) бинарного файла, полученное в результате вызова enumerateBinaryFiles

deleteCertificate(deviceId, certId)

Удаление сертификата с устройства.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата, полученный в результате вызова enumerateCertificates

deleteKeyPair(deviceId, keyId)

Удаление ключевой пары.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор закрытого ключа из ключевой пары

derive(deviceId, keyId, publicKey, options) → {string}

Выработка ключа обмена.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор закрытого ключа
3	publicKey	string	Открытый ключ (hex-строка) (для ECDSA uncompressed форма)
4	options	object	Объект, содержащий параметры подписи в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	ukm	string	00:00:00:00:00:00:00:01	Синхропосылка (hex-строка) (только для ГОСТ)

Возвращает:

Выработанный ключ (hex)

digest(deviceId, hashType, data, options) → {string}

Вычисление хеша.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	hashType	number	Алгоритм хеширования. Следующие алгоритмы хеширования доступны только при опции useHardwareHash=false: HASH_TYPE_MD5; HASH_TYPE_SHA1; HASH_TYPE_SHA256; HASH_TYPE_SHA384; HASH_TYPE_SHA512
3	data	string	Хешируемые данные
4	options	object	Объект, содержащий параметры хеширования в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	useHardwareHash	bool	false	Производить аппаратное хеширование данных
2	base64	bool	false	Если true – данные, переданные в data, должны быть в Base64. Если false – в data передаются текстовые данные

Возвращает:

Хеш (hex)

enumerateBinaryFiles(deviceId) → {string[]}

Получение перечня идентификаторов бинарных файлов.
Поиск бинарных файлов осуществляется по шаблону.

Примечание

Приватные бинарные файлы доступны только из приватной сессий.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства

Возвращает:

Массив строк с идентификаторами бинарных файлов

enumerateCertificates(deviceId, category) → {string[]}

Получение массива с идентификаторами сертификатов.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	category	number	Тип сертификата

Возвращает:

Массив строк с идентификаторами сертификатов

enumerateDevices(options) → {number[]}

Получение идентификаторов доступных устройств.

Параметры:

	Название	Тип	Описание
1	options	object	Объект, содержащий дополнительные параметры в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	mode	enum	ENUMERATE_DEVICES_LIST	Тип получаемой информации об устройствах

Возвращает:

Список идентификаторов устройств

enumerateKeys(deviceId, marker) → {string[]}

Получение массива с идентификаторами закрытых ключей в HEX.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	marker	string	Идентификатор группы ключей, "" – все ключи

Возвращает:

Массив строк с идентификаторами закрытых ключей (hex)

enumerateStoreCertificates(options) → {string[]}

Получение массива с идентификаторами установленных в системном хранилище сертификатов.

Предупреждение

С версии Рутокен Плагин 4.11.0 метод считается устаревшим и не рекомендуется к применению. В будущих обновлениях он может быть удален из состава продукта. Используйте метод enumerateCertificates.

formatToken(deviceId, options)

Форматирование токена.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	options	object	Объект, содержащий дополнительные параметры в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	adminPin	string	87654321	Текущий PIN-код Администратора
2	newUserPin	string	12345678	PIN-код Пользователя после форматирования
3	label	string	–	Метка токена (если опция отсутствует, то устанавливается текущая метка)

generateKeyPair(deviceId, reserved, marker, options) → {string}

Генерация ключевой пары на устройстве.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	reserved	string	Зарезервировано для будущего использования (необходимо передавать undefined)
3	marker	string	Идентификатор группы ключей
4	options	object	Объект, содержащий дополнительные свойства ключевой пары в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	id	string	""	Уникальный идентификатор ключевой пары (hex). Примечание При генерации ключей для ЕГАИС необходимо указывать id:string, состоящий из печатных символов и не содержащий пустого символа. Пример правильного id:string для ЕГАИС -> "abc123", что в шестнадцатеричной кодировке будет выглядеть как id:string("41:42:43:31:32:33"). Для автоматического преобразования рекомендуем использовать функцию asciitohex(), как в примере. Если опция не задана, или в качестве значения указана пустая строка, идентификатор будет сгенерирован автоматически
2	publicKeyAlgorithm	enum	PUBLIC_KEY_ALGORITHM_GOST3410_2001	Алгоритм генерации ключевой пары. Примечание В ЕГАИС используется PUBLIC_KEY_ALGORITHM_GOST3410_2012_256. Алгоритм ГОСТ Р 34.10-2001 был выведен из эксплуатации в 2019 году
3	signatureSize	number	–	Размер подписи в битах: 512 – для ГОСТ Р 34.10-2001 и ГОСТ Р 34.10-2012 с длиной закрытого ключа 256 бит; 1024 – для ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит; 2048 – для RSA. Допустимые значения длины RSA в битах: "512", "768", "1024", "1280", "1536", "1792", "2048", "4096"
4	paramset	string	–	Задает параметры ключевой пары. Если опция не задана, будут выбраны параметры А для любого из алгоритмов ГОСТ. Возможные значения (в скобках указан OID набора параметров, соответствующий выбранному буквенному обозначению): ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит: "XA" (1.2.643.2.2.36.0); "XB" (1.2.643.2.2.36.1); "TC26-A" (1.2.643.7.1.2.1.1.1); "TC26-B" (1.2.643.7.1.2.1.1.2); "TC26-C" (1.2.643.7.1.2.1.1.3); "TC26-D" (1.2.643.7.1.2.1.1.4); "A" (1.2.643.2.2.35.1); "B" (1.2.643.2.2.35.2); "C" (1.2.643.2.2.35.3). ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит: "TC26-A" (1.2.643.7.1.2.1.2.1); "TC26-B" (1.2.643.7.1.2.1.2.2); "TC26-C" (1.2.643.7.1.2.1.2.3); "A" (1.2.643.7.1.2.1.2.1); "B" (1.2.643.7.1.2.1.2.2). ECDSA: "secp256k1" (1.3.132.0.10); "secp256r1" (1.2.840.10045.3.1.7); "secp384r1" (1.3.132.0.34); "secp521r1" (1.3.132.0.35). ГОСТ Р 34.10-2001: "A" (1.2.643.2.2.35.1); "B" (1.2.643.2.2.35.2); "C" (1.2.643.2.2.35.3); "XA" (1.2.643.2.2.36.0); "XB" (1.2.643.2.2.36.1)
5	keyType	enum	KEY_TYPE_COMMON	Тип ключевой пары
6	keySpec	enum	KEY_SPEC_SIGN_AND_EXCHANGE	Назначение ключевой пары. Пример кода Для корректной генерации ключей на всех Рутокен ЭЦП, включая экспортные исполнения, воспользуйтесь примером кода Примечание Назначение cледует задавать явно. Для использования константы KEY_SPEC_SIGN_AND_EXCHANGE (обмен сообщениями (шифрование) и подпись) необходимо, чтобы: устройство поддерживало генерацию симметричного ключа (механизм ВКО). Экспортные версии Рутокен ЭЦП 3.0 не содержат механизм ВКО; ключевая пара не являлась журнальной: keyType != KEY_TYPE_JOURNAL.
7	privateKeyUsagePeriod	object	–	Объект, содержащий опциональные поля в формате Unix-времени (целое число секунд, прошедших с 1970.01.01.00:00:00): notBefore:number – дата начала валидности закрытого ключа; notAfter:number – дата окончания валидности закрытого ключа. Требования к полям privateKeyUsagePeriod: дата должна быть существующей; дата из диапазона от 1970.01.01.00:00:00 до 9999.12.31.00:00:00 включительно; часть даты HH:MM:SS равна 00:00:00 (значение Unix-времени кратно 86'400); при заданных одновременно полях notBefore и notAfter: notBefore < notAfter

Возвращает:

ID ключа (hex)

Примеры:

 // Преобразование шестнадцатеричного id ключевой пары в формат для ЕГАИС
function asciitohex(str){
    var result = [];
    for (var n = 0, l = str.length; n < l; n++) {
         var code = str.charCodeAt(n);
         if(code > 128 || code == 32)
             continue;

         var hex = code.toString(16);
         result.push(hex);
    }
    return result.join(':');
}

 // Генерация ключевой пары c возможностью обмена только на поддерживающих это токенах

// Генерация ключевой пары будет производиться на устройстве с этим
// идентификатором, полученным из enumerateDevices()
var deviceId = 0;

var info = plugin.TOKEN_INFO_SUPPORTED_MECHANISMS;
plugin.pluginObject.getDeviceInfo(deviceId, info).then(function (result) {
    // Определение, поддерживает ли устройство генерацию симметричного ключа
    // по алгоритмам ГОСТ
    var supportedMechs = result["keyExchange"]["hardware"];
    var exchangeSupported =
        supportedMechs.includes(
            plugin.PUBLIC_KEY_ALGORITHM_EXCHANGE_VKO_GOST3410_2012_256)
        || supportedMechs.includes(
            plugin.PUBLIC_KEY_ALGORITHM_EXCHANGE_VKO_GOST3410_2012_512);

    // Авторизация на устройстве
    plugin.pluginObject.login(deviceId, "12345678").then(function () {
        var algorithm = plugin.PUBLIC_KEY_ALGORITHM_GOST3410_2012_256;
        var options = { "publicKeyAlgorithm": algorithm };

        // Параметры ключевой пары ГОСТ
        options.paramset = "TC26-A";
        options.signatureSize = 512;
        options.id = "AA:BB:CC"; // Идентификатор ключевой пары

        // Если Рутокен поддерживает генерацию симметричного ключа,
        // тогда назначение ключевой пары должно быть
        // "обмен сообщениями (шифрование) и подпись".
        // Если поддержка отсутствует, то назначение следует указать как
        // "подпись"
        if (exchangeSupported)
            options.keySpec = plugin.KEY_SPEC_SIGN_AND_EXCHANGE;
        else
            options.keySpec = plugin.KEY_SPEC_SIGN;

        var marker = "Test"; // Метка

        // Генерация ключевой пары с выбранным назначением
        plugin.pluginObject.generateKeyPair(deviceId, undefined, marker, options).
            then(function () {
            console.info("Success");

            // Закрытие сессии
            plugin.pluginObject.logout(deviceId).then(function () {
            }, function (errorCode) { console.error(errorCode) });
        }, function (errorCode) { console.error(errorCode) });
    }, function (errorCode) { console.error(errorCode) });
}, function (errorCode) { console.error(errorCode) });
 

getBinaryFileInfo(deviceId, fileName, option) → {object}

Получение информации о бинарном файле.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	fileName	string	Имя (идентификатор) бинарного файла
3	option	number	Тип запрашиваемой информации. Задается константой BINARY_FILE_INFO_PRIVATE, передача которой возвращает флаг приватности бинарного файла

Возвращает:

Информация о бинарном файле

getCertificate(deviceId, certId) → {string}

Получение тела сертификата в формате PEM.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата

Возвращает:

Описатель сертификата в виде объекта

getCertificateInfo(deviceId, certId, option) → {object}

Получение информации о сертификате.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата
3	option	number	Тип запрашиваемой информации. Задается константой CERT_INFO_SERIAL_NUMBER, передача которой возвращает серийный номер сертификата в формате hex-строки

Возвращает:

Для серийного номера сертификата – строка (hex)

getCertLabel(deviceId, certId) → {string}

Получение метки сертификата.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата

Возвращает:

Метка сертификата

getDeviceInfo(deviceId, option) → {object}

Получение информации об устройстве.
Тип возвращаемой информации задается константами в параметре options.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	option	number	Тип запрашиваемой информации

Возвращает:

Информация об устройстве в зависимости от типа запрашиваемой информации

getJournal(deviceId, keyId, options) → {object}

Получение журнала операций устройства и журнала, сформированного на соответствующем ГОСТ-ключе.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор ключа
3	options	object	Объект, содержащий дополнительные параметры. Зарезервирован для будущего использования

Возвращает:

Ассоциативный массив с полями "journal" и "signature". Если с момента подключения токена никаких операций не производилось, то возвращается null

getKeyByCertificate(deviceId, certId) → {string}

Получение идентификатора ключевой пары по сертификату.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата

Возвращает:

Идентификатор ключа (hex)

getKeyInfo(deviceId, keyId, option) → {object}

Получение информации о ключе.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор ключа
3	option	number	Тип запрашиваемой информации

Возвращает:

Информация о ключе в зависимости от типа запрашиваемой информации

getKeyLabel(deviceId, keyId) → {string}

Получение метки закрытого ключа.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор ключа

Возвращает:

Метка закрытого ключа

getLicence(deviceId, licenceId) → {string}

Получение лицензии с токена.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	licenceId	number	Идентификатор лицензии (значения 1, 2)

Возвращает:

Лицензия (hex)

getPublicKeyValue(deviceId, keyId, options) → {string}

Получение значения открытого ключа.

Предупреждение

Не поддерживается для ключей RSA.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор ключа
3	options	object	Объект, содержащий дополнительные параметры. Зарезервирован для будущего использования

Возвращает:

Открытый ключ (hex) (для ECDSA uncompressed форма)

getStoreCertificate(certId, options) → {string}

Получение тела сертификата из системного хранилища в формате PEM.

Предупреждение

С версии Рутокен Плагин 4.11.0 метод считается устаревшим и не рекомендуется к применению. В будущих обновлениях он может быть удален из состава продукта. Используйте метод getCertificate.

importCertificate(deviceId, certificate, category) → {string}

Импорт сертификата на устройство.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certificate	string	Тело сертификата в PEM-формате
3	category	number	Тип сертификата

Возвращает:

Идентификатор сертификата (hex)

login(deviceId, pin)

Авторизация на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	pin	string	PIN-код доступа к устройству

logout(deviceId)

Закрытие сессии.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства

parseCertificate(deviceId, certId) → {object}

Получение ассоциативного массива с разобранными полями из сертификата.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата, полученный в результате вызова enumerateCertificates

Возвращает:

Ассоциативный массив объектов

parseCertificateFromString(text) → {object}

Получение ассоциативного массива с разобранными полями из сертификата из строки.

Параметры:

	Название	Тип	Описание
1	text	string	Тело сертификата в PEM-формате

Возвращает:

Ассоциативный массив объектов

rawSign(deviceId, keyId, data, options) → {string}

Подпись на ключе.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор закрытого ключа
3	data	string	Подписываемый хеш (hex-строка) или текстовые данные
4	options	object	Объект, содержащий параметры подписи в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	computeHash	bool	false	Если true – хешировать данные. Если false – не хешировать данные. Если в параметр data переданы текстовые данные, то computeHash должен принимать значение true. Примечание Хеш считается только для ключей ГОСТ
2	useHardwareHash	bool	false	Если true – хешировать данные аппаратно. Если false – не хешировать данные аппаратно. Примечание Требуется: computeHash == true
3	hashAlgorithm	enum	–	Алгоритм хеширования. Примечание Для ключей RSA обязателен, даже если computeHash == false. Для ключей ГОСТ, если не задан, будет выбран автоматически

Возвращает:

Электронная подпись (hex)

readBinaryFile(deviceId, fileName) → {string}

Чтение бинарного файла.

Примечание

Приватные бинарные файлы доступны только из приватной сессий.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	fileName	string	Имя (идентификатор) бинарного файла, полученное в результате вызова enumerateBinaryFiles

Возвращает:

Тело считанного бинарного файла

removePin(deviceId)

Удаление закешированного PIN-кода из файла.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства

savePin(deviceId)

Сохранение PIN-кода в файл для автоматической аутентификации.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства

setCertLabel(deviceId, certId, label)

Установка метки сертификата.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата
3	label	string	Новая метка сертификата

setKeyLabel(deviceId, keyId, label)

Установка метки закрытого ключа.

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	keyId	string	Идентификатор ключа
3	label	string	Новая метка закрытого ключа

setLicence(deviceId, licenceId, licence)

Запись лицензии на токен.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	licenceId	number	Идентификатор лицензии (значения 1, 2)
3	licence	string	72 байта данных, представленные в hex-строке

sign(deviceId, certId, data, dataFormat, options) → {string}

Вычисление электронной подписи.
В зависимости от параметров можно получить подпись в форматах CMS (RFC5652), CAdES-BES (RFC5126, 4.3.1), CAdES-T (RFC5126, 4.4.1).

Примечание

Для выполнения этого метода требуется авторизоваться на устройстве.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	certId	string	Идентификатор сертификата
3	data	string	Подписываемые данные (текстовая строка или Base64-encoded бинарные данные)
4	dataFormat	number	Формат данных. Если формат данных – DATA_FORMAT_HASH, то в параметр data передается посчитанный хеш сообщения (hex-строка), при этом необходимо присвоить опции detached значение true
5	options	object	Объект, содержащий параметры подписи в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	detached	bool	false	Если true – генерировать отсоединенную подпись. Если false – генерировать присоединенную подпись
2	addUserCertificate	bool	true	Если true – включить в подпись сертификат пользователя. Если false – не включать в подпись сертификат пользователя
3	addEssCert	bool	false	Если true – включить в подпись хеш от сертификата пользователя и серийный номер сертификата. Если false – не включать в подпись хеш от сертификата пользователя и серийный номер сертификата. CAdES-BES и CAdES-T Для формирования требуется присвоить addEssCert значение "true"
4	addSignTime	bool	false	Если true – включить в подпись локальное время. Если false – не включать в подпись локальное время. CAdES-BES и CAdES-T Для формирования требуется присвоить addSignTime значение "true"
5	useHardwareHash	bool	false	Если true – производить аппаратное хеширование данных на ключах ГОСТ. Если false – не хешировать данные аппаратно
6	outputFormat	enum	DATA_FORMAT_BASE64	Формат вывода подписанного сообщения
7	rsaHashAlgorithm	enum	–	Алгоритм хеширования при использовании ключей RSA. Примечание Для алгоритмов ГОСТ параметр должен быть пустым
8	CMS	string	empty	Уже сформированный CMS в формате PEM или Base64, в который требуется добавить подпись. Если параметр не указан, то будет создан новый CMS. Примечание Если в параметр CMS передается отсоединенная подпись, то параметр data должен содержать данные, которые были подписаны. Если в параметр CMS передается присоединенная подпись, то параметр data должен быть пустым
9	eContentType	string	empty	Задать тип содержимого CMS (OID, например "1.2.3.4"). Требуется: опция CMS должна быть пуста; addSignTime == true
10	addSystemInfo	bool	false	Если true – включать информацию о месте подписи. Если false – не включать информацию о месте подписи. Требуется: addSignTime == true. Добавляет в подписанные атрибуты ASN.1 последовательность с OID 1.2.643.2.74.2.1.1.1
11	addSecurityProductsInfo	bool	false	Если true – включить информацию об установленных продуктах безопасности. Если false – не включать информацию об установленных продуктах безопасности. Требуется: addSignTime == true. Добавляет в подписанные атрибуты ASN.1 последовательность с OID 1.2.643.2.74.2.1.1.2
12	tspOptions	object	null	Параметры добавления метки времени. Требуется для формирования CAdES-T. Доступны следующие опции (значения по умолчанию указаны в скобках): url:string – адрес TSA-сервера. При подключении будут учтены системные настройки прокси. На данный момент поддерживаются только TSA-серверы, работающие по протоколу HTTP; digestAlg:enum – алгоритм хеширования (кроме MD5); policy:string (empty) – политика, по которой ожидается создание метки времени; cert:bool (false) – если true – серверу требуется включить сертификат подписи в ответ. Если false – серверу не требуется включить сертификат подписи в ответ; nonce:bool (true) – если true – включить псевдослучайное 64-битное число в запрос. Если false – не включать псевдослучайное число; extensions:object – массив, содержащий расширения в виде: {oid: "1.2.3", value: "MA0GCCqFAwICLgAIAgEB", criticality: false}; verifyTsToken:bool (true) – если true – проверить метку доверенного времени. Если false – не проверять метку доверенного времени; certificates:string[] (null) – набор сертификатов в PEM-формате, на которых необходимо проверять подпись полученной метки времени. Сертификат, который может содержаться в метке доверенного времени, будет проигнорирован; CA:string[] (null) – список дополнительных корневых сертификатов в PEM-формате для проверки сертификата. Кроме этих сертификатов берутся сертификаты с устройства; CRL:string[] (null) – список отозванных сертификатов в PEM-формате Минимально требуемым набором параметров добавления метки времени являются url и digestAlg с корректным указанием опций проверки ответа TSA-сервера. Для проверки полученного ответа через Рутокен Плагин необходимо передать сертификат TSA-сервера (если включение данного сертификата в метку времени не производилось), необходимые промежуточные сертификаты, а также доверенные корневые сертификаты. При проверке ответа через внешнее ПО верификация в Рутокен Плагине может быть отключена путем присвоения значения false опции verifyTsToken

Возвращает:

Электронная подпись (в формате Base64 или PEM)

unblockUserPin(deviceId, adminPin)

Разблокировка заблокированного PIN-кода Пользователя.

Примечание

Пользователь не должен быть авторизован.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	adminPin	string	PIN-код Администратора

verify(deviceId, cms, options) → {bool}

Криптографическая проверка электронной подписи сообщения в формате CMS, а также опциональная проверка цепочки сертификатов подписанта.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	cms	string	Контейнер с электронной подписью в формате CMS (RFC5652) (PEM-формат или Base64)
3	options	object	Объект, содержащий параметры проверки подписи в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	data	string	null	Подписанные данные (текстовые или Base64-encoded), только в случае detached подписи
2	base64	bool	false	Если true – то данные, переданные в cms, должны быть в Base64. Если false – то переданные в cms, должны быть в PEM-формате
3	certificates	string[]	null	Набор сертификатов в PEM-формате, на которых необходимо проверять подпись. Сертификаты, которые содержатся в cms, будут проигнорированы
4	CA	string[]	null	Cписок дополнительных корневых сертификатов в PEM-формате для проверки сертификата. Кроме них берутся сертификаты с устройства
5	CRL	string[]	null	Cписок отозванных сертификатов в PEM-формате
6	verifyCertificate	bool	true	Проверить сертификат подписанта

Возвращает:

true – подпись верна / false – не верна

verifyTsResponse(deviceId, response, data, dataFormat, options) → {bool}

Проверка метки доверенного времени.

Параметры:

	Название	Тип	Описание
1	deviceId	number	Идентификатор устройства
2	response	string	Base64-encoded метка доверенного времени (TSResponse)
3	data	string	Запрос метки доверенного времени (TSRequest)
4	dataFormat	number	Формат данных. Задается константой DATA_FORMAT_BASE64
5	options	object	Объект, содержащий параметры проверки подписи в виде пар "опция: значение"

Параметры (опции) аргумента options:

	Название	Тип	По умолч.	Описание
1	certificates	string[]	null	Набор сертификатов в PEM-формате, на которых необходимо проверять подпись. Сертификат, который может содержаться в метке доверенного времени, будет проигнорирован
2	CA	string[]	null	Cписок дополнительных корневых сертификатов в PEM-формате для проверки сертификата. Кроме них берутся сертификаты с устройства
3	CRL	string[]	null	Cписок отозванных сертификатов в PEM-формате

Возвращает:

true – метка верна / false – метка не верна