Не так давно, была ��публикована статья «Пастильда — открытый аппаратный менеджер паролей». Так как данный проект является открытым, то мы решили, что будет интересно, если мы будем писать небольшие заметки о процессе проектирования, о задачах, которые перед нами стоят и о трудностях, с которыми мы сталкиваемся.
Основная суть Пастильды заключается в том, что она является своеобразным переходником между клавиатурой и ПК. Таким образом, она должна уметь:
- быть USB хостом для клавиатуры, которая к ней подключается,
- быть клавиатурой для ПК, чтобы либо перенаправлять сообщения от реальной клавиатуры, либо самой быть клавиатурой,
- быть дисковым накопителем, чтобы можно было редактировать базу данных паролей в удобном для человека виде.
Данный функционал является скелетом нашего проекта, поэтому первая заметка будет посвящена именно ему.
Реализация USB хоста
Итак, во-первых мне нужно было реализовать на устройстве USB хост, чтобы оно могло распознавать и общаться с подключенной к нему клавиатурой. Так как в работе я использую связку Eclipse + GNU ARM Eclipse + libopencm3, то очень хотелось найти уже что-то готовое и желательно написанное с использованием библиотеки libopencm3. Желание мое было очень жирным, до последнего момента не верила, что мои поиски увенчаются успехом. Однако под конец рабочего дня, проскролив интернет до самого дна, я вдруг наткнулась вот на это. libusbhost? Серьезно? И это был не просто написанный на основе libopencm3 usb хост, он еще и был написан под STM32F4, под тот самый, который мы решили использовать в проекте. В общем, звезды сошлись и радости моей не было предела. Кстати, оказалось, что этот проект создавался как часть libopencm3, однако его так и не добавили в библиотеку.
Как библиотеку, libusbhost я не собирала, просто взяла необходимые мне исходники, написала драйвер для клавиатуры и, в общем-то все, погнали! Но обо всем по-порядку.
Из libusbhost я взяла следующие файлы:
- usbh_device_driver.h
- usbh_config.h
- usbh_hubbed.[ch]
- usbh_lld_stm32f4.[ch]
Там был еще файл usart_helpers.[ch], с его помощью можно было по UART передавать в терминал все сообщения, приходящие от устройства в хост и еще много различной отладочной информации. Я с этим функционалом поигралась, но из проекта его убрала.
По аналогии с usbh_driver_hid_mouse.[ch], я написала драйвер для клавиатуры (usbh_driver_hid_kbd.[ch]).
Далее был реализован простенький класс, для работы с хостом:
USB Host Class
constexpr uint8_t USB_HOST_TIMER_NUMBER = 6; constexpr uint16_t USB_HOST_TIMER_PRESCALER = (8400 - 1); constexpr uint16_t USB_HOST_TIMER_PERIOD = (65535); typedef void (*redirect)(uint8_t *data, uint8_t len); typedef void (*control_interception)(); static redirect redirect_callback; static control_interception control_interception_callback; class USB_host { public: USB_host(redirect redirect_callback, control_interception control_interception_callback); void poll(); static void kbd_in_message_handler(uint8_t data_len, const uint8_t *data); static constexpr hid_kbd_config_t kbd_config = { &kbd_in_message_handler }; static constexpr usbh_dev_driver_t *device_drivers[] = { (usbh_dev_driver_t *)&usbh_hid_kbd_driver }; private: TIMER_ext *_timer; void timer_setup(); uint32_t get_time_us(); void oth_hs_setup(); };
Здесь все прозрачно. Устройство должно слушать клавиатуру и ждать набора специальной комбинации клавиш, для перехода в режим выбора логина и пароля. Это происходит в обработчике прерывания от клавиатуры kbd_in_message_handler(uint8_t data_len, const uint8_t *data). Тут есть два варианта развития событий:
- Если комбинации нет, то нам нужно пропустить сообщение от клавиатуры дальше в ПК. Для обработки данного события, в конструктор передана функция _redirect_callback.
- Если комбинация нажата, то нам нужно оповестить систему о том, что мы перешли в режим выбора логина и пароля, следовательно, мы больше не транслируем сообщения от клавиатуры в ПК. Теперь само устройство является клавиатурой, а сообщения от настоящей клавиатуры теперь интерпретируются как команды устройству. Для обработки такого события, в конструктор передана функция _control_interception_callback.
Реализация составного USB устройства
Далее мне нужно было сделать так, чтобы наше устройство отображалось в диспетчере устройств и как клавиатура, и как дисковый накопитель. Тут вся магия в дескрипторах=) В этом документе, в главе 9, подробно описан USB Device Framework. Эту главу нужно очень внимательно прочитать и в соответствии с ней описать дескрипторы устройства. В моем случае получилось следующее:
Composite USB Descriptors
static constexpr uint8_t keyboard_report_descriptor[] = { 0x05, 0x01, 0x09, 0x06, 0xA1, 0x01, 0x05, 0x07, 0x19, 0xE0, 0x29, 0xE7, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0x95, 0x01, 0x75, 0x08, 0x81, 0x01, 0x95, 0x03, 0x75, 0x01, 0x05, 0x08, 0x19, 0x01, 0x29, 0x03, 0x91, 0x02, 0x95, 0x05, 0x75, 0x01, 0x91, 0x01, 0x95, 0x06, 0x75, 0x08, 0x15, 0x00, 0x26, 0xFF, 0x00, 0x05, 0x07, 0x19, 0x00, 0x2A, 0xFF, 0x00, 0x81, 0x00, 0xC0 }; static constexpr char usb_strings[][30] = { "Third Pin", "Composite Device", "Pastilda" }; static constexpr struct usb_device_descriptor dev = { USB_DT_DEVICE_SIZE, //bLength USB_DT_DEVICE, //bDescriptorType 0x0110, //bcdUSB 0x0, //bDeviceClass 0x00, //bDeviceSubClass 0x00, //bDeviceProtocol 64, //bMaxPacketSize0 0x0483, //idVendor 0x5741, //idProduct 0x0200, //bcdDevice 1, //iManufacturer 2, //iProduct 3, //iSerialNumber 1 //bNumConfigurations }; typedef struct __attribute__((packed)) { struct usb_hid_descriptor hid_descriptor; struct { uint8_t bReportDescriptorType; uint16_t wDescriptorLength; } __attribute__((packed)) hid_report; } type_hid_function; static constexpr type_hid_function keyboard_hid_function = { { 9, //bLength USB_DT_HID, //bDescriptorType 0x0111, //bcdHID 0, //bCountryCode 1 //bNumDescriptors }, { USB_DT_REPORT, sizeof(keyboard_report_descriptor) } }; static constexpr struct usb_endpoint_descriptor hid_endpoint = { USB_DT_ENDPOINT_SIZE, //bLength USB_DT_ENDPOINT, //bDescriptorType Endpoint::E_KEYBOARD, //bEndpointAddress USB_ENDPOINT_ATTR_INTERRUPT, //bmAttributes 64, //wMaxPacketSize 0x20 //bInterval }; static constexpr struct usb_endpoint_descriptor msc_endpoint[] = { { USB_DT_ENDPOINT_SIZE, //bLength USB_DT_ENDPOINT, //bDescriptorType Endpoint::E_MASS_STORAGE_IN, //bEndpointAddress USB_ENDPOINT_ATTR_BULK, //bmAttributes 64, //wMaxPacketSize 0 //bInterval }, { USB_DT_ENDPOINT_SIZE, //bLength USB_DT_ENDPOINT, //bDescriptorType Endpoint::E_MASS_STORAGE_OUT, //bEndpointAddress USB_ENDPOINT_ATTR_BULK, //bmAttributes 64, //wMaxPacketSize 0 //bInterval } }; static constexpr struct usb_interface_descriptor iface[] = { { USB_DT_INTERFACE_SIZE, //bLength USB_DT_INTERFACE, //bDescriptorType Interface::I_KEYBOARD, //bInterfaceNumber 0, //bAlternateSetting 1, //bNumEndpoints USB_CLASS_HID, //bInterfaceClass 1, //bInterfaceSubClass 1, //bInterfaceProtocol 0, //iInterface &hid_endpoint, &keyboard_hid_function, sizeof(keyboard_hid_function) }, { USB_DT_INTERFACE_SIZE, //bLength USB_DT_INTERFACE, //bDescriptorType Interface::I_MASS_STORAGE, //bInterfaceNumber 0, //bAlternateSetting 2, //bNumEndpoints USB_CLASS_MSC, //bInterfaceClass USB_MSC_SUBCLASS_SCSI, //bInterfaceSubClass USB_MSC_PROTOCOL_BBB, //bInterfaceProtocol 0x00, //iInterface msc_endpoint, 0, 0 }, }; static constexpr struct usb_config_descriptor::usb_interface ifaces[] { { (uint8_t *)0, //cur_altsetting 1, //num_altsetting (usb_iface_assoc_descriptor*)0, //iface_assoc &iface[Interface::I_KEYBOARD] //altsetting }, { (uint8_t *)0, //cur_altsetting 1, //num_altsetting (usb_iface_assoc_descriptor*)0, //iface_assoc &iface[Interface::I_MASS_STORAGE] //altsetting }, }; static constexpr struct usb_config_descriptor config_descr = { USB_DT_CONFIGURATION_SIZE, //bLength USB_DT_CONFIGURATION, //bDescriptorType 0, //wTotalLength 2, //bNumInterfaces 1, //bConfigurationValue 0, //iConfiguration 0x80, //bmAttributes 0x50, //bMaxPower ifaces };
keyboard_report_descriptor был взят из документа Device Class Definition for Human Interface Devices (HID) , Appendix E.6 Report Descriptor (Keyboard). Честно, сильно не разбиралась со структурой отчета, поверила документу) В целом, вот пара моментов, на которые нужно обратить особое внимание:
- usb_config_descriptor: поле bNumInterfaces должно отражать столько интерфейсов, сколько реально реализовано. В нашем случае два: HID и MSD
- usb_interface_descriptor: поле bInterfaceNumber обозначает номер интерфейса, но отсчет начинается с нуля, следовательно, номер первого интерфейса — 0.
Вот, с описательной точки зрения, наверно, и все. Не могу не отметить, как грамотно в библиотеке описаны дескрипторы (их описание находится в файле usbstd.h). Все четко по документации. Полагаю, это значительно упростило мне задачу, так как не возникало вопросов «Как же мне описать составное устройство?». Все сразу было понятно.
Для работы с составным устройством был написан класс USB_composite, представленный ниже.
Composite USB Class
extern "C" void USB_OTG_IRQ(); int USB_control_callback(usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len, usbd_control_complete_callback *complete); void USB_set_config_callback(usbd_device *usbd_dev, uint16_t wValue); static uint8_t keyboard_protocol = 1; static uint8_t keyboard_idle = 0; static uint8_t keyboard_leds = 0; class USB_composite { public: uint8_t usbd_control_buffer[500]; UsbCompositeDescriptors *descriptors; uint8_t usb_ready = 0; usbd_device *my_usb_device; USB_composite(const uint32_t block_count, int (*read_block)(uint32_t lba, uint8_t *copy_to), int (*write_block)(uint32_t lba, const uint8_t *copy_from)); void usb_send_packet(const void *buf, int len); int hid_control_request(usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len, void (**complete)(usbd_device *usbd_dev, struct usb_setup_data *req)); void hid_set_config(usbd_device *usbd_dev, uint16_t wValue); };
Ключевыми в этом классе являются две функции:
- Функция hid_control_request нужна для общения Пастильды как клавиатуры с хостом (в данном случае, хост — это ПК). Вне класса данная функция вызывается через USB_control_callback.
- Функция hid_set_config нужна для того, чтобы настроить конечные точки (endpoints) и зарегистрировать USB_control_callback, описанный в предыдущем пункте. Вне класса данная функция вызывается через USB_set_config_callback.
Ниже представлен вариант их реализации:
Callbacks
int USB_composite::hid_control_request(usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len, void (**complete)(usbd_device *usbd_dev, struct usb_setup_data *req)) { (void)complete; (void)usbd_dev; if ((req->bmRequestType & USB_REQ_TYPE_DIRECTION) == USB_REQ_TYPE_IN) { if ((req->bmRequestType & USB_REQ_TYPE_TYPE) == USB_REQ_TYPE_STANDARD) { if (req->bRequest == USB_REQ_GET_DESCRIPTOR) { if (req->wValue == 0x2200) { *buf = (uint8_t *)descriptors->keyboard_report_descriptor; *len = sizeof(descriptors->keyboard_report_descriptor); return (USBD_REQ_HANDLED); } else if (req->wValue == 0x2100) { *buf = (uint8_t *)&descriptors->keyboard_hid_function; *len = sizeof(descriptors->keyboard_hid_function); return (USBD_REQ_HANDLED); } return (USBD_REQ_NOTSUPP); } } else if ((req->bmRequestType & USB_REQ_TYPE_TYPE) == USB_REQ_TYPE_CLASS) { if (req->bRequest == HidRequest::GET_REPORT) { *buf = (uint8_t*)&boot_key_report; *len = sizeof(boot_key_report); return (USBD_REQ_HANDLED); } else if (req->bRequest == HidRequest::GET_IDLE) { *buf = &keyboard_idle; *len = sizeof(keyboard_idle); return (USBD_REQ_HANDLED); } else if (req->bRequest == HidRequest::GET_PROTOCOL) { *buf = &keyboard_protocol; *len = sizeof(keyboard_protocol); return (USBD_REQ_HANDLED); } return (USBD_REQ_NOTSUPP); } } else { if ((req->bmRequestType & USB_REQ_TYPE_TYPE) == USB_REQ_TYPE_CLASS) { if (req->bRequest == HidRequest::SET_REPORT) { if (*len == 1) { keyboard_leds = (*buf)[0]; } return (USBD_REQ_HANDLED); } else if (req->bRequest == HidRequest::SET_IDLE) { keyboard_idle = req->wValue >> 8; return (USBD_REQ_HANDLED); } else if (req->bRequest == HidRequest::SET_PROTOCOL) { keyboard_protocol = req->wValue; return (USBD_REQ_HANDLED); } } return (USBD_REQ_NOTSUPP); } return (USBD_REQ_NEXT_CALLBACK); } int USB_control_callback(usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len, usbd_control_complete_callback *complete) { return(usb_pointer->hid_control_request(usbd_dev, req, buf, len, complete)); } void USB_composite::hid_set_config(usbd_device *usbd_dev, uint16_t wValue) { (void)wValue; (void)usbd_dev; usbd_ep_setup(usbd_dev, Endpoint::E_KEYBOARD, USB_ENDPOINT_ATTR_INTERRUPT, 8, 0); usbd_register_control_callback(usbd_dev, USB_REQ_TYPE_INTERFACE, USB_REQ_TYPE_RECIPIENT, USB_control_callback ); } void USB_set_config_callback(usbd_device *usbd_dev, uint16_t wValue) { usb_pointer->hid_set_config(usbd_dev, wValue) ; }
Как правило, функции control_request и set_config должны быть явно описаны для каждого устройства. Однако из этого правила есть исключение: Mass Storage Device. Итак, разберемся с конструктором класса USB_Composite.
Во-первых, мы инициализируем ноги USB OTG FS:
GPIO_ext uf_p(PA11); GPIO_ext uf_m(PA12); uf_p.mode_setup(Mode::ALTERNATE_FUNCTION, PullMode::NO_PULL); uf_m.mode_setup(Mode::ALTERNATE_FUNCTION, PullMode::NO_PULL); uf_p.set_af(AF_Number::AF10); uf_m.set_af(AF_Number::AF10);
Во-вторых, нам нужно проинициализировать наше составное устройство, зарегистрировать USB_set_config_callback, о котором шла речь выше, и разрешить прерывание:
my_usb_device = usbd_init(&otgfs_usb_driver, &(UsbCompositeDescriptors::dev), &(UsbCompositeDescriptors::config_descr), (const char**)UsbCompositeDescriptors::usb_strings, 3, usbd_control_buffer, sizeof(usbd_control_buffer)); usbd_register_set_config_callback(my_usb_device, USB_set_config_callback); nvic_enable_irq(NVIC_OTG_FS_IRQ);
Этого достаточно для того, чтобы в диспетчере устройств наше устройство распознавалось:
- Во вкладке «Контроллеры USB»: как составное устройство,
- В этой же вкладке, как «Запоминающее устройство для USB»,
- Во вкладке «Клавиатуры», как «Клавиатура HID».
Однако «Запоминающее устройство для USB» будет помечено предупреждением о том, что устройство работает неправильно. Все дело в том, что в отличие от других USB устройств, Mass Storage инициализируется немного иначе, через функцию usb_msc_init, описанную в файле usb_msc.c библиотеки libopencm3. Выше я уже упоминала о том, что для MSD нет необходимости явно описывать функции control_request и set_config. Это потому, что функция usb_msc_init все сделает за нас: и конечные точки настроит, и все колбэки зарегистрирует. Таким образом, нам нужно дополнить конструктор еще одной строчкой:
usb_msc_init(my_usb_device, Endpoint::E_MASS_STORAGE_IN, 64, Endpoint::E_MASS_STORAGE_OUT, 64, "ThirdPin", "Pastilda", "0.00", block_count, read_block, write_block);
Тут можно заметить, что при инициализации MSD, нам нужно передать ему минимальное API для работы с памятью:
- block_count: количество секторов памяти,
- read_block: функция для чтения сектора,
- write_block: функция для записи сектора.
В Пастильде мы используем внешний флеш SST25VF064C. Драйвер для этой микросхемы можно посмотреть здесь. В дальнейшем, на основе этого драйвера, во флеше будет реализована файловая система. Скорее всего, об этом как-нибудь подробно напишет мой коллега. Но так как я хотела поскорее протестировать работу MSD, я написала зародыш файловой системы=) Над ним можно поплакать здесь.
Так вот. Теперь, когда конструктор класса USB_Composite дописан, можно собрать проект, прошить устройство и увидеть, что «Запоминающее устройство для USB» больше не помечено предупреждением, а во вкладке «Дисковые устройства» можно обнаружить «ThirdPin Pastilda USB Device». И, казалось бы, все хорошо. Но нет=) Проблем стало больше:
1. Зайти на диск невозможно. При попытке сделать это все виснет, умирает, компьютеру очень плохо.
2. Распознавание устройства как дискового занимает более 2-х минут.
Об этих проблемах и о том, как их решить без вреда для здоровья написано здесь: USB mass storage device и libopencm3.
И, о, чудо! Никаких пятен=) Теперь все работает. У нас есть USB хост и составное USB устройство. Осталось только объединить их работу.
Объединение хоста и составного устройства
Наша цель:
- Транслировать сообщения от клавиатуры в ПК до тех пор, пока не нажата комбинация Ctrl + Shift + ~.
- После нажатия комбинации Ctrl + Shift + ~, Пастильда должна перехватить управление и отправить сообщение в ПК как клавиатура, после чего мы возвращаемся в режим трансляции и снова ожидаем комбинацию.
Код, реализующий все это, простой как палка:
App.cpp
App *app_pointer; App::App() { app_pointer = this; clock_setup(); systick_init(); _leds_api = new LEDS_api(); _flash = new FlashMemory(); usb_host = new USB_host(redirect, control_interception); usb_composite = new USB_composite(_flash->flash_blocks(), _flash->flash_read, _flash->flash_write); } void App::process() { _leds_api->toggle(); usb_host->poll(); } void App::redirect(uint8_t *data, uint8_t len) { app_pointer->usb_composite->usb_send_packet(data, len); } void App::control_interception() { memset(app_pointer->key, 0, 8); app_pointer->key[2] = KEY_W; app_pointer->key[3] = KEY_O; app_pointer->key[4] = KEY_N; app_pointer->key[5] = KEY_D; app_pointer->key[6] = KEY_E; app_pointer->key[7] = KEY_R; app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8); app_pointer->key[2] = 0; app_pointer->key[3] = 0; app_pointer->key[4] = 0; app_pointer->key[5] = 0; app_pointer->key[6] = 0; app_pointer->key[7] = 0; app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8); app_pointer->key[2] = KEY_SPACEBAR; app_pointer->key[3] = KEY_W; app_pointer->key[4] = KEY_O; app_pointer->key[5] = KEY_M; app_pointer->key[6] = KEY_A; app_pointer->key[7] = KEY_N; app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8); app_pointer->key[2] = 0; app_pointer->key[3] = 0; app_pointer->key[4] = 0; app_pointer->key[5] = 0; app_pointer->key[6] = 0; app_pointer->key[7] = 0; app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8); }
В конструкторе мы инициализируем все, что необходимо:
- Светодиоды, чтобы моргали;
- Флеш, чтобы можно было файлы на диске создавать / удалять;
- Хост, передав ему при этом функцию redirect (что делать, если комбинации нет) и control_interception (что делать, если комбинация нажата);
- Составное устройство, передав ему функции чтения / записи памяти;
И вот, собственно, и все. Начало положено, скелет нашего устройства создан. Совсем скоро будет доработана файловая система, по нажатию комбинации Ctrl + Shift + ~, мы будем попадать в однострочное меню, а во флеше будет храниться наша зашифрованная база данных паролей.
Буду рада любым комментариям и пожеланиям.
И, конечно же, ссылка на github.
UPD 27.06.2017:
- Репозиторий проекта Пастильда переехал сюда. Недавно был опубликован релиз 1.0.
- Последние новости по проекту можно смотреть здесь.
- А еще мы наконец-то запустили сайт проекта!
