Skip to content

Latest commit

 

History

History
521 lines (444 loc) · 9.1 KB

APDU Commands for KeyManager.md

File metadata and controls

521 lines (444 loc) · 9.1 KB
Raw

APDU Commands for KeyManager

The applet AID for the KeyManager is 4B4D313031 for acquiring basic data from KeyManager and to securely set your RTC clock on the KeyManager.

Query KeyManager Public Key

CLA INS P1 P2 LC DATA LE
B0 FF 00 C0 00 N/A 33

Return: Unique ECC-P256K1 public key for KeyManager's Identity Key.

Query KeyManager General State Information

CLA INS P1 P2 LC DATA LE
B0 FF 00 C0 00 N/A 09

Return: Current KeyManager provisioning state, available persistent memory, available transient memory (RESET type).

Prov State Memory (Persist) Memory (Trans)
1 byte. 4 bytes. 32-bit Integer representation. 4 bytes. 32-bit Integer representation.

Note: Provisioning state should be in FF otherwise the card is unusable.

Query Root Authorization Serial Number

CLA INS P1 P2 LC DATA LE
B0 FF 00 00 00 N/A 08

Return: Root Authority's Serial Number used for Trustchain attestation.

Query Root Authorization Creation Timestamp

CLA INS P1 P2 LC DATA LE
B0 FF 00 01 00 N/A 04

Return: Root Authority's creation timestamp used for Trustchain attestation.

Query Root Authorization Object ID

CLA INS P1 P2 LC DATA LE
B0 FF 00 02 00 N/A 20

Return: Root Authority'sObject ID used for Trustchain attestation.

Query Intermediate Authorization Serial Number

CLA INS P1 P2 LC DATA LE
B0 FF 00 03 00 N/A 08

Return: Intermediate Authority's Serial Number used for Trustchain attestation.

Query Intermediate Authorization Creation Timestamp

CLA INS P1 P2 LC DATA LE
B0 FF 00 04 00 N/A 04

Return: Intermediate Authority's creation timestamp used for Trustchain attestation.

Query Intermediate Authorization Object ID

CLA INS P1 P2 LC DATA LE
B0 FF 00 05 00 N/A 20

Return: Intermediate Authority's Object ID used for Trustchain attestation.

Query KeyManager Authorization Serial Number

CLA INS P1 P2 LC DATA LE
B0 FF 00 06 00 N/A 08

Return: KeyManager's Serial Number used for Trustchain attestation.

Query KeyManager Creation Timestamp

CLA INS P1 P2 LC DATA LE
B0 FF 00 07 00 N/A 04

Return: KeyManager's creation timestamp used for Trustchain attestation.

Query KeyManager Object ID

CLA INS P1 P2 LC DATA LE
B0 FF 00 08 00 N/A 20

Return: KeyManager's Serial Number used for Trustchain attestation. Used on the Front Panel mode to double check the ID displayed.

Query Current Device RTC Time

CLA INS P1 P2 LC DATA LE
B0 FF 00 09 00 N/A 04

Return: Current device RTC time.

Query TrustChain Certificate Chain Length

CLA INS P1 P2 LC DATA LE
B0 FF 01 00 00 N/A 02

Return: Two byte short representation of the length of the Trustchain certificate chain loaded in the KeyManager. Trustchain chains from Root Authority to Intermediate Authority to KeyManager level chaining.

Segmented Reading of Trustchain Data

CLA INS P1 P2 LC DATA LE
B0 FF 02 00 04 2 byte short representation offset to read followed by 2 byte short representation length to read. FF

Return: Trustchain data in segments.

Set Time Key

CLA INS P1 P2 LC DATA LE
B0 04 00 00 20 new Time Key bytes - 256 bits long. 00

Return: Set new Time Key. Can only be done if the device is in 'Factory' mode.

Set Time

  1. Query for random challenge nonce (8 bytes) before setting time.

    CLA INS P1 P2 LC DATA LE
    B0 03 00 00 00 N/A 08

    Return: First step retrieving time setting challenge will return 8 bytes of nonce.

  2. Format payload

    Header Nonce Timestamp (UNIX)
    3 bytes. Use bytes `010001` 8 bytes. 4 bytes.

    The header 010001 with the first two bytes 0100 represents version 1 of the time setting protocol. The last 01 represents option 1. Option 1 uses a clear channel with HMAC-SHA256 signing. Currently only Option 1 setting method is available. Introduction of other methods maybe intorudced in later times when necessary.

  3. Sign payload with Time Key

    Sign the above payload with HMAC-SHA256 using a Time Key you set and append the 32 byte output from the MAC to the end of the above payload. Your payload should now look like this:

    Header Nonce Timestamp (UNIX) MAC
    3 bytes. Use bytes `010001` 8 bytes. 4 bytes. 32 bytes.

  4. Send payload to device

    Use the same APDU as Step 1 but now adjust it to have the payload data.

    CLA INS P1 P2 LC DATA LE
    B0 03 00 00 2F Signed Payload 00

    Return: It should return 9000 to indicate successful setting of new RTC time. If it returns 6984, either the length or format is invalid (which may include incorrect header) or the signature is signed incorrectly (i.e. using wrong Time Key or bad formatting). You should query the device RTC time to confirm that the new time has been set correctly.

Cleanup Global/Applet Object Containers

CLA INS P1 P2 LC DATA LE
B0 FF 0F FF for Global Users, otherwise default to AOC Containers 00 N/A 00

Description: If the command is used with P2 set to FF for Global Users, any Global Object Containers with its Global User credential either already expired or the PIN/Password retry have exceed the maximum retry threshold would automatically be destroyed to free Global Object Container slots. Destruction includes the destroying of the particular Global Object Container meeting the above criterias (including the data objects in the Global Object Container) and deleting all membership of the particular Global User from all existing AOC Conrainer. If the command is used with any byte on P2 except FF, the cleanup would be targetted on all AOC containers that have their registered JavaCard applet not accessible by the JavaCard Virtual Machine (due to the applet already deleted from the card but failure to cleanly delete the corresponding AOC container).

Return: 9000 should always be returned.