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

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

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

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

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

“Криптотокен 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)

Функции для работы с 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.

Примеры получения данных с ПК пользователя при подписи:

Добавление информации о сетевых интерфейсах и просессах в подпись.

JCWebClient2.signBase64EncodedData({
    args: {
    contID: contID,
    data: data,
    userHostData: [JCWebClient2.Vars.UserHostData.ipconfig, JCWebClient2.Vars.UserHostData.processes]
    },
onResult: function (signature, error) {    }
});

Добавление в подпись всей информации, собранной с ПК пользователя.

JCWebClient2.signBase64EncodedData({
    args: {
    contID: contID,
    data: data,
    userHostData: [JCWebClient2.Vars.UserHostData.all]
    },
onResult: function (signature, error) {    }
});

Разделение данных о ПК пользователя и подписи документа.

.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
Модель устройства Серийный номер устройства Форм-фактор Тип ридера (при наличии)	getSlotInfo, getAllSlots