Keyring project version 1.0

Background

I have too many passwords to keep them in mind, so one day I have decided to develop my own hardware secured password storage. It should have met the following requirements to satisfy my needs:

1. Usability: hardware and software should be simple in usage and maintenance.
2. Security: it should have basic internal pseudo-encryption (it is enough for the first version) and it should not store master password.
3. Storage: device should be able to store about a hundred passwords at a minimum.
4. Performance: password retrieve time should not exceed 1 second.
5. Sizes: device with enclosing should have typical size of USB stick.
6. Price: should not exceed $30.00.

I believe there are many analogues presented at the market and you may find many varieties of encrypted storage, here are couple of examples:

• Portable Password Vault – project at Hack A Day
• SplashID KeySafe – stores up to 4 GB of data secured

But the idea is to focus on passwords and descriptions for them (addresses, URLs, devices, etc.), current, full and, I hope, final name of the project is OWLSAN Keyring.

Architecture

The next step was to define architecture. Omitting the details and reasons of my choice, I have finally decided on implementing basic client-server architecture, where the client is user's PC and the server is Keyring device.
On the client side there is a small program in Python, which sends requests to Keyring device via USB, retrieves replies and fetches data. Server side receives requests, performs required actions and sends back replies.
Refer to the table 1 for Keyring Interaction Protocol (KIP) commands, to the table 2 for KIP statuses and to the table 3 for KIP variable sizes.

Command	Value	Description
ACCESS	0	Accesses Keyring using master password. Authentication should be done using this command prior to performing any other actions, otherwise FAIL status will be returned for every action. Session is initially set by this command and should be used for further interaction by UI. Request: [Command][Session][Master password] Reply: [Command][Status]
LIST	1	Returns the list of record statuses chunk-by-chunk – returns the specified chunk of statuses. Request: [Command][Session][Chunk number] Reply: [Command][Status][Chunk list]
READ	2	Reads record data. Full reading should be done in two steps: first reply contains description, the second one contains password. Request: [Command][Session][Number] Reply: [Command][Status][Description] – after the first request [Command][Status][Password] – after the second request
WRITE	3	Writes data to the specified record. Request: [Command][Session][Number][Description][Password] Reply: [Command][Status]
DELETE	4	Deletes specified record. Request: [Command][Session][Number] Reply: [Command][Status]
MASTER	5	Changes master password. Device should not be disconnected/powered off during this operation, otherwise data integrity is not guaranteed. Request: [Command][Session][New master password] Reply: [Command][Status]
FORMAT	6	Formats Keyring – clears data and resets master password to default – “OWLSANKEYRING”. Request: [Command][Session] Reply: [Command][Status]
FLUSH	7	Flushes number flag for READ command – service command. Request: [Command][Session] Reply: [Command][Status]
RESET	8	Resets Keyring – clears access flag and session (sign out analogue). Request: [Command][Session] Reply: [Command][Status]
PROGRAM	9	Sets programming flag, device enters DFU bootloader after the next reset. Request: [Command][Session] Reply: [Command][Status]

Table 1

Status	Value	Description
FAIL	0	Command execution has failed
DONE	1	Command performed successfully

Table 2

Variable	Size, bytes	Description
Command	1	Refer to table 1 for the list of available commands.
Session	4	Unique ID that should be assigned to the connection on every ACCESS command invocation.
Status	1	Refer to table 2 for the list of available statuses.
Number	4	Record number – number of pair description + password.
Description	32	Description (hint) for the password.
Password/Master password	16	–
Chunk number	4	Number of record list status chunk.
Chunk list	32	List of record statuses. Refer to table 4 for KIP record statuses details.

Table 3

Record status	Value	Description
FREE	0	Record space is free
DATA	1	Record space contains data
CORRUPTED	2	Corrupted record space – cannot be verified

Table 4

Notes:

1. Master password is not stored anywhere, only its hash in order to authenticate user.
2. Default master password is equal to signature – “OWLSANKEYRING” (uppercase, without quotes).
3. USB data packet size is 64 bytes.

Internal and external EEPROM structure is presented in the table 5.

Location	Offset, bytes	Item
Internal	0	Signature – “OWLSANKEYRING” (w/o quotes)
Internal	128	Master password CRC32 hash
Internal	256	Programming flag
External	0	CRC32 hash table – used in CRC32 calculations
External	1024	Records statuses list
External	2048	Records data

Table 5

Hardware

Hardware core of the Keyring is Atmel AT90USB162 MCU (image 1), it has several important features which meet my initial requirements:

1. Size – 7x7x1 mm in TQFP32 package.
2. Price – $5 per unit.
3. Performance – up to 16 MIPS at 16 MHz.
4. Interface – USB 2.0.
5. Storage – 16 kbytes of flash, 512 bytes of internal EEPROM.

Also it has DFU bootloader which will make your life easier with programming FLIP software – you don't need to use serial programmer anymore.
As a storage unit I have utilized Microchip 24LC512 I2C EEPROM (image 2), which has 512 kbits (64 kbytes) of memory – quite enough to store a hundred of passwords with their short descriptions (hints):

1. Size – 6x4.9x1.25 mm in SOIC8 package.
2. Price – $3 per unit.
3. Performance – page (128 bytes) write time is 5 ms max.
4. Interface – TWI/I2C.
5. Storage – 65536 bytes.

Image 1

Image 2

The other required components are:

• 22 Ohm resistors for MCU USB data lines
• 4.7 uF bypass capacitor for MCU USB
• 16 MHz quarz for MCU
• 22 pF load capacitors for quartz
• 100 nF ceramic (fast) and 4.7 uF bypass capacitors
• 4.7 kOhm pull-up resistors for EEPROM
• USB-A SMD connector
• Material for PCB
• Enclosure

Refer to table 6 for bill of material.
 

Type	Component	Count	Price per unit, $	Total price, $
MCU	AT90USB162	1	5.04	5.04
EEPROM	24LC512	1	2.94	2.94
Quartz	HC-49/SMD 16 MHz	1	2.58	2.58
Capacitor	22 pF	2	0.02	0.04
Capacitor	100 nF	2	0.05	0.10
Capacitor	4.7 uF	2	0.05	0.10
Resistor	22 Ohm	2	0.01	0.02
Resistor	4.7 kOhm	2	0.01	0.02
Connector	USB-A SMD	1	1.83	1.83
PCB material	Glass textolite	–	1.00	1.00
Enclosure	Plastic box	1	2.00	2.00
				15.67

Table 6

For enabling DFU programmer you will also need to implement HWB (hardware boot) and RST (reset) buttons. Take a look at image 3 for complete circuit – moreover, it shows connections to FT232RL board for serial programming. Image 4 depicts circuit after assembling components on the breadboard.

Image 3

Image 4

Firmware

Keyring Firmware utilizes LUFA library for interaction via USB interface. AT90USB162 MCU does not have “native” TWI/I2C interface for interaction with 24LC512 EEPROM chip, so the corresponding library is implemented to emulate it.
Keyring Firmware consists of the following modules:

• LUFA
• TWI/I2C firmware library
• Core firmware

Core initializes hardware, checks signature integrity and starts “listening”: when USB data buffer is filled, it is parsed by core and processing cycle is done, after that core awaits when the buffer will be filled again.
TWI/I2C library pins are mapped to hardware pins the following way:

• SCL – pin 15 (PB1)
• SDA – pin 16 (PB2)

Software

Keyring Software is simple and written in Python, it utilizes PyUSB library and PyQt and consists of the following components:

• PyQt
• PyUSB library
• Core library
• Core software

Keyring Software implements the following functionality:

1. Connect – authenticate at the Keyring (image 5).
2. Reset – sign out and disconnect.
3. Browse records (image 6).
4. View password (image 7).
5. Edit record (images 8-9).
6. Delete record (image 8).
7. Add record (image 10).
8. Set master password (image 11).
9. Format device.

Image 5

Image 6

Image 7

Image 8

Image 9

Image 10

Image 11

 

Schematics

I have designed two variants of PCB schematics:

• Debug (images 12-20): includes pins for serial programming and required elements for hardware boot and reset buttons on the board

Image 12

Image 13

Image 14

Image 15

Image 16

Image 17

Image 18

Image 19

Image 20

• Release (images 21-27): has only serial programming (with external Vcc/Vss) and HWB/RST pins and is much smaller than debug version

Image 21

Image 22

Image 23

Image 24

Image 25

Image 26

Image 27

Both are two-sided PCBs with minimum amount of vias and maximum wire thickness (0.4 mm).
Sizes (w/o pins, enclosure and USB connector):

1. Debug: 60x30x8 mm.
2. Release: 40x25x8 mm.

Enclosure for release version is not ready yet, but I'm working on it, also as soon as possible I will present another – more compact – PCB design.

Programming

Programming should be performed in a several steps:

1. Connect Keyring to FT232RL serial programmer.
2. Upload new bootloader which supports 16 MHz quartz using avrdude to Keyring.
3. Upload new fuses values to enable 16MHz support.
4. Disconnect serial programmer.
5. Connect Keyring to PC via USB.
6. Enter DFU bootloader: Press RST and HWB buttons, then release RST button and finally release HWB button.
7. Upload Keyring Firmware (Firmware/Keyring.hex) using FLIP software.
8. Reset device (plug out and plug in it again or press RST button).

Steps 2-3 can be easily performed by executing Hardware/Fuses/Fuses.sh bash script, required bootloader is already there.
After first upload device will auto-format itself and will not be visible for a few seconds.
Its USB vendor ID and device ID are 0x03eb:0x204f, which corresponds to “LUFA Generic HID Demo Application”.

Installation

Currently Keyring Software has been tested only under Linux (Ubuntu/Mint), the next version will support Microsoft Windows.
To use Keyring Software you should prepare appropriate environment:

1. Install Python.
2. Install Qt and PyQt.
3. Install PyUSB library.
4. Copy rules.d/81-owlsan-keyring.rules permissions file to /etc/udev/rules.d/ in order to have non-root access to Keyring.

To run Keyring Software just execute Software/Keyring.py with Python. Keep in mind that default master password is “OWLSANKEYRING” (uppercase, w/o quotes).
Also please be notified that Keyring software is rather raw yet.

License

1. OWLSAN Keyring Hardware is licensed under Creative Commons Attribution-ShareAlike 3.0 Unported License, refer to corresponding LICENSE.txt file or proceed via the link for more information: http://creativecommons.org/licenses/by-sa/3.0/
2. OWLSAN Keyring Firmware is licensed under GNU GPLv3, refer to corresponding LICENSE.txt file or proceed via the link for more information: https://gnu.org/licenses/gpl.html
3. OWLSAN Keyring Software is licensed under GNU GPLv3, refer to corresponding LICENSE.txt file or proceed via the link for more information: https://gnu.org/licenses/gpl.html

Downloads

The packages below contain all data related to this project: circuits, PCB schematics, bills of materials, firmware and software source codes and some required software.

• OWLSAN-Keyring-v10.7z
• OWLSAN-Keyring-v10.tar.gz
• OWLSAN-Keyring-v10.zip

And here you may get AVRDUDE (Linux 32/64) with FT232RL serial bitbang programming mode support:

• avrdude_5.10-1_i386.deb
• avrdude_5.10-1_amd64.deb
• avrdude-ftbb-linux-x86.tar.gz
• avrdude-ftbb-linux-x86_64.tar.gz

Specifications:

• Atmel AT90USB162
• Microchip 24LC512

Links

1. Atmel AT90USB162 product page
2. Microchip 24LC512 product page
3. Atmel AT90USB162 DFU bootloader
4. Atmel AT90USB162 DFU bootloader discuss on AVR Freaks
5. FLIP utility page
6. AVRDUDE home
7. Adafruit Eagle Library (very useful!) at github
8. PyQt page
9. PyUSB page