Class: CryptoPlugin

Объект с константами ошибок

Версия плагина в формате 1.2.3.4

Аутентификация по сертификату. Не поддерживается для ключей RSA. Для выполнения этой функции требуется авторизоваться на устройстве.

Расшифрование данных в формате CMS. Аргумент options принимает параметры расшифрования. Доступны следующие опции (в скобках указано значение по умолчанию):

• base64:bool (false) - получить расшифрованные данные в base64

Создание бинарного файла (далее БФ) на устройстве.
Ограничения на создаваемый БФ (их необходимо придерживаться при создании БФ альтернативными способами - напрямую через PKCS, например):

• Атрибуты PKCS создаваемого БФ:
•   CKA_CLASS = CKO_DATA - класс для хранения БФ по умолчанию.
•   CKA_TOKEN = CK_TRUE - флаг хранения БФ на устройстве.
•   CKA_MODIFIABLE = CK_TRUE - флаг, разрешающий модификацию БФ после его создания.
•   CKA_LABEL - имя БФ без '\0'. Ограничения:
•     Имя бинарного файла должно быть задано.
•     Имена файлов должны быть уникальными.
•   CKA_APPLICATION = "Rutoken Plugin"
•   CKA_PRIVATE - флаг приватности БФ.
•   CKA_VALUE - тело БФ в бинарном формате.
• На отформатированном токене гарантированно можно создать 250 приватных и 250 публичных БФ.
• Максимальный суммарный размер атрибутов CKA_LABEL (имя БФ) и CKA_VALUE (тело БФ) в конечном бинарном представлении - 32'768 байт.
• Тело БФ должно быть передано в интерфейс плагина в кодировке Base64. На устройстве тело БФ хранится в бинарном виде. То есть при создании БФ не через плагин тело БФ должно быть представлено в бинарном виде.

Создание запроса на метку времени. Аргумент options принимает следующие параметры (в скобках указано значение по умолчанию):

• policy:string (empty) - политика, по которой ожидается создание метки времени
• cert:bool (false) - указать, что серверу требуется включить сертификат подписи в ответ
• nonce:bool (true) - включить псевдослучайное 64 битное число в запрос
• extensions:object - массив, содержащий расширения в виде: {oid: "1.2.3", value: "MA0GCCqFAwICLgAIAgEB", criticality: false}

Удаление сертификата с устройства. Для выполнения этой функции требуется авторизоваться на устройстве.

Выработка ключа обмена. Аргумент options принимает параметры выработки. Доступны следующие опции (в скобках указано значение по умолчанию):

• ukm:string (00:00:00:00:00:00:00:01) - Синхропосылка (hex-строка)

Получение перечня идентификаторов бинарных файлов (далее БФ).
Шаблон поиска БФ:

• CKA_CLASS = CKO_DATA
• CKA_APPLICATION = "Rutoken Plugin"
• CKA_TOKEN = CK_TRUE

Получение идентификаторов доступных устройств. Аргумент options опционален и принимает параметры перебора подключенных устройств. Доступны следующие опции (в скобках указано значение по умолчанию):

• mode:enum (ENUMERATE_DEVICES_LIST) - тип получаемой информации об устройствах, доступны варианты:
• ENUMERATE_DEVICES_LIST - получить список доступных устройств;
• ENUMERATE_DEVICES_EVENTS - получить списки подключенных и отключенных устройств;

Получение массива с идентификаторами установленных в системном хранилище сертификатов. Аргумент options принимает параметры перебора сертификатов. Зарезервирован для будущего использования.

Генерация ключевой пары на устройстве. Для выполнения этой функции требуется авторизоваться на устройстве. Аргумент options задает различные свойства ключа. Доступны следующие опции:

• id:string("") - уникальный идентификатор ключевой пары (hex). Если опция не задана, или в качестве значения указана пустая строка, будет сгенерирован автоматически.
  При генерации ключей для ЕГАИС необходимо указывать id:string, состоящий из печатных символов и не содержащий пустого символа. Пример правильного id:string для ЕГАИС -> "abc123", что в шестнадцатеричной кодировке будет выглядеть как id:string("41:42:43:31:32:33"), для автоматического преобразования рекомендуем использовать функцию asciitohex() см. пример ниже.


• publicKeyAlgorithm:enum(PUBLIC_KEY_ALGORITHM_GOST3410_2001) - алгоритм, варианты:
• PUBLIC_KEY_ALGORITHM_GOST3410_2001 - ГОСТ Р 34.10-2001;
• PUBLIC_KEY_ALGORITHM_GOST3410_2012_256 - ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит;
• PUBLIC_KEY_ALGORITHM_GOST3410_2012_512 - ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит;
• PUBLIC_KEY_ALGORITHM_RSA - RSA
• Примечание: В ЕГАИС используется PUBLIC_KEY_ALGORITHM_GOST3410_2012_256. Алгоритм ГОСТ Р 34.10-2001 выводится из эксплуатации в 2019 году


• signatureSize:number - размер подписи в битах, значения по умолчанию:
• ГОСТ Р 34.10-2001 - 512
• ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит - 512
• ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит - 1024
• RSA - 2048
• paramset:string - задает параметры ключевой пары. Если опция не задана, будут выбраны параметры А для любого из алгоритмов ГОСТ. Ниже приведены возможные варианты; в скобках указан OID набора параметров, соответствующий выбранному буквенному обозначению:
• ГОСТ Р 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)
• ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит:
• "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)
• "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)
• ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит:
• "A" (1.2.643.7.1.2.1.2.1)
• "B" (1.2.643.7.1.2.1.2.2)
• "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)
• keyType:enum(KEY_TYPE_COMMON) - тип ключевой пары, доступны варианты:
• KEY_TYPE_COMMON - обычная ключевая пара;
• KEY_TYPE_JOURNAL - журнальная ключевая пара (может быть использована только для подписи журнала);
• keySpec:enum(KEY_SPEC_SIGN_AND_EXCHANGE) - назначение ключевой пары, следует задавать явно; доступны варианты:
• KEY_SPEC_SIGN - подпись;
• KEY_SPEC_SIGN_AND_EXCHANGE - подпись и обмен; требования:
  • keyType != KEY_TYPE_JOURNAL,
  • для ГОСТ-ключей: устройство поддерживает операции ВКО.
• 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.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	reserved	string			Зарезервировано для будущего использования (необходимо передавать undefined)
3	marker	string			Идентификатор группы ключей
4	options	object			Дополнительные свойства ключевой пары в виде ассоциативного массива, см. подробное описание функции

Возвращает:

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(':');
}
 

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

Получение информации о бинарном файле (далее БФ). Тип информации задается константами. Доступны следующие константы (в скобках указан тип возвращаемого значения):

• BINARY_FILE_INFO_PRIVATE (bool) - флаг приватности БФ

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	fileName	string			Имя (идентификатор) БФ
3	option	number			Тип запрашиваемой информации

Возвращает:

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

getCertificate(deviceId, certId) → {string}

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certId	string			Идентификатор сертификата

Возвращает:

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

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

Получение информации о сертификате. Тип информации задается константами: CERT_INFO_SERIAL_NUMBER. Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certId	string			Идентификатор сертификата
3	option	number			Тип запрашиваемой информации

Возвращает:

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

getCertLabel(deviceId, certId) → {string}

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certId	string			Идентификатор сертификата

Возвращает:

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

getDeviceInfo(deviceId, option) → {object}

Получение информации об устройстве. Тип информации задается константами. Доступны следующие константы (в скобках указан тип возвращаемого значения):

• TOKEN_INFO_MODEL (string) - модель токена, не поддерживается и может быть удалена в последующих версиях плагина
• TOKEN_INFO_READER (string) - имя считывателя
• TOKEN_INFO_LABEL (string) - метка токена
• TOKEN_INFO_DEVICE_TYPE (integer) - константа, определяющая тип токена, не поддерживается и может быть удалена в последующих версиях плагина
• TOKEN_INFO_SERIAL (string) - серийный номер токена
• TOKEN_INFO_IS_PIN_CACHED (bool) - сохранён ли PIN-код. Начиная с версии 4.0.5 не поддерживается и может быть удалена в последующих версиях плагина. Используйте константу TOKEN_INFO_PINS_INFO.
• TOKEN_INFO_IS_LOGGED_IN (bool) - состояние аутентифицированности токена
• TOKEN_INFO_FORMATS (см. ниже) - поддерживаемые форматы входных данных для подписи
• TOKEN_INFO_FEATURES (см. ниже) - аппаратные возможности устройства
• TOKEN_INFO_ALGORITHMS (см. ниже) - поддерживаемые криптографические алгоритмы ЭЦП. Начиная с версии 4.0.5 не поддерживается и может быть удалена в последующих версиях плагина. Используйте константу TOKEN_INFO_SUPPORTED_MECHANISMS.
• TOKEN_INFO_SUPPORTED_MECHANISMS (см. ниже) - поддерживаемые программные и аппаратные алгоритмы.
• TOKEN_INFO_SPEED (integer) - класс скорости устройства.
• TOKEN_INFO_PIN_RETRIES_LEFT (integer) - оставшееся количество попыток ввода PIN-кода. Начиная с версии 4.0.5 не поддерживается и может быть удалена в последующих версиях плагина. Используйте константу TOKEN_INFO_PINS_INFO.
• TOKEN_INFO_PINS_INFO (см. ниже) - информация о PIN-кодах устройства
• TOKEN_INFO_FKN_SUPPORTED (bool) - поддерживает ли токен ФКН
• TOKEN_INFO_FREE_MEMORY (integer) - свободное место на токене в байтах.
• TOKEN_INFO_VENDOR_MODEL_NAME (string) - имя модели токена возвращаемое самим устройством. Проверить поддержку можно флагом vendorModelName из TOKEN_INFO_FEATURES.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	option	number			Тип запрашиваемой информации

Возвращает:

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

В случае передачи в качестве параметра TOKEN_INFO_FORMATS возвращается список форматов, которые поддерживает устройство, в виде массива констант:

• DEVICE_DATA_FORMAT_PLAIN - произвольные данные
DEVICE_DATA_FORMAT_SAFETOUCH - данные для отображения на Safetouch

В случае передачи в качестве параметра TOKEN_INFO_ALGORITHMS возвращается список алгоритмов, которые поддерживает устройство, в виде массива констант:

• PUBLIC_KEY_ALGORITHM_GOST3410_2001 - ГОСТ Р 34.10-2001
• PUBLIC_KEY_ALGORITHM_GOST3410_2012_256 - ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит
• PUBLIC_KEY_ALGORITHM_GOST3410_2012_512 - ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит
• PUBLIC_KEY_ALGORITHM_RSA - RSA

В случае передачи в качестве параметра TOKEN_INFO_FEATURES возвращается ассоциативный массив, определяющий возможности устройства, со следующими полями:

• journal:bool - поддержка журнала операций
• pin2:bool - поддержка ввода PIN-кода "PIN2" на устройстве
• visualization:bool - поддержка генерации ключей, требующих визуализации данных
• sm:bool - поддержка secure messaging
• flashDrive:bool - наличие flash-памяти
• rtc:bool - наличие часов реального времени
• confirmation:bool - поддержка генерации ключей, требующих подтверждения
• externalAuth:bool - поддержка внешней аутентификации
• customPin:bool - поддержка пользовательских PIN-кодов
• interfaces:array - поддерживаемые интерфейсы
• bio:enum - наличие биометрического считывателя
• smType:enum - тип secure messaging
• vendorModelName:bool - поддержка самоидентификации токена (имя модели устройства)

Для поля interfaces возможны варианты:

• INTERFACE_TYPE_USB - USB
• INTERFACE_TYPE_BT - Bluetooth
• INTERFACE_TYPE_UART - UART
• INTERFACE_TYPE_ISO - ISO 7816
• INTERFACE_TYPE_SD - SD-карта
• INTERFACE_TYPE_NFC - NFC

Для поля bio возможны варианты:

• BIO_TYPE_NOT_SUPPORTED - биометрия не поддерживается
• BIO_TYPE_NOT_SPECIFIED - биометрия поддерживается, но тип считывателя не удалось определить

Для поля smType возможны варианты:

• SECURE_MESSAGING_OFF - secure messaging отключен
• SECURE_MESSAGING_ON - secure messaging включен
• SECURE_MESSAGING_ENHANCED - secure messaging включен (усиленный режим)
• SECURE_MESSAGING_UNSUPPORTED - secure messaging не поддерживается
• SECURE_MESSAGING_NOT_SPECIFIED - secure messaging поддерживается, но тип определить не удалось

В случае передачи в качества параметра TOKEN_INFO_SUPPORTED_MECHANISMS возвращается ассоциативный массив, содержащий следующие поля:

• cipher - ассоциативный массив, содержащий поддерживаемые алгоритмы шифрования. Содержит поля:
  • hardware:array - аппаратные алгоритмы шифрования
  • software:array - программные алгоритмы шифрования
• hash - ассоциативный массив, содержащий поддерживаемые алгоритмы хеширования. Содержит поля:
  • hardware:array - аппаратные алгоритмы хеширования
  • software:array - программные алгоритмы хеширования
• sign - ассоциативный массив, содержащий поддерживаемые алгоритмы цифровой подписи. Содержит поля:
  • hardware:array - аппаратные алгоритмы подписи
  • software:array - программные алгоритмы подписи
• keyExchange - ассоциативный массив, содержащий поддерживаемые устройством алгоритмы выработки производного ключа. Содержит поля:
  • hardware:array - аппаратные алгоритмы выработки производного ключа
  • software:array - программные алгоритмы выработки производного ключа

Для вложенных полей поля cipher возможны варианты:

• CIPHER_ALGORITHM_GOST28147 - ГОСТ 28147-89
• CIPHER_ALGORITHM_AES128 - AES длина секретного ключа 128 бит
• CIPHER_ALGORITHM_AES192 - AES длина секретного ключа 192 бит
• CIPHER_ALGORITHM_AES256 - AES длина секретного ключа 256 бит

Для вложенных полей поля hash возможны варианты:

• HASH_TYPE_GOST3411_94 - ГОСТ Р 34.11-94
• HASH_TYPE_GOST3411_12_256 - ГОСТ Р 34.11-2012 длина хеш-кода 256 бит
• HASH_TYPE_GOST3411_12_512 - ГОСТ Р 34.11-2012 длина хеш-кода 512 бит
• HASH_TYPE_MD5 - MD5
• HASH_TYPE_SHA1 - SHA-1
• HASH_TYPE_SHA256 - SHA-2 длина хеш-кода 256 бит
• HASH_TYPE_SHA384 - SHA-2 длина хеш-кода 384 бит
• HASH_TYPE_SHA512 - SHA-2 длина хеш-кода 512 бит

Для вложенных полей поля sign возможны варианты:

• PUBLIC_KEY_ALGORITHM_GOST3410_2001 - ГОСТ Р 34.10-2001
• PUBLIC_KEY_ALGORITHM_GOST3410_2012_256 - ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит
• PUBLIC_KEY_ALGORITHM_GOST3410_2012_512 - ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит
• PUBLIC_KEY_ALGORITHM_RSA_512 - RSA длина закрытого ключа 512 бит
• PUBLIC_KEY_ALGORITHM_RSA_768 - RSA длина закрытого ключа 768 бит
• PUBLIC_KEY_ALGORITHM_RSA_1024 - RSA длина закрытого ключа 1024 бит
• PUBLIC_KEY_ALGORITHM_RSA_1280 - RSA длина закрытого ключа 1280 бит
• PUBLIC_KEY_ALGORITHM_RSA_1536 - RSA длина закрытого ключа 1536 бит
• PUBLIC_KEY_ALGORITHM_RSA_1792 - RSA длина закрытого ключа 1792 бит
• PUBLIC_KEY_ALGORITHM_RSA_2048 - RSA длина закрытого ключа 2048 бит
• PUBLIC_KEY_ALGORITHM_RSA_4096 - RSA длина закрытого ключа 4096 бит

Для вложенных полей поля keyExchange возможны варианты:

• PUBLIC_KEY_ALGORITHM_EXCHANGE_VKO_GOST3410_2001
• PUBLIC_KEY_ALGORITHM_EXCHANGE_VKO_GOST3410_2012_256
• PUBLIC_KEY_ALGORITHM_EXCHANGE_VKO_GOST3410_2012_512

В случае передачи в качестве параметра TOKEN_INFO_SPEED возвращается константа, определяющая класс скорости устройства (выше класс - выше скорость). Возможные варианты: 1 - 5.

В случае передачи в качестве параметра TOKEN_INFO_PINS_INFO возвращается ассоциативный массив, содержащий информацию о PIN-кодах, со следующими полями:

• isPinCached:bool - сохранён ли PIN-код
• isPinDefault:bool - установлен ли PIN-код пользователя по умолчанию
• isAdminPinDefault:bool - установлен ли PIN-код администратора по умолчанию
• canUserChangeUserPin:bool - может ли пользователь сменить PIN-код пользователя
• canAdminChangeUserPin:bool - может ли администратор сменить PIN-код пользователя
• retriesLeft:integer - оставшееся количество попыток ввода PIN-кода пользователя

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

Получение журнала операций на токене и его журнала, сформированной на соответствующем ключе. Если с момента подключения токена никаких операций не производилось будет возвращен null

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	keyId	string			Идентификатор ключа
3	options	object			Массив, содержащий дополнительные параметры - объекты вида {параметр:значение} (зарезервирован для будущего использования)

Возвращает:

Ассоциативный массив с полями journal и signature

getKeyByCertificate(deviceId, certId) → {string}

Получение идентификатора ключевой пары по сертификату. Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certId	string			Идентификатор сертификата

Возвращает:

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

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

Получение информации о ключе. Тип информации задается константами: KEY_INFO_ALGORITHM, KEY_INFO_SPEC, KEY_INFO_USAGE_PERIOD. Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	keyId	string			Идентификатор ключа
3	option	number			Тип запрашиваемой информации (тип алгоритма, дата начала/конца действия закрытого ключа)

Возвращает:

В случае передачи KEY_INFO_ALGORITHM - число, равное одной из констант (числовые значения констант в общем случае не совпадают с реальными значениями длин ключей):

•   PUBLIC_KEY_ALGORITHM_GOST3410_2001 - ГОСТ Р 34.10-2001
•   PUBLIC_KEY_ALGORITHM_GOST3410_2012_256 - ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит
•   PUBLIC_KEY_ALGORITHM_GOST3410_2012_512 - ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит
•   PUBLIC_KEY_ALGORITHM_RSA_512 - RSA длина закрытого ключа 512 бит
•   PUBLIC_KEY_ALGORITHM_RSA_768 - RSA длина закрытого ключа 768 бит
•   PUBLIC_KEY_ALGORITHM_RSA_1024 - RSA длина закрытого ключа 1024 бит
•   PUBLIC_KEY_ALGORITHM_RSA_1280 - RSA длина закрытого ключа 1280 бит
•   PUBLIC_KEY_ALGORITHM_RSA_1536 - RSA длина закрытого ключа 1536 бит
•   PUBLIC_KEY_ALGORITHM_RSA_1792 - RSA длина закрытого ключа 1792 бит
•   PUBLIC_KEY_ALGORITHM_RSA_2048 - RSA длина закрытого ключа 2048 бит
•   PUBLIC_KEY_ALGORITHM_RSA_4096 - RSA длина закрытого ключа 4096 бит

В случае передачи KEY_INFO_SPEC - Назначение ключевой пары:

• KEY_SPEC_SIGN - подпись
• KEY_SPEC_SIGN_AND_EXCHANGE - подпись и обмен

В случае передачи KEY_INFO_USAGE_PERIOD - объект, содержащий опциональные поля в формате Unix-время (целое число секунд, прошедших с 1970.01.01.00:00:00):

• notBefore:number - дата начала валидности закрытого ключа
• notAfter:number - дата окончания валидности закрытого ключа
• Инварианты полей notBefore/notAfter:
  • существующая дата

getKeyLabel(deviceId, keyId) → {string}

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	keyId	string			Идентификатор ключа

Возвращает:

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

getLicence(deviceId, licenceId) → {object}

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	licenceId	number			Идентификатор лицензии (значения 1, 2)

Возвращает:

Ассоциативный массив с полями journal и signature

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

Получение значения открытого ключа. Не поддерживается для ключей RSA. Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	keyId	string			Идентификатор ключа
3	options	object			Массив, содержащий дополнительные параметры - объекты вида {параметр:значение} (зарезервирован для будущего использования)

Возвращает:

Открытый ключ (hex)

getStoreCertificate(certId, options) → {string}

Получение тела сертификата из системного хранилища в PEM. Аргумент options принимает параметры поиска сертификатов. Зарезервирован для будущего использования.

Параметры:

	Name	Type	Attributes	Default	Description
1	certId	string			Идентификатор сертификата
2	options	object			Массив, содержащий дополнительные параметры - объекты вида {параметр:значение}

Возвращает:

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

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

Импорт сертификата на устройство. Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certificate	string			Тело сертификата в формате PEM
3	category	number			Тип сертификата, задается константами: CERT_CATEGORY_UNSPEC - категория сертификата не уточняется CERT_CATEGORY_USER - пользовательский сертификат. Может быть использован в операциях, требующих операцию подписи CERT_CATEGORY_CA - доверенный в рамках текущего устройства сертификат CERT_CATEGORY_OTHER - сертификат третьей стороны

Возвращает:

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

login(deviceId, pin)

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	pin	string			PIN-код доступа к устройству

logout(deviceId)

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства

parseCertificate(deviceId, certId) → {object}

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certId	string			Идентификатор сертификата, полученный в результате вызова enumerateCertificates

Возвращает:

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

parseCertificateFromString(text) → {object}

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

Параметры:

	Name	Type	Attributes	Default	Description
1	text	string			Тело сертификата в PEM

Возвращает:

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

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

Подпись на ключе. Аргумент options принимает параметры подписи. Доступны следующие опции (в скобках указано значение по умолчанию):

• computeHash:bool (false) - должен быть true, если data — текстовые данные (хеш считается только для ключей ГОСТ)
• useHardwareHash:bool (false) - производить аппаратное хеширование данных, только если computeHash = true
• hashAlgorithm:enum - алгоритм хеширования. Для ключей RSA обязателен, даже если computeHash выставлен в false. Для ключей ГОСТ, если не задан, будет выбран автоматически. Варианты: HASH_TYPE_GOST3411_94, HASH_TYPE_GOST3411_12_256, HASH_TYPE_GOST3411_12_512, HASH_TYPE_MD5, HASH_TYPE_SHA1, HASH_TYPE_SHA256, HASH_TYPE_SHA384, HASH_TYPE_SHA512.

Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	keyId	string			Идентификатор закрытого ключа
3	data	string			Подписываемый хеш (hex-строка) или текстовые данные
4	options	object			Массив, содержащий параметры подписи - объекты вида {параметр:true/false}

Возвращает:

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

readBinaryFile(deviceId, fileName) → {string}

Чтение бинарного файла (далее БФ).
Приватные БФ доступны только из приватной сессии. Подробно об ограничениях на БФ написано в createBinaryFile.


Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	fileName	string			Имя (идентификатор) БФ, полученное в результате вызова enumerateBinaryFiles

Возвращает:

Тело считанного БФ

removePin(deviceId)

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства

savePin(deviceId)

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

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства

setCertLabel(deviceId, certId, label)

Установка метки сертификата. Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certId	string			Идентификатор сертификата
3	label	string			Новая метка сертификата

setKeyLabel(deviceId, keyId, label)

Установка метки закрытого ключа. Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

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

setLicence(deviceId, licenceId, licence)

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

Параметры:

	Name	Type	Attributes	Default	Description
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).
Аргумент options принимает параметры подписи. Доступны следующие опции (в скобках указано значение по умолчанию):

• detached:bool (false) - генерировать отсоединенную подпись
• addUserCertificate:bool (true) - включить в подпись сертификат пользователя
• addEssCert:bool (false) - включить в подпись хеш от сертификата пользователя и серийный номер сертификата
• addSignTime:bool (false) - включить в подпись локальное время
• useHardwareHash:bool (false) - производить аппаратное хеширование данных на ключах ГОСТ
• rsaHashAlgorithm:enum - алгоритм хеширования при использовании ключей RSA, варианты: HASH_TYPE_MD5, HASH_TYPE_SHA1, HASH_TYPE_SHA256, HASH_TYPE_SHA384, HASH_TYPE_SHA512.
• CMS:string (empty) - уже сформированный CMS, в который требуется добавить подпись. Если в CMS подпись отсоединённая, то параметр data должен присутствовать и соответствовать данным, подпись которых находится в CMS, если в CMS подпись не отсоединённая, то параметр data должен быть пустым если CMS отсутствует, то будет создан новый CMS
• eContentType:string (empty) - задать тип содержимого CMS (OID, напр. "1.2.3.4"). Требует отсутствия опции CMS. Требует опции addSignTime == true.


• addSystemInfo:bool (false) - включать информацию о месте подписи. Требует опции addSignTime == true. Добавляет в подписанные атрибуты ASN1 последовательность с OID 1.2.643.2.74.2.1.1.1. Внутри содержится поле типа INTEGER, обозначающее версию формата UTF8String строки. В случае невозможности получения значения какого-либо элемента информации о компьютере формат строки будет сохранен, а значение элемента пропущено.
  SEQUENCE {
    OBJECTIDENTIFIER 1.2.643.2.74.2.1.1.1
    SET {
      SEQUENCE {
        INTEGER 0x01 (1 decimal)
        UTF8String 'DateTime:[Дата и время];MachineId:[Уникальный идентификатор рабочей станции];OS:[Информация об ОС];Username:[Имя пользователя];IP-MAC:[adapter1-MAC] [adapter1-ipv4-1] [apdater1-ipv4-2] [apdater1-ipv6-1] [apdater1-ipv6-2], [apdater2-MAC] [adapter2-ipv4-1] [apdater2-ipv4-2] [apdater2-ipv6-1] [apdater2-ipv6-2]'
      }
    }
  }
  В элементе "IP-MAC" будут содержаться типы IPv4 и IPv6 адресов в следующем порядке: Unicast, Anycast и Multicast.


• addSecurityProductsInfo:bool (false) - включать информацию об установленных продуктах безопасности. Требует опции addSignTime == true. Добавляет в подписанные атрибуты ASN1 последовательность с OID 1.2.643.2.74.2.1.1.2. Внутри содержится поле типа INTEGER, обозначающее версию формата UTF8String строки. В случае невозможности получения списка продуктов безопасности UTF8String строка будет пустой.
  SEQUENCE {
    OBJECTIDENTIFIER 1.2.643.2.74.2.1.1.2
    SET {
      SEQUENCE {
        INTEGER 0x01 (1 decimal)
        UTF8String
      }
    }
  }
  UTF8String является закодированным в формате Json списком структур, содержащих следующие поля:
  • productType:string - тип продукта, варианты: Antivirus, Antispyware, Firewall.
  • name:string - название продукта.
  • state:string - состояние продукта, варианты: On, Off, Snoozed, Out of date.
  • timestamp:string - метка времени продукта (может отсутствовать).
  • signatureStatus:string - статус продукта, варианты: Up to date, Out of date
• tspOptions:object (null) - параметры добавления метки времени. Доступны следующие опции:
  • url:string - адрес TSA сервера. При подключении будут учтены системные настройки прокси. На данный момент поддерживаются только TSA серверы, работающие по протоколу HTTP.
  • digestAlg:enum - алгоритм хеширования, варианты: HASH_TYPE_GOST3411_12_256, HASH_TYPE_GOST3411_12_512, HASH_TYPE_SHA1, HASH_TYPE_SHA256, HASH_TYPE_SHA384, HASH_TYPE_SHA512;
  • policy:string (empty) - политика, по которой ожидается создание метки времени
  • cert:bool (false) - указать, что серверу требуется включить сертификат подписи в ответ
  • nonce:bool (true) - включить псевдослучайное 64 битное число в запрос
  • extensions:object - массив, содержащий расширения в виде: {oid: "1.2.3", value: "MA0GCCqFAwICLgAIAgEB", criticality: false}
  • verifyTsToken:bool (true) - проверить метку доверенного времени
  • certificates:string[] (null) - набор сертификатов в PEM формате, на которых необходимо проверять подпись полученной метки времени, при этом сертификат, который может содержаться в метке доверенного времени, будет проигнорирован;
  • CA:string[] (null) - список дополнительных корневых сертификатов в PEM формате для проверки сертификата, кроме них берутся сертификаты с устройства;
  • CRL:string[] (null) - список отозванных сертификатов в PEM формате;
  Минимально требуемым набором параметров добавления метки времени являются url и digestAlg с корректным указанием опций проверки ответа TSA сервера. Для проверки полученного ответа через плагин необходимо передать сертификат TSA сервера (если включение данного сертификата в метку времени не производилось), необходимые промежуточные сертификаты, а также доверенные корневые сертификаты. При проверке ответа через внешнее ПО, проверка в плагине может быть отключена путем присвоения значения false опции verifyTsToken.
  Обращаем внимание, что проверка метки времени должна быть осуществлена согласно Приказу Министерства цифрового развития, связи и массовых коммуникаций Российской Федерации от 06.11.2020 № 580 "Об утверждении порядка создания и проверки метки доверенного времени"

Любая сформированная подпись, возвращенная этой функцией, соответствует формату CMS. Чтобы сформировать CAdES-BES подпись, опциям addEssCert и addSignTime требуется присвоить значение true. Для формирования CAdES-T подписи требуется присвоить значение true опциям addEssCert и addSignTime, а также передать корректные параметры добавления метки времени.
Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	certId	string			Идентификатор сертификата
3	data	string			Подписываемые данные (текстовая строка или base64-encoded бинарные данные)
4	dataFormat	number			Формат данных. Возможные варианты: DATA_FORMAT_PLAIN, DATA_FORMAT_BASE64, DATA_FORMAT_HASH. Если формат данных - DATA_FORMAT_HASH, то в параметр data передается посчитанный хеш сообщения (hex-строка), при этом необходимо выставить опцию detached в true.
5	options	object			Массив, содержащий параметры подписи - объекты вида {параметр:true/false}

Возвращает:

Электронно-цифровая подпись (base64)

unblockUserPin(deviceId, adminPin)

Разблокирует заблокированный PIN-код пользователя. Пользователь не должен быть авторизован.

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	adminPin	string			PIN-код Администратора

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

Проверка цифровой подписи. Аргумент options принимает параметры проверки подписи. Доступны следующие опции (в скобках указано значение по умолчанию):

• data:string (null) - подписанные данные (текстовые или base64-encoded), только в случае detached подписи;
• base64:bool (false) - указывает, закодированы ли данные, переданные в data, в base64;
• certificates:string[] (null) - набор сертификатов в PEM формате, на которых необходимо проверять подпись, при этом сертификаты, которые содержатся в cms, будут проигнорированы;
• CA:string[] (null) - список дополнительных корневых сертификатов в PEM формате для проверки сертификата, кроме них берутся сертификаты с устройства;
• CRL:string[] (null) - список отозванных сертификатов в PEM формате;
• useHardwareHash:bool (false) - производить хеширование на устройстве (игнорируется для алгоритмов отличных от ГОСТ Р 34.10-2001);
• verifyCertificate:bool (true) - проверить сертификат пользователя;

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	cms	string			Контейнер с цифровой подписью
3	options	object			Массив, содержащий параметры проверки подписи - объекты вида {параметр:значение}

Возвращает:

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

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

Проверка метки доверенного времени. Аргумент options принимает параметры проверки подписи. Доступны следующие опции (в скобках указано значение по умолчанию):

• certificates:string[] (null) - набор сертификатов в PEM формате, на которых необходимо проверять подпись, при этом сертификат, который может содержаться в метке доверенного времени, будет проигнорирован;
• CA:string[] (null) - список дополнительных корневых сертификатов в PEM формате для проверки сертификата, кроме них берутся сертификаты с устройства;
• CRL:string[] (null) - список отозванных сертификатов в PEM формате;

Параметры:

	Name	Type	Attributes	Default	Description
1	deviceId	number			Идентификатор устройства
2	response	string			base-64 encoded метка доверенного времени (TSResponse)
3	data	string			Запрос метки доверенного времени (TSRequest)
4	dataFormat	number			Формат данных. Возможные варианты: DATA_FORMAT_BASE64.
5	options	object			Массив, содержащий параметры проверки подписи - объекты вида {параметр:значение}

Возвращает:

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