Крипто-модуль¶
Модуль 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:
IAI – CustomerData содержит строго IAI-часть PAN карты (соотв. ISO-7813);
WHOLE_PAN – передается весь PAN, считанный с карты, включая контрольный разряд (соотв. CEN/XFS версии 3.03);
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>