T104-Devhub

T104 Applet APDU Guide

The T104 Applet is responsible for the access to the low level drivers for the card’s timeout settings, E-Ink display and the E-Wallet feature.

Certain features including the management of the E-Wallet feature as well as the card’s timeout function maybe carried out via directly accessing the T104 Applet as a T104 Applet Administrator role.

A secure channel between the Host application (i.e. T104 Manager GUI console) and T104 applet has to be established before accessing the features and settings.

The Secure Channel Protocol as well as the APDUs for accessing the T104 Applet is given below.

T104 Applet AID

0x4B4D31303400

T104 Secure Channel Protocol Key Agreement - A03

The A03 SCP protocol uses a ephemeral-static ECDH key agreement protocol. The card applet hosts a long term static keypair while the Host Application dynamically generates an ephemeral keypair for the secure channel key agreement.

T104 Applet uses the following cryptographic primitives for Secure Channel negotiations and Secure Messaging.

ECC SECP-256K1 for ECC public and private key
KeyAgreement.ALG_EC_SVDP_DH_PLAIN for key agreement protocol
Cipher.ALG_AES_CBC_PKCS5 for symmetric key encryption of messages
MessageDigest.ALG_SHA_256 for hashing of messages and HMAC message authentication

The steps from Host Application (Host) to T104 Applet for negotiating the A03 Secure Channel is as follows:

Host generates ephemeral keypair and sends uncompressed public key in ASN.1 format (0x04 || X || Y ) to the card applet. A total of 65 bytes are required with 32 bytes of X and Y each.
A Nonce for Secure Messaging is generated by hashing the host ephemeral public key followed by the T104 Applet public key and extracting the first 12 bytes.

Nonce <-- First12Bytes(SHA256(HostPublicKey || T104PublicKey))
A shared secret is created on the Host and T104 Applet by performing an ECDH and extracting the first 32 bytes (X coordinates) of the shared secret.

X <-- First32Bytes(ECDH(PrivateKey == Host / Applet Private Key, PublicKey == Host / Applet Public Key))
SHA-256 hash the 32 bytes X coordinates that was extracted as the session key.

SessionKey <-- SHA256(X)
Session OTP Key is generated by a second SHA-256 hash on the X coordinates.

OTPKey <-- SHA256(SessionKey)
Generate the OTP Code according to HOTP mode of RFC-4226.

Check the OTP Code the Host generated and the OTP Code displayed on the E-Ink screen.

T104 Secure Channel Protocol Message Protection - A03

Protected messages that are encrypted and authenticated occuring after a Key Agreement will use the following protocol. All plain messages are to be exactly 197 or less bytes before being encrypted and then authenticated. If the messages are more than 197 bytes, chunk them into portions of 197 bytes with the last message packet having the remainder bytes.

Two counters, one for the Host and one for the Applet exists on both sides. A HostToApplet and a AppletToHost counter are taken care of by both the Host and Applet in an ephemeral manner. Both starts with a counter of zero 0x0000 of data type short.

Enveloping a Message from Host to Applet

Check to ensure session counters HostToApplet and AppletToHost are less than 65536 or 0xFFFF. Host must manually execute another fresh Key Agreement if any counters are close to reaching maximum counter for any of the session counters. Ensure input message is of correct length.
Form encryption IV by concatenating Nonce, HostToApplet and AppletToHost, hashing them with SHA-256 and extracting the first 16 bytes.

MessageIV <-- First16Bytes(SHA256( Nonce || HostToApplet || AppletToHost ))
Encrypt message with Cipher.ALG_AES_CBC_PKCS5.

CipherText <-- AES_CBC_PKCS5(Key == SessionKey, Message == Input, IV = MessageIV)
Create a Message Hash by concatenating APDU CLA, INS, P1, P2, MessageIV, CipherText

MessageHash <-- SHA256( CLA || INS || P1 || P2 || MessageIV || CipherText)
MAC using SessionKey and MessageHash.

MAC <-- HMACSHA256(Key == SessionKey, Message == MessageHash)
Format enveloped message as follows:

EnvelopedAPDUMessage <-- CLA || INS || P1 || P2 || LC == Length(CipherText) + Length(MAC) || Content == CipherText || MAC
Increment HostToApplet counter once.
Send enveloped APDU message to T104 applet.

Un-enveloping a Message from Applet to Host

Check to ensure session counters HostToApplet and AppletToHost are less than 65536 or 0xFFFF. Host must manually execute another fresh Key Agreeement if any counters are close to reaching maximum counter for any of the session counters. Ensure input message is of correct length.
If returned length is only 2 bytes SW, increment AppletToHost counter and exit.
Form encryption IV by concatenating Nonce, HostToApplet and AppletToHost, hashing them with SHA-256 and extracting the first 16 bytes.

MessageIV <-- First16Bytes(SHA256( Nonce || HostToApplet || AppletToHost ))
Create a Response Hash by concatenating APDU SW, MessageIV, CipherText

ResponseHash <-- SHA256( SW || MessageIV || CipherText)
MAC using SessionKey and ResponseHash and compare received MAC and computed MAC. If successful matching of the MAC, proceed to step 6 and decrypt the CipherText.

MAC <-- HMACSHA256(Key == SessionKey, Message == ResponseHash)
Decrypt message with Cipher.ALG_AES_CBC_PKCS5.

ResponseMessage <-- AES_CBC_PKCS5(Key == SessionKey, Message == CipherText, IV = MessageIV)
Increment AppletToHost counter once regardless if the MAC was verified or not.

Management APDUs

Please not that APDU commands marked with requiring secure APDU request will require encryption and authentication of APDU commands before sending them to the T104 applet. APDU responses marked with requiring secure APDU response will need to go through the un-enveloping process to verify the secure responses as well a optionally decrypt the response content if available.

Retrieving T104 Applet Information

Retrieves the following information of the T104:

Version of Applet
Capability of Applet
Supported User Type
Supported SCP protocol
Supported applet backup method
Hardware Interaction method
Applet login format
Persistent memory space available (estimated)
Transient resettable memory space available (estimated)
Transient deselectable memory space available (estimated)
Unique Hardware ID
- Long term public key (SECP256K1 algorithm)

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
CONDITIONAL	CONDITIONAL

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
88 (PLAIN)/ 84 (SECURE)	B2	00	00	00	N/A	N/A

Response APDU:
Returns information about the card.

TLV is being used after the initial two byte version sequence. All TLV length are restricte to one byte length only.

A list of supported TLV tags:

public static final byte TLV_TAG_HW_INFO = (byte) 0x01;
public static final byte TLV_TAG_HW_CAP = (byte) 0x02;
public static final byte TLV_TAG_HW_USR = (byte) 0x03;
public static final byte TLV_TAG_HW_MEM_PERSIST = (byte) 0x04;
public static final byte TLV_TAG_HW_MEM_TEMP_RST = (byte) 0x41;
public static final byte TLV_TAG_HW_MEM_TEMP_DST = (byte) 0x42;
public static final byte TLV_TAG_HW_ID = (byte) 0x05;
public static final byte TLV_TAG_HW_ID_PUB = (byte) 0x51;
public static final byte TLV_TAG_HW_ID_ATTEST = (byte) 0x52;
public static final byte TLV_TAG_HW_SCP = (byte) 0x06;
public static final byte TLV_TAG_HW_BK = (byte) 0x07;
public static final byte TLV_TAG_HW_INTERACT = (byte) 0x08;
public static final byte TLV_TAG_HW_CRED_FORMAT = (byte) 0x09;
public static final byte TLV_TAG_AOC_CRED_ID = (byte) 0x0A;
public static final byte TLV_TAG_AOC_AUXDATA = (byte) 0x0B;
public static final byte TLV_OBJ_FIELD_ID = (byte) 0x08;
public static final byte TLV_OBJ_FIELD_HANDLE = (byte) 0x0E; <br> HW Info Format (sequence):

Tag	Value Length (bytes)	Data Type	Value	TLV Entry
Version	2	byte[]	0x0100	FALSE
TLV_TAG_HW_CAP // HW Secure Input Capability	4	int	0x00 - No capability (i.e. secure keypad)	TRUE
TLV_TAG_HW_USR // User	1	byte	0x01 - Card Admin User	TRUE
TLV_TAG_HW_SCP // Secure Channel	1	byte	0x0A03 - Proprietary ThothTrust A03 SCP protocol	TRUE
TLV_TAG_HW_BK // HW Partition Backup Capability	0	N/A	N/A	TRUE
TLV_TAG_HW_INTERACT // HW Interactive Capability	1	byte	0x01 - Screen available	TRUE
TLV_TAG_HW_CRED_FORMAT // Credential Secret Format	1	byte	CRED_AUTHTYPE_PIN (0x80). Use numerical PIN only.	TRUE
TLV_TAG_HW_MEM_PERSIST // Persistent Memory	4	int		TRUE
TLV_TAG_HW_MEM_TEMP_RST // Temporary Resettable Memory	4	int		TRUE
TLV_TAG_HW_MEM_TEMP_DST // Temporary Deselectable Memory	4	int		TRUE
TLV_TAG_HW_ID // Hardware ID	0	nested tlv	N/A	TRUE
TLV_TAG_HW_ID_PUB // Hardware Public Key	variable	byte[]	Raw 64 bytes X \|\| Y representation of non-exportable ECC-SECP256K1 public key for secure channel and other hardware related PKI security for T104 environment	TRUE

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization

List AOC Container Information

Retrieves a byte array list of AOC slots

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	B2	01	00	00	N/A	N/A

Response APDU:
Returns a byte array list of AOC slots. If the current byte us 00, it is available. If the current byte is 01, it is occupied. The returned length of the byte array list indicates the total available AOC container slots the T104 applet can provide.

An example is a 10 byte array return indicating a 10 slot capable AOC container storage as shown in the example below. Index #1 and #4 have 01 indicating slot 01 and slot 04 have AOC container occupied.

After requesting a list of AOC containers, it is highly advisable to follow up with a Get AOC Container Information method supplying the AOC container slot index to query more information about each AOC container slot.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization

Get AOC Container Information

Retrieves information of AOC Container from slot index.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	B2	02	00	01	Slot Index	N/A

Response APDU:
Extracts the publicly available AOC container information. Does not require AOC container registration and login to access.

AOC Container Information Format (sequence):

Tag	Value Length (bytes)	Data Type	Value	TLV Entry
TLV_TAG_AOC_CRED_ID // Registered AID	variable	byte[]	AID of registered applet to T104 AOC container	TRUE
TLV_TAG_AOC_AUXDATA // Auxilliary Data	variable	byte[]	0x30 - No E-Wallet access; 0x31 - Have E-Wallet access	TRUE

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6700	Wrong length. Only 1-byte sot index is needed.

Retrieves the number of login retries left for T104 Applet administrator role without needing to login into the administrator role.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	B2	04	01	00	N/A	01

Response APDU:
Get the number of login retries left for T104 Applet administrator role. If 0xFF is returned, incorrect P2 (incorrect role) was used in the query.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6FA1	Invalid user role in P2. P2 must be 0x01.

Get Card Timeout

Retrieves the card timeout status. T104 Applet administrator role login is not required.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	B2	05	00	00	N/A	02

Response APDU:
A 2-byte short returned on the card timeout status. If 0 is returned, the card never times out. Other return values indicate a positive short value of timeout time on the card.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6F20	Retrieving card timeout timer has error. This is an internal error.

Update AOC Container Information

Updates the AOC Container information. Currently only supports updating the access to E-Wallet function. T104 Administrator role login is required.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	D2	00	00	00	TLV request sequence	02

AOC Container Information Format (sequence):

Tag	Value Length (bytes)	Data Type	Value	TLV Entry
TLV_TAG_AOC_CRED_ID // Registered AID	variable	byte[]	AID of target registered applet to update information	TRUE
TLV_TAG_AOC_AUXDATA // Auxilliary Data	variable	byte[]	0x30 - Disable E-Wallet access; 0x31 - Enable E-Wallet access	TRUE

Response APDU:
No response content.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6FA1	T104 Administrator role has not been logged in.
0x6984	Invalid data format for payload.

Perform update of T104 Applet administrator role PIN. T104 Administrator role login is required. PIN must be more than or equals to 6 digits long.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	D2	01	00	PIN Length	PIN Code< in ASCIIfied numbers i.e. `0x313233343536` for numerical PIN of `123456`	N/A

Response APDU:
No response content.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6FA1	T104 Administrator role has not been logged in.
0x6985	Invalid data format for payload. New PIN must be 6 bytes or more.

Update T104 Applet Card Timeout Status

Perform update to card timeout timer status. T104 Administrator role login is required. If 0xFFFF is set for card timeout time, the card never times out. Otherwise, any card timeout time is in seconds. All card timeout time from 0x0000 (0 seconds) to 0x000A (10 seconds) automatically is forced into 0x000A (10 seconds) timeout time as the card has a minimum timeout time of 10 seconds and cannot be any lower than 10 seconds. The maximum timeout time is 0xFFFE (65534 seconds).

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	D2	02	00	02	Card timer timeout in short type</code>	N/A

Response APDU:
No response content.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6FA1	T104 Administrator role has not been logged in.
0x6700	Wrong length for card timeout timing. It needs to be 2-byte short.
0x6F20	Setting card timeout timer has error. This is an internal error.

Cleanup Orphaned AOC Containers

Cleanup orphaned AOC container slots. T104 Administrator role login is not required. Forces all AOC containers with non-existing applets on card to have their AOC container slots destroyed and freed.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	0E	00	00	00	N/A	N/A

Response APDU:
No response content.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6FA1	T104 Administrator role has not been logged in.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	82	00	00	PIN Length	PIN Code< in ASCIIfied numbers i.e. `0x313233343536` for numerical PIN of `123456`	N/A

Response APDU:
No response content.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6700	Wrong length for PIN. PIN must not be 0 or less bytes.
0x6982	Incorect PIN or blocked Administrator role. Unable to login.

WHOAMI

Checks the current logged in user(s) and statuses. T104 Administrator role login is not required.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	82	FF	00	00	N/A	N/A

Response APDU:
Return 0x01 to indicate T104 Applet administrator is logged in. Return 0x00 if no login has been done.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization

Open Secure Channel - A03

Opens a new Secure Channel session overriding any existing Secure Channel session. T104 Administrator role login is not required. Only 1 logical Secure Channel session is supported. An OTP Code is generated and displayed on E-Ink screen from the logical Secure Channel establishment and shown.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
88 (PLAIN)/ 84 (SECURE)	88	00	00	33	Uncompressed ASN.1 Host side ephemeral public key for SECP-256K1 (65 bytes)</code>	N/A

Response APDU:
No response content.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization
0x6700	Wrong length for Secure Channel Key Agreement. A 65-bytes ASN.1 encoded ECC-SECP256K1 public key has to be supplied.

Logout of T104 Applet Admin Role

Logout of T104 Applet administrator role but does not close Secure Channel. T104 Administrator role login is not required.

APDU Message Security:

Require Enveloping Message	Require Un-enveloping Mesage
TRUE	TRUE

Request APDU:

CLA	INS	P1	P2	LC	DATA	LE
84 (SECURE)	FE	00	00	00	N/A	N/A

Response APDU:
No response content.

Status Words:

SW	Description
0x9000	No error
0x6999	Internal state error due to failed aplet initialization

Other Status Words

Status Words:

SW	Description
0x6FCC	Secure Channel initialization is required. Open Secure Channel protocol must be called.
0x6FCD	Issues occured when trying to process secure messages. Ensure messages are enveloped correctly.
0x6FE2	T104 Applet encounters an error when trying to envelope a secure response.
0x6E00	Invalid CLA byte.
0x6D00	Invalid INS byte.
0x6D00	Invalid INS byte.
0x6A86	Invalid P1 and/or P2 byte.

Page Links

Product Overview MD WIKI
Basic User Manual MD WIKI
Developer Guide MD WIKI
Developer Samples Guide MD WIKI
JavaDoc API
T104 Applet APDU Guide MD WIKI

This site is open source. Improve this page.

T104-Devhub

T104 Applet APDU Guide

T104 Applet AID

T104 Secure Channel Protocol Key Agreement - A03

T104 Secure Channel Protocol Message Protection - A03

Enveloping a Message from Host to Applet

Un-enveloping a Message from Applet to Host

Management APDUs

Retrieving T104 Applet Information

List AOC Container Information

Get AOC Container Information

Get T104 Applet Admin Login Retries Information

Get Card Timeout

Update AOC Container Information

Update T104 Applet Admin Login PIN

Update T104 Applet Card Timeout Status

Cleanup Orphaned AOC Containers

Login to T104 Applet Admin Role

WHOAMI

Open Secure Channel - A03

Logout of T104 Applet Admin Role

Other Status Words

Page Links