Навигация

Доработка кода клиентской части прикладного ПО для реализации прикладных сценариев

Перед чтением этого раздела рекомендуется ознакомиться с описанием сценариев использования Антифрод-терминала. В данном разделе даны некоторые пояснения и детализации к сценариям.

Для работы с устройством на клиентской стороне используется набор методов, входящих в состав решения JC-WebClient. Эти методы позволяют:

  • Осуществлять поиск Антифрод-терминалов, подключённых к ПК.
  • Запрашивать PIN-код пользователя для ввода с помощью Антифрод-терминала.
  • Стартовать защищённый SWYX-режим работы Антифрод-терминала.
  • Отображать текст на экране Антифрод-терминала в SWYX-режиме.
  • Прекращать работу Антифрод-терминала в SWYX-режиме.
  • Подписывать документы с подтверждением их ключевых данных на терминале.

Поиск Антифрод-терминалов, подключенных к ПК

В JC-WebClient API в методах для работы с устройствами используется идентификаторы слота и токена. Идентификатор токена может указывать на USB-токен, Антифрод-терминал со вставленной смарт-картой или другой считыватель со вставленной смарт-картой. Идентификатор слота указывает на Антифрод-терминал без вставленной смарт-карты. Ниже представлены способы получения идентификаторов для работы с Антифрод-терминалом со вставленной смарт-картой и без неё.

Примечание

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

Ниже приведены примеры кода для получения идентификаторов Антифрод-терминалов, подключенных к ПК.

  • Получить массив Антифрод-терминалов с подключённой смарт-картой:

    // Получение информации о всех слотах
var slots = JCWebClient2.getAllSlots();

//Из полученного массива выделим смарт-карты,
//которые подключены к ридерам, являющимся Антифрод-терминалами
var smartcard_AFTs = [];
for (var i = 0; i < slots.length; ++i) {
   var slot = slots[i];

   if(slot.reader != undefined
     && slot.reader.type == JCWebClient2.Vars.ReaderType.antifraud
     && slot.reader.smartCardInserted == true) {
      smartcard_AFTs.push(slot);
   }
}

  • Получить массив Антифрод-терминалов без подключённой смарт-карты:

    // Получение информации о всех слотах
var slots = JCWebClient2.getAllSlots();

//Из полученного массива выделим ридеры,
// являющимся Антифрод-терминалами без подключённой карты
var cardless_AFTs = [];
for (var i = 0; i < slots.length; ++i) {
   var slot = slots[i];

   if(slot.reader != undefined
     && slot.reader.type == JCWebClient2.Vars.ReaderType.antifraud
     && slot.reader.smartCardInserted == false) {
      cardless_AFTs.push(slot);
   }
}

В дальнейших примерах идентификатор Антифрод-терминала:

  • С подключённой смарт-картой будет обозначен как smartcard_AFT;
  • Без подключённой смарт-карты будет обозначен как cardless_AFT;
  • С или без смарт-карты будет обозначен как AFT.

Запрос PIN-кода пользователя для ввода с помощью Антифрод-терминала

Формированию электронной подписи под документом предшествует выполнение команды аутентификации (см. bindToken), в процессе которого пользователь должен ввести PIN-код. В приложениях, рассчитанных исключительно на работу с Антифрод-терминалом и не поддерживающих обычные считыватели, не следует использовать аргумент useUI и предлагать пользователям вводить PIN-код с клавиатуры компьютера. Команда запросит у пользователя ввести PIN-код на клавиатуре терминала.

//Используем метод для аутентификации на смарт-карте, вставленной в АФТ.
JCWebClient2.bindToken({
   args: {
      tokenID: smartcard_AFT,
      antifraud: {
         langID: JCWebClient2.Vars.AftLang.rus,
         timeout: 30
      }
   }
});

Начало работы Антифрод-терминала в защищенном SWYX-режиме

Для старта SWYX-режима используется команда aftSwyxStart.

//включить SWYX-режим для Антифрод-терминала,
//передавая в качестве параметра reference
//последовательность из 8-байт 0102030405060708, присланную сервером.
JCWebClient2.aftSwyxStart({
   args: {
      deviceID: AFT,
      reference: [1, 2, 3, 4, 5, 6, 7, 8]
   }
});

Антифрод-терминал поместит значение reference в тег Reference журнала операций.

Отображение текста на экране Антифрод-терминала в SWYX-режиме

Для отображения текста на экране Антифрод-терминала необходимо вызвать команду aftSwyxDisplay.

//вывести ключевые реквизиты для подписания
JCWebClient2.aftSwyxDisplay({
   args: {
      deviceID: AFT,
      message: 'Плч ЗАО “Мажторг”\nСум 238,000 руб.\nБИК 044525225\nСч№ 5.000.0008933',
      timeout: 24,
      extensions: {
         langID: JCWebClient2.Vars.AftLang.rus,
         messageIDx: JCWebClient2.Vars.AftAcceptMessageID.sign
      }
   }
});

//вывести данные для подтверждения аутентификации
JCWebClient2.aftSwyxDisplay({
   args: {
      deviceID: AFT,
      message: 'Подтвердите\nаутентификацию\nна портале\ndemo.aladdin-rd.ru',
      timeout: 24,
      extensions: {
         langID: JCWebClient2.Vars.AftLang.rus,
         messageIDx: JCWebClient2.Vars.AftAcceptMessageID.confirm
      }
   }
});

Если текст, который нужно вывести на экран терминала и подтвердить, превышает 400 символов, следует выводить его на экран терминала по частям, последовательно вызывая команду aftSwyxDisplay для всех частей текста, не превышающих размер 400 символов.

Терминал позволяет отображать на своём экране текстовые данные в кодировке UTF-8.

Окончание работы Антифрод-терминала в защищенном SWYX-режиме

Для прекращения работы Антифрод-терминала в SWYX-режиме необходимо вызвать команду aftSwyxStop.

// получить структуру журнала операций в переменную val
var val = JCWebClient2.aftSwyxStop({
   args: {
      deviceID: AFT
   }
});

Журнал операций Антифрод-терминала, полученный с помощью команды aftSwyxStop можно перевести из байтового представления в строковое следующим образом:

// Создаем метод для форматирования журнала Антифрод-терминала
function formatToHex(value) {
   var retval = '';
   for (i = 0; i < value.length; ++i)
     retval += '0x' + (+value[i]).toString(16).toUpperCase() + ' ';
   return retval;
}

var journal = val.journal;            // Журнал операций в формате XML в виде массива байт.
var signature = val.journalSignature; // Подпись журнала в виде массива байт.

// Формируем user friendly результат
var retval = 'Получен лог: \n';

var log = '';
for (i = 0; i < journal.length; i++)
  log += String.fromCharCode(journal[i]);

log = formatXml(log);
retval += log;

retval += '\nПолучена цифровая подпись (длина: ' + signature.length + '): \n';
retval += formatToHex(signature);

Подписание документа с подтверждением его ключевых данных на терминале

Необходимо выполнить следующую последовательность действий:

  1. Инициировать SWYX-режим командой aftSwyxStart.

  2. Визуализировать ключевые данные документа командой aftSwyxDisplay.

  3. Подписать данные командой signData.

    Данный метод подписывает данные с помощью ключевой пары токена:

    • Для Антифрод-терминала с подключённой смарт-картой подпись данных должна происходить на смарт-карте.
    • Для Антифрод-терминала в режиме работы с USB-токенами подпись данных должна происходить на USB-токене.

  4. Прекратить работу терминала в SWYX-режиме командой aftSwyxStop.

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

var tokenID = 0,  // Идентификатор USB-токена
    deviceID = 1, // Идентификатор Антифрод-терминала, работающем в бескарточном режиме
    contID = 10;  // Идентификатор контейнера, с помощью которого будет производиться подпись


// Предъявить PIN-код
JCWebClient2.bindToken({
   args: {
      tokenID: tokenID,
      antifraud: {
         deviceID: deviceID,
         langID: JCWebClient2.Vars.AftLang.rus,
         timeout: 30
      }
   }
});

// Инициация SWYX-режима
JCWebClient2.aftSwyxStart({
   args: {
      deviceID: deviceID,
      reference: [1, 2, 3, 4, 5, 6, 7, 8]
   }
});

// Визуализация ключевых данных документа
JCWebClient2.aftSwyxDisplay({
   args: {
      deviceID: deviceID,
      message: 'Плч ЗАО “Мажторг”\nСум 238,000 руб.\nБИК 044525225\nСч№ 5.000.0008933',
      timeout: 12,
      extensions: {
         langID: JCWebClient2.Vars.AftLang.rus,
         messageIDx: JCWebClient2.Vars.AftAcceptMessageID.sign
      }
   }
});

// Подписать данные 01020304h
JCWebClient2.signData({
   args: {
      contID: contID,
      attachedSignature: true,
      useHardwareHash: true,
      data: [1,2,3,4]
   }
});

// получить структуру журнала операций в переменную val
var stopData = JCWebClient2.aftSwyxStop({
   args: {
      deviceID: deviceID
   }
});

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

Оглавление