Introduction

The Seed Administration applet is used to manage a 256 bits master secret called seed, with the BIP32 standard. This seed can be externally computed from a mnemonic using BIP39 implementation design. The key pairs used for the Elliptic Curve Digital Signature Algorithm (ECDSA) are then derived from this seed using SLIP10/BIP32 derivation scheme.

📘

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

You can generate the master seed or key for the card using the random number generator in the chip system from AIS 20 class DRG.3. You can generate a key using the Generate Key Command_ in the following two ways:

• 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 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. 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 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 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 is 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 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).

📘

Prerequisites:

• Secure channel must be open.
• PIN or challenge-response must be validated.

Data Values

The following table outlines the values for the Data field within the ADPU components based on some conditions:

Response

The following table outlines the possible responses that you will receive:

📘

Notes

• 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("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.

Response

The following table outlines the possible responses that you will receive:

📘

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). This ensures that the generated numbers are highly unpredictable, as they are derived from inherent physical processes within the hardware. Such randomness is crucial for cryptographic operations, including key generation and secure communications.

Using this command, we ensure that the random numbers used in its cryptographic processes are rooted in true physical randomness, enhancing the security and integrity of its operations.

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).

Response

The following table outlines the possible responses that you will receive: