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

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

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

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

  1. Передача значения в качестве аргумента.

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

  3. Использование Антифрод-терминала в качестве устройства ввода.

    Важно

    Если команды вызываются для смарт-карты, подключенной к Антифрод-терминалу, то работать надо как описано в подразделе Использование смарт-карты, вставленной в Антифрод-терминал

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

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-кода

Необходимо передать в аргумент antifraud заполненную структуру.

При использования Антифрод-терминала есть 2 сценария работы с ним. От сценария использования зависит значение, передаваемое в параметр deviceID аргумента antifraud.

Ниже описаны возможные сценарии.

Использование смарт-карты, вставленной в Антифрод-терминал

В данном случае необходимо передавать аргумент antifraud, но параметр deviceID при обработке команды будет игнорироваться, поэтому его можно не устанавливать.

var tokenID = 0; // Идентификатор токена на смарт-карте, вставленной в Антифрод-терминал

// Изменить PIN-код пользователя использую прикладной графический интерфейс JC-WebClient
JCWebClient2.changePIN({
   args: {
      tokenID: tokenID,
      antifraud: {
         // deviceID: tokenID, // В данном случае, наличие или отсутствие deviceID ни на что не повлияет
         langID: JCWebClient2.Vars.AftLang.eng,
         timeout: 30,
         confirmRequired: true
      }
   }
});

Использование Антифрод-терминала в бескарточном режиме

Используется USB-токен (или смарт-карта, вставленная в обычный ридер) и Антифрод-терминал в бескарточном режиме (смарт-карта не вставлена в него) как устройство для ввода PIN-кодов.

В данном случае необходимо передавать аргумент antifraud и в параметр deviceID передать идентификатор Антифрод-терминала в бескарточном режиме через который необходимо взаимодействовать с пользователем. При этом в аргумент tokenID необходимо передавать идентификатор токена.

var tokenID = 0,       // Идентификатор токена
    aftCardlessID = 1; // Идентификатор Антифрод-терминала в бескарточном режиме

// Изменить PIN-код пользователя на токене, используя Антифрод-терминал для ввода PIN-кодов
JCWebClient2.changePIN({
   args: {
      tokenID: tokenID,
      antifraud: {
         deviceID: aftCardlessID,
         langID: JCWebClient2.Vars.AftLang.eng,
         timeout: 30,
         confirmRequired: true
      }
   }
});

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

Предъявление PIN-кода необходимо для аутентификации на токене и выполняется при помощи команды bindToken.
Проверить текущее состояние позволяет команда getLoggedInState.
Отмена предъявленного 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-кода администратора для токенов GOST и PRO

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-кода пользователя для токенов GOST и PRO

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-кода пользователя для токена GOST 2

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

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

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

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

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

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

Примечание

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

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

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.

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-кода подписи

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

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

Так как информация о предъявлении 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