1 Contents

2 Overview

This section describes the OpenFIPS201 interface, including communications, command and data interfaces.

3 Communications (ISO 7816 and ISO 14443)

3.1.1 Application Identifier (AID)

The PIV AID is specified by the standard [SP800-73]:

A0 00 00 03 08 00 00 10 00 01 00

The standard requires that this AID be used as the PIV application, however there may be use cases where you wish to have two or more instances on a card, for instance in multi-domain card configurations. You will need to have multi-instance aware middleware to achieve this.

3.1.2 Communications

OpenFIPS201 is intended to be used on cards that support ISO 7816 Part 4 (T=0 and T=1) and ISO 14443 Part 4 (T=CL) framing.
Only ISO 7816 single-length APDU formatting supported. Any extended-length APDU sent to the card will be rejected with an error.
ISO 7816 command chaining and GET RESPONSE is supported for the following commands:
- VERIFY
- GENERAL AUTHENTICATE
- PUT DATA
- GENERATE ASYMMETRIC KEYPAIR
- PUT DATA ADMIN
- CHANGE REFERENCE DATA ADMIN

3.1.3 Card Selection

For ISO 7816-4 interface, whilst the ATR value is not mandatory, it is recommended that cards predominantly used for PIV include the PIV AID in their Historical Bytes field (tag ‘F9’)

3.1.4 Inter-Industry Commands

To facilitate applet selection and Secure Channel functionality, the following ISO 7816 inter-industry commands are implemented:

INITIALIZE UPDATE (INS = ‘50’)
EXTERNAL AUTHENTICATE (INS = ‘82’)
SELECT (INS = 'A4')
GET RESPONSE (INS = ‘C0’)

More detail on these inter-industry commands can be found in the ISO 7816 standard [ISO-7816-4].

4 Commands - ISO Inter-Industry

4.1 Command - SELECT

Command

Command
CLA	‘00’
INS	‘A4’
P1	‘04’
P2	‘00’
LC	Variable - Length of Application Identifier
Data	Either full or the right-truncated AID of the PIV Card Application: This value is always `A0 00 00 03 08 00 00 10 00 01 00` unless the applet is used in a multi-domain environment
LE	‘00’
Normal Response
DATA	The Application Property Template as described in [SP800-73-4] Part 2, 3.1 - Table 3
STATUS	‘9000’ - Success
Error Responses
STATUS	‘6A82’ - SW_FILE_NOT_FOUND (Incorrect AID specified)
Implementation Notes This command does not support command chaining

4.2 Command - INITIALIZE UPDATE

Command

Command
CLA	‘80’
INS	‘50’
P1	Key Version Number
P2	‘00’
LC	Length of host challenge
Data	Host challenge
LE	‘00’
Normal Response
DATA	Key diversification data (10 bytes) Key information (2 bytes) Sequence Counter (2 bytes) Card challenge (6 bytes) Card cryptogram (8 bytes)
STATUS	‘9000’ - Success
Error Responses
STATUS	‘6A88’ - SW_REFERENCE_NOT_FOUND (The specified key version was not found)
Implementation Notes This command does not support command chaining Executing this command will invalidate any existing Secure Channel session

4.3 Command - EXTERNAL AUTHENTICATE

Command

Command
CLA	‘84’
INS	‘82’
P1	Security Level From GlobalPlatform Secure Channel Protocol 03 - Addendum D Specification
P2	‘00’
LC	Length of host cryptogram and MAC
Data	Host cryptogram and MAC
LE	Not present
Normal Response
DATA	Not present
STATUS	‘9000’ - Success
Error Responses
STATUS	‘6300’ - Authentication of host cryptogram failed
Implementation Notes This command does not support command chaining

4.4 Command - GET RESPONSE

This command is used where a single response APDU frame is not large enough to return all the required data. This is defined as Response Chaining in [ISO 7816-4].

Command

Command
CLA	‘00'
INS	‘C0’
P1	‘00’
P2	‘00’
LC	‘00’
Data	Not Present
LE	Maximum length of data expected in response
Normal Response
DATA	Response Data
STATUS	‘9000’ - Success ‘61XX' - More data available (where 'XX' indicates the number of remaining bytes to read. If set to ‘00’ there may be more than 255 bytes remaining)
Error Responses
STATUS	‘6281' - Part of returned data may be corrupt ‘6700’ - The LC field is incorrect ‘6A86’ - The P1 and/or P2 parameters are incorrect ‘6CXX’ - The LE field is incorrect (XX indicates exact length)
Implementation Notes This command does not support command chaining

5 Commands - Operational

5.1 Command - GET DATA

The GET DATA card command retrieves the data content of the single data object whose tag is given in the data field.

Command

Command
CLA	‘00’ - Plain communications; OR ‘0C’ - Secure Messaging
INS	‘CB’
P1	‘3F’
P2	‘FF’
LC	Length of data field
Data	Tag list ‘5C’ as specified in [SP800-73] Part 2, 3.1.2
LE	‘00’
Normal Response
DATA	Content of the requested data object, contained within the tag ‘53’
STATUS	‘9000’ - Success ‘61XX' - More data available (where 'XX' indicates the number of remaining bytes to read. If set to ‘00’ there may be more than 255 bytes remaining)
Error Responses
STATUS	‘6982’ - Cardholder not verified ‘6A82’ - Data object not found
Command Pre-Conditions PRE-CONDITION 1 - The 'TAG' data element must be present PRE-CONDITION 2 - The access rules must be satisfied for the requested object PRE-CONDITION 3 - The requested object must be initialised with data Implementation Notes This command does not support command chaining This command may require the GET RESPONSE command

5.2 Command - VERIFY

The VERIFY command is the used for a number of purposes, all around verification of the cardholder or reader:

Verify the local or global PIN
Verify the Pairing Code over Secure Messaging
Verify biometric minutiae for on-card biometric comparison (not currently supported)
Clear the verification status of a PIN, Pairing Code or Biometric
Return the number of remaining attempts for a PIN

Command

Command
CLA	‘00’ - Plain communications, no chaining; OR ‘10’ - Plain communications, chaining; OR ‘0C’ - Secure Messaging, no chaining; OR ‘1C’ - Secure Messaging, chaining
INS	‘20’
P1	Either: ‘00’ - Verify ‘FF’ - Reset Verification
P2	PIN, Pairing Code or Biometric Reference
LC	If P1 is ‘00’ (Verify): ‘00’ (no data) to return the number of remaining attempts for the PIN reference given in P2 ‘08’ for PIN or Pairing Code verification Otherwise the length of the biometric minutiae If P1 is ‘FF’ (Reset Verification): ‘00’ (no data) to reset the verification status of the PIN, Pairing Code or Biometric reference given in P2
Data	If P1 is ‘00’ (Verify): The ASCII value of the numeric PIN 6-8 digits in length, padded with 'FF'; or The Pairing Code The biometric minutiae If P1 is ‘FF’ (Reset Verification): Not present
LE	Not present
Normal Response
DATA	Not present
STATUS	‘9000’ - Success
Error Responses
STATUS	'6300' Verification failed '63CX' Verification failed or remaining retries requested, X indicates the number of further allowed retries '6982' The PIN reference may not be used over the contactless interface '6983' Authentication method blocked '6A80' Incorrect parameter in command data field '6A81' Function not supported '6A86' Incorrect parameter in P1 '6A88' Key reference not found
Command Pre-Conditions PRE-CONDITION 1 - The PIN reference must point to a valid PIV Card Application or Global PIN PRE-CONDITION 2 - If FEATURE_PIN_GLOBAL_ENABLED is false, the PIN reference may not be the Global PIN PRE-CONDITION 3 - If FEATURE_PIN_CARD_ENABLED is false, the PIN reference may not be the PIV Card Application PIN PRE-CONDITION 4 - If FEATURE_PIN_OVER_CONTACTLESS is false and the PIN reference is the PIV Card Application PIN or Global PIN, the interface must not be contactless PRE-CONDITION 5 - The supplied PIN format must be valid according to [SP800-73-4] PRE-CONDITION 6 - The PIN must not be blocked PRE-CONDITION 7 - If using the contactless interface, the pin retries remaining must not fall below the specified intermediate retry amount Implementation Notes This command supports command chaining

5.3 Command - CHANGE REFERENCE DATA

Command

Command
CLA	‘00’ - Plain communications; OR ‘0C’ - Secure Messaging
INS	‘24’
P1	‘00’
P2	‘00’ - Global PIN ‘80’ - PIV Card Application PIN ‘81’ - PUK
LC	Variable
Data	Current value, concatenated immediately with new value.
LE	Not present
Normal Response
DATA	Not present
STATUS	‘9000’ - Success
Error Responses
STATUS	'63CX' Verification failed or remaining retries requested, X indicates the number of further allowed retries '6982' The PIN reference may not be used over the contactless interface '6983' Authentication method blocked '6A80' Incorrect parameter in command data field '6A81' Function not supported '6A88' Key reference not found
Command Pre-Conditions PRE-CONDITION 1 - The PIN reference must point to a valid PIV Card Application, Global PIN or PUK PRE-CONDITION 2 - If FEATURE_PIN_GLOBAL_ENABLED is false, the PIN reference may not be the Global PIN PRE-CONDITION 3 - If FEATURE_PIN_GLOBAL_CHANGE is false, the PIN reference may not be the Global PIN PRE-CONDITION 4 - If FEATURE_PIN_CARD_ENABLED is false, the PIN reference may not be the PIV Card Application PIN PRE-CONDITION 5 - If FEATURE_PIN_OVER_CONTACTLESS is false and the PIN reference is the PIV Card Application PIN or Global PIN, the interface must not be contactless PRE-CONDITION 6 - If FEATURE_PUK_CHANGE is false, the PIN reference may not be the PUK PRE-CONDITION 7 - If FEATURE_PUK_OVER_CONTACTLESS is false and the PIN reference is the PUK, the interface must not be contactless Implementation Notes This command does not support command chaining

5.4 Command - RESET RETRY COUNTER

This command changes the value of the PIV Card Application PIN and resets the retry counter of the to its initial value. Its intended use is to allow a PIN reset / unblock by an authorised person (Security Officer role) or management system.

Command

Command
CLA	‘00’
INS	‘2C’
P1	‘00’
P2	‘80’ - PIV Card Application PIN
LC	‘10’
Data	Current PUK value, concatenated immediately with new PIN value.
LE	Not present
Normal Response
DATA	Not present
STATUS	‘9000’ - Success
Error Responses
STATUS	'63CX' Operation failed or remaining retries requested, X indicates the number of further allowed retries '6983' Reset operation blocked '6A80' Incorrect parameter in command data field '6A81' Function not supported '6A88' Key reference not found
Command Pre-Conditions PRE-CONDITION 1 - If FEATURE_PIN_OVER_CONTACTLESS is false, the interface must not be contactless PRE-CONDITION 2 - If FEATURE_PUK_OVER_CONTACTLESS is false, the interface must not be contactless PRE-CONDITION 3 - The supplied PIN reference must be the PIV Card Application PIN only PRE-CONDITION 4 - The PUK must not be blocked PRE-CONDITION 5 - The supplied PIN format must be valid according to [SP800-73-4] Implementation Notes This command does not support command chaining

5.5 Command - GENERAL AUTHENTICATE

All operational cryptographic commands are encapsulated under the ‘General Authentication’ command, including:

Authentication
Digital Signatures
Key Establishment
Secure Messaging

There are 6 authentication cases that make up all of the GENERAL AUTHENTICATE functionality.

	Case

	Case
1	Internal Authenticate	The CLIENT presents a CHALLENGE to the CARD, which then returns the encrypted/signed CHALLENGE RESPONSE. This is handled in 3 different mode variants, depending on the key TDEA/AES keys with the AUTHENTICATE role will encipher the challenge. RSA/ECC keys with the SIGNATURE role will perform signing operations (on already padded data). RSA keys with the KEY_ESTABLISH role will perform RSA key transport. SM keys with the KEY_ESTABLISH role will perform the Opacity-ZKM key agreement. All other cases are invalid
2	External Authenticate Request	The client requests a CHALLENGE from the CARD.
3	External Authenticate Response	The client presents a CHALLENGE RESPONSE to the CARD, which then verifies it.
4	Mutual Authenticate Request	The client requests a WITNESS (a proof of key possession) from the CARD. The card generates the WITNESS, encrypts it and returns it as ciphertext.
5	Mutual Authenticate Response	The client decrypts the received WITNESS, generates a CHALLENGE REQUEST and presents both to the CARD. The card verifies the decrypted WITNESS and encrypts the CHALLENGE, which it then returns as the CHALLENGE RESPONSE.
6	Key Establishment Scheme	The client requests an Elliptic Curve key agreement operation against the supplied exponentiation parameter.

Command

Command
CLA	‘00’ - Plain communications, no chaining; OR ‘10’ - Plain communications, chaining; OR ‘0C’ - Secure Messaging, no chaining; OR ‘1C’ - Secure Messaging, chaining
INS	‘87’
P1	Requested mechanism (See TBD ref)
P2	Requested key reference (See TBD ref)
LC	Variable
Data	Dynamic Authentication Template (Tag ‘7C’)
LE	Not present or ‘00’
Normal Response
DATA	Cryptographic operation output data
STATUS	‘9000’ - Success ‘61XX' - More data available (where 'XX' indicates the number of remaining bytes to read. If set to ‘00’ there may be more than 255 bytes remaining)
Error Responses
STATUS	‘61XX' More data still available (where XX is the number of remaining bytes or ‘00’ for greater than maximum data payload remaining) '6982' Security status not satisfied '6A80' Incorrect parameter in command data field '6A86' Incorrect parameter in P1
Command Pre-Conditions General PRE-CONDITION 1 - The requested key reference and mechanism must point to an existing key PRE-CONDITION 2 - The access rules must be satisfied for the requested key PRE-CONDITION 3 - The key's private or secret values must have been set PRE-CONDITION 4 - The Dynamic Authentication Template tag must be present in the data Case 1 - Internal Authenticate A CHALLENGE must be present with data A RESPONSE must be present but empty If the key type is ECC and the key has the SECURE_MESSAGE role, it is Variant A If the key type is RSA or ECC and the key has the SIGNATURE role, it is Variant B If the key type is RSA and the key has the KEY_ESTABLISH role, it is Variant C If the key type is TDEA or AES and the key has the AUTHENTICATE role, it is Variant D Case 2 - External Authenticate Request A CHALLENGE must be present but empty The key type must be SYMMETRIC The key has the AUTHENTICATE role set; AND The key attribute MUTUAL ONLY is not set Case 3 - External Authenticate Response A RESPONSE must present with data The key type must be SYMMETRIC The key must have the AUTHENTICATE role set The key attribute MUTUAL ONLY must not be set A successful EXTERNAL AUTHENTICATE REQUEST must have immediately preceded this command Case 4 - Mutual Authenticate Request A WITNESS must be present but empty The key must have the AUTHENTICATE role set Case 5 - Mutual Authenticate Response A WITNESS must be present with data A CHALLENGE must be present with data The key type must be SYMMETRIC A successful MUTUAL AUTHENTICATE REQUEST must have immediately preceded this command Case 6 - Key Establishment Scheme An EXPONENTIATION parameter must present with data The key type must be ECC The key must have the KEY_ESTABLISH role Implementation Notes This command supports command chaining This command may require the GET RESPONSE command

5.6 Command - PUT DATA

This command completely replaces the contents of a single data object in the PIV card application with new content.

Command

Command
CLA	‘00’ - Plain communications; OR ‘0C’ - Secure Messaging
INS	‘DB’
P1	‘3F’
P2	‘FF’
LC	Variable
Data	BER-TLV of data object
LE	Not present
Normal Response
DATA	Not present
STATUS	‘9000’ - Success
Error Responses
STATUS	'6982' Security status not satisfied '6A81' Function not supported '6A84' Key reference not found
Command Pre-Conditions PRE-CONDITION 1 - The access rules must be satisfied for administrative access PRE-CONDITION 2 - The requested object must be specified in one of the following ways If the data length is 1 byte and the data value is ‘7E’, the requested object is the ‘Discovery Object'; OR If the data length is 2 bytes and the data value is ‘7F61’, the requested object is the ‘Biometric Information Template Group'; OR For all other cases, the ‘TAG LIST' tag (’5C') must be present PRE-CONDITION 3 - The tag supplied in the 'TAG LIST' element must exist in the data store Implementation Notes This command supports command chaining This command dynamically allocates EEPROM memory and may request execution of the garbage collection process if the card supports it.

5.7 Command - GENERATE ASYMMETRIC KEYPAIR

Command

Command
CLA	‘00’ - Plain communications; OR ‘0C’ - Secure Messaging
INS	‘47’
P1	‘00’
P2	Key reference
LC	Variable
Data	Control reference template (See [SP800-73-4] Part 2, Table 11)
LE	‘00’
Normal Response
DATA	Public key value of generated key pair (See [SP800-73-4] Part 2, Table 12)
STATUS	‘9000’ - Success ‘61XX' - More data available (where 'XX' indicates the number of remaining bytes to read. If set to ‘00’ there may be more than 255 bytes remaining)
Error Responses
STATUS	'6982' - Security status not satisfied '6A80' - Unsupported cryptographic mechanism '6A81' - Function not supported '6A86' - Cryptographic mechanism of reference data to be generated different than cryptographic mechanism of reference data of given key reference
Implementation Notes This command does not support command chaining This command may dynamically allocate EEPROM memory This command may require the GET RESPONSE command

6 Commands - Extended

The following commands extend the PIV command set, providing additional functionality for card management, status and key injection.

6.1 Command - PUT DATA ADMIN

This command permits management of the dynamic file system and configuration values.

This is an extended version of the PIV 'PUT DATA' command, with the following changes made:

The P1/P2 value must be set to 3F00 instead of 3FFF used by the normal PUT DATA command.
The command will only work under a Secure Channel Protocol session with the CENC and CMAC options set
The data content must conform to the basic ASN.1 structure defined below and encoded using BER-TLV.

Command

Command
CLA	‘0C’ - Secure Messaging
INS	‘DB’
P1	‘3F’
P2	‘00'
LC	Variable
Data	One of the following objects encoded using BER-TLV: PutDataLegacyRequest PutDataCreateObjectRequest PutDataDeleteObjectRequest PutDataCreateKeyRequest PutDataDeleteKeyRequest PutDataUpdateConfigRequest PutDataBulkRequest (For details and examples of these command objects, see Appendix - ASN.1 Schema)
LE	Not present
Normal Response
DATA	Not present
STATUS	‘9000’
Error Responses
STATUS	'6982' Security status not satisfied
Implementation Notes This command does not support command chaining

6.2 Command - CHANGE REFERENCE DATA ADMIN

The PIV standard defines commands to write data objects, generate asymmetric keys and change PIN values. It does not however define any administrative mechanism to inject key values.

This is always necessary for symmetric keys (such as 9B and optionally 9E), but only required for asymmetric keys (9A, 9C, 9D, 9E and retired keys) if they have been generated off-card (i.e. inside a HSM).

OpenFIPS201 supports key injection to address this need, as well as securely configuring default PIN/PUK values.

6.2.1 Key Injection Command

This command is the equivalent of the CHANGE REFERENCE DATA command APDU, however it is intended to operate on key references that are NOT listed in SP800-73-4.

The main differences to CHANGE REFERENCE DATA are:

It supports updating any key reference that is not covered by CHANGE REFERENCE DATA already
The command will only work under a Secure Channel Protocol session with the CENC and CMAC options set
It does NOT require the old value to be supplied in order to change a key
It also supports updating the PIN/PUK values without requiring knowledge of the old value (The value of P1 does is ignored for PIN/PUK updates)
The APDU supports command chaining for large key values

The data content for this command depends on whether you are updating a PIN or a KEY reference.

For KEY references, the data contains a BER-TLV formatted ASN.1 object.

Command

Command
CLA	‘0C’ - Secure Messaging
INS	‘24’
P1	‘00’
P2	Key Reference
LC	Variable
Data	Where `P2` refers to the PIN, Global PIN or PUK: The data is the new value of the referenced PIN/PUK only Where the value of `P2` is any other value: The data is a single BER-TLV encoded ChangeReferenceDataKeyRequest (see Appendix - ASN.1 Schema)
_LE	Not present
Normal Response
DATA	Not present
STATUS	‘9000’
Error Responses
STATUS	‘6A82’ - SW_FILE_NOT_FOUND (Incorrect AID specified)
Implementation Notes This command supports command chaining

6.3 Command - GET STATUS

This command is equivalent to the PIV GET DATA command, with the following differences:

The value of P2 is 00 instead of FF to indicate this is an extended GET DATA command.
The tag reference is 2F4753h, which equates to the ASCII value /GS.

Command

Command
CLA	‘00’
INS	‘CB’
P1	‘3F’
P2	‘00’
LC	‘05’
Data	‘5C032F4753’
LE	‘00’
Normal Response
DATA	A GetStatusResponse object encoded in BER-TLV format (See Appendix - ASN.1 Schema)
)STATUS	‘9000’
Error Responses
STATUS	‘6A82’ - SW_FILE_NOT_FOUND (Incorrect AID specified)
Command Pre-Conditions None Implementation Notes This command does not support command chaining

6.4 Command - GET VERSION