Операции с PIN-кодами

USB-токены и смарт-карты JaCartaAPI и SDKUSB-токены и смарт-карты JaCarta

JC-WebClient позволяет производить операции с PIN-кодами.

Способы ввода PIN-кода

В командах ввод PIN(PUK)-кодов возможен несколькими способами:

1. Передача значения в качестве аргумента.
2. Вызов определенного диалога графического интерфейса приложения JC-WebClient. Диалог подбирается автоматически в зависимости от выполняемой команды.

На примере смены PIN-кода пользователя (команда changePIN) рассмотрим 2 способа.

PIN-код в качестве аргумента

Необходимо передать значение PIN-кода в соответствующий аргумент.

var tokenID = 0,                 // Идентификатор токена
    oldUserPIN = 'old user pin', // Текущий PIN-код пользователя
    newUserPIN = 'new user pin'; // Устанавливаемый PIN-код пользователя

// Изменить PIN-код пользователя передав PIN-коды в качестве аргументов
JCWebClient2.changePIN({
   args: {
      tokenID: tokenID,
      oldPin: oldUserPIN,
      newPin: newUserPIN
   }
});

Ввод PIN-кода через прикладной графический интерфейс

Необходимо передать значение true в аргумент useUI.

var tokenID = 0; // Идентификатор токена

// Изменить PIN-код пользователя использую прикладной графический интерфейс JC-WebClient
JCWebClient2.changePIN({
   args: {
      tokenID: tokenID,
      useUI: true
   }
});

Предъявление PIN-кода

Предъявление PIN-кода необходимо для аутентификации на токене и выполняется при помощи команды bindToken. Проверить текущее состояние позволяет команда getLoggedInState. Отмена предъявленного PIN-кПредъявление PIN-коода выполняется при помощи команды unbindToken.

Для примера возьмем токен, который только что подключили и он получил идентификатор 0.

var tokenID = 0,        // Идентификатор токена
    userPin = 'my pin'; // PIN-код пользователя

// Проверить текущее состояние аутентификации на токене
// (должно равняться JCWebClient2.Vars.AuthState.notBinded)
var tokenState = JCWebClient2.getLoggedInState();

console.log('1) Token is binded: ' + (tokenState.state == JCWebClient2.Vars.AuthState.binded));

// Предъявить PIN-код
JCWebClient2.bindToken({
   args: {
      tokenID: tokenID,
      pin: userPin
   }
});

// Проверить изменившееся состояние
// (должно равняться JCWebClient2.Vars.AuthState.binded)
tokenState = JCWebClient2.getLoggedInState();

console.log('2) Token is binded: ' + (tokenState.state == JCWebClient2.Vars.AuthState.binded));

// Отменить предъявление PIN-кода
JCWebClient2.unbindToken();

// Проверить текущее состояние аутентификации на токене
// (должно равняться JCWebClient2.Vars.AuthState.notBinded)
var tokenState = JCWebClient2.getLoggedInState();

console.log('3) Token is binded: ' + (tokenState.state == JCWebClient2.Vars.AuthState.binded));

// ----- Результат -----
// 1) Token is binded: false
// 2) Token is binded: true
// 3) Token is binded: false

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

Инициализация PIN-кода пользователя (команда initUserPIN) необходима, если токен был инициализирован без PIN-кода пользователя. Если на токене уже установлен PIN-код пользователя, то команда вернет ошибку. Таким образом это действие можно выполнить только один раз после инициализации.

// Функция обработки результата
function handleResult(result, error) {
   if(error) {
      console.error('Error: ' + error);
      return;
   }

   console.log('User PIN has been initialized');
}

var tokenID = 0,              // Идентификатор токена
    adminPin = 'admin pin',   // PIN-код администратора
    userPin = 'new user pin'; // Инициализируемый PIN-код пользователя

// Инициализировать PIN-код пользователя
JCWebClient2.initUserPIN({
   args: {
      tokenID: tokenID,
      adminPin: adminPin,
      userPin: userPin,
      onResult: handleResult
   }
});

// Попытка повторной инициализации PIN-кода пользователя
JCWebClient2.initUserPIN({
   args: {
      tokenID: tokenID,
      adminPin: adminPin,
      userPin: userPin + '_new',
      onResult: handleResult
   }
});

// ----- Результат -----
// User PIN has been initialized
// Error: JCWebClientError: USER_PIN_ALREADY_INITIALIZED

Смена PIN-кода пользователя/администратора

Для смены PIN-кода пользователя/администратора используется команда changePIN. При смене PIN-кода пользователя необходимо, чтобы токен уже имел PIN-код пользователя.

Осторожно

При работе с токеном GOST 2 PIN-код можно поменять только для пользователя (см. changePIN).

Пример смены PIN-кода администратора для токена PKI

var tokenID = 0,        // Идентификатор токена
    oldPin = 'old pin', // Старый PIN администратора
    newPin = 'new pin'; // Новый PIN администратора

// Сменить PIN-код администратора
JCWebClient2.changePIN({
   args: {
      tokenID: tokenID,
      userType:JCWebClient2.Vars.UserType.admin,
      oldPin: oldPin,
      newPin: newPin
   }
});

console.log('Admin PIN has been changed.');

// ----- Результат -----
// Admin PIN has been changed.

Пример смены PIN-кода пользователя для токенов PKI и GOST 2

var tokenID = 0,        // Идентификатор токена
    oldPin = 'old pin', // Старый PIN пользователя
    newPin = 'new pin'; // Новый PIN пользователя

// Сменить PIN-код пользователя
JCWebClient2.changePIN({
   args: {
      tokenID: tokenID,
      userType:JCWebClient2.Vars.UserType.user,
      oldPin: oldPin,
      newPin: newPin
   }
});

console.log('User PIN has been changed.');

// ----- Результат -----
// User PIN has been changed.

Разблокировка PIN-кода пользователя

Для разблокировки PIN-кода пользователя используется команда unblockUserPIN. Данное действие необходимо выполнять, если истекли попытки ввода PIN-кода.

Осторожно

Для разблокировки токена GOST 2 необходимо ввести PUK-код.

Пример разблокировки PIN-кода пользователя для токена PKI

var tokenID = 0,            // Идентификатор токена
    adminPin = 'admin pin'; // PIN-код администратора

// Разблокировать PIN-код пользователя
JCWebClient2.unblockUserPIN({
   args: {
      tokenID: tokenID,
      adminPin: adminPin
   }
});

console.log('User PIN has been unblocked.');

// ----- Результат -----
// User PIN has been unblocked.

Пример разблокировки PIN-кода пользователя для токена GOST 2

var tokenID = 0,          // Идентификатор токена
    pukCode = 'puk code'; // PUK-код

// Разблокировать PIN-код пользователя
JCWebClient2.unblockUserPIN({
   args: {
      tokenID: tokenID,
      pukCode: pukCode
   }
});

console.log('User PIN has been unblocked.');

// ----- Результат -----
// User PIN has been unblocked.

7.11.6 PIN-код подписи токена GOST 2

Установка PIN-кода подписи

Для установки PIN-кода подписи используется команда setSignaturePIN.

var tokenID = 0, // Идентификатор токена
    pin = 'pin'; // PIN подписи

// Сменить PIN-код пользователя
JCWebClient2.setSignaturePIN({
   args: {
      tokenID: tokenID,
      pin: pin
   }
});

console.log('Signature PIN has been set.');

// ----- Результат -----
// Signature PIN has been set.

Смена PIN-кода подписи

Для смены PIN-кода подписи используется команда changeSignaturePIN. При смене PIN-кода подписи необходимо, чтобы он уже был установлен.

var tokenID = 0,        // Идентификатор токена
    oldPin = 'old pin', // Старый PIN подписи
    newPin = 'new pin'; // Новый PIN подписи

// Сменить PIN-код пользователя
JCWebClient2.changeSignaturePIN({
   args: {
      tokenID: tokenID,
      oldPin: oldPin,
      newPin: newPin
   }
});

console.log('Signature PIN has been changed.');

// ----- Результат -----
// Signature PIN has been changed.

Проверка наличия PIN-кода подписи

Признак наличия PIN-кода подписи можно получить из дополнительной информации о токене. Для этого используется команда getTokenInfo с аргументом extendedInfo равным true, в результате выполнения которой можно получить признак наличия PIN-кода подписи (extendedInfo.signPinState.exists).

var tokenID = 0;        // Идентификатор токена

// Получить информацию о токене, включая дополнительные данные
var tokenInfo = JCWebClient2.getTokenInfo({
   args: {
      tokenID: tokenID,
      extendedInfo: true
   }
});

var isExists = tokenInfo.extendedInfo.signPinState.exists;
console.log('Signature PIN exists: ' + isExists);

// ----- Результат -----
// Signature PIN exists: true // если PIN-код подписи установлен
// или
// Signature PIN exists: false // если PIN-код подписи не установлен

Признак необходимости предъявления PIN-кода подписи устанавливается при создании ключевой пары в аргументе requireSignaturePin команды createKeyPair. Таким образом этот признак можно получить в списке ключевых парах (команда getKeyPairList) или в списке контейнеров (команда getContainerList).

Обе команды возвращают список объектов и в каждом из объектов есть параметр signaturePin, который принимает следующие значения:

• JCWebClient2.Vars.SignaturePinState.on - требуется предъявление PIN-кода подписи;
• JCWebClient2.Vars.SignaturePinState.off - не требуется предъявление PIN-кода подписи;
• JCWebClient2.Vars.SignaturePinState.n_a - нет информации о предъявлении PIN-кода подписи.

Так как информация о предъявлении PIN-кода подписи является приватной, то при состоянии аутентификации равной JCWebClient2.Vars.AuthState.notBinded всегда будет возвращаться значение JCWebClient2.Vars.SignaturePinState.n_a.

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

• container_pin_required - контейнер требует предъявления PIN-кода;
• container_pin_not_required - контейнер не требует предъявления PIN-кода.

Получение признака необходимости предъявления PIN-кода подписи при состоянии аутентификации JCWebClient2.Vars.AuthState.notBinded

// Вспомогательная функция отображения списка контейнеров
function printContainerList(message, list) {
   console.log(message);

   list.forEach(function(element) {
      console.log(element.description + ': signaturePin - ' + element.signaturePin);
   });
}

var tokenID = 0,        // Идентификатор токена
    userPin = 'my pin'; // PIN-код пользователя

// Пример 1. Получение признака необходимости предъявления PIN-кода подписи
// при состоянии аутентификации JCWebClient2.Vars.AuthState.notBinded

// Получить список контейнеров
var containers = JCWebClient2.getContainerList({
   args: {
      tokenID: tokenID
   }
});

// Отобразить список контейнеров
printContainerList('Example 1', containers);

// Пример 2. Получение признака необходимости предъявления PIN-кода подписи
// при состоянии аутентификации выше, чем JCWebClient2.Vars.AuthState.notBinded

// Предъявить PIN-код
JCWebClient2.bindToken({
   args: {
      tokenID: tokenID,
      pin: userPin
   }
});

// Получить список контейнеров
containers = JCWebClient2.getContainerList({
   args: {
      tokenID: tokenID
   }
});

// Отобразить список контейнеров
printContainerList('Example 2', containers);

// Отменить ввод PIN-кода
JCWebClient2.unbindToken();

// ----- Результат -----
// Example 1:
// container_pin_required: signaturePin - n_a
// container_pin_not_required: signaturePin - n_a
// Example 2:
// container_pin_required: signaturePin - on
// container_pin_not_required: signaturePin - off