Page History

RtPcsc - фреймворк для работы с Рутокен ЭЦП Bluetooth, виртуальными считывателями Рутокен VCR, а также NFC-устройствами семейства Рутокен ЭЦП.

...

Для работы с

...

Добавить в Info.plist ключ UISupportedExternalAccessoryProtocols со значением com.aktivco.rutokenecp.

<key>UISupportedExternalAccessoryProtocols</key>
<array>
  <string>com.aktivco.rutokenecp</string>
</array>

Для работы с NFC устройствами Рутокен необходимо

...

Для работы с виртуальными считывателями (Рутокен VCR) необходимо

1. в Info.plist добавить ключ Bonjour services со значениями:

   Code Block
   language xml title Entitlements.plist
   <key>NSBonjourServices</key>

...

1. <array>    <string>_ru-rutoken-vcr._udp</string>    <string>_ru-rutoken-vcr._tcp</string>

...

1. </array>

2. в Info.plist добавить ключ Privacy - Local Network Usage Description с описанием причины необходимости доступа, например: Доступ необходим для работы с VCR

   Code Block
   language xml title Entitlements.plist
   <key>NSLocalNetworkUsageDescription</key> <string>Доступ необходим для работы с виртуальным считывателем Рутокен</string>

3. Работа в приложениях с VCR API на macOS в режиме совместимости с iPad
   Чтобы в приложении для iPadOS, когда оно запускается в режиме совместимости на macOS, работал VCR API необходимо:

   Добавить в Entitlements.plist ключ keychain-access-groups.
   
   

Для работы с USB-токенами необходимо

Начиная с iOS/iPadOS 16.2 стала возможна работа USB-токенов.
Для включения поддержки USB-токенов достаточно только обновления RtPcsc.framework до версии 4.0.0 или новее.

Описание интерфейса RtPcsc для работы с NFC/VCR

SCARD_READERSTATE state;
state.szReader = "\\\\?PnP?\\Notification";
state.dwCurrentState = (1 << 16);

...

• RUTOKEN_CONTROL_CODE_START_NFC - запуск обнаружения по NFC;
• RUTOKEN_CONTROL_CODE_STOP_NFC - остановка обнаружения по NFC;
• RUTOKEN_CONTROL_CODE_STOP_NFC_WITH_ERROR - остановка обнаружения по NFC с показом иконки ошибки;
• RUTOKEN_CONTROL_CODE_LAST_NFC_STOP_REASON - возврат причины прекращения обнаружения по NFC.

Параметр pbSendBuffer используется для передачи дополнительной информации:

• при RUTOKEN_CONTROL_CODE_START_NFC: параметр задан в формате "\(waitMessage)\0\(workMessage)\0\0" и содержит два сообщения:
  • waitMessage отображается во время ожидания карты,
  • workMessage отображается во время работы с картой.;
• при RUTOKEN_CONTROL_CODE_STOP_NFC: параметр содержит сообщение о завершении работы с картой;
• при RUTOKEN_CONTROL_CODE_STOP_NFC_WITH_ERROR: параметр содержит сообщение о завершении работы с картой .с уведомлением об ошибке;
• при RUTOKEN_CONTROL_CODE_LAST_NFC_STOP_REASON: параметр не используется.

Рекомендуемый порядок работы с Рутокеном с NFC

...

• получить список доступных ридеров с помощью функции SCardListReaders;
• вызов функции SCardConnect для нужного ридера с параметром dwShareMode == SCARD_SHARE_DIRECT;
• вызов функции SCardControl с параметром RUTOKEN_CONTROL_CODE_START_NFC;
• работа с Рутокеном;
• вызов функции SCardControl с параметром RUTOKEN_CONTROL_CODE_STOP_NFC;
• вызов функции SCardDisconnect.

Причину завершения обнаружения NFC устройств можно получить с помощью вызова функции SCardControl с параметром RUTOKEN_CONTROL_CODE_LAST_NFC_STOP_REASON.

...

• RUTOKEN_NFC_STOP_REASON_FINISHED - вызов SCardControl с параметром RUTOKEN_CONTROL_CODE_STOP_NFC;
• RUTOKEN_NFC_STOP_REASON_UNKNOWN - причина завершения неизвестна;
• RUTOKEN_NFC_STOP_REASON_TIMEOUT - системный таймаут (на устройствах под управлением iOS предоставляется 20 секунд на одну NFC сессию);
• RUTOKEN_NFC_STOP_REASON_CANCELLED_BY_USER - нажатие кнопки "Отмена" на системном окне обнаружения NFC;
• RUTOKEN_NFC_STOP_REASON_NO_ERROR - системное окно работы с NFC еще не опускалось, ошибок нет.

Получение типа устройства Рутокен

...

Работа с виртуальным считывателем

Для спаривания запуска процедуры создания пары с новым виртуальным считывателем необходимо вызвать функцию NSString* generatePairingQR(void), она возвращает изображение QR-кода в виде base64 строки. Для спаривания этого необходимо отобразить QR-код на экране и считать его с помощью приложения Рутокен VCR.

Для получения списка спаренных сопряженных считывателей необходимо вызвать функцию NSArray* listPairedVCR(void).
Функция возвращает массив словарей, содержащих информацию о считывателях. Для каждого считывателя Рутокен VCR существует один сертификат, который хранится в keychain. Он необходим, чтобы удостовериться, что данные устройства (iPad и iPhone) спаренысопряжены.

Ключи словаря:

• name - имя считывателя
• cert - сертификат считывателя в виде BASE64-строки
• fingerprint - SHA1-хеш от сертификата считывателя

Для отмены спаривания разрыва пары со считывателем необходимо вызвать функцию BOOL unpairVCR(NSData* vcrId).

Функция возвращает true, если спаривание отмененоразрыв произошёл успешно, и false в противном случае. В качестве параметра она принимает SHA1-хеш от сертификата считывателя, спаривание пару с которым котором необходимо отменитьразорвать.

Рекомендуемый порядок работы с VCR

...

• Вызвать функцию SCardEstablishContext;
• Сгенерировать сгенерировать QR-код для спаривания создания пары с помощью функции generatePairingQR
• осуществить спаривание с VCR
• ;
• Запустить процесс ожидания подключения ридеров, вызвав функцию SCardGetStatusChange;
• Осуществить сопряжение с VCR и дождаться подключения ридера на уровне RtPcsc получить список доступных считывателей с помощью функции SCardListReaders (для iPad будут отображаться доступные виртуальные считыватели);
• вызов Вызов функции SCardConnect для нужного считывателя с параметром dwShareMode == SCARD_SHARE_DIRECT;
• вызов Вызов функции SCardControl с параметром RUTOKEN_CONTROL_CODE_START_NFC;
• работа Работа с Рутокеном;
• вызов Вызов функции SCardControl с параметром RUTOKEN_CONTROL_CODE_STOP_NFC;вызов функции SCardDisconnect
• Вызов функции SCardDisconnect.

Пример работы с API

Примеры работы с API есть в репозитории на GitHub rutoken-demoshift-ios в файле https://github.com/AktivCo/rutoken-demoshift-ios/blob/master/demoshift/PcscWrapper/PcscWrapper.swift