1. Introduction

Creds101 is a credential management system. It has 2 parts:

  1. Software that you run on your computer (the "host") to send commands to…

  2. A USB "token" which 1) encrypts and stores credentials from the host and 2) decrypts and displays them on its LCD.

Creds101 serves the same purpose as traditional "password database" solutions but it is different in two fundamental ways:

  1. Credentials aren’t stored on the user’s computer - they’re stored on a USB "token".

  2. Sensitive credential data cannot be read by malicious software on the user’s computer - credentials can only be viewed on the token’s "trusted LCD display".

2. Credential format

This section describes the data stored by Creds101. It also gives a few examples of what a typical user might store on his Creds101 token.

2.1. Credential format

The basic unit of storage in the Creds101 system is the "credential". A credential contains four fields:

2.1.1. Name

This field is meant to describe the account.

This field cannot be left blank because it is used by the client software to reference credentials.

2.1.2. Username

This field is meant for the primary username for the account.

This field can be left blank. Some credentials (e.g. an office voicemail system) require only a PIN.

2.1.3. Password

This field is meant for the primary password for the account.

This field can be left blank.

2.1.4. Notes

This field is a "catch-all" for other sensitive data related to the credential.

This field is a nice place to store…

  • The answers to the "secret questions" some sites require e.g. "What was your first pet’s name?"

  • The email address associated with the account.

This field can be left blank.

2.2. Examples

2.2.1. Chuck Norris' Savings Account with Captial One Bank

This example illustrates the use of the "Notes" field to store a "shared secret" for online access to a bank account.

Mr. Norris recently signed up for a savings account at Capital One Bank.

When Mr. Norris first signed on to Capital One’s website, he was asked to choose a question whose answer only he would know. He chose "What was your first pet’s name?" even though he recieved two two puppies on his 9th birthday - alas it was the best question offered by the site
[http://www.slate.com/id/2183030/ "Why are bank security questions so monstrously stupid?" - By Josh Levin - Slate Magazine]

Next, the site asked him to type the answer to the question. He typed "barfy", his favorite of the two puppies.

Whenever Mr. Norris logs in to his bank’s website from a new IP address (e.g. while travelling) he is asked to answer the "first pet" question to prove his identity.

Here’s what Mr. Norris might store on his Creds101 token:

Name:     'capital_one_savings'
Username: 'chucknorris'
Password: 'oem7siew'
Notes:    'acct number: 928374928301. first pet's name: barfy'

3. Host→token serial protocol

The token accepts commands one-at-a-time from the host via a serial connection.

Arduino Duemilanove-based tokens read commands at 9600 baud via their on-board FTDI FT232RL USB-to-TTL chip.

4. Host→token commands

4.1. Command format

Each command occupies a line of text. I.e. commands are terminated with a linefeed (0x0A) character.

Each command is composed of the command name and 0 or more arguments. Each argument is "hex-encoded" such that each byte of the argument is encoded as to its hexadecimal representation. The the string "foo" is an argument, it will be encoded to "666f6f".

The command name and the hex-encoded arguments are delimited by a single space (0x20) character. So… CMD_NAME(0x20)HEXENCODE(ARG0)(0x20)HEXENCODE(ARG1)(0x0A)

4.2. Conventions

The word "read" in a command suggests that the token will return some data via the serial port.

The word "show" in a command suggests that the token will print something to its trusted display.

For commands that respond with a linefeed-delimited lists, list entries are separated by linefeeds. A list of containing a single item will contain no linefeeds.

TOK_STOR_KEY

This key is used by the token firmware to decrypt and encrypt stored credentials.

TOK_AUTH_KEY

This key is required when accessing "restricted" commands. "Restricted" commands typically involve reading credential fields other than the name field from one or more credentials.

4.3. Commands

Name Arguments Notes Use case Response

write

CRED_NAME USERNAME PASSWORD NOTES TOK_STOR_KEY

Store a credential named CRED_NAME with username USERNAME, password PASSWORD, and notes NOTES on the token.

1. The user has created a new Gmail account: bowlingchamp@gmail.com. Gmail generated a password for the account - an4yo9hi. He wishes to store his new credential on the token. He issues this command: write gmail bowlingchamp an4yo9hi BEEF where BEEF is his token’s storage key. Notice the user chose not to store a note with this new credential - hence the two consecutive space characters between the password and TSK arguments. 2. The user has chosen to change his password for his Gmail account in the above example to da7iezei. He uses the write command to update (i.e. overwrite) his old credential: write gmail bowlingchamp da7iezei BEEF where BEEF is his token’s storage key.

None
[Host remains unaware in the case of failure]

show

CRED_NAME TOK_STOR_KEY

Look up credential with name CRED_NAME and output its USERNAME, PASSWORD, and NOTES to the token’s "trusted display".

The user can’t remember his Gmail password and wishes to retrieve it from the token’s "trusted display". He issues this command: show gmail BEEF where BEEF is his token’s storage key.

None
[oblivious_to_failure]

read_cred_names

TOK_STOR_KEY

Return the names of all stored credentials via the serial port.

1) The user has previously stored a credential with name 192.168.2.220 - a credential containing login information for the machine with that IP address. This machine has a new IP address now and he can’t remember 192.168.2.220 to issue a show command. He issues this command: read_cred_names BEEF where BEEF is his token’s storage key and quickly sees the IP in the returned list.

A linefeed-delimited list of the names of all credentials stored on the token.
[Return an error code as well?]

delete

CRED_NAME TOK_STOR_KEY

Look up credential with name CRED_NAME and remove it from storage.

1) The user has cancelled his Gmail accound and no longer needs to store the credential on his token. He deletes the credential with the command delete gmail BEEF where BEEF is his token’s storage key.

None
[oblivious_to_failure]

read

CRED_NAME TOK_STOR_KEY TOK_AUTH_KEY

Same as "show" command but uses serial port instead of "trusted display". Should only be used for debugging because it returns sensitive credential data via the serial port.

A developer wishes to confirm that a credential has been correctly stored by a write command.

The username, password, and notes for the requested credential.

readall

TOK_STOR_KEY TOK_AUTH_KEY

Return all usernames and associated passwords from the token.

1) The user fears he’ll lose his token and wishes to create a copy of all his credentials on e.g. a thumb drive. 2) The user wishes to search all his passwords for any insecure (e.g. short) passwords.

A linefeed-delimited list of all the credentials stored on the token.

self_destruct

?

?

?

Smoke

5. Data flow diagrams

5.1. Token Initialization

Initializing a new token for use.

The user wishes to prepare a new token (or token simulator) for storing his credentials.

  1. Generate a Token Storage Key (TSK) from a cryptographic random source. This key will be necessary and sufficient to encrypt and decrypt credentials stored on the new token. It is stored on the host for use during future transactions with the token.

  2. Create an empty "map" data structure and encrypt it with the TSK. Store the result on the token. The token will use this data structure to store credentials.

  3. Generate a Token Authentication Key (TAK) as in Step 1. This key will be necessary for "privileged" operations such as "read". This key is also stored on the host for use during future transactions with the token.

  4. The TAK is hashed with a cryptographic hash and the result is stored on the token so that the token can later validate "privileged" operations requested by the host.

  5. The host activates the token’s tamper resistance features. The token is now ready for use.

images/dataflow_init_yed_export_scaled_80pct.png

5.2. Writing a Credential to a Token

Storing a credential on the token.

The user wishes to either… A) store a new credential on his token or… B) overwrite an existing credential on his token.

  1. Read the Token Storage Key (TSK) from disk. Encode the TSK and the fields of the credential for transmission to the token.

  2. Construct the complete "write" command and transmit it to the token.

  3. Decode the command arguments, yielding the TSK and credential fields.

  4. Read the encryped credential map from storage. Decrypt it with the TSK received from the host.

  5. If a credential already exists with the name specified by the user, overwrite the existing credential with the new data. If the credential is new, simply insert it into the credential map.

  6. Re-encrypt the credential map and write it to storage.

images/dataflow_write_yed_export_scaled_80pct.png

6. Colophon

6.1. Diagrams

  1. Fire up Yed 3.4.1

  2. Open [png to export]

  3. File → Export…

  4. Name the output docs/images/[png to export]_yed_export_scaled_80pct.png

  5. Choose 0.8 as the Scaling factor

6.2. XHTML

  1. Generate the XHTML output with AsciiDoc: docs$ /home/tz/src/asciidoc-8.5.3/asciidoc.py --attribute=toc --attribute=numbered index.txt or on another machine… /media/humid_data/src_tu/[...]

  2. Alternatively, use the docbook backend: /home/tz/src/asciidoc-8.5.3/a2x.py -d book -f xhtml index.txt