Introduction

The Change Pairing Key command allows you to update the shared secret, known as the 'pairing key', between the Cryptnox card and the host device. This pairing key is essential for establishing an authenticated secure channel, ensuring that communications between the card and the host remain encrypted and protected.

By updating the pairing key, you maintain the security and integrity of the communication channel between your Cryptnox card and the host device, safeguarding against unauthorized access.

What Is Pairing?

Pairing is a phase in Cryptnox card secret setup. Once the pairing is complete, all communications with the card can utilize the secure channel. The following steps are necessary to complete pairing:

• After initialization, the card and the host must establish a shared secret (the pairing key) to enable an authenticated secure channel. This shared secret is necessary for all future communication with the card via the secure channel. The initial registration of the pairing key occurs during the init phase.
• The card has one Pairing Key slot. You have the option to rely on a common public PairingKey, using only a PIN for authentication. Alternatively, you must securely store your pairing key. If a client communicates with multiple cards, the pairing key should be associated with the card's unique serial number (SN) to ensure proper management and usage of the correct pairing key with each card.

📘

Note

Once the pairing phase is complete, all communications with the card can utilize the secure channel. This secure channel provides encrypted and two-way authenticated communication through standard Application Protocol Data Unit (APDU) messages. Many applet commands require the use of this secure channel.

Changing The Pairing Key

If you lose the pairing information, then you can derive a replacement pairing key by applying SHA-256 hashing to the PUK, 32 times. This derived key, referred to as the pairing key with key index 0xFF (or -1), can always be used to establish a secure channel.

For more details, refer to the CHANGE PAIRING KEY command section below.

Command specifications

Change Pairing Key Command

The Change Pairing Key command is used to update the shared secret (pairing key) between the card and the host. This pairing key is essential for establishing and maintaining a secure, authenticated communication channel.

The following code snippet outlines the Python object for this command:

def change_pairing_key(index: int, pairing_key: bytes, puk: str):
    card.change_pairing_key(index, pairing_key, puk)

For example, change_pairing_key(1, b'new_pairing_key', "puk_code").

Application Protocol Data Unit (APDU) Components

The following table outlines the components of the Application Protocol Data Unit (APDU).

📘

Prerequisites:

• The secure channel must be open and the paring key for the secure channel must be up-to-date.
• If you lose the pairing key, then it will prevent you from opening any secure channel that is required to change the pairing key. In such case, use the PUK derived key as the pairing key (key index 0xFF). You cannot change the PUK pairing slot altogether, but it is updated when the PUK is changed.

Response

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