1 Contents

1 2 Overview
2 3 Command - GET STATUS
- 2.1 3.1 Schema
- 2.2 3.2 Example
3 4 Command - GET VERSION
- 3.1 4.1 Schema
- 3.2 4.2 Example
4 5 Command - PUT DATA ADMIN
5 6 Command - CHANGE REFERENCE DATA ADMIN
- 5.1 6.1 Schema
- 5.2 6.2 Example

2 Overview

OpenFIPS201 extend commands make use of BER-TLV command and/or response structures which are defined using Abstract Syntax Notation One (ASN.1).

These ASN.1 schemas have been compiled/validated inside the excellent and free OSS ASN.1 Playground. You are encouraged to load these schemas into their web tool to easily construct command data and parse response data.

All Response objects have all been tagged as [APPLICATION 19] to match the PIV GET DATA Response tag value, however with this ASN.1 the tag would actually render to 73h, whereas the PIV response is 53h. The difference is that ASN.1 would require the above to have the Constructed flag (bit 6, 20h) set, which accounts for the mismatch. To put it simply, you should expect your responses from the card to be tagged with 53h, not 73h.

3 Command - GET STATUS

3.1 Schema

OpenFIPS201_GET_STATUS_Schema DEFINITIONS IMPLICIT TAGS ::= 
BEGIN

AppletState ::= ENUMERATED {
	selectable	 	(0),
	personalised	(1),
	blocked 		(2),
	terminated  	(127)
}

GetStatusResponse ::= [APPLICATION 19] SEQUENCE {
	appletState		[0] AppletState,
	pinVerified		[1] BOOLEAN,
	pinAlways		[2] BOOLEAN,
	smState			[3] BOOLEAN,
	vciState		[4] BOOLEAN,
	scpState		[5] BOOLEAN,
	contactless		[6] BOOLEAN,
	fipsMode		[7] BOOLEAN
}

END

3.2 Example

53 15
  80 01 01 -- appletState = personalised
  81 01 FF -- pinVerified = TRUE
  82 01 00 -- pinAlways = FALSE
  83 01 00 -- smState = FALSE
  84 01 00 -- vciState = FALSE
  85 01 00 -- scpState = FALSE
  86 01 FF -- contactless = TRUE

4 Command - GET VERSION

4.1 Schema

OpenFIPS201_GET_VERSION_Schema DEFINITIONS IMPLICIT TAGS ::= 
BEGIN

GetVersionResponse ::= [APPLICATION 19] SEQUENCE {
	application	[0] UTF8String (SIZE(0..127)),
	major		[1] INTEGER (0..127),
	minor		[2] INTEGER (0..127),
	revision	[3] INTEGER (0..127),
	debug		[4] BOOLEAN
}

END

4.2 Example

53 1C
  80 0B 4F70656E46495053323031  -- application = 'OpenFIPS201'
  81 01 01 -- major = 1
  82 01 09 -- minor = 9
  83 01 14 -- revision = 20
  84 01 FF -- debug = TRUE
  85 01 00 -- fipsMode = FALSE

5 Command - PUT DATA ADMIN

5.1 Schema

OpenFIPS201_PUT_DATA_ADMIN_Schema DEFINITIONS IMPLICIT TAGS ::= 
BEGIN

LegacyOperation ::= ENUMERATED {
	undefined	(0),		
	dataObject	(1),
	key			(2)
}  

AccessMode ::= ENUMERATED {
	never		(0),
	pin			(1),  
	pinAlways	(2),
    occ			(4),  
	userAdmin	(16),
	always		(127)
}

KeyRole ::= ENUMERATED {
	authenticate	(1),
	keyEstablish	(2),
	sign		(4),
	verify		(8),
	encrypt		(16),
	decrypt		(32)
}
  
KeyAttribute ::= ENUMERATED {

	none			(0),
	permitInternal	(2),
	permitExternal	(4),
    permitMutual	(8),
	importable	(16)
}

KeyMechanism ::= ENUMERATED {
	undefined (0),
    tdea192 (3),
	rsa1024 (6),
	rsa2048 (7),
	aes128 (8),
	aes192 (10),
	aes256 (12),
	ecc256 (17),
	ecc384 (20),
	cs2 (39),
	cs7 (46)
}

PinCharSet ::= ENUMERATED {
	numeric				(0),
	alphaCaseVariant 	(1),
	alphaCaseInvariant	(2),
	raw					(3)
}

PinPolicyParameter ::= SEQUENCE {
	enableLocal				[0] BOOLEAN OPTIONAL,	
	enableGlobal			[1] BOOLEAN OPTIONAL,
	preferGlobal			[2] BOOLEAN OPTIONAL,
	permitContactless 		[3] BOOLEAN OPTIONAL,
	minLength				[4] INTEGER (4..32) OPTIONAL,
	maxLength				[5] INTEGER (4..32) OPTIONAL,
	maxRetriesContact 		[6] INTEGER (1..127) OPTIONAL,
	maxRetriesContactless 	[7] INTEGER (1..127) OPTIONAL,	
	charset					[8] PinCharSet OPTIONAL,
	history					[9] INTEGER (0..8) OPTIONAL,
	ruleSequence			[10] INTEGER (0..32) OPTIONAL,
	ruleDistinct			[11] INTEGER (0..32) OPTIONAL
}

PukPolicyParameter ::= SEQUENCE {

	enabled				[0] BOOLEAN OPTIONAL,
	permitContactless 	[1] BOOLEAN OPTIONAL,
	length				[2]	INTEGER (4..32) OPTIONAL,
	retriesContact		[3] INTEGER (1..127) OPTIONAL,
	retriesContactless	[4] INTEGER (1..127) OPTIONAL,
	restrictUpdate		[5] BOOLEAN OPTIONAL
}

VciMode ::= ENUMERATED {
	disabled (0),
	enabled (1),
	requirePairing (2)
}

OccMode ::= ENUMERATED {
	disabled (0),
	enabled (1)
}

VciPolicyParameter ::= SEQUENCE {
	mode			[0] VciMode OPTIONAL
}

OccPolicyParameter ::= SEQUENCE {
	mode			[0] OccMode OPTIONAL
}

OptionsParameter ::= SEQUENCE {
	restrictContactlessGlobal	[0] BOOLEAN OPTIONAL,
	restrictContactlessAdmin	[1] BOOLEAN OPTIONAL,
	restrictEnumeration			[2] BOOLEAN OPTIONAL,
	restrictSingleKey 			[3] BOOLEAN OPTIONAL,
	ignoreContactlessAcl		[4] BOOLEAN OPTIONAL,
	readEmptyDataObject 		[5] BOOLEAN OPTIONAL,
	useRSACRT 					[6] BOOLEAN OPTIONAL
}

PutDataLegacyRequest ::= SEQUENCE {
	operation		[10] LegacyOperation,
	id				[11] OCTET STRING (SIZE(1..3)),
	modeContact		[12] AccessMode,
	modeContactless	[13] AccessMode,
	keyMechanism	[14] KeyMechanism OPTIONAL,
	keyRole			[15] KeyRole OPTIONAL,
	keyAttribute	[16] KeyAttribute OPTIONAL
}

PutDataCreateObjectRequest ::= SEQUENCE {
	id				[11] OCTET STRING (SIZE(1..3)),
	modeContact		[12] AccessMode,
	modeContactless	[13] AccessMode,
	adminKey		[17] INTEGER (0..127) OPTIONAL
}

PutDataDeleteObjectRequest ::= SEQUENCE {
	id				[11] OCTET STRING (SIZE(1..3))
}

PutDataCreateKeyRequest ::= SEQUENCE {
	id				[11] OCTET STRING (SIZE(1)),
	modeContact		[12] AccessMode,
	modeContactless	[13] AccessMode,
	adminKey		[17] INTEGER (0..127) OPTIONAL,
	keyMechanism	[14] KeyMechanism,
	keyRole			[15] KeyRole,
	keyAttribute	[16] KeyAttribute
}

PutDataDeleteKeyRequest ::= SEQUENCE {
	id				[11] OCTET STRING (SIZE(1)),
	keyMechanism	[14] KeyMechanism
}

PutDataUpdateConfigRequest ::= SEQUENCE {
	pinPolicy		[0] PinPolicyParameter OPTIONAL,
	pukPolicy 		[1] PukPolicyParameter OPTIONAL,
	vciPolicy 		[2] VciPolicyParameter OPTIONAL,
	occPolicy 		[3] OccPolicyParameter OPTIONAL,
	options			[4] OptionsParameter OPTIONAL
}

PutDataRequest ::= CHOICE {
	legacyRequest		PutDataLegacyRequest,
	createObjectRequest	[APPLICATION 4] PutDataCreateObjectRequest,
	deleteObjectRequest	[APPLICATION 5] PutDataDeleteObjectRequest,
	createKeyRequest 	[APPLICATION 6] PutDataCreateKeyRequest,
	deleteKeyRequest 	[APPLICATION 7] PutDataDeleteKeyRequest,
	configRequest		[APPLICATION 8] PutDataUpdateConfigRequest
}

PutDataBulkRequest ::= [APPLICATION 10] SEQUENCE OF PutDataRequest

END

5.2 Example - Legacy Request

-- Create Data Object -- 
30 0E
  8A 01 01      -- operation = dataObject
  8B 03 5FC107  -- id = 5FC107
  8C 01 7F      -- modeContact = always
  8D 01 00      -- modeContactless = never
  
-- Create Key --
30 15
  8A 01 02 -- operation = key
  8B 01 9B -- id = 9Bh
  8C 01 7F -- modeContact = always
  8D 01 00 -- modeContactless = never
  8E 01 08 -- keyMechanism = aes128
  8F 01 01 -- keyRole = authenticate
  90 01 10 -- keyAttribute = importable

5.3 Example - Create Object Request

64 0E
  8B 03 5FC107 -- id = 5FC107h 
  8C 01 7F -- modeContact = always
  8D 01 08 -- modeContactless = never
  91 01 9B -- adminKey = 9Bh

5.4 Example - Delete Object Request

65 05
  8B 03 5FC107 -- id = 5FC107

5.5 Example - Create Key Request

66 15
  8B 01 9B -- id = 9Bh
  8C 01 7F -- modeContact = always
  8D 01 00 -- modeContactless = never
  91 01 9B -- adminKey = 9Bh
  8E 01 0C -- keyMechanism = aes256
  8F 01 01 -- keyRole = authenticate
  90 01 10 -- keyAttribute = importable

5.6 Example - Delete Key Request

# Specific key/mechanism pair
67 06
  8B 01 9B -- id = 9Bh 
  8E 01 0C -- mechanism = aes256
  
  OR 
  
# All mechanisms for id [xx]
67 03
  8B 01 9B -- id = 9Bh

5.7 Example - Config Update Request

68 5B
  A0 24       - # PIN POLICY
    80 01 FF  - enableLocal = TRUE
    81 01 00  - enableGlobal = FALSE
    82 01 00  - preferGlobal = FALSE
    83 01 00  - permitContactless = TRUE
    84 01 06  - minLength = 6
    85 01 08  - maxLength = 8
    86 01 06  - maxRetriesContact = 6
    87 01 05  - maxRetriesContactless = 5
    88 01 00  - charset = numeric
    89 01 04  - history = 4 
    8A 01 04  - ruleSequence = 4 (enabled)
    8B 01 04  - ruleDistinct = 4 (enabled)
  A1 12       - # PUK POLICY
    80 01 FF  - enabled = TRUE
    81 01 00  - permitContactless = FALSE
    82 01 08  - length = 8
    83 01 06  - retriesContact = 6
    84 01 05  - retriesContactless = 5
    85 01 00  - restrictUpdate = FALSE
  A2 03       - # VCI POLICY
    80 01 00  - mode = disabled
  A3 03       - # OCC POLICY
    80 01 00  - mode = disabled
  A4 15       - # OPTIONS
    80 01 00  - restrictContactlessGlobal = FALSE
    81 01 00  - restrictContactlessAdmin = FALSE
    82 01 00  - restrictEnumeration = FALSE
    83 01 00  - restrictSingleKey = FALSE
    84 01 00  - ignoreContactlessAcl = FALSE
    85 01 00  - readEmptyDataObject = FALSE
    86 01 00  - useRSACRT = false

5.8 Example - Bulk Request

6A 1E
  64 0E           # CREATE DATA OBJECT 1
    8B 03 5FC102  -- id = 5FC102
    8C 01 7F      -- modeContact = always
    8D 01 00      -- modeContactless = never
    91 01 9B
  64 0C           # CREATE DATA OBJECT 2
    8B 01 7E      -- id = 7E
    8C 01 7F      -- modeContact = always
    8D 01 7F      -- modeContactless = always
    91 01 9B      -- keyAdmin = 9B

6 Command - CHANGE REFERENCE DATA ADMIN

6.1 Schema

OpenFIPS201_CHANGE_REFERENCE_DATA_ADMIN_Schema DEFINITIONS IMPLICIT TAGS ::= 
BEGIN

ChangeReferenceDataKeyRequest ::= SEQUENCE {
	element CHOICE	{
		key		[0] OCTET STRING (SIZE(16..32)),
		rsaN	[1] OCTET STRING (SIZE(128..256)), 	-- The RSA modulus
		rsaE	[2] OCTET STRING (SIZE(3)),			-- The RSA public exponent
		rsaD	[3] OCTET STRING (SIZE(128..256)),	-- The RSA private exponent 
		eccW	[6] OCTET STRING (SIZE(32..48)),	-- The point of the curve comprising the public ECC key
		eccS	[7] OCTET STRING (SIZE(32..48))		-- The secret component of the ECC key
	}
}

END

6.2 Example

30 22
  80 20 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF -- key = [32 byte key value]

Appendix - ASN.1 Schema