Add User Key
The Add User Key command allows you to store a user’s public key in a designated slot on the card. This key can be used for authentication instead of a PIN, enabling secure access and transactions. This command:
- Saves a user’s public key in one of three available slots.
- Supports EC256r1 (Elliptic Curve) and RSA 2048-bit public keys.
- Each slot can store an optional 64-byte description for identification.
- A FIDO key with a credential ID can be stored in slot 3.
- Requires a PUK (Personal Unlock Key) for security.
- Once a key is stored, it must be deleted before a new one can be added.
- Enables user authentication for signing transactions and replacing PIN entry.
This command enhances security by allowing authentication through cryptographic keys instead of traditional PINs.
Command specifications
Add User Key
The Add User Key command allows you to store a user’s public key in a specific slot on the card. Once stored, this public key can be used for authentication purposes, providing an alternative to traditional PIN-based verification. This enables a more secure and seamless way to authorize access or perform sensitive transactions.
The following code snippet demonstrates the structure of the Python object used to issue this command:
def add_user_key(slot_index: SlotIndex, data_info: str, public_key: bytes, puk: str, cred_id: bytes):
card.user_key_add(slot_index, data_info, public_key, puk, cred_id)
For example, add_user_key(SlotIndex.SLOT_1, “data_info”, b’public_key’, “puk_code”, b’cred_id’).
Application Protocol Data Unit (APDU) Components
The following table outlines the components of the Application Protocol Data Unit (APDU).
Field | Description | Value |
CLA | This field specifies the class of the instruction. | 0x80 |
INS | This field specifies the particular command or operation that the smart card or secure element should execute. | 0xD5 |
P1 | First parameter of the instruction that specifies the details about the operation being requested. | 0x00 |
Data | Key data | Slotindex (1-3)
|
📘 Prerequisites
- The secure channel must be open.
- Save the user public key in the corresponding slot index.
Response
The following table outlines the possible responses that you will receive:
Response Code | Description |
0x9000 | Success |
0x6A80 | The slot index is valid. |
0x6700 | Incorrect length. |
0x6985 | Pin not provided. |
0x6984 | Invalid public key. |
0x6986 | The key is already present in the key slot. |
Additional Information
Public Key Description & Storage
Each stored public key can have a 64-byte description that helps in identifying the key more easily. This description can include labels or short identifiers, but it must always be exactly 64 bytes in length. To retrieve the stored description, you can use the ReadDataInfo (0xFA) command along with the relevant slot index (1–3). This makes it simple to access key-related information when needed.
Public Key Slot Details
- Slot 1: Stores an EC 256r1 public key in X9.62 uncompressed format (65 bytes: x04 | X | Y).
- Slot 2: Stores an RSA 2048-bit public key. Only the modulus (256 bytes, big-endian) is saved. The public exponent is always 65537 and is not stored.
- Slot 3 (FIDO Key): Used for FIDO authentication. Stores a public key with its credential ID. Data format:
- Slot number (3)
- 64-byte description
- Credential ID length (1 byte)
- Credential ID (up to 64 bytes)
- EC 256r1 public key (65 bytes, X9.62 uncompressed format)
- PUK (Personal Unlock Key)
Key Management
- Once a user key is stored, it must be deleted using the Delete User Key command before adding a new one.
- Stored user keys can be used to authenticate SIGN commands or replace PIN entry for authentication.
- When uploading an RSA key or verifying an RSA signature, extended frame format headers are used to handle data larger than 256 bytes.
- Currently, EC public keys are not validated when stored on the card.