Seed Administration
Introduction
Note
It is not possible to erase or change the seed or master key once it is generated for a card. Although, you can reset it using the PUK.
Seed Generation
- Single generation method: This is the simple way of key generation, where the backup for the generated key isn’t available later. You can also generate the seed on your local machine, using the card’s random entropy. Then you can upload this Seed Administration in the card using the Load Key Command.
- Dual generation method: This method allows you to cross-generate keys between 2 cards which share a common seed. Simply put, one card becomes the backup of the other card. This method provides a backup of the seed as the cards share some public information to agree on a common Seed Administration. Each card generates a part of the secret that is used in combination with the other. This caters for additional security as it is not possible for a third party to read the seed. Furthermore, this method also provides a backup option, as the 2 cards become identical after a dual generation initialization. For more details, refer to the Load Key Command topic on this page.Â
The card can also deliver random data as output. However, only this output data is not used internally by the card. It also uses the data that you upload using the Load Key Command. You are required upload the Seed Administration to the card, using the Load Key Command, that you computed with the mnemonic derived using the Generate Random Command. You are required to do this when you generate the mnemonic from the secure random generator of the card, before it is shown to the user to copy it on the paper.
Seed Administration Recovery
You can recover the seed if you had previously opted for the dual key generation method. The javacard applet can load binary seed or an EC key pair on the card. Once this seed administrationis loaded on the cards, either of the cards behaves like a backup of the other. It is important to note that that key derivation paths are not backups, and these paths must be identical to retrieve the same key pairs. For more details about the recovery command, refer to the Load Key Command below.
Refer to the Derive Key section for more details.
Command Specifications
Load Key Command
The Load Key command in Cryptnox is used to securely load a cryptographic key into the device’s secure element. This operation is essential for initializing, updating, or configuring the device with cryptographic material needed for its operations.
Once you are done running this command, the 2 cards will have a common seed, SHA256( ECDH). As a result, one card becomes a backup of the other. The common seed can be checked by deriving a path and reading the matching blockchain public keys of the cards.
The computer facilitating the transfer or exchange cannot compute the Seed Administration because it is protected using Elliptic Curve Diffie-Hellman (ECDH). Additionally, the computer cannot participate in the key exchange since this process requires a signature generated with a secret key stored exclusively within the paired cards’ secure elements, which cannot be extracted.
The following code snippet represents this command in the relevant language set:
Note
Python:
- The load_seed method allows you to load a 32-byte seed into the card, enabling key derivation and cryptographic operations.
- Make sure that the cryptnoxpy library is installed in your Python environment. You can find more details and documentation in the [Cryptnoxpy GitHub repository](cryptnoxpy GitHub repository).
from cryptnoxpy import Card
# Initialize the card
card = Card()
# Define your 32-byte seed and PIN
seed = bytes.fromhex('your_32_byte_seed_in_hex')
pin = 'your_pin'
# Load the seed into the card
card.load_seed(seed, pin)In the above example,
- Replace ‘your_32_byte_seed_in_hex’ with your actual 32-byte seed in hexadecimal format.
- Replace ‘your_pin’ with your card’s PIN.
Application Protocol Data Unit (APDU) Components
The following table outlines the components of the Application Protocol Data Unit (APDU).
Note
- Secure channel must be open.
- PIN or challenge-response must be validated.
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. | 0xD0 This value writes the binary data to a file. |
P1 | First parameter of the instruction that specifies the details about the operation being requested. |
|
P2 | First parameter of the instruction that specifies additional details about the operation being requested. | 0x00 |
Data | Key data | PIN (if no user auth, 9 bytes padded). Refer to the ‘Data Values’ table below for more conditions around this field. |
Condition | Data Value | Additional Details |
|---|---|---|
P1 is 0x01 or 0x02 |
| The key source is set to:
|
P1 is 0x03 | A 16 to 64 byte seed seed administration byte sequence generated according to the BIP39 specifications. | The master key node pairs will be computed according to the SLIP10 standard and will be compatible with the BIP32 specification. One master key is computed for k1 curve and r1 curve each. The key source is set to ‘L’ using this command with P1=3. |
P1 is 0x04 | The cards initializes the dual generation seed mode and sends back a public key to be used for the other card as the public counterpart. This public key is provided with an ECDSA signature with the basic group key. | No action around the key and seed loading is taken at this stage. The card only generates and sends a signed public key for the dual EC seed generation mode.
|
P1 is 0x05 |
|
|
Response Code | Description |
|---|---|
0x9000 | Success |
0x63CX | PIN is not valid. |
0x6A80 |
|
0x6A86 | P1 is invalid. |
0x6986 | A key/seed administration is already loaded. We recommend performing a reset if you receive this response. |
Note
- You cannot erase the current wallet seed key. You can only reset it with the PUK. The Load Key command can be performed only once after a card reset.
- The Load Key command validates the pin after a successful loading. You are not required to re-verify the pin during an active session.
Generate Key Command
The Generate Key command is used to create cryptographic key pairs within the Cryptnox smart card, ensuring that private keys are generated and stored securely without ever leaving the card. This process is fundamental for various security applications, including SSH authentication and hardware wallet functionalities.
The following code snippet outlines the Python object for this command:
def generate_seed(pin: str) -> bytes:
# Generate new seed on the card
card.generate_seed(pin)For example, generate_seed administration(“1234”).
Application Protocol Data Unit (APDU) Components
The following table outlines the components of the Application Protocol Data Unit (APDU).
Prerequisites
- Secure channel must be open.
- The user PIN must be provided if no the user keys were not authenticated.
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. | 0xD4 |
P1 | First parameter of the instruction that specifies the details about the operation being requested. | 0x00 |
P2 | First parameter of the instruction that specifies additional details about the operation being requested. | 0x00 |
Data | Key data | PIN (if no user auth, 9 bytes 0x00 right-padded). Refer to the ‘Data Values’ table below for more conditions around this field. |
Response
The following table outlines the possible responses that you will receive:
| Response Code | Description |
|---|---|
| 0x9000 | Success |
| 0x63CX | PIN is not valid. |
| 0x6986 | A key/seed administration is already loaded. We recommend performing a reset if you receive this response. |
Note
- You cannot erase the current wallet seed key. You can only reset it with the PUK. The Load Key command can be performed only once after a card reset.
- This command validates the pin after a successful loading. You are not required to re-verify the pin during an active session.
- The state of the card after execution is the same as if a Load Key command had been performed. The key source is set to ‘S’ using this command.
Generate Random Command
The Generate Random command is used to produce true random numbers directly from the card’s hardware-based True Random Number Generator (TRNG). These numbers are highly unpredictable, as they are derived from physical processes within the hardware. Such randomness is essential for cryptographic operations like key generation and secure communications.
By using this command, Cryptnox ensures that all random numbers used in its cryptographic processes are grounded in true physical randomness, significantly enhancing security and operational integrity in line with modern cryptographic standards.
The following code snippet outlines the Python object for this command:
def generate_seed(pin: str) -> bytes:
# Generate random seed on the card
random_bytes = card.generate_random(16) Note
This command is only an output to use the chip's secure random number generator. This can be used to generate a mnemonic in the host machine from confident random source. It does not change any state in the card.
Application Protocol Data Unit (APDU) Components
The following table outlines the components of the Application Protocol Data Unit (APDU).
Prerequisites
- Secure channel must be open as it is used to generate some random data, from the chip's internal True Random Number Generator (TRNG).
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. | 0xD3 |
P1 | First parameter of the instruction that specifies the details about the operation being requested. | Random output in bytes (size between 16 and 64 bytes, and should be a multiple of 4). For example, 16, 20, 24, and so on, up to 64. |
P2 | First parameter of the instruction that specifies additional details about the operation being requested. | 0x00 |
Response
The following table outlines the possible responses that you will receive:
| Response | Description |
|---|---|
| 0x9000 | Success |
| 0x6A86 | P1 is not valid. |
| Response data | Raw data. |
- Updated 5 months ago