API v4.6.0.0

Class: CryptoPlugin

Главный класс плагина. Реализует всю функциональность плагина. Для работы с плагином рекомендуется использовать модуль-обертку: https://github.com/AktivCo/rutoken-plugin-js

Новый асинхронный интерфейс

Все интерфейсные функции плагина возвращают promise и работают асинхронно. Сразу после вызова все функции возвращают управление. В случае успешного выполнения возвращенный promise переходит в состояние "fulfilled", в случае ошибки — в состояние "rejected". В соответствующий обработчик будет передан или результат выполнения или код произошедшей ошибки.

Устаревший интерфейс

Так же, в целях сохранения совместимости плагин поддерживает старый интерфейс, основанный на функциях обратного вызова. Мы рекомендуем использовать новый интерфейс с promise.

Интерфейсные функции плагина могут вызываться двумя способами: асинхронно и синхронно. При использовании синхронных вызовов происходит блокирование интерфейса браузера на время выполнения функции.

Асинхронный интерфейс

Все функции принимают resultCallback и errorCallback двумя последними параметрами и работают асинхронно. Сразу после вызова все функции возвращают управление. Функция вызывает resultCallback в случае успешного выполнения и errorCallback в случае ошибки. resultCallback принимает один параметр - результат выполнения операции. errorCallback - принимает код ошибки первым параметром.

Cинхронный интерфейс

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

Пример:
//Использование интерфейса с promise
window.onload = function () {
   rutoken.ready.then(function () {
       if (window.chrome || typeof InstallTrigger !== 'undefined') {
           return rutoken.isExtensionInstalled();
       } else {
           return Promise.resolve(true);
      }
  }).then(function (result) {
      if (result) {
          return rutoken.isPluginInstalled();
      } else {
          throw "Rutoken Extension wasn't found";
      }
  }).then(function (result) {
      if (result) {
          return rutoken.loadPlugin();
      } else {
          throw "Rutoken Plugin wasn't found";
      }
  }).then(function (plugin) {
     //Можно начинать работать с плагином

      return plugin.enumerateDevices();
  }).then(onSuccess(result), onError(reason));
}
//Для работы со старым интерфейсом
plugin.wrapWithOldInterface()
.then(function (wrappedPlugin) {
    //Можно начинать работать через старый интерфейс плагина

    //Использование старого асинхронного интерфейса
    wrappedPlugin.enumerateDevices(
        function(devices) {
            console.log(devices);
        },
        function(error) {
            console.log(error);
        });
    //Использование синхронного интерфейса
    var devices = Array();
    try {
        devices = plugin.enumerateDevices();
    }
    catch (error) {
        console.log(error);
    }
});

Резюме

Свойства

errorCodes :weak_ptr< ErrorCodesApi >
valid :boolean
version :string

Методы

authenticate(deviceId, certId, salt) → {string}
Аутентификация по сертификату. Не поддерживается для ключей RSA. Для выполнения этой функции требуется авторизоваться на устройстве.
changePin(deviceId, authPin, newPin, options)
Изменение PIN-кода пользователя.
cmsDecrypt(deviceId, keyId, cmsData, options) → {string}
Расшифрование данных в формате CMS. Аргумент options принимает параметры расшифрования. Доступны следующие опции (в скобках указано значение по умолчанию):
  • base64:bool (false) - получить расшифрованные данные в base64
Для выполнения этой функции требуется авторизоваться на устройстве.
cmsEncrypt(deviceId, certId, recipientCerts, data, options) → {string}
Шифрование данных в формате CMS. Аргумент options принимает параметры шифрования. Доступны следующие опции (в скобках указано значение по умолчанию):
  • base64:bool (false) - закодированы ли переданные данные в base64
  • cipherAlgorithm:enum - алгоритм шифрования в режиме cbc (необходимо указывать только для ключей RSA), варианты: CIPHER_ALGORITHM_DES, CIPHER_ALGORITHM_3DES, CIPHER_ALGORITHM_AES128, CIPHER_ALGORITHM_AES192, CIPHER_ALGORITHM_AES256
Для выполнения этой функции требуется авторизоваться на устройстве.
createPkcs10(deviceId, keyId, subject, extensions, options) → {string}
Формирование самоподписанного PKCS#10 запроса Для выполнения этой функции требуется авторизоваться на устройстве.
createTsRequest(data, dataFormat, hashType, options) → {string}
Создание запроса на метку времени. Аргумент options принимает следующие параметры (в скобках указано значение по умолчанию):
  • policy:string (empty) - политика, по которой ожидается создание метки времени
  • cert:bool (false) - указать, что серверу требуется включить сертификат подписи в ответ
  • nonce:bool (true) - включить псевдослучайное 64 битное число в запрос
  • extensions:object - массив, содержащий расширения в виде: {oid: "1.2.3", value: "MA0GCCqFAwICLgAIAgEB", criticality: false}
deleteCertificate(deviceId, certId)
Удаление сертификата с устройства. Для выполнения этой функции требуется авторизоваться на устройстве.
deleteKeyPair(deviceId, keyId)
Удаление ключевой пары Для выполнения этой функции требуется авторизоваться на устройстве.
derive(deviceId, keyId, publicKey, options) → {string}
Выработка ключа обмена. Аргумент options принимает параметры выработки. Доступны следующие опции (в скобках указано значение по умолчанию):
  • ukm:string (00:00:00:00:00:00:00:01) - Синхропосылка (hex-строка)
Для выполнения этой функции требуется авторизоваться на устройстве.
digest(deviceId, hashType, data, options) → {string}
Вычисления хеша. Аргумент options принимает параметры хеширования. Доступны следующие опции (в скобках указано значение по умолчанию):
  • useHardwareHash:bool (false) - производить аппаратное хеширование данных
  • base64:bool (false) - указывает, закодированы ли данные, переданные в data, в base64;
enumerateCertificates(deviceId, category) → {string[]}
Получение массива с идентификаторами сертификатов.
enumerateDevices(options) → {number[]}
Получение идентификаторов доступных устройств. Аргумент options опционален и принимает параметры перебора подключенных устройств. Доступны следующие опции (в скобках указано значение по умолчанию):
  • mode:enum (ENUMERATE_DEVICES_LIST) - тип получаемой информации об устройствах, доступны варианты:
    • ENUMERATE_DEVICES_LIST - получить список доступных устройств;
    • ENUMERATE_DEVICES_EVENTS - получить списки подключенных и отключенных устройств;
enumerateKeys(deviceId, marker) → {string[]}
Получение массива с идентификаторами закрытых ключей в HEX. Для выполнения этой функции требуется авторизоваться на устройстве.
enumerateStoreCertificates(options) → {string[]}
Получение массива с идентификаторами установленных в системном хранилище сертификатов. Аргумент options принимает параметры перебора сертификатов. Зарезервирован для будущего использования.
formatToken(deviceId, options)
Форматирование токена. Аргумент options принимает параметры форматирования. Доступны следующие опции (в скобках указано значение по умолчанию):
  • adminPin:string ("87654321") - текущий PIN-код Администратора;
  • newUserPin:string ("12345678") - PIN-код после форматирования;
  • label:string - метка токена (если опция отсутствует, устанавливается текущая);
generateKeyPair(deviceId, reserved, marker, options) → {string}
Генерация ключевой пары на устройстве. Для выполнения этой функции требуется авторизоваться на устройстве. Аргумент 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 - задает параметры ключевой пары. Если опция не задана, будут выбраны параметры А для любого из алгоритмов ГОСТ. Возможные варианты:
    • ГОСТ Р 34.10-2001:
      • "A"
      • "B"
      • "C"
      • "XA"
      • "XB"
    • ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит:
      • "A"
      • "B"
      • "C"
      • "XA"
      • "XB"
    • ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит:
      • "A"
      • "B"
  • keyType:enum(KEY_TYPE_COMMON) - тип ключевой пары, доступны варианты:
    • KEY_TYPE_COMMON - обычная ключевая пара;
    • KEY_TYPE_JOURNAL - журнальная ключевая пара (может быть использована только для подписи журнала);
Для ключевой пары типа KEY_TYPE_COMMON так же доступны следующие атрибуты:
getCertificate(deviceId, certId) → {string}
Получение тела сертификата в PEM.
getCertificateInfo(deviceId, certId, option) → {object}
Получение информации о сертификате. Тип информации задается константами: CERT_INFO_SERIAL_NUMBER. Для выполнения этой функции требуется авторизоваться на устройстве.
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) - свободное место на токене в байтах.
getDeviceLabel(deviceId) → {string}
Получение метки устройства
getDeviceModel(deviceId) → {string}
Получение строки с моделью устройства, понятной для человека. Внимание: возвращаемая строка может меняться в будущем.
getDeviceType(deviceId) → {Promise< FB::variant >}
Получение константы, обозначающей тип устройства.
getJournal(deviceId, keyId, options) → {object}
Получение журнала операций на токене и его журнала, сформированной на соответствующем ключе. Если с момента подключения токена никаких операций не производилось будет возвращен null
getKeyByCertificate(deviceId, certId) → {string}
Получение идентификатора ключевой пары по сертификату. Для выполнения этой функции требуется авторизоваться на устройстве.
getKeyInfo(deviceId, keyId, option) → {object}
Получение информации о ключе. Тип информации задается константами: KEY_INFO_ALGORITHM. Для выполнения этой функции требуется авторизоваться на устройстве.
getKeyLabel(deviceId, keyId) → {string}
Получение метки закрытого ключа. Для выполнения этой функции требуется авторизоваться на устройстве.
getLicence(deviceId, licenceId) → {object}
Получение лицензии с токена
getPublicKeyValue(deviceId, keyId, options) → {string}
Получение значения открытого ключа. Не поддерживается для ключей RSA. Для выполнения этой функции требуется авторизоваться на устройстве.
getStoreCertificate(certId, options) → {string}
Получение тела сертификата из системного хранилища в PEM. Аргумент options принимает параметры поиска сертификатов. Зарезервирован для будущего использования.
importCertificate(deviceId, certificate, category) → {string}
Импорт сертификата на устройство. Для выполнения этой функции требуется авторизоваться на устройстве.
login(deviceId, pin)
Авторизация на устройстве
logout(deviceId)
Закрытие сессии
parseCertificate(deviceId, certId) → {object}
Получение ассоциативного массива с разобранными полями из сертификата.
parseCertificateFromString(text) → {object}
Получение ассоциативного массива с разобранными полями из сертификата.
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_SHA512.
Для выполнения этой функции требуется авторизоваться на устройстве.
removePin(deviceId)
Удаление закешированного PIN-кода из файла.
savePin(deviceId)
Сохранение PIN-кода в файл для автоматической аутентификации.
setKeyLabel(deviceId, keyId, label)
Установка метки закрытого ключа. Для выполнения этой функции требуется авторизоваться на устройстве.
setLicence(deviceId, licenceId, licence)
Запись лицензии на токен
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_SHA512.
  • CMS:string (empty) - уже сформированный CMS, в который требуется добавить подпись. Если в CMS подпись отсоединённая, то параметр data должен присутствовать и соответствовать данным, подпись которых находится в CMS, если в CMS подпись неотсоединённая, то параметр data должен быть пустым если CMS отсутствует, то будет создан новый CMS
  • eContentType:string (empty) - задать тип содержимого CMS (OID, напр. "1.2.3.4"). Требует отсутствия опции CMS. Tребует опции addSignTime == true.

  • addSystemInfo:bool (false) - включать информацию о месте подписи. Tребует опции 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_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, а также передать корректные параметры добавления метки времени.
Для выполнения этой функции требуется авторизоваться на устройстве.
unblockUserPin(deviceId, adminPin)
Разблокирует заблокированный 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) - проверить сертификат пользователя;
verifyTsResponse(deviceId, response, data, dataFormat, options) → {bool}
Проверка метки доверенного времени. Аргумент options принимает параметры проверки подписи. Доступны следующие опции (в скобках указано значение по умолчанию):
  • certificates:string[] (null) - набор сертификатов в PEM формате, на которых необходимо проверять подпись, при этом сертификат, который может содержаться в метке доверенного времени, будет проигнорирован;
  • CA:string[] (null) - список дополнительных корневых сертификатов в PEM формате для проверки сертификата, кроме них берутся сертификаты с устройства;
  • CRL:string[] (null) - список отозванных сертификатов в PEM формате;

Подробно

Свойства

errorCodes :weak_ptr< ErrorCodesApi >

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

valid :boolean

Правильно созданный объект всегда возвращает true

version :string

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

Методы

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

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата
3
saltstringАутентификационные данные
Возвращает:

Строка для аутентификации в формате CMS

changePin(deviceId, authPin, newPin, options)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
authPinstringСтарый PIN-код пользователя или PIN-код администратора
3
newPinstringНовый PIN-код пользователя
4
optionsobjectМассив, содержащий дополнительные параметры - объекты вида {параметр:значение}
  • useAdminPin:bool (false) - если опция выставлена в false, параметр authPin считается старым PIN-кодом пользователя, если в true - PIN-кодом Администратора и пользователь не должен быть авторизован
cmsDecrypt(deviceId, keyId, cmsData, options) → {string}

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

  • base64:bool (false) - получить расшифрованные данные в base64
Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
keyIdstringИдентификатор ключа для расшифровыания
3
cmsDatastringCMS-сообщение, содержащие зашифрованные данные
4
optionsobjectМассив, содержащий параметры расшифрования - объекты вида {параметр:значение}
Возвращает:

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

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

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

  • base64:bool (false) - закодированы ли переданные данные в base64
  • cipherAlgorithm:enum - алгоритм шифрования в режиме cbc (необходимо указывать только для ключей RSA), варианты: CIPHER_ALGORITHM_DES, CIPHER_ALGORITHM_3DES, CIPHER_ALGORITHM_AES128, CIPHER_ALGORITHM_AES192, CIPHER_ALGORITHM_AES256
Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата, зарезервированно для будущего использования
3
recipientCertsobjectмассив, содержащий сертификаты получателей в формате PEM
4
datastringЗашифровываемые данные (текстовая строка или base64-encoded бинарные данные)
5
optionsobjectМассив, содержащий параметры шифрования - объекты вида {параметр:значение}
Возвращает:

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

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

Формирование самоподписанного PKCS#10 запроса Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
keyIdstringИдентификатор ключа
3
subjectobjectМассив, содержащий объекты вида: {rdn: "commonName", value: "значение"}
4
extensionsobjectАссоциативный массив, содержащий массивы расширений: {keyUsage: ["digitalSignature",...], extKeyUsage: ["oid", "longName" ], certificatePolicies: ["OID", ...]}
5
optionsobjectДополнительные опции: subjectSignTool:string - значение соответствующего расширения; hashAlgorithm:enum - алгоритм хеширования, варианты: 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_SHA512; customExtensions:object - массив, содержащий объекты вида: {oid: "1.2.3", value: "MA0GCCqFAwICLgAIAgEB", criticality: false}.
Возвращает:

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:  "pseudonymus"
           }
           ,{
               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 extensions = {
           "keyUsage":            keyUsageVal,
           "extKeyUsage":         extKeyUsageVal,
           "certificatePolicies": certificatePolicies
       };
       var options = {
           "subjectSignTool":     'СКЗИ "РУТОКЕН ЭЦП"',
           "hashAlgorithm":       plugin.HASH_TYPE_GOST3411_94,
           "customExtensions":    [
               {
                   oid: "1.3.6.1.4.1.311.21.7",
                   value: "MA0GCCqFAwICLgAIAgEB",
                   criticality: false
               }
           ];
       };
       plugin.createPkcs10(deviceID, keyID, subject, extensions, options,
               this.printResult, this.printError);
   }


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

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

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

Параметры:
Name Type Attributes Default Description
1
datastringданные, для которых нужно создать метку времени
2
dataFormatnumberФормат данных. Возможные варианты: DATA_FORMAT_BASE64, DATA_FORMAT_HASH. Если формат данных - DATA_FORMAT_HASH, то в параметр data передается посчитанный хеш от данных (hex-строка).
3
hashTypenumberИдентификатор алгоритма хеширования
4
optionsobjectДополнительные опции
Возвращает:

Запрос (base64)

Для параметра hashType возможны варианты:
  • 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_SHA512 - SHA-2 длина хеш-кода 512 бит

deleteCertificate(deviceId, certId)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата, полученный в результате вызова enumerateCertificates
deleteKeyPair(deviceId, keyId)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
keyIdstringИдентификатор закрытого ключа из ключевой пары
derive(deviceId, keyId, publicKey, options) → {string}

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

  • ukm:string (00:00:00:00:00:00:00:01) - Синхропосылка (hex-строка)
Для выполнения этой функции требуется авторизоваться на устройстве.

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
keyIdstringИдентификатор закрытого ключа
3
publicKeystringОткрытый ключ (hex-строка)
4
optionsobjectМассив, содержащий параметры подписи - объекты вида {параметр:true/false}
Возвращает:

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

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

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

  • useHardwareHash:bool (false) - производить аппаратное хеширование данных
  • base64:bool (false) - указывает, закодированы ли данные, переданные в data, в base64;

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
hashTypenumberИдентификатор алгоритма хеширования
3
datastringХешируемые данные (текстовые или base64-строка)
4
optionsobjectМассив, содержащий параметры хеширования - объекты вида {параметр:true/false}
Возвращает:

Хеш (hex)

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

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
categorynumberТип сертификата: CERT_CATEGORY_UNSPEC, CERT_CATEGORY_USER, CERT_CATEGORY_CA или CERT_CATEGORY_OTHER, см. описание функции importCertificate
Возвращает:

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

enumerateDevices(options) → {number[]}

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

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

Параметры:
Name Type Attributes Default Description
1
optionsobjectМассив, содержащий дополнительные параметры - объекты вида {параметр:значение}
Возвращает:

В случае передачи в качестве параметра ENUMERATE_DEVICES_LIST возвращается список идентификаторов подключенных устройств. В случае передачи в качестве параметра ENUMERATE_DEVICES_EVENTS возвращаются списки подключенных и отключенных устройств в виде ассоциативного массива:

  • connected - список устройств, которые были подключены
    • disconnected - список устройств, которые были отключены

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

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

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
markerstringИдентификатор группы ключей, "" - все ключи
Возвращает:

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

enumerateStoreCertificates(options) → {string[]}

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

Параметры:
Name Type Attributes Default Description
1
optionsobjectМассив, содержащий дополнительные параметры - объекты вида {параметр:значение}
Возвращает:

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

formatToken(deviceId, options)

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

  • adminPin:string ("87654321") - текущий PIN-код Администратора;
  • newUserPin:string ("12345678") - PIN-код после форматирования;
  • label:string - метка токена (если опция отсутствует, устанавливается текущая);

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
optionsobjectМассив, содержащий дополнительные параметры - объекты вида {параметр:значение}
generateKeyPair(deviceId, reserved, marker, options) → {string}

Генерация ключевой пары на устройстве. Для выполнения этой функции требуется авторизоваться на устройстве. Аргумент 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 - задает параметры ключевой пары. Если опция не задана, будут выбраны параметры А для любого из алгоритмов ГОСТ. Возможные варианты:
    • ГОСТ Р 34.10-2001:
      • "A"
      • "B"
      • "C"
      • "XA"
      • "XB"
    • ГОСТ Р 34.10-2012 длина закрытого ключа 256 бит:
      • "A"
      • "B"
      • "C"
      • "XA"
      • "XB"
    • ГОСТ Р 34.10-2012 длина закрытого ключа 512 бит:
      • "A"
      • "B"
  • keyType:enum(KEY_TYPE_COMMON) - тип ключевой пары, доступны варианты:
    • KEY_TYPE_COMMON - обычная ключевая пара;
    • KEY_TYPE_JOURNAL - журнальная ключевая пара (может быть использована только для подписи журнала);
Для ключевой пары типа KEY_TYPE_COMMON так же доступны следующие атрибуты:

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
reservedstringЗарезервировано для будущего использования (необходимо передавать undefined)
3
markerstringИдентификатор группы ключей
4
optionsobjectДополнительные свойства ключевой пары в виде ассоциативного массива, см. подробное описание функции
Возвращает:

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(':');
}
 
getCertificate(deviceId, certId) → {string}

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата
Возвращает:

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

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

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

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата
3
optionnumberТип запрашиваемой информации
Возвращает:

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

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) - свободное место на токене в байтах.

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
optionnumberТип запрашиваемой информации
Возвращает:

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

В случае передачи в качестве параметра 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
Для поля 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 - программные алгоритмы подписи
Для вложенных полей поля cipher возможны варианты:
  • CIPHER_ALGORITHM_GOST28147 - ГОСТ 28147-89
  • CIPHER_ALGORITHM_DES - DES
  • CIPHER_ALGORITHM_3DES - Triple DES
  • 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_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 бит
В случае передачи в качестве параметра 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-кода пользователя

getDeviceLabel(deviceId) → {string}

Получение метки устройства

Deprecated:
Внимание: начиная с версии 0.15.0.0, функция не поддерживается и может быть удалена в последующих версиях плагина. Используйте метод getDeviceInfo.
Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
Возвращает:

Метка устройства

getDeviceModel(deviceId) → {string}

Получение строки с моделью устройства, понятной для человека. Внимание: возвращаемая строка может меняться в будущем.

Deprecated:
Внимание: начиная с версии 0.15.0.0, функция не поддерживается и может быть удалена в последующих версиях плагина. Используйте метод getDeviceInfo.
Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
Возвращает:

Тип устройства в виде человеко-понятной строки

getDeviceType(deviceId) → {Promise< FB::variant >}

Получение константы, обозначающей тип устройства.

Deprecated:
Внимание: начиная с версии 0.15.0.0, функция не поддерживается и может быть удалена в последующих версиях плагина. Используйте метод getDeviceInfo.
Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
Возвращает:

deviceType Тип устройства в виде числовой константы

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

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

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

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

getKeyByCertificate(deviceId, certId) → {string}

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата
Возвращает:

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

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

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

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
keyIdstringИдентификатор ключа
3
optionnumberТип запрашиваемой информации (тип алгоритма)
Возвращает:

В случае передачи 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 - RSA

getKeyLabel(deviceId, keyId) → {string}

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
keyIdstringИдентификатор ключа
Возвращает:

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

getLicence(deviceId, licenceId) → {object}

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
licenceIdnumberИдентификатор лицензии (значения 1, 2)
Возвращает:

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

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

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

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

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

getStoreCertificate(certId, options) → {string}

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

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

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

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

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

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

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

login(deviceId, pin)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
pinstringPIN-код доступа к устройству
logout(deviceId)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
parseCertificate(deviceId, certId) → {object}

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата, полученный в результате вызова enumerateCertificates
Возвращает:

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

parseCertificateFromString(text) → {object}

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

Параметры:
Name Type Attributes Default Description
1
textstringТело сертификата в 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_SHA512.
Для выполнения этой функции требуется авторизоваться на устройстве.

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

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

removePin(deviceId)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
savePin(deviceId)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
setKeyLabel(deviceId, keyId, label)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
keyIdstringИдентификатор ключа
3
labelstringНовая метка закрытого ключа
setLicence(deviceId, licenceId, licence)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
licenceIdnumberИдентификатор лицензии (значения 1, 2)
3
licencestring72 байта данных, представленные в 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_SHA512.
  • CMS:string (empty) - уже сформированный CMS, в который требуется добавить подпись. Если в CMS подпись отсоединённая, то параметр data должен присутствовать и соответствовать данным, подпись которых находится в CMS, если в CMS подпись неотсоединённая, то параметр data должен быть пустым если CMS отсутствует, то будет создан новый CMS
  • eContentType:string (empty) - задать тип содержимого CMS (OID, напр. "1.2.3.4"). Требует отсутствия опции CMS. Tребует опции addSignTime == true.

  • addSystemInfo:bool (false) - включать информацию о месте подписи. Tребует опции 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_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
deviceIdnumberИдентификатор устройства
2
certIdstringИдентификатор сертификата
3
datastringПодписываемые данные (текстовая строка или base64-encoded бинарные данные)
4
dataFormatnumberФормат данных. Возможные варианты: DATA_FORMAT_PLAIN, DATA_FORMAT_BASE64, DATA_FORMAT_HASH. Если формат данных - DATA_FORMAT_HASH, то в параметр data передается посчитанный хеш сообщения (hex-строка), при этом необходимо выставить опцию detached в true.
5
optionsobjectМассив, содержащий параметры подписи - объекты вида {параметр:true/false}
Возвращает:

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

unblockUserPin(deviceId, adminPin)

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

Параметры:
Name Type Attributes Default Description
1
deviceIdnumberИдентификатор устройства
2
adminPinstringPIN-код Администратора
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
deviceIdnumberИдентификатор устройства
2
cmsstringКонтейнер с цифровой подписью
3
optionsobjectМассив, содержащий параметры проверки подписи - объекты вида {параметр:значение}
Возвращает:

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
deviceIdnumberИдентификатор устройства
2
responsestringbase-64 encoded метка доверенного времени (TSResponse)
3
datastringЗапрос метки доверенного времени (TSRequest)
4
dataFormatnumberФормат данных. Возможные варианты: DATA_FORMAT_BASE64.
5
optionsobjectМассив, содержащий параметры проверки подписи - объекты вида {параметр:значение}
Возвращает:

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