Biometric FingerPrint Software Development Kit (BFP SDK) для Linux/Unix платформ. Copyright (c) 2005 Dmitry Stefankov. Предварительное описание. Версия 1.3 Апрель 2005 года. 1. Общее описание 2. Требования к программному обеспечению и оборудованию 3. Состав BFP SDK 4. Установка и применение 5. Описание структур и функций 6. Драйвер и конфигурационный файл bfpsdk.conf 7. Дополнения и разъяснения 1. Общее описание Цель BFP SDK - использование средств биометрической аутентификации на Unix/Linux платформах. До сегодняшнего дня применение любых биометрических технологий в мире Unix в широком масштабе было практически невозможно. Основными причинами этого являлись крайне сложное и дорогое оборудование, несовершенство самих технологий, а также перенос программного обеспечения (ПО) с платформы Microsoft Windows в мир Unix. Стандарты и ПО для Microsoft Windows всегда были крайне сложны, противоречивы и очень неудобны в использовании. Однако по мере совершенствования биометрических технологий и увеличения надежности оборудования стало возможным добиться желаемой простоты и экономичности для биометрических решений. Теперь с появлением такого простого и удобного пакета SDK будет наконец возможным внедрение и эксплуатация биометрической аутентификации в мире Unix/Linux. 2. Требования к программному обеспечению и оборудованию BFP SDK предназначен пока только для эксплуатации на аппаратных платформах на базе процессора x86 фирмы Intel или совместимых платформах. Операционные системы для которых разрабатывался BFP SDK следующие: ОС на базе ядра Linux (например, дистрибутивы Suse Linux, Debian Linux, RedHat Linux, Mandrake Linux, ASP Linux) и ОС на базе ядра BSD 4.4 (например, FreeBSD, NetBSD, OpenBSD). Мы поддерживаем все версии ядра Linux, начиная с версии 2.2.18 и все версии ОС FreeBSD, начиная с версии 4.9. Также поддерживаются все версии ОС OpenBSD, начиная с версии 3.0, и все версии ОС NetBSD, начиная с версии 1.5.2 . На момент написания этого рукодство текущими версиями были: ядро Linux - 2.4.30 и 2.6.11; ОС FreeBSD - 4.11 или 5.3; ОС NetBSD - 2.0; ОС OpenBSD - 3.6; BFP SDK был оттестирован на следующих платформах и ОС: 1) Intel Pentium 200Mhz, 64MB ОЗУ, Intel chipset 430HX (Mainboard P/I-XP55T2P4) FreeBSD 4.11, OpenBSD 3.0, Suse Linux 6.3 (kernel 2.2.25), RedHat Linux 6.2 (kernel 2.2.18,2.2.25,2.4.25); 2) Intel Pentium 166MHz, 64MB ОЗУ, Intel chipset 430TX (Mainboard Asus TX97-XE) - FreeBSD 4.11, NetBSD 1.5.2; Debian Linux 2.2 (kernel 2.4.14) 3) Intel Pentium III 2x1000Mhz, 1 GB ОЗУ, VIA Apollo Pro133A chipset (Mainboard 694D Pro2-IR, MS-6321 v2.X) FreeBSD 4.11, Suse Linux 7.3 (kernel 2.4.10 - 2.4.20), RedHat Linux 9.0 (kernel 2.4.20 - 2.6.5), Mandrake Linux 8.1 (kernel 2.4.8), Mandrake Linux 9.1 (kernel 2.4.21); Mandrake Linux 10.0 (kernel 2.6.11); 4) Intel Pentium III 1GHz, 512 MB memory, VIA Twister (Asus B1000 Series) FreeBSD 5.3, RedHat Linux 9.0 (kernel 2.4.20 - 2.6.1) Сейчас в BFP SDK поддерживается в качестве аппаратного обеспечения только биометрический сканер отпечатков пальцев фирмы Futronic с интерфейсом USB. Пока нет каких-либо планов поддерживать сканеры других фирм-изготовителей. В составе BFP SDK нет драйвера для сканера (т.наз. kernel mode driver). При правильном проектировании аппаратного обеспечения для данной задачи он не нужен. Интерфейс USB обладает режимом передачи неструктурированного массива данных. Этого достаточно для работы с USB устройством из пользовательского режима (user mode). BFP SDK полагается здесь на широко распространенную многоплатформенную библиотеку libusb. Последняя версия libusb - 0.1.7 (на момент создания BFP SDK). Именно эта версия рекомендуется для установки и использования совместно с BFP SDK. Официальный сайт этой библиотеки - http://libusb.sourceforge.net. После установки этой библиотеки не забудьте обновить кеш для динамических библиотек (для помощи: man ldconfig). Примечание: см. также 6 (драйвер). 3. Состав BFP SDK BFP SDK включает в себя следующие файлы: bfpsdk-x.y.z.tar.gz - собственно весь комлект ПО для BFP SDK, где x.y.z - это номер версии. bfpsdk.so - динамически подгружаемая библиотека BFP SDK для приложений libbfpsdk.a - библиотека BFP SDK для статической сборки приложений bfpsdk.h - включаемый файл объявлений и определений BFP SDK для приложений bfpsdk.mak - makefile для установки/удаления BFP SDK библиотеки в систему, сборка/удаление примеров sample.c - базовый текст для применения BFP SDK Содержит стандартный код для примения BFP SDK. Включает получение изображений со сканера, построение темплейта и модели по этим изображениям, сравнение темплейта и модели. sample.mak - makefile для сборки примера sample sample - скомпилированный код для вашей платформы text-demo.c - демонстрационный пример применения BFP SDK для работы с базой пользовательских биометрических темплейтов. Полностью показывает все возможности BFP SDK. Реализованы все стандартые функции биометрической аутентификации (enrollment/identification/verification). Простой текстовой интерфейс для любой среды Linux/Unix (даже без curses). text-demo.mak - makefile для сборки примера text-demo text-demo - скомпилированный код для вашей платформы ncurses-demo.c - функционально идентичен text-demo Текстовой пользовательский интерфейс базируется на библиотеке curses. ncurses-demo.mak - makefile для сборки примера ncurses-demo ncurses-demo - скомпилированный код для вашей платформы gtk-demo.c - функционально идентичен text-demo Графический интерфейс для GNOME/GTK2+. Также должен быть установлен пакет ImagePick. gtk-demo.mak - makefile для сборки примера gtk-demo gtk-demo - скомпилированный код для вашей платформы logo.png - легко узнаваемый образ ("penguin") fp-off.png - графический образ ("уберите палец") fp-on.png - графический образ ("приложите палец") 4. Установка и применение Порядок установки: а) Скопируйте BFP SDK в какой-либо каталог, например, /usr/local/src/bfpsdk б) Разверните библиотеку: # tar xzf bfpsdk.tar.gz в) Установите BFP SDK в систему # make -f bfpsdk.mak install (Для удаления BFP SDK из системы используйте uninstall вместо install) г) Необязательно. Как собрать примеры из библиотеки? # make -f sample.mak # make -f text-demo.mak # make -f ncurses-demo.mak # make -f gtk-demo.mak Для удаления используйте те же команды, но с параметром clean. Порядок применения. Теперь вы можете использовать BFP SDK в своих приложениях. а) В текст приложения должна быть добавлена строка: #include б) При компиляции должно быть добавлено: -I/usr/local/include в) При сборке должно быть добавлено: /usr/lib/bfpsdk.so или просто bfpsdk.so г) Для статической сборки нужно добавить следующее: -static -lbfpsdk Cмотрите для уточнения исходный текст примеров из BFP SDK. 5. Описание структур и функций Структуры. В BFP SDK определены две следующие структуры - bfp_hardware_info и bfp_software_info. Структура bfp_hardware_info хранит описание аппаратных особенностей каждого сканера. Для прикладного программиста интересен только серийный номер сканер. Структура bfp_software_info содержит необходимые величины и константы, делающие код прикладной программы, независимым от особенностей реализации библиотеки BFP SDK (аппаратной части и математического алгоритма для работы с отпечатками пальцев). Необходимые поля прикладному программисту следующие: model_size -- размер модели (в байтах) total_size -- размер темплейта (в байтах) measure -- мера сравнения (порог узнавания или пропуска) image_size -- размер изображения (в байтах) samples_num -- число изображений для построения темплейта models_num -- минимальное число моделей для темплейта max_models -- максимальное число моделей для темплейта Правильное использование этих структур можно найти в демонстрационных примерах BFP SDK. Обязательно посмотрите этот код из BFP SDK, прежде чем разрабатывать свой код. Функции. Название Назначение --------------------- --------------------------------------- bfp_init подключить библиотеку bfp_deinit отключить библиотеку bfp_get_software_info вернуть параметры библиотеки bfp_get_hardware_info вернуть параметры оборудования bfp_get_image_timeo получить изображение с отпечатком пальца bfp_extract построить темплейт/модель bfp_match сравненить темплейт/модель ---------------- Инициализация библиотеки BFP SDK. int bfp_init(); Возвращаемые значения: 0 = успешно, -1 = ошибка Вызывается самой первой. Если инициализация прошла успешно, то можно продолжать работу. В противном случае необходимо завершить работу приложения. ---------------- Завершение работы библиотеки BFP SDK. int bfp_deinit(); Возвращаемые значения: 0 = успешно Вызывается самой последней. После ее вызова работа с BFP SDK уже невозможна. ---------------- Получить значения констант библиотеки BFP SDK. int bfp_get_software_info( struct bfp_software_info * p_soft_param ); Параметры: struct bfp_software_info * p_soft_param -- указатель на буфер для заполнения Возвращаемые значения: 0 = успешно, -1 = ошибка Прикладной программист передает указатель на структуру bfp_software_info и после вызова можно применить найденные значения в этой структуре для корректной инициализации других объектов в прикладной программе. Рекомендуется вызывать эту функции после bfp_init(), хотя она может быть вызвана в любой момент времени. ---------------- Получить описание BFP сканера, подключеннго к системе. int bfp_get_hardware_info( struct bfp_hardware_info * p_hard_param, int scanner ); Параметры: struct bfp_hardware_info * p_hard_param -- указатель на буфер для заполнения int scanner -- порядковое число сканера (только для подсчета) Возвращаемые значения: 0 = успешно, -1 = ошибка, -2 = нет сканера Прикладной программист передает указатель на структуру bfp_hardware_info и порядковое число сканера. Меняя это число от 0 до N вы можете подсчитать число сканеров в системе. Однако, необходимо где-то запомнить серийные номера этих сканеров, потому что если к системе подключено несколько сканеров, то иного способа при получении изображения их различать нет. Используя эту функцию с числом 0 всегда можно убедиться, что есть как минимум один подключенный сканер. ---------------- Получить изображение отпечатка пальца с BFP сканера. int bfp_get_image_timeo( unsigned char * buf, unsigned long int bufsize, int timeout, unsigned long int sernum ); Параметры: unsigned char * buf -- буфер для запоминания изображения unsigned long int bufsize -- размер буфера int timeout -- время ожидания для получения отпечатка пальца (в сеkундах) 0 = считать изображение без ожидания unsigned long int sernum -- серийный номер сканера 0 = использовать первый найденный сканер в системе Возвращаемые значения: 0 = успешно, -1 = ошибка Эта функция завершается успешно, только если изображение содержит действительно отпечаток пальца, в остальных случаях всегда будет возвращена ошибка. При значении timeout отличного от нуля сканер опрашивается в среднем раз в секунду для получения изображения. ---------------- Построение биометрической модели/темплейта по изображению(-ям). int bfp_extract(void *images, int n, void *buf); Параметры: void *images -- буфер содержащий от 1 до n изображений int n -- число изображений (если 1=построить модель, >1=построить темплейт) void *buf -- буфер для запоминания данных модели или темплейта (размер буфера должен достаточным, иначе приложение будет завершено обычно по SEGV) Возвращаемые значения: -2 = неверные параметры, -1 = ошибка, >0=размер возвращаемых данных (успешно завершение) Прикладной программист должен передать корректные параметры для успешного построения модели/темплейта. Примеры правильного использования этой функции можно посмотреть в демонстрационных текстах BFP SDK. Размеры буферов вычисляются следующим образом: для изображений - размер_изображения * число_изображений; для биометрический данных - размер модели/темплейта (взять значения из структруры, полученной при вызове функции bfp_get_software_info. ---------------- Сравнение темплейтов и моделей. int bfp_match(void *buf1, int n1, void *buf2, int n2); Параметры: void *buf1 -- буфер для данных модели/темплейта int n1 -- размер модели/темплейта в первом буфере (в байтах) void *buf2 -- буфер для данных модели/темплейта int n2 -- размер модели/темплейта в втором буфере (в байтах) Возвращаемые значения: -2 = неверные параметры, -1 = ошибка, [0..1000] = величина меры совпадения (успешно завершение) Чем ближе это число к 1000, тем более совпадают предъявленные биометрические характеристики. Рекомендуемый порог равен 300, а еще лучше 600. Прикладной программист должен передать корректные параметры для успешного сравнения модели/темплейта. Примеры правильного использования этой функции можно посмотреть в демонстрационных текстах BFP SDK. Как правильно вычислить размеры буферов смотрите выше в описании функции bfp_extract. 6. Драйвер и конфигурационный файл bfpsdk.conf Для некоторых конфигураций ОС и оборудования библиотека libusb может работать не очень корректно. В этом случае рекомендуется установить драйвер, релизованный в виде модуля ядра. Для ОС FreeBSD это модуль uscan_bfp. Для ядра Linux это модуль uscanner (для всех версий ядра - 2.2.X,2.4.X,2.6.X). Драйвер поставляется по запросу, в исходных текстах и без поддержки. Вы должны будете собрать и установить модуль самостоятельно для своей платформы и ОС. Для сборки достаточно выполнить make. Для переключения работы BFP SDK между библиотекой libusb и драйвером используйте конфигурационный файл bfpsdk.conf. Этот файл должен быть скопирован в каталог /usr/local/etc. Следующие директивы определены и используются: use_libusb=[0|1] (0=использовать драйвер, 1=использовать libusb) use_multi_devices=[0|1] (Если выбрано использовать драйвер, то при включении это директивы в 1, можно использовать несколько устройств, заданных при помощи директив device_name_x, где x может меняться от 0 до 15) device_name_0="/dev/uscanner0" (для ОС Linux используйте /dev/usb/scanner0, см. текст uscanner как создать это устройство и подключить, для ОС FreeBSD используйте /dev/uscanner0 и отключите uscanner в ядре, если Вам нужен модуль uscanner, то модифицируйте код для поддержки Вашего устройства) #usb_device_vendor_id=xxxx #usb_device_product_id=yyyy (использовать также заданные пользователем значения для USB устройства дополнительно ко встроенной таблице поддерживаемых устройств) print_error_messages=[0|1] (0=выключить, 1=включить; печатать сообщения об ошибках в отладочной версии SDK) fast_match=0 (0=выключить, 1=включить; быстрое сравнение, остановка на первой совпадении моделей если уровень меры был превышен) samples_num=N (число изображений запрашиваемых в ходе обучения, заметим, что пользовательская программа может использовать любое число иозображений для обучения, данная величина - это устанавливаемый параметр для библиотеки) Драйвер поддерживает только одно устройство в отличие от библиотеки libusb. 7. Дополнения Ограничения. A) Текущая реализация В текущей реализации BFP SDK следующие функции являются нереентерабельными: Название Причина ------------------- --------------------------------------------- bfp_get_image_timeo шина USB не является многоканальной магистралью bfp_extract использование глобальных данных bfp_match использование глобальных данных Возможно, что в следующих реализациях ограничения для двух последних функций будут преодолены (bfp_extract и bfp_match). А при использовании первой функции это ограничение является естественным и не будет изменено в дальнейшем. При использовании этих функций в многопоточных и параллельных приложениях рекомендуется применять собственные алгоритмы и дисциплины порядка доступа/блокировки/ожидания. В BFP SDK такие алгоритмы/дисциплины не будут встроены, чтобы согласно заветам отцов-основателей Unix не увеличивать бездумно сложность ПО на каждом уровне. Б) Дисциплина программирования В функциях BFP SDK есть минимальная проверка входных параметров, однако все остальное целиком на совести прикладного программиста. Неверные размеры буферов и т.д. будут приводить к фатальному завершению работы BFP SDK. Несмотря на удивительную простоту функций от программиста требуется аккуратность и внимательность при их использовании. Не стесняйтесь заимствовать код из примеров BFP SDK, так как данный код прежде всего именно для этого и предназначен. В) Сканеры "Futronic" Большинство сканеров "Futronic" сегодня поставляются с firmware, в котором нет поддержки серийного номера для сканера. BFP SDK автоматически обнаруживает такое firmware и в этом случае поддерживает только один сканер в системе. Примечание 1. На момент версии руководства версии 1.1 практически все сканеры "Futronic" поставляются с поддержкой серийного номера.