...
| Info |
|---|
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 set to True, the contactless interface is globally disabled regardless of individual data object or key permissions. If set to False, contactless is generally enabled and specific file system rules apply as normal.
| Note |
|---|
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 set to True, the contactless interface is disabled for all administrative operations. This includes PIV administration (9B) key and GlobalPlatform Secure Channel. If set to False, the contactless interface may be used for administrative operations.
| Note |
|---|
If the Options.ignoreContactlessAcl parameter is set to True, this parameter is ignored. |
| Next authentication | False |
Options.restrictEnumeration Type: BOOLEAN | Possible Values: If set to True, the host will not be able to list data objects and keys. If set to False, the host will be able to list data objects and keys.
| Info |
|---|
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: If set to True, the applet will prevent multiple keys with the same identifier but different mechanisms from being defined in the key store. If set to False, the applet will allow multiple keys with the same identifier but different mechanisms to be defined in the key store.
| Info |
|---|
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: If set to True, the Contactless permissions defined for data objects and keys are ignored and the Contact access control rules are evaluated when assessing permissions. If set to False, the application follows normal permission checks based on the current communications interface.
| Info |
|---|
This parameter has no effect if Options.restrictContactlessGlobal is set to True. |
| Warning |
|---|
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: 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.
| Immediate | False |
Options.useRSACRT Type: BOOLEAN | This value is currently ignored and will always be read as False. Possible Values: If set to True, RSA keys will be generated and injected using the Chinese Remainder Theorem method. If set to False, RSA keys will be generated
| Info |
|---|
RSA-CRT private key operations can be significantly faster, especially on limited embedded devices such as smartcards. |
| Note |
|---|
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. |
| Note |
|---|
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: If set to True, the local (Application) PIN may be used as a verification method. If set to False, the local (Application) PIN may not be used as a verification method.
| Immediate | True |
PinPolicy.enableGlobal Type: BOOLEAN | Possible Values: If set to True, the global (Card) PIN may be used as a verification method. If set to False, the global (Card) PIN may not be used as a verification method.
| Immediate | False |
PinPolicy.preferGlobal Type: BOOLEAN | Possible Values: If set to True, the Discovery Object will indicate that the global (Card) PIN is the preferred PIN to use. If set to False, the Discovery Object will indicate that the local (Application) PIN is the preferred PIN to use.
| Immediate | False |
PinPolicy.permitContactless Type: BOOLEAN | Possible Values: If set to True, the PIN may be presented over the contactless interface without the VCI condition satisfied. If set to False, the PIN may only be presented over the contactless interface when the VCI condition is satisfied.
| Info |
|---|
If the Options.ignoreContactlessAcl parameter is set to True, PIN is permitted over contactless regardless of this setting. |
| Immediate | False |
PinPolicy.minLength Type: INTEGER (4 to 16) | Indicates the minimum permitted length of the cardholder PIN verification value. | Note |
|---|
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. |
| Note |
|---|
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. | Info |
|---|
This value must be greater than or equal to the PinPolicy.minLength value. |
| Note |
|---|
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). |
| Note |
|---|
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. | Info |
|---|
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. | Info |
|---|
This value must be less than or equal to thePinPolicy.MaxRetriesContact value. 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. |
| Info |
|---|
If the Options.ignoreContactlessAcl parameter is set to True, this value is ignored and only MaxRetriesContact is used. |
| Immediate | 5 |
PinPolicy.Charset Type: Enumeration | Possible Values: If set to Numeric (0), only the digits 0 to 9 may be used in the PIN value If set to AlphaCaseVariant (1), ASCII values 20h (Space) to 7Eh (~) may be used, but all lowe-case values will be automatically converted to their upper-case equivalents when setting or comparing the PIN values. If set to AlphaCaseInvariant (2), ASCII values 20h (Space) to 7Eh (~) may be used. If set to Raw (3), PIN digits may be comprised of any byte value 00h to FFh. All other values are reserved
| Note |
|---|
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. |
| Note |
|---|
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: If set to Zero (0), no PIN history check is performed when changing PIN values If set to any other valid number [n], the Application will record the last [n] rolling PIN values and prevent them from being used again.
| 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 123456 or ABCDEF. Possible Values: If set to Zero (0), no checking of this rule applies If set to any other number [n], prevents a PIN being set where [n] or more characters are in ascending or descending sequence in the ASCII table.
| Tip |
|---|
Example If PinPolicy.RuleSequence is set to 4: |
| Note |
|---|
This number should be selected based on the PinPolicy.minLength and PinPolicy.maxLength values to achieve a balance of weak PIN prevention without restricting too many of the possible PIN values available. |
| 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 111111 or AAAAAA. Possible Values: If set to Zero (0), no checking of this rule applies If set to any other number [n], prevents a PIN being set where a single digit is used [n] or more times anywhere in the PIN value.
| Tip |
|---|
Example If PinPolicy.RuleDistinct is set to 4: |
| Note |
|---|
This number should be selected based on the PinPolicy.minLength and PinPolicy.maxLength values to achieve a balance of weak PIN prevention without restricting too many of the possible PIN values available. |
| Next PIN change | 0 (Disabled) |
4.3 PUK Policy
Element | Description | Effect | Default Value |
|---|
PukPolicy.Enabled Type: BOOLEAN | Possible Values: If set to True, the PUK may be used to reset and/or unblock the PIN value. If set to False, the PUK may not be used to reset and/or unblock the PIN value.
| 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. | Note |
|---|
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 set to True, the PUK may be presented over the contactless interface without the VCI condition satisfied. If set to False, the PUK may only be presented over the contactless interface when the VCI condition is satisfied.
| Info |
|---|
If the Options.ignoreContactlessAcl parameter is set to True, PUK is permitted over contactless regardless of this setting. |
| 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. | Info |
|---|
If the PUK is blocked, it can only be reset the Administrative role (Someone who has established a Secure Channel). |
| Info |
|---|
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. | Info |
|---|
This value must be less than or equal to thePukPolicy.MaxRetriesContact value. 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. |
| Info |
|---|
If the Options.ignoreContactlessAcl parameter is set to True, this value is ignored and only MaxRetriesContact is used. |
| Immediate | 10 |
PukPolicy.Updateable TYPE: BOOLEAN | Possible Values: If set to True, the PUK may be changed using the PIV CHANGE REFERENCE DATA command. If set to False, the PUK may not be changed using the PIV CHANGE REFERENCE DATA command.
| Info |
|---|
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.
...
| Info |
|---|
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. | Info |
|---|
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 112233h and 333333h would be treated as duplicates. It is strongly recommended to still pre-perso with full 3-byte PIV identifiers to future-proof your personalisation scripts. |
|
Mode Contact Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contact interface. | Info |
|---|
See Enumeration - Access Mode below for details on populating this value. |
|
Mode Contactless Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contactless interface. | Info |
|---|
See Enumeration - Access Mode below for details on populating this value. |
| Info |
|---|
If the Options.ignoreContactlessAcl parameter is set to True, this value is not used in assessing permissions. |
|
Admin Key Type: OCTET STRING (1 byte) OPTIONAL | Specifies which symmetric key can be used for managing this object using the PUT DATA or GENERATE ASSYMETRIC KEYPAIR command. 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. | Info |
|---|
This field is optional and if it is not specified, the default administrative key 9B is used. For systems that only want to administrate using Secure Channel, simply setting this value to a non-existent key id, or not initialising the 9B key will be sufficient to disable this capability. |
|
Key Mechanism Type: Enumeration | Describes which cryptographic primitive (mechanism) will be associated with this key. | Info |
|---|
See Enumeration - Key Mechanism below for details on populating this value. |
|
Key Role Type: Enumeration | Specifies what role(s) this key may perform for GENERAL AUTHENTICATE commands. | Info |
|---|
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. | Info |
|---|
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. | Info |
|---|
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 112233h and 333333h would be treated as duplicates. It is strongly recommended to still pre-perso with full 3-byte PIV identifiers to future-proof your personalisation scripts. |
|
Mode Contact Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contact interface. | Info |
|---|
See Enumeration - Access Mode below for details on populating this value. |
|
Mode Contactless Type: Enumeration | Provides access control restrictions and permissions for this object when connecting over the Contactless interface. | Info |
|---|
See Enumeration - Access Mode below for details on populating this value. |
| Info |
|---|
If the Options.ignoreContactlessAcl parameter is set to True, this value is not used in assessing permissions. |
|
Admin Key Type: OCTET STRING (1 byte) OPTIONAL | Specifies which symmetric key can be used for managing this object using the PUT DATA or GENERATE ASSYMETRIC KEYPAIR command. 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. | Info |
|---|
This field is optional and if it is not specified, the default administrative key 9B is used. For systems that only want to administrate using Secure Channel, simply setting this value to a non-existent key id, or not initialising the 9B key will be sufficient to disable this capability. |
|
5.1.1 Enumeration - Access Mode
| Info |
|---|
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. | Info |
|---|
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. | Info |
|---|
It is acceptable to also set the Pin flag in addition to this, but not necessary as Pin Always will take precedence. |
|
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. | Info |
|---|
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 PUT DATA ADMIN and CHANGE REFERENCE DATA ADMIN, which require a GlobalPlatform Secure Channel. |
|
Always | The object may be read or used without any authentication. | Info |
|---|
This is a special value that cannot be combined with any other value. |
| Note |
|---|
When reading this field, take care to evaluate for Always and Never special values first, as the Always value sets all lower 7 bits, which can look like other options are set. |
|
5.2 Key Object Parameters
Element | Description |
|---|
Key Mechanism Type: Enumeration | Describes which cryptographic primitive (mechanism) will be associated with this key. | Info |
|---|
See Enumeration - Key Mechanism below for details on populating this value. |
|
Key Role Type: Enumeration | Specifies what role(s) this key may perform for GENERAL AUTHENTICATE commands. | Info |
|---|
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. | Info |
|---|
See Enumeration - Key Attribute below for details on populating this value. |
|
5.2.1
...
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.
...
2.
...
2 Enumeration - Key Role
Element | Description |
|---|
Authenticate | This key can be used for card (internal), host (external) or card/host (mutual) authentication. For TDEA or AES key types, this role indicates the key may be used for authentication operations. For RSA key types, this role is not supported. For ECC key types, this role is not supported. For SM key types, this role is not supported.
|
Key Establish | This key can be used for key establishment schemes. For TDEA or AES key types, this role is not supported. For RSA key types, this role indicates the key may be used for RSA Key Transport. For ECC key types, this role indicates the key may be used for Elliptic-Curve Diffie-Helman Agreements (ECDH). For SM key types, this role indicates the key may be used for PIV Opacity Zero-Key Management (ZKM).
|
Sign | This key can be used for digital signature mechanisms. For TDEA or AES key types, this role is not currently supported. For RSA key types, this role indicates the key may be used for RSA Digital Signatures against pre-formatted signature blocks. For ECC key types, this role indicates the key may be used for Elliptic-Curve Digital Signature Algorithm operations (ECDSA). For SM key types, this role is not supported.
|
Verify | Reserved for future use |
Encrypt | Reserved for future use |
Decrypt | Reserved for future use |
5.
...
2.
...
3 Enumeration - Key Attributes
Element | Description |
|---|
Permit Internal | Symmetric Keys Only - Permits the PIV General Authenticate command to used to request an INTERNAL authentication. | Note |
|---|
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 EXTERNAL authentication. | Note |
|---|
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 GENERATE ASSYMETRIC KEYPAIR command may be used to generate key pairs. | Info |
|---|
This flag is mandatory for all symmetric key types (TDEA or AES). |
|
RSA CRT | RSA Keys Only - Instructs the applet to generate and store this RSA key using Chinese Remainder Theorem (CRT) format. | Info |
|---|
NOTES: This improves performance of private key operations at the cost of some flash space and for most modern Java Cards is highly recommended. If set with the Importable flag, the issuance system will need to inject all CRT key parts to initialise the key correctly.
|
|
6 NIST-Compliant Pre-Personalisation Scripts
...
