1 Contents
2 Overview
OpenFIPS201 is intended to be highly flexible to support a variety of usage scenarios whilst being capable of fully complying with the PIV card application standard.
To support this:
It has a dynamic file system, which can describe any number of data objects, including access permissions
It has a dynamic key store, which permits any combination of keys and mechanisms (algorithms), with flexible access permissions, key roles and attributes.
The applet has a number of configuration parameters which drive behaviour of the applet. These can be dynamically configured during issuance, post-issuance or even left untouched to make use of NIST-compliant default values.
All of the above can be managed securely using a GlobalPlatform Secure Channel either locally or over a network.
3 Personalisation Steps
Apply any Configuration changes required (this should be done first as it may effect subsequent steps)
Define which Data Objects and Keys are required on the card.
Populate data objects using standard PIV interoperable commands.
Generate or Inject Key values using either standard PIV interoperable commands or the Secure Messaging interface.
4 Configuration
OpenFIPS201 configuration parameters can be applied at any time during the card life-cycle, so long as it is done under a GlobalPlatform Secure Channel or using Delegated Administrative Commands.
Configuration is broken down into the following groups:
Applet options that effect general behaviour
Policies relating to usage of the Cardholder PINs
Policies relating to usage of the Security Officer PUK
Policies relating to Secure Messaging and the Virtual Contact Interface
Policies relating to Biometric On-Card Comparison
All commands are sent via the PUT DATA ADMIN command and constructed using BER-TLV encoded ASN.1. The schema for this command can be found on the https://openfips201.atlassian.net/wiki/spaces/OD/pages/459060/Appendix+-+ASN.1+Schema#5-Command---PUT-DATA-ADMIN page, which includes encoding examples.
All configuration parameters are marked as OPTIONAL, which means you can update all configuration parameters or only a single one.
If you do not update configuration at all, the Default values described in the tables below will apply. These values have been chosen to comply with the NIST PIV interoperability requirements.
4.1 Applet Options
Element | Description | Effect | Default Value |
|---|---|---|---|
Options.restrictContactlessGlobal Type: BOOLEAN | Possible Values:
If this parameter is set to True, the applet will no longer be selectable on the contactless interface. | Next applet selection | False |
Options.restrictContactlessAdmin Type: BOOLEAN |
If the | Next authentication | False |
Options.restrictEnumeration Type: BOOLEAN | Possible Values:
No data object or key content is exposed by enabling this parameter, only the file system headers that show identifiers, permissions and whether or not the object is initialised. | Immediate | False |
Options.restrictSingleKey Type: BOOLEAN | Possible Values:
This only applies to keys added after this has been set to True. Any existing key / mechanism combinations will not be affected. | Immediate | False |
Options.ignoreContactlessAcl Type: BOOLEAN | This option can be used to treat both the Contact and the Contactless interface the same for the purposes of checking file permissions. This is useful for environments where the standard operating environment uses contactless readers. Possible Values:
This parameter has no effect if Take care with this parameter as it increases risks relating to passive interception of personal information and PIN values. Using Secure Messaging is the more appropriate way to achieve the same effect, but with channel confidentiality and integrity protection. | Next applet selection | False |
Options.readEmptyDataObject Type: BOOLEAN | Possible Values:
| Immediate | False |
Options.useRSACRT Type: BOOLEAN | This value is currently ignored and will always be read as False. Possible Values:
RSA-CRT private key operations can be significantly faster, especially on limited embedded devices such as smartcards. RSA-CRT keys consume more EEPROM space due to the pre-computed components P, Q, DP, DQ and Qinv. As a general guide, expect around 75% more space used, though this can be platform and implementation dependent. It is important to set this value before generating or injecting keys as changing this parameter will not affect RSA keys that have already been initialised by generating or injecting key values. You can get around this by clearing any existing keys using the CHANGE REFERENCE DATA ADMIN command. Upon next generation / injection, they will make use of the correct RSA key type. | Immediate | False |
4.2 PIN Policy
Element | Description | Effect | Default Value |
|---|---|---|---|
PinPolicy.enableLocal Type: BOOLEAN | Possible Values:
| Immediate | True |
PinPolicy.enableGlobal Type: BOOLEAN | Possible Values:
| Immediate | False |
PinPolicy.preferGlobal Type: BOOLEAN | Possible Values:
| Immediate | False |
PinPolicy.permitContactless Type: BOOLEAN | Possible Values:
If the | Immediate | False |
PinPolicy.minLength Type: INTEGER (4 to 16) | Indicates the minimum permitted length of the cardholder PIN verification value. Setting this to a value less than 6 may cause it to be non-compliant with PIV client applications and middleware that are not aware of OpenFIPS201 extended functionality. Any changes to this value should be immediately followed by an update or reset of the PIN to a default value, otherwise the cardholder may no longer be able to verify. | Immediate | 6 |
PinPolicy.maxLength Type: INTEGER (4 to 16) | Indicates the maximum permitted length of the cardholder PIN verification value. This value must be greater than or equal to the Setting this to a value greater than 8 will cause it to be non-compliant with PIV client applications and middleware that are not aware of OpenFIPS201 extended functionality, due to the fixed padding length (all PIN values in PIV are padded to 8 bytes). Any changes to this value should be immediately followed by an update or reset of the PIN to a default value, otherwise the cardholder may no longer be able to verify. | Immediate | 8 |
PinPolicy.MaxRetriesContact Type: INTEGER (1 to 15) | Indicates how many failed PIN verification attempts may be made over the Contact interface before the PIN object is locked and requires privileged intervention. If the PIN is blocked, it can be reset by the Security Officer Role (Someone who possesses the PUK) or by the Administrative role (Someone who has established a Secure Channel). | Immediate | 6 |
PinPolicy.MaxRetriesContactless Type: INTEGER (1 to 15) | Indicates how many failed PIN verification attempts may be made over the Contactless interface before the PIN object is locked and requires privileged intervention. This value must be less than or equal to the These two parameters are not evaluated independently and the intention is for a cardholder to have [n] more attempts to unlock the PIN over the contact interface after it has been blocked on the contactless interface. If the | Immediate | 5 |
PinPolicy.Charset Type: Enumeration | Possible Values:
Setting this to any value other than Numeric (0) may cause it to be non-compliant with PIV client applications and middleware that are not aware of OpenFIPS201 extended functionality. Any changes to this value should be immediately followed by an update or reset of the PIN to a default value, otherwise the cardholder may no longer be able to verify. | Immediate | 0 - Numeric |
PinPolicy.History Type: INTEGER (0 to 8) | Possible Values:
| Immediate | 0 (Disabled) |
PinPolicy.RuleSequence Type: INTEGER (0 to 16) | This value is used to prevent common weak PIN values whereby consecutive sequences of numbers are used, for example Possible Values:
Example If
This number should be selected based on the | Next PIN change | 0 (Disabled) |
PinPolicy.RuleDistinct Type: INTEGER (0 to 16) | This value is used to prevent common weak PIN values, whereby the same digit is used too many times, for example Possible Values:
Example If
This number should be selected based on the | Next PIN change | 0 (Disabled) |
4.3 PUK Policy
Element | Description | Effect | Default Value |
|---|---|---|---|
PukPolicy.Enabled Type: BOOLEAN | Possible Values:
| Immediate | True |
PukPolicy.Length Type: INTEGER (4 to 16) | Sets the permissible length of the PUK value. Unlike the PIN value there is no minimum and maximum for PUK’s, since they are typically generated by systems, not people. Any changes to this value should be immediately followed by an update or reset of the PUK to a default value, otherwise the cardholder may no longer be able to verify. | Immediate | True |
PukPolicy.PermitContactless Type: BOOLEAN | Possible Values:
If the | Immediate | False |
PukPolicy.MaxRetriesContact Type: INTEGER (1 to 15) | Indicates how many failed PIN verification attempts may be made over the Contact interface before the PUK object is locked and requires privileged intervention. If the PUK is blocked, it can only be reset the Administrative role (Someone who has established a Secure Channel). Blocking the PUK does not block any other functionality, including the PIN. | Immediate | 8 |
PukPolicy.MaxRetriesContactless Type: INTEGER (1 to 15) | Indicates how many failed PIN verification attempts may be made over the Contactless interface before the PUK object is locked and requires privileged intervention. This value must be less than or equal to the These two parameters are not evaluated independently and the intention is for a cardholder to have [n] more attempts to unlock the PUK over the contact interface after it has been blocked on the contactless interface. If the | Immediate | 10 |
PukPolicy.Updateable TYPE: BOOLEAN | Possible Values:
The PUK may always be changed by the Administrative Role over a Secure Channel, regardless of this setting. | Immediate | 9 |
4.4 VCI Policy
Element | Description | Effect | Default |
|---|---|---|---|
VCIPolicy.Mode Type: BOOLEAN | This parameter is reserved and not yet implemented | N/A | 0 (Disabled) |
4.5 OCC Policy
Element | Description | Effect | Default |
|---|---|---|---|
OCCPolicy.Mode Type: INTEGER (0 to n) | This parameter is reserved and not yet implemented | N/A | 0 (Disabled) |
5 Data and Key Objects
All data and key in OpenFIPS201 can be dynamically managed at any point in the card life cycle, providing a great deal of flexibility. Each object has a number of common parameters that govern basic attributes such as identifiers and conditions of access.
OpenFIPS201 allows a number of additional capabilities which can be controlled through these parameters.
5.1 Common Parameters
Common parameters are used for all objects. These are described below.
The common parameters are all that is required for Data Objects. For Keys, additional fields are described later in this document.
Element | Description |
|---|---|
Id TYPE: OCTET STRING (1 to 3 bytes for data objects, 1 byte for keys) | The unique identifier for this object on the card. OpenFIPS201 only makes use of the least-significant byte for identification storage. This may change in the future but for now this means the identifiers |
Mode Contact Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contact interface. See |
Mode Contactless Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contactless interface. See If the |
Admin Key Type: OCTET STRING (1 byte) OPTIONAL | Specifies which symmetric key can be used for managing this object using the This is useful where a particular implementation wishes to define specific Data or Key objects that are managed by a third party, where it is desirable to compartmentalise access to only those objects. This field is optional and if it is not specified, the default administrative key |
Key Mechanism Type: Enumeration | Describes which cryptographic primitive (mechanism) will be associated with this key. See Enumeration - Key Mechanism below for details on populating this value. |
Key Role Type: Enumeration | Specifies what role(s) this key may perform for See Enumeration - Key Role below for details on populating this value. |
Key Attribute Type: Enumeration | Specifies what special attributes / options are flagged against this key. See Enumeration - Key Attribute below for details on populating this value. |
Element | Description |
|---|---|
Id TYPE: OCTET STRING (1 to 3 bytes for data objects, 1 byte for keys) | The unique identifier for this object on the card. OpenFIPS201 only makes use of the least-significant byte for identification storage. This may change in the future but for now this means the identifiers |
Mode Contact Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contact interface. See |
Mode Contactless Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contactless interface. See If the |
Admin Key Type: OCTET STRING (1 byte) OPTIONAL | Specifies which symmetric key can be used for managing this object using the This is useful where a particular implementation wishes to define specific Data or Key objects that are managed by a third party, where it is desirable to compartmentalise access to only those objects. This field is optional and if it is not specified, the default administrative key |
5.1.1 Enumeration - Access Mode
This enumeration is a Bit Field, however for legacy reasons it was encoded as an OCTET STRING
Element | Description |
|---|---|
Never | The object may not be read or used under any circumstances. This is a special value that cannot be combined with any other value. |
Pin | The object may be accessed only after PIN authentication. |
Pin Always | The object may be accessed only IMMEDIATELY after PIN authentication in the current session. It is acceptable to also set the |
Occ | The object may be accessed only after a successful Biometric On-Card Comparison in the current session. |
User Admin | The object may be managed after the access conditions have been successfully met. This has the effect or permitting the PUT DATA and GENERATE ASSYMMETRIC KEYPAIR commands for these values. It does not permit extended administration commands such as |
Always | The object may be read or used without any authentication. This is a special value that cannot be combined with any other value. When reading this field, take care to evaluate for |
Key Object Parameters
Element | Description |
|---|---|
Key Mechanism Type: Enumeration | Describes which cryptographic primitive (mechanism) will be associated with this key. See Enumeration - Key Mechanism below for details on populating this value. |
Key Role Type: Enumeration | Specifies what role(s) this key may perform for See Enumeration - Key Role below for details on populating this value. |
Key Attribute Type: Enumeration | Specifies what special attributes / options are flagged against this key. See Enumeration - Key Attribute below for details on populating this value. |
5.1.2 Enumeration - Key Mechanism
This defines the supported cryptographic primitives as specified by NIST SP 800-78-4.
Element | Description |
|---|---|
TDEA192 | Triple-DES-ECB using 3-key length (192 bits) |
RSA1024 | RSA Asymmetric Keypair, 1024-bit key length |
RSA2048 | RSA Asymmetric Keypair, 2048-bit key length |
AES128 | Advanced Encryption Standard, 128-bit key length |
AES192 | Advanced Encryption Standard, 192-bit key length |
AES256 | Advanced Encryption Standard, 256-bit key length |
ECC256 | Elliptic Curve using curve NIST P-256 |
ECC384 | Elliptic Curve using curve NIST P-384 |
SMCS2 | Cipher Suite 2 - Used for Secure Messaging (PIV Opacity ZKM) based on curve NIST P256, SHA-256 and AES 128-bit |
SMCS7 | Cipher Suite 7 - Used for Secure Messaging (PIV Opacity ZKM) based on curve NIST P384, SHA-384 and AES 256-bit |
5.1.3 Enumeration - Key Role
Element | Description |
|---|---|
Authenticate | This key can be used for card (internal), host (external) or card/host (mutual) authentication.
|
Key Establish | This key can be used for key establishment schemes.
|
Sign | This key can be used for digital signature mechanisms.
|
Verify | Reserved for future use |
Encrypt | Reserved for future use |
Decrypt | Reserved for future use |
5.1.4 Enumeration - Key Attributes
Element | Description |
|---|---|
Permit Internal | Symmetric Keys Only - Permits the PIV General Authenticate command to used to request an INTERNAL authentication. Great care should be taken before enabling this feature. Most environments should leave it switched off. |
Permit External | Symmetric Keys Only - Permits the PIV General Authenticate command to used to request an INTERNAL authentication. Great care should be taken before enabling this feature. Most environments should leave it switched off. |
Importable | Permits the key value to be injected instead of generated on the card. If this is set to False, only the This flag is mandatory for all symmetric key types (TDEA or AES). |
6 NIST-Compliant Pre-Personalisation Scripts
A set of APDU scripts to provide NIST compliance with the full range of mandatory and optional configuration, data objects, and keys has been created here: Appendix - NIST Compliant Profile
Add Comment