KeepassNFC

IMPORTANT

This repository is used for class PV204 Security Technologies at Masaryk University. All meaningful improvements will be attempted to be pushed to upstream repository in June 2018.

Overview

KeePass Password Safe is an open source password manager that aims to store passwords securely.

KeepassNFC is an applet that can protect the secret key of the KeePass database.

This applet was based on the project smartcard_crypto_applet and can be run on javacard platform with JCRE version 2.2.x or above. It is meant to be used in a card supporting NFC (Near Field Communication) technology.

Compiling the project

This project has two different build systems that can be used. JCIDE is the one originally used, while the Gradle integration has been added later using the template from @crocs-muni.

JCIDE

A project file (KeepassNFC.jcproj) has been created for the users of JCIDE. If you have already installed the JCIDE, only a simple double-clicking on this file is needed to start the development environment. You can view, edit, build or debug the code with JCIDE, a powerful Javacard Integrated Development Environment. You can use pyApdutool to download and install the applet, please reference the topic in the JavaCardOS for the operation detail.

Support for this configuration is guaranteed until commit 701cdfc.

Gradle

This configuration gives the ability to easily compile and convert the applet to cap files, it has support for easy tests creation, including test coverage. Also, it provides integration with Travis CI platform (and easily with any other CI platform). It additionally provides the means to execute on both real cards and JCardSim.org simulator.

This build configuration can be used with all the IDEs that provide integration (native or by plugins) with Gradle (IntelliJ, NetBeans, Eclipse...).

After recursively cloning the repository (to gather all the JavaCard SKDs),

git clone --recurse-submodules git@github.com:JavaCardSpot-dev/KeepassNFCApplet.git 

you can choose the desired JavaCard SDK to use by setting the JCSDK environment variable (by default it is empty, and the minimum required SDK version will be used). Then simply run

./gradlew buildJavaCard --info
JCSDK=jc304 ./gradlew buildJavaCard --info

to get the .cap file. It will be located under bin/net/lardcave/keepassnfcapplet/{JCSDK}/keepassnfcapplet.cap

Usage

Here, the user is intended as both you and the client application.

Also, when talking about APDU headers, the length will be always omitted, just like P1 and P2, except when needed.

General functionality

Actually, the applet is able to decrypt the user-supplied database using AES-256. Future development will include also its encryption, and possibly support for more algorithms (Twofish/ChaCha20).

The applet uses three classes of commands:

• 0x90: includes commands always accessible by any user
• 0xA0: includes all PIN-related commands. Some of them are freely accessible (PIN verifications), others require the Master PIN to have been previously verified.
• 0xB0: any command under this class needs the User PIN to have been previously verified. This class includes all actual implementation of the required functionality to decrypt the database.

PIN management

Authentication is provided by the means of two PIN verifications. Both PINs initial values are actually hardcoded.

• Master PIN: this PIN is required to change both itself and the User PIN. Its default (hardcoded) value is the string 123456. For increased security its minimum length is 6.
• User PIN: this PIN is needed by the actual decryption functionality. Its default (hardcoded) value is the string 1234, with a minimum required length of 4 characters.

Both PINs are recommended to be changed by the final user using commands under the 0xA0 class.

Both PIN verifications are kept valid until the card is extracted (or the applet is deselected).

Applet configuration

For applet configuration, all commands are of class 0xB0, and as such require verify User PIN (A082) to have been called successfully.

1. As first one-time-only step, the user will let the card generate an internal key pair (2048b RSA)(B075).
2. After generation, the user will be able to get the public key by means of exponent and modulus (B070).
3. Then, the user will send its Password Key to the applet, encrypted with the card's public key (B076, B071).

After calling these commands, the applet is configured to actually decrypt the KeePass database.

Applet usage

For applet usage, all commands are of class 0xB0, and as such require verify User PIN (A082) to have been called successfully. Also, the configuration is considered to be done.

Each usage is identified by a transaction, with related transaction key (AES-128). The user is required to:

1. generate a AES-128 transaction key, encrypt it with card's public key and send it to card using write to scratch (B076).
2. send to card IVs to initialize password and transaction ciphers (B072).
3. send to card the password-encrypted database split in blocks, getting the same transaction-encrypted (B073).
4. decrypt each block with transaction key, obtaining plaintext database.

Infomative commands

The user can obtain two different information pieces about the status of the applet, without changing its state and without any authentication:

• version of the applet (9074, B074)
• number of PIN trials remaining (9072). This can explain why some actions may be blocked in different situations.

APDU formats

B074 instruction to get version is maintained only for compatibility reasons, and it's deprecated. Nevertheless, since it's a B0-class instruction, it still needs correct User PIN verification.

Error codes

Apart from standard exception codes, the following specific SW codes are used:

Future work

Help is always appreciated! Please read these suggestions for what to do, and always follow the contibution rules!

This applet can be improved in several ways:

• [ ] Drop usage of 01/02 to show success/failure of commands, and just use SW codes
• [ ] Offer method to know the maximum amount of data that can be sent each time
• [ ] Support for long APDUs
• [ ] Support for encryption of database
• [ ] Support for ChaCha20/Twofish/other algorithms supported by KeePass or its plugins
• [ ] HMAC encrypted communication
• [ ] Manage states of the applet to prevent wrong commands to be called
• [ ] Setting initial Master/User PINs during installation with a payload
• [ ] DH-like key derivation instead of PIN/transaction key (with shared secret set during installation)
• [ ] Optimize for execution on real cards (currently, it can take several seconds or minutes to perform specific actions)

Also the repository can be improved:

• [ ] Leave a single build system, or correctly maintain/link both
• [ ] Provide multiple client implementations (different simulators/libraries)
• [ ] Run tests using different simulators and directly calling methods
• [ ] Add tests to cover all the applet code. Also, test and check coverage of clients.

Known compatibilities

Until 701cdfc it should work on JC30M48, the downloading and installation have been tested on this card.

Until June 2018 it was successfully tested with NXP J2E 081 (NXP JCOP v2.4.x).

Timings

Some profiling has been performed for all the commands (timings are in ms, average over 20 trials, smartcard NXP J2E 081):

About the B073 command (block decryption): a fully populated KeePass database can be long around 200 KiB, that corresponds to 1600 executions of given command. These result in a total execution time of around 150 seconds, or 2.5 minutes. This should be improved.

Maintainers

The original creator of the project is the JavaCardOS community.

As the initial notice explains, this project will be maintained by students of the Masaryk University about until June 2018.