This section describes the development environment and architecture of the OpenFIPS201 applet.

1 Contents

2

OpenFIPS201 is built with the following high-level design goals in mind:

• Simplicity and Readability - The code is designed to be a clean interpretation of the [SP 800-73] Part 2 document, using the standard terms wherever possible.

• Flexibility - The file system, access control rules and applet behaviour are all configured from a single class before compilation, allowing for strict compliance to PIV or to allow for additional data objects or security requirements (PIV-I or CIV for example).

• Production Quality - The project aims to be of a quality that can be used directly in a production environment and submitted for certification.

• Low Memory Footprint - Although the file system itself is capable of taking up enormous amounts of EEPROM, the applet itself is designed to minimise its EEPROM and RAM footprint. Data Object arrays are only allocated when first written to and the APDU buffer is used where possible for intermediate operations.

3 Building OpenFIPS201

3.1 Setting Up The Build Environment

First, you'll need to grab the latest OpenFIPS201 master branch:

git clone https://github.com/makinako/OpenFIPS201.git

To simplify the build process, the following third-party tools are already included in the repository under the tools directory:

• Apache Ant (Apache Software Foundation, https://ant.apache.org/ )

• ant-javacard (Martin Paljak, https://github.com/martinpaljak/ant-javacard )

• Javacard SDK 3.0.4 (Oracle, http://www.oracle.com/technetwork/java/embedded/javacard/overview/index.html )

In addition, the Oracle Java SE JDK and JRE must be installed (JDK v9 is not recommended). (http://www.oracle.com/technetwork/java/javase/downloads/index.html )

3.2 Build Process

From the root repository folder:

1. Go to the build folder

2. Edit the build.cmd and set the 'JDK' environment variable to the version you have installed.

3. Optionally, edit the build.xml ant configuration file, overriding any default build properties at the top (this is where you can change the target Javacard or GlobalPlatform version in particular).

4. Run build.cmd, which will build the CAP file to the ./bin folder and the intrinsic documentation to the ./doc folder.

3.3 Applet Configuration

The OpenFIPS201 source contains a file Config.java, which drives the advanced behaviour of the applet. Each feature / parameter is described below, along with the requirement for compliance with NIST SP800-73-4.

3.3.1.1 Features

Feature

Description

Default Value

PIV TEST VECTORS

This must only be enabled for protocol debugging and analysis, as this forces the applet to use FIXED values for cryptographic nonces and will cripple security.
SP800-73-4 Requirement: Must be set to false

False

RESTRICT SCP TO CONTACT

If set to true, an authentication to GlobalPlatform will fail on the contactless interface.
SP800-73-4 Requirement: Issuer-defined

True

ERROR ON EMPTY DATA OBJECT

If set to true, a call to GET DATA for an object that exists in the file system, but which has not been initialised with data will result in SW_FILE_NOT_FOUND. If set to false, it will return an empty data field with SW OK.
SP800-73-4 Requirement: Issuer-defined

False

DISCOVERY OBJECT DEFAULT

If set to true, when the discovery object is created it will automatically be populated with a default value based on the configured parameters (specifically the PIN policy element dynamic elements).
SP800-73-4 Requirement: Issuer-defined

True

PIN CARD ENABLED

Indicates that the mandatory PIV Card Application PIN satisfies the PIV Access Control Rules (ACRs) for command execution and data object access.
SP800-73-4 Requirement: Issuer-defined

False

PIN GLOBAL ENABLED

Indicates that the optional 'Global PIN' feature of PIV is enabled.
SP800-73-4 Requirement: Issuer-defined

False

PIN GLOBAL PREFERRED

Indicates that the Global PIN is the primary PIN used to satisfy the PIV ACRs for command execution and object access.
SP800-73-4 Requirement: Issuer-defined

False

PIN GLOBAL CHANGE

Indicates that the Global PIN may be updated by the PIV applet.
SP800-73-4 Requirement: Issuer-defined

False

PIN INIT RANDOM

Indicates that the PIN will be set to a random value at applet instantiation. If this is set to False, it will be set to a default value defined in the same Config file (DEFAULT PIN).
SP800-73-4 Requirement: Issuer-defined

True

PUK CHANGE

Indicates that the PUK may be updated by the PIV applet.
SP800-73-4 Requirement: Issuer-defined

True

PUK INIT RANDOM

Indicates that the PUK will be set to a random value at applet instantiation. If this is set to False, it will be set to a default value defined in the same Config file (DEFAULT PUK).
SP800-73-4 Requirement: Issuer-defined

True

PIN OVER CONTACTLESS

Permits the PIN or Global PIN to be used over contactless without the need for the VCI condition.
SP800-73-4 Requirement: Must be set to false

False

PUK OVER CONTACTLESS

Permits the PUK to be used over contactless without the need for the VCI condition.
SP800-73-4 Requirement: Must be set to false

False

3.3.1.2 PIN and PUK Settings

Parameter

Description

Default Value

PIN RETRIES

The number of retries before the PIN object is blocked.
SP800-73-4 Requirement: Issuer-defined

6

PIN RETRIES INTERMEDIATE

The number of retries remaining before the PIN object is blocked on the contactless interface only.
SP800-73-4 Requirement: Issuer-defined

1

PUK RETRIES

The number of retries before the PUK object is blocked.
SP800-73-4 Requirement: Issuer-defined

6

PUK RETRIES INTERMEDIATE

The number of retries before the PIN object is blocked on the contactless interface only.
SP800-73-4 Requirement: Issuer-defined

1

PIN LENGTH MIN

The minimum length of the PIN value (SP800-73-4 default is '6' - NOTE: Changing this value from its default will break PIV compliance).
SP800-73-4 Requirement: Must be set to 6

6

PIN LENGTH MAX

The maximum length of the PIN value (SP800-73-4 default is '8' - NOTE: Changing this value from its default will break PIV compliance).
SP800-73-4 Requirement: Must be set to 8

8

4 Applet Architecture

Building OpenFIPS201

2.1 Setting Up The Build Environment

3 Applet Architecture

OpenFIPS201 is built with the following high-level design goals in mind:

• Simplicity and Readability - The code is designed to be a clean interpretation of the [SP 800-73] Part 2 document, using the standard terms wherever possible.

• Flexibility - The file system, access control rules and applet behaviour are all configured from a single class before compilation, allowing for strict compliance to PIV or to allow for additional data objects or security requirements (PIV-I or CIV for example).

• Production Quality - The project aims to be of a quality that can be used directly in a production environment and submitted for certification.

• Low Memory Footprint - Although the file system itself is capable of taking up enormous amounts of EEPROM, the applet itself is designed to minimise its EEPROM and RAM footprint. Data Object arrays are only allocated when first written to and the APDU buffer is used where possible for intermediate operations.

3.1 Component Hierarchy

3.1.1 Key Role

The following key roles are defined:

3.1.2 Key Attributes

The following key attributes are defined:

3.

2 Applet Lifecycle

OpenFIPS201 supports the following lifecycle states:

3.

3 Development Principles

OpenFIPS201 follows a number of design principles to ensure that undefined or unintended behaviour does not occur, whether through the fault of development (bugs), fault of use or malicious act.

3.

3.1 Private-Package Class Declarations

All classes in the OpenFIPS201 package shall be declared ‘Private-Package', with the intention that they are non-accessible outside the main package. This is intended to reduce attack surface related to static members.

// BAD
public class MyClass {
}

// GOOD
class MyClass {
}

3.

3.2 Exception-based Error Handling

All functions generate errors via the Java Card exceptions paradigm, which causes the applet to stop functioning unless the exception is explicitly handled.

Return values are only ever informational or functional, they are never used to express the failure of a function to operate normally. Conversely, exceptions are never used to convey information or drive application flow.

This is done to prevent calling code from unintentionally ignoring error conditions, which may then lead to unintended behaviours or exposure to attackers.

3.

3.3 Object Locking

Utility and Cryptographic objects make use of a simple Acquire and Release locking mechanism, which ensures that any unintended or malicious attempts to execute functionality are caught.

Before a call to any protected object is made, the caller must Acquire a lock. If a lock already exists, the object will throw an exception. Once a lock is requested, the caller must then explicitly release the object.

3.

3.4 Early Initialisation - Critical Data

OpenFIPS201 ensures that all critical objects and buffers are defined at applet installation. This has a number of impacts:

1. It eliminates the chance of undefined behaviour due to allocation failures on memory-constrained devices.

2. The card issuance system is immediately aware of any memory allocation failures, which prevents installation and renders the applet unable to be selected.

3. It provides early visibility of how much memory the base installation of OpenFIPS201 uses

The following elements are instantiated at applet install:

• All functional modules (classes)

• The primary transient (RAM-based) temporary buffer (called the Scratch space)

• The dedicated transient authentication state

• The [ISO-7816] communications command-chain handler (Chain Buffer)

• The PIV Implementation

• The PIV Security Provider including all Java Card cryptographic primitive instances

• TLV Parsing and Construction Utilities

3.

3.5 Lazy Initialisation - Filesystem and Key Store

In contrast to critical data, OpenFIPS201 deliberately avoids allocating memory for dynamic objects until they are populated with data. This is because a PIV filesystem has the potential to consume large amounts of memory and data object lengths are not always known, so early instantiation would need to take into account worst-case memory usage which would further impact the applet footprint.

In any typical PIV deployment, many objects will remain unpopulated for the entire life-time of the applet. Lazy initialisation optimises this by only allocating memory for these resources until they are first used and the requested size is known.

This includes:

• File System Descriptors

• Data Objects

• Key Objects

3.

3.6 Defined Cryptographic Boundary

All cryptographic operations occur inside specific classes and internal Java Card implementations are not accessible outside of these objects. This reduces the chances of sensitive cryptographic functions being used in an unintended or malicious way.

The classes that contain references to cryptographic primitive instances are:

• PIV Security Provider

• PIV Crypto

3.

3.7 Optimised File Allocation Table

All Data Object and Key records are held by a simple linked list. Since it is possible that many data objects and keys will not be populated, OpenFIPS201 optimises this linked list by moving objects to the top of the list as they are allocated. This ensures that the lookup time is minimised as empty objects are never hit in normal operational circumstances.

3.

3.8 Approved Algorithms

OpenFIPS201 makes use of only cryptographic mechanisms which are approved by:

• NIST Cryptographic Standards and Guidelines

• ASD Approved Cryptographic Algorithms

3.

3.9 Critical Security Parameter (CSP) Management

All CSPs are carefully managed to ensure that the potential for exposure or misuse is limited. Some of the ways in which this is implemented are:

• All cryptographic keys are only ever stored in Java Card Key objects, which are protected by the JCRE / JCVM.

• All PIN and PUK values are stored in Java Card OwnerPin objects, which are protected by the JCRE / JCVM.

• Keys and cryptographic primitives are kept within defined classes and access to them is only permitted through abstracted operations.

• Transport of cryptographic keys is only ever permitted over a secure channel with command Encryption and MAC, never in plaintext.

• Asymmetric Keys are able to be decorated with a 'Generate Only' attribute, which prevents key injection. This provides assurance of key ownership and guards against repudiation.

• All temporary and intermediate values are zeroised immediately after they are no longer needed

3.

3.10 No ‘Roll Your Own’ Crypto

OpenFIPS201 does not make use of any cryptographic primitives that are defined in software, but rather makes use of the existing primitives provided by the Java Card API.

4 Environment - Java Card

Anchor
Environment-Java-Card Environment-Java-Card

OpenFIPS201 avoids the use of any platform-specific API outside of Java Card and GlobalPlatform namespaces, to ensure maximum compatibility with commercially available cards.

The minimum Java Card Runtime Environment (JCRE) version is targeted at v3.0.4 and as such, does not make use of functionality in later versions. There are several reasons for this:

• A number of cryptographic primitives are not supported by JC22, especially in the Elliptic Curve domain. This makes it impossible to fully implement SP800-73-4 without resorting to a soft-crypto implementation.

• The PIV requirement to format signature input blocks off-card, which is not supported by JC22 resulted in the need to implement a hack to encrypt using the private key. Moving to JC30 will allow the use of Signature with signPreComputedHash() and setInitialDigest(), which are both specifically intended for off-card signature block formatting.

• JC22 does not support the Applet.reselectingApplet() feature, which again is a breaking point for PIV. NIST have indicated they will permit certification exceptions to support JC22 cards, however this hasn't been tested to our knowledge.

4.1.1 Java Card API

The following Java Card API objects are required for OpenFIPS201 to install:

4.1.2 Cryptographic Primitives

OpenFIPS201 dynamically checks which cryptographic primitives are available on the target card during installation. If one or more are not available (cannot be instantiated), the applet will disable that mechanism and prevent keys of those types from being added to the file system during pre-personalisation.

The following primitives are used if available:

5 Environment - Global Platform

• OpenFIPS201 makes use of functionality in the GlobalPlatform API for version 2.12.1 or higher

• OpenFIPS201 avoids the use of any platform-specific API outside of Java Card and GlobalPlatform namespaces, to ensure maximum compatibility with commercially available cards.

• OpenFIPS201 makes use of the Global Platform Secure Channel Protocol 03 functionality, specifically to mutually authenticate the card and the issuer (or card manager). For an administrative status to be considered valid, both the C-ENC and C-MAC protocol options must be set.

• The following Global Platform API objects are required at a minimum:

6 Applet Interoperability Testing

NIST has supplied testing documentation and software that is used to perform black-box testing of a PIV applet and/or middleware component.

OpenFIPS201 has been tested using this software, excluding tests that fall into a number of categories:

• Unsupported features (Biometric On-Card Comparison)

• Inapplicable (i.e. Middleware tests)

• Data Format Validation (It tests the contents of a data object, which is outside the scope of the Card Application to enforce)

The document and software links can be found here:

• PIV Card Application and Middleware Interface Test Guidelines (SP 800-73-4 Compliance)

• NIST PIV Test Runner

   (Requires a password, which can be obtained from NIST with instructions provided on their web site)

6.1.1.1 Installation Requirements

PIV Test Runner requires the following:

• Microsoft Windows XP or above

• At least 40MB disk space

• Oracle Java Runtime Environment (JRE) version 1.8 (Java 8) or later

• "The Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6.0" (http://www.oracle.com/technetwork/java/embedded/embedded-se/downloads/jce-7-download-432124.html )

• 1 x contact (ISO-7816) PC/SC compliant reader

• 1 x contactless (ISO-14443) PC/SC compliant reader

• 2 x Javacard / GlobalPlatform smartcards

6.1.1.2 Installation and Configuration

1. Download and install the PIV Test Runner (from the above link) to a writable folder

2. Execute startTestRunner_SP800_73_4.bat in the install directory

3. Open the OPENFIPS201.xml configuration file

4. Customise the following configuration settings to your test readers

   • Configuration / Connectivity / Contact Reader Name

   • Configuration / Connectivity / Contactless Reader Name

6.1.1.3 Test Preparation

1. If you do not already have a compile OpenFIPS201 applet

   • Configure the OpenFIPS201 project (See Development)

   • Compile the OpenFIPS201 project

2. Load and install the OpenFIPS201 applet onto each target Javacard with the Default Applet privilege!

3. Perform pre-personalisation by executing the NIST Compliant Profile on each card

4. Execute the Test Personalisation on each card

6.1.1.4 Test Execution

Unless you are testing a comprehensive PIV setup (i.e. Middleware and Personalisation system), it is not recommended to use the 'Run All' functionality. Instead, only selected tests should be executed from the list below.

• ChangeReferenceDataCommand

• GeneralAuthenticateCommand

• GenerateAsymmetricKeyPairCommand

• GetDataCommand

• PutDataCommand

• ResetRetryCounterCommand

• ChangeReferenceDataCommand

• SelectCommand

• VerifyCommand

These can be executed either individually, or all selected. PIV Test Runner does not appear to provide a mechanism to generate a 'test profile' file.

6.1.1.5 Test Results

PIV Test Runner provides summary test results by clicking on the parent Test item. Each test category will show either PASS, FAIL or blank if they were not executed.

Inside each test sub-category you have the option to select the Log tab, which will give detailed diagnostic output for the execution of each test with a summary of each step outcome at the end of the log.

Note that all test numbering maps back to the NIST test documentation described at the start of this page.