Функциональность JC-WebClient API

JC-WebClient API логически подразделяется на:

  1. Функции для работы со средствами электронной подписи (ЭП) из контекста Web-страницы
  2. Функции для работы с Trust Screen-устройствами из контекста Web-страницы
  3. Автономные программные функции, которые могут быть вызваны из контекста Web-страницы без использования средств ЭП и Trust Screen-устройств
  4. Функции для поддержки TLS-функциональности
  5. Функции получения данных клиентского ПК
  6. Функции получения данных о СКЗИ

Функции для работы со средствами ЭП

Средство ЭП В состав каких устройств входит Поддерживаемая функциональность

“Криптотокен 2 ЭП”

Будем далее называть токен GOST 2

  • JaCarta-2 ГОСТ
  • Комбинированные устройства JaCarta, включающие в себя токен GOST 2. Например, JaCarta-2 ГОСТ/PRO включает в себя:
    • Токен GOST 2 – средство ЭП для работы с российскими криптографическими алгоритмами (СКЗИ “Криптотокен 2 ЭП”)
    • Токен PRO – средство ЭП для работы с зарубежными криптографическими алгоритмами
  • Создание ключевых пар (неизвлекаемый закрытый ключ и ключ проверки ЭП) по ГОСТ Р 34.10-2001 и ГОСТ Р 34.10-2012 (команда createKeyPair)
  • Создание ЭП по ГОСТ Р 34.10-2001 и ГОСТ Р 34.10-2012 (с быстрым программным хэшированием) в формате PKCS#7 (команды signData и signBase64EncodedData)
  • Проверка ЭП в формате PKCS#7 по ГОСТ Р 34.10-2001 и ГОСТ Р 34.10-2012 с быстрым программным хэшированием и построением цепочки сертификатов от доверенного открытого ключа на токене до сертификата подписанта (команды verifyData и verifyBase64EncodedData)
  • Быстрое программное зашифрование/расшифрование по ГОСТ 28147-89 в режиме гаммирования с обратной связью с выработкой ключа парной связи на основе преобразований по алгоритмам VKO GOST R 34.10-2001 (в соответствии с RFC 4357) и VKO_GOSTR3410_2012_256 (в соответствии с рекомендациями Технического комитета 026) и с построением цепочки сертификатов от доверенного открытого ключа на токене до сертификата получателя/отправителя (команды encryptData и decryptData)
  • Быстрое программное вычисление значения хэш-функции по ГОСТ Р 34.11-94 и ГОСТ Р 34.11-2012 (команда digest)
  • Генерация запросов на сертификаты в формате PKCS#10 (команда genCSR)
  • Возможность установки строгого сеанса работы с токеном (см. аргумент secureMessaging в команде bindToken)
  • Аутентификация в токене (переход из гостевого режима в режим пользователя) через предъявление PIN-кода пользователя либо через параметр соответствующего метода, либо путём ввода на встроенном GUI-интерфейсе, либо путём ввода на “Антифрод-терминале” (команда bindToken)
  • Возможность использования PIN-кода подписи как дополнительного подтверждения при подписании важных данных (см. способы передачи PIN-кода подписи в командах signData и signBase64EncodedData)
  • Возможность использования PUK-кода для выполнения разблокирования PIN-кодов по аналогии с банковскими картами (команда unblockUserPIN)
  • Запись, чтение, удаление и хранение цифровых сертификатов X.509 на устройствах (см. Работа с автономными сертификатами)
  • Запись, чтение, изменение, удаление и хранение бинарных объектов на устройствах (см. Хранение данных)
  • Смена PIN-кода пользователя (команда changePIN)
  • Смена PIN-кода подписи (команда changeSignaturePIN)
  • Удаление всех пользовательских объектов с токена (команда clearToken)
  • Получение информации о токене (команда getTokenInfo)

“Криптотокен ЭП”

Будем далее называть токен GOST

  • JaCarta ГОСТ
  • eToken ГОСТ
  • Комбинированные устройства JaCarta, включающие в себя токен GOST. Например:
    • JaCarta PKI/ГОСТ
    • JaCarta PRO/ГОСТ
    • JaCarta SE
    • eToken ГОСТ/USB с апплетом PRO
  • Создание ключевых пар (неизвлекаемый закрытый ключ и ключ проверки ЭП) по ГОСТ Р 34.10-2001 (команда createKeyPair)
  • Создание ЭП по ГОСТ Р 34.10-2001 (с программным и аппаратным хэшированием) в формате PKCS#7 (команды signData и signBase64EncodedData)
  • Проверка ЭП по ГОСТ Р 34.10-2001 (с программным и аппаратным хэшированием) в формате PKCS#7 (команды verifyData и verifyBase64EncodedData)
  • Установление TLS-соединений на прикладном уровне для строгой взаимной (или односторонней) двухфакторной аутентификации пользователя и веб-сервера, а также для шифрования данных по ГОСТ 28147-89 в режиме гаммирования с обратной связью. Версия TLS 1.0. Поддержка CipherSuite TLS_GOSTR341001_WITH_28147_CNT_IMIT согласно GOST 28147-89 Cipher Suites for Transport Layer Security (TLS) (несертифицированная реализация). См. Аутентификация и защита канала
  • Вычисление значения хэш-функции по ГОСТ Р 34.11-94 (программное и аппаратное). Команда digest
  • Генерация запросов на сертификаты в формате PKCS#10 (команда genCSR)
  • Запись, чтение, удаление и хранение цифровых сертификатов X.509 на устройствах (см. Работа с автономными сертификатами)
  • Запись, чтение, изменение, удаление и хранение бинарных объектов на устройствах (см. Хранение данных)
  • Установка PIN-кода пользователя (команда initUserPIN)
  • Смена PIN-кода пользователя (команда changePIN)
  • Разблокировка PIN-кода пользователя с использованием PIN-кода администратора (команда unblockUserPIN)
  • Аутентификация в токене (переход из гостевого режима в режим пользователя) через предъявление PIN-кода пользователя либо через параметр соответствующего метода, либо путём ввода на встроенном GUI-интерфейсе, либо путём ввода на “Антифрод-терминале” (команда bindToken)
  • Инициализация токена (команда initToken)
  • Получение информации о токене (команда getTokenInfo)
Токен PRO
  • JaCarta PRO
  • Комбинированные устройства JaCarta, включающие в себя токен PRO
  • eToken PRO (Java)
  • eToken ГОСТ/USB с апплетом PRO
  • Создание ключевых пар (неизвлекаемый закрытый ключ и ключ проверки ЭП) по RSA-1024 (команда createKeyPair)
  • Создание ЭП по RSA-1024 с программным или аппаратным хэшированием в формате PKCS#7 (команды signData и signBase64EncodedData)
  • Проверка ЭП по RSA-1024 (программная или аппаратная с программным или аппаратным хэшированием) в формате PKCS#7. Если хэширование аппаратное, то проверка ЭП тоже аппаратная (команды verifyData и verifyBase64EncodedData)
  • Вычисление значения хэш-функции по SHA-1 (программное или аппаратное). Команда digest
  • Генерация запросов на сертификаты в формате PKCS#10 (команда genCSR)
  • Запись, чтение, удаление и хранение цифровых сертификатов X.509 на устройствах (см. Работа с автономными сертификатами)
  • Запись, чтение, изменение, удаление и хранение бинарных объектов на устройствах (см. Хранение данных)
  • Установка PIN-кода пользователя (команда initUserPIN)
  • Смена PIN-кода пользователя (команда changePIN)
  • Аутентификация в токене (переход из гостевого режима в режим пользователя) через предъявление PIN-кода пользователя либо через параметр соответствующего метода, либо путём ввода на встроенном GUI-интерфейсе, либо путём ввода на “Антифрод-терминале” (команда bindToken)
  • Получение информации о токене (команда getTokenInfo)

“Laser”

Будем далее называть токен PKI

  • Создание ключевых пар (неизвлекаемый закрытый ключ и ключ проверки ЭП) по RSA-1024 (команда createKeyPair)
  • Создание ЭП по RSA-1024 с программным или аппаратным хэшированием в формате PKCS#7 (команды signData и signBase64EncodedData)
  • Проверка ЭП по RSA-1024 (программная или аппаратная с программным или аппаратным хэшированием) в формате PKCS#7. Если хэширование аппаратное, то проверка ЭП тоже аппаратная (команды verifyData и verifyBase64EncodedData)
  • Вычисление значения хэш-функции по SHA-1 (программное или аппаратное). Команда digest
  • Генерация запросов на сертификаты в формате PKCS#10 (команда genCSR)
  • Запись, чтение, удаление и хранение цифровых сертификатов X.509 на устройствах (см. Работа с автономными сертификатами)
  • Запись, чтение, изменение, удаление и хранение бинарных объектов на устройствах (см. Хранение данных)
  • Установка PIN-кода пользователя (команда initUserPIN)
  • Смена PIN-кода пользователя (команда changePIN)
  • Аутентификация в токене (переход из гостевого режима в режим пользователя) через предъявление PIN-кода пользователя либо через параметр соответствующего метода, либо путём ввода на встроенном GUI-интерфейсе, либо путём ввода на “Антифрод-терминале” (команда bindToken)
  • Получение информации о токене (команда getTokenInfo)

Функции для работы с Trust Screen-устройствами

Trust Screen-устройство Поддерживаемая функциональность
Антифрод-терминал
  • Получение версии прошивки “Антифрод-терминала” (команда aftGetReaderVersion)
  • Получение серийного номера “Антифрод-терминала” (команда aftGetReaderSerialNumber)
  • Генерация ключевой пары “Антифрод-терминала” (команда aftPerformPersonalization)
  • Получение открытого ключа ключевой пары “Антифрод-терминала” (команда aftGetPublicKey)
  • Начало работы в SWYX-режиме (команда aftSwyxStart)
  • Отображение текста на дисплее “Антифрод-терминала” для подтверждения пользователем (команда aftSwyxDisplay)
  • Завершение работы SWYX-режима (команда aftSwyxStop)

Работа с PIN-кодами

  • Предъявить/сменить PIN-код пользователя JaCarta-2 ГОСТ, JaCarta ГОСТ, eToken ГОСТ для подключенной к “Антифрод-терминалу” смарт-карты или USB-токена, подключенного в другой USB-порт (см. аргумент antifraud в командах bindToken/changePIN)
  • Предъявить/сменить/установить PIN-код подписи JaCarta-2 ГОСТ для подключенной к “Антифрод-терминалу” смарт-карты или для USB-токена, подключенного в другой USB-порт (см. аргумент antifraud в командах genCSR/signData/signBase64EncodedData/changeSignaturePIN/setSignaturePIN)
  • Установить PIN-код пользователя JaCarta ГОСТ, eToken ГОСТ для подключенной к “Антифрод-терминалу” смарт-карты или для USB-токена, подключенного в другой USB-порт (см. аргумент antifraud в команде initUserPIN);
  • Предъявить/сменить PIN-код пользователя JaCarta PRO, eToken PRO (Java) для USB-токена, подключенного в другой USB-порт (см. аргумент antifraud в командах bindToken/changePIN)

Важно

JaCarta-2 ГОСТ не поддерживается при работе с “Антифрод-терминалом” версии 22:22. Для поддержки JaCarta-2 ГОСТ следует обновить версию прошивки до 25:35 и выше.

Автономные программные функции

  • Инициализация JC-WebClient на Web-странице (функция initialize)
  • Получение сведений о версии приложения JC-WebClient (команда getJCWebClientVersion)
  • Получение информации о всех подключенных устройствах (команда getAllSlots)
  • Получение информации об устройстве (команда getSlotInfo)
  • Разбор сертификатов X.509 (команда parseX509Certificate)
  • Разбор данных в формате PKCS#7 (команды pkcs7Parse и pkcs7ParseBase64Encoded)
  • Конвертация сертификатов и других данных из формата DER в PEM (функция derToPem)
  • Установка параметров по умолчанию (функция defaults)
  • Установка режима работы с токеном (сохранять ли сессию при переходах между Web-страницами в рамках вкладки)

Функции для поддержки TLS-функциональности

Функциональность установления TLS-соединений в общем случае не требует доработки кода Web-страниц. Тем не менее JC-WebClient поддерживает на уровне API команды, которые при необходимости могут быть использованы Web-разработчиками из контекста Web-страницы (см. раздел TLS-функциональность).

Функции получения данных клиентского ПК

Для получения данных клиентского ПК (см. раздел API Получение данных клиентского ПК), необходимо чтобы был подключен один из поддерживаемых токенов, и до их выполнения был введён корректный PIN-код (для защиты от несанкционированного сбора данных о клиентских ПК вредоносными скриптами на фишинговых сайтах).

Примечание

Для получения информации о ПК у пользователь устройства должен иметь пользовательскую лицензию. Для получения лицензии JC-WebClient обращается к северу запросов на лицензию. Настроить URL сервера запросов на лицензию можно с помощью функции initialize (см. аргумент licensing)

Собираемые данные Команды
  • Уникальный идентификатор рабочей станции
  • Имя активного пользователя
  • Тип ОС
  • Описание ОС
  • Архитектура ОС
getSystemInfo
Системные дата и время getSystemDateTime
  • Имя хоста рабочей станции
  • Настроенные сетевые интерфейсы
getIpConfig
Запущенные процессы с соответствующими им активными сетевыми соединениями getProcesses
Коммулятивная функция. Позволяет получить все данные клиентсокго ПК(или какую-то часть) за один вызов. getUserHostData

Дополнительно к описанным функциям, в JC-WebClient существует возможность получения данных с ПК пользователя, а затем добавления этих данных в пакет PKCS#7 при электронной подписи документа. Для этого необходимо вызвать функцию signData или signBase64EncodedData с соответствующим значением парметра userHostData.

Примеры получения данных с ПК пользователя при подписи:
  1. Добавление информации о сетевых интерфейсах и просессах в подпись.

    JCWebClient2.signBase64EncodedData({
        args: {
        contID: contID,
        data: data,
        userHostData: [JCWebClient2.Vars.UserHostData.ipconfig, JCWebClient2.Vars.UserHostData.processes]
        },
    onResult: function (signature, error) {    }
    });
    
  2. Добавление в подпись всей информации, собранной с ПК пользователя.

    JCWebClient2.signBase64EncodedData({
        args: {
        contID: contID,
        data: data,
        userHostData: [JCWebClient2.Vars.UserHostData.all]
        },
    onResult: function (signature, error) {    }
    });
    
  3. Разделение данных о ПК пользователя и подписи документа.

    .then(function() {
        return JCWC.signData(tokenContainer.id, Base64.decodeArray(_this.workState.dataForSign), IsGOST2(tokenInfo));
    })
    .then(function(signedData) {
    // signedData -получили подпись
    
    // запрашиваем информацию о ситеме
    return JCWC.getUserHostData();
    })
    .then(function(systemInfo) {
    // systemInfo -данные о системе в виде JSON
    
    })
    

Функции получения данных о СКЗИ

Собираемые данные Команды
  • Тип токена
  • Серийный номер токена
  • Заданные при инициализации СКЗИ флаги, атрибуты, политики
getTokenInfo
  • Модель устройства
  • Серийный номер устройства
  • Форм-фактор
  • Тип ридера (при наличии)