Крипто-модуль

Модуль PinManager реализует к доступ к функциям крипто-модуля: импорт сессионных ключей, ввод открытых данных, ввод ПИН-кода, получение зашифрованного PIN-кода, подписывание данных (MAC). В процессе ввода PIN-кода PinManager обеспечивает рассылку оповещений о нажатиях на клавиши EPP (как на цифровые, так и на функциональные). Для того чтобы компонент получал оповещения о нажатиях, необходимо, чтобы он реализовал интерфейс IKeyHandler. Наиболее часто используемые реализации IKeyHandler: кнопка EPP, строка редактирования. Данный модуль несовместим с модулем Управление вводом с PIN Keypad (ContentManager), поэтому на html-странице может быть размещен либо ContentManager, либо PinManager.

Идентификаторы подключения

  • ProgID: AXPinManager.PinManager;

  • CLSID: 6D33A788-8D9C-4CA0-999B-9A4DAFDBA73E.

Свойства

  • CustomerData – PAN карты.

    Предусмотрено три стратегии передачи данных в CustomerData:

    1. IAI – CustomerData содержит строго IAI-часть PAN карты (соотв. ISO-7813);

    2. WHOLE_PAN – передается весь PAN, считанный с карты, включая контрольный разряд (соотв. CEN/XFS версии 3.03);

    3. PAN_WITHOUT_CD – передается PAN без контрольного разряда (соотв. CEN/XFS версий 3.10, 3.20).

    Стратегия передачи данных указана в настройке HKLM\Software\XFS\PHYSICAL_SERVICES\EPP-<модель клавиатуры>@@CustomerDataInterpretation (по умолчанию – IAI).

    Пример получения значения IAI-части PAN карты:

    Есть Track2 карты – «4714200000770003=22122011289102700000». В нем берем PAN карты (цифры до знака равно), получаем – «4714200000770003».

                   Track2
 ___________________________________
|                                   |
4714200000770003=22122011289102700000
|______________|
   PAN карты

    В PAN cправа налево отсчитываем 12 цифр со второй цифры (первая цифра – это контрольный разряд), получаем – «420000077000». Эти цифры – IAI-часть PAN карты.

    4714200000770003=22122011289102700000
   |__________|
   CustomerData

  • Format – формат генерируемого PIN-блока в соответствии с классификацией CEN/XFS 3.09 (для ISO – 4).

  • Key – символическое имя ключа, на котором осуществляется шифрование PIN-кода.

  • KeyEncKey – вспомогательный ключ шифрования, который используется для импорта других ключей.

  • MaxLen – максимальная длина PIN-кода (4 или 12 символов).

  • TerminateFDKs – список FDK-клавиш, при нажатии на которые ввод PIN-кода считается завершенным. Актуально только для банкоматов и киосков, оснащенных боковыми функциональными клавишами.

  • Padding – стартовый вектор для вычисления PIN-блока (в практической работе не используется).

  • AutoComplete – атрибут отвечает за автоматическое завершение ввода PIN-кода.

    Возможные значения:

    • 1 – при вводе максимального количества цифр PIN-кода ввод автоматически завершается;

    • 0 – ввод PIN-кода не завершается до тех пор, пока клиент не нажмет кнопку ACCEPT.

  • BaseUrl – базовый Url-адрес, к которому добавляется относительный адрес, указанный в свойствах кнопки. Изменение этого свойства может контролироваться компонентами (кнопками) путем подписки на соответствующее событие.

  • XORData – параметр XORData, для формирования PIN-блока. Если PIN-код шифруется дважды для построение финального PIN-блока, то эти данные могут быть использованы для изменения результата первого шифрования путем применения операции XOR.

  • TerminateKeys – терминирующие функциональные клавиши, которые могут быть использованы для завершения команды ввода PIN-кода.

  • MinLen – минимальная длина PIN-кода. По умолчанию установлено значение 0 (минимальная длина PIN-кода не контролируется).

  • OpentextActiveFDK (BSTR) – cписок кнопок FDK через запятую, реакцию от которых требуется получать (идентификаторы кнопок в нотации XFS, раскладка left[8->5] .. right[1->4]). Пустое значение – все кнопки активируются, none – ни одна кнопка не будет активна.

  • OpentextActiveFK (LONG) – cписок активных кнопок PIN-пада через запятую (идентификаторы кнопок в нотации XFS). По умолчанию все кнопки включены.

Методы

GetStatus()

Метод возвращает состояние устройства:

  • 0 – устройство работает штатно;

  • 1 – устройство находится в режиме offline;

  • 2 – питание к устройству не подключено;

  • 3 – устройство отсутствует;

  • 4 – аппаратная ошибка;

  • 5 – ошибка конфигурирования устройства;

  • 6 – устройство находится в процессе выполнения команды.

GetEncStatus()

Метод возвращает состояние крипто-модуля:

  • 0 – устройство готово к работе;

  • 1 – устройство не готово к работе;

  • 2 – устройство не проинициализировано;

  • 3 – устройство находится в процессе выполнения команды;

  • 4 – состояние устройства не определено;

  • 5 – устройство проинициализировано.

InputPin()

Команда начала ввода PIN-кода. Работы команды завершается сразу после того, как пользователь наживает кнопку ACCEPT или вводит PIN-код максимальной длины (зависит от значения атрибута AutoComplete). При завершении ввода PIN-кода, компонент генерирует уведомление OnEnter().

GetPinBlock()

Получение PIN-блока. Команда получения PIN-блока сформированного на основе введенного PIN-кода, указанного PAN карты и зашифрованная на PIN-ключе EPP.

CreateKey(BSTR bstrKey, BSTR bstrEncKey, BSTR bstrValue, USHORT usUse)

Создание ключа в крипто-модуле. Ключи создаются посредством CEN/XFS.

Параметры:

  • BSTR bstrKey – имя создаваемого ключа;

  • BSTR bstrEncKey – имя ключа, на котором дешифруется ключ (не используется в случае импорта ключа в открытом виде);

  • BSTR bstrValue – цифровое значение ключа в виде текстовой строки (формат–последовательность шестнадцатеричных цифр, например для 3DES-ключа – 33120608AFE098120123456789ABCDEF);

  • USHORT usUse – тип ключа в соответствии с соответствующей классификацией в CEN/XFS.

    Используются следующие константы:

    • «1» – ключ может быть использован в операциях шифрования/дешифрования;

    • «2» – ключ может быть использован для формирования PIN блока;

    • «4» – ключ может быть использован для формирования MAC-подписи сообщения.

    В случае если один и тоже ключ предполагается использовать в различных операциях, значение usUse формируется операцией «побитовое ИЛИ» с соответствующими константами. В целях безопасности запрещено создание ключей при usUse с установленными битами 5 или 6. При попытке создания такого ключа генерируется событие OnError со значением параметра ulErrorCode равным 1.

    Возвращаемым значением метода является строка текста, являющаяся проверочным кодом (KVC – Key Validation Check).

SetKeyMask(ULONG ulStates, ULONG ulMask)

Метод позволяет установить маску разрешенных для использования кнопок PinBlockа. Актуально только для банкоматов и киосков оснащенных боковыми функциональными клавишами.

Mac( BSTR bstrMessage, BSTR bstrKeyName)

Функция расчета MAC. Возвращаемым значением метода является строка текста, являющаяся MAC (формат – ASCII HEX). По умолчанию выполняется попытка генерации MAC с параметром WFS_PIN_CRYPTTRIDESMAC. Если этот алгоритм не поддерживается сервис-провайдером XFS для PIN-клавиатуры, то выполняется попытка подсчета MAC по алгоритму WFS_PIN_CRYPTDESMAC.

OpentextDataEntry

Запуск ввода открытых данных. Ранее запущенный ввод PIN-кода будет автоматически прерван.

StopPanpadEntry

Прервать ввод PIN-кода или открытых данных.

Уведомления

OnEnter()

Вызывается при завершении клиентом ввода PIN-кода.

OnCancel()

Вызывается в случае отказа клиентом ввода PIN-кода, т.е. при нажатии кнопки CANCEL.

OnError(ULONG ulErrorCode, BSTR bstrErrorText)

Вызывается в случае возникновения каких-либо ошибок, например, в случае отсутствия требующегося PIN-ключа или при возникновении аппаратных ошибок.

OnChar(LONG lChar)

Вызывается в режиме ввода PIN при нажатии кнопок на PIN-клавиатуре.

Параметры:

  • lChar – код кнопки. Нажатие кнопки с цифрой 0..9 сопровождается кодом «0». За кнопками закреплены следующие значения:

    • 0 – 0x00000001;

    • 1 – 0x00000002;

    • 2 – 0x00000004;

    • 3 – 0x00000008;

    • 4 – 0x00000010;

    • 5 – 0x00000020;

    • 6 – 0x00000040;

    • 7 – 0x00000080;

    • 8 – 0x00000100;

    • 9 – 0x00000200;

    • CLEAR – 0x00001000;

    • HELP – 0x00004000;

    • . – 0x00008000.

OnTimeout()

Функция уведомления об аппаратном таймауте на ввод PIN-кода.

OnOpentextKeyPressed( LONG ulKeyCode, VARIANT_BOOL bIsFdk )

Нажата клавиша в режиме ввода открытых данных.

Параметры:

  • ulKeyCode – код кнопки в нотации XFS;

  • bIsFdk – признак FDK-кнопки.

Пример кода

<OBJECT ID='PinManager' CLASSID='CLSID:6D33A788-8D9C-4CA0-999B-9A4DAFDBA73E'
                            width='0' height='0'>
                <param name='CustomerData' value='420000077000'>
                <param name='Format' value='4'>
                <param name='Key' value='IKEY2'>
                <param name='MaxLen' value='4'>
</OBJECT>
<script language='javascript' for='window' event='OnLoad()'>
                PinManager. InputPin ();
</script>

<script language='javascript' for='PinManager' event='OnEnter()'>
                alert(PinManager.GetPinBlock());
</script>
<script language='javascript' for='PinManager' event=' OnChar(lChar)'>
                alert(lChar);
</script>