L2 Protocol Layer

The L2 protocol layer handles low-level communication with the TROPIC01 chip, including CRC validation, encrypted sessions, and command/response framing.

L2 Protocol Layer for TROPIC01 Secure Element

This module implements the L2 (Link Layer) protocol for communication with the TROPIC01 chip. It handles low-level SPI communication, CRC validation, retry logic, and message framing.

The L2 layer is responsible for:

  • SPI bus communication and chip select management

  • Request/response framing and CRC validation

  • Chip status monitoring and retry logic

  • Encrypted command transmission

  • Session handshake protocol

The L2 layer does NOT handle:

  • Cryptographic operations (delegated to parent)

  • Command parsing/building (done by L3 layer)

  • Session state management (done by TropicSquare)

class tropicsquare.l2_protocol.L2Protocol(transport)[source]

Bases: object

L2 protocol layer implementation.

Provides low-level chip communication primitives for the TROPIC01 secure element. This class handles SPI communication, framing, CRC validation, and chip state management.

Parameters:

transport (L1Transport)

__init__(transport)[source]

Initialize L2 protocol layer.

Parameters:

transport (L1Transport) – Transport instance

Return type:

None

get_info_req(object_id, req_data_chunk=GET_INFO_DATA_CHUNK_0_127)[source]

Request information object from chip.

Sends GET_INFO request to retrieve chip information like certificate, chip ID, firmware version, etc.

Parameters:

  • object_id (int) – Information object type to retrieve

  • req_data_chunk (int) – Data chunk selector (for objects > 128 bytes)

Returns:

Raw information data

Return type:

bytes

Raises:

TropicSquareError – If chip status is not ready

handshake_req(ehpub, p_keyslot)[source]

Perform secure session handshake.

Sends ephemeral public key to chip and receives chip’s ephemeral public key and authentication tag.

Parameters:

  • ehpub (bytes) – Ephemeral public key (32 bytes)

  • p_keyslot (int) – Pairing key slot index (0-3)

Returns:

(chip_ephemeral_pubkey, chip_auth_tag)

Return type:

tuple

Raises:

TropicSquareError – If chip status is not ready

get_log()[source]

Retrieve firmware logs from chip.

Returns:

Raw log data

Return type:

bytes

Raises:

TropicSquareError – If chip status is not ready

encrypted_command(command_size, command_ciphertext, command_tag)[source]

Send encrypted L3 command to chip.

Handles chunking of large commands (> 128 bytes) and sends them to the chip. Returns encrypted response.

Parameters:

  • command_size (int) – Size of command ciphertext

  • command_ciphertext (bytes) – Encrypted command data

  • command_tag (bytes) – AES-GCM authentication tag (16 bytes)

Returns:

(response_ciphertext, response_tag)

Return type:

tuple

Raises:
encrypted_session_abt()[source]

Abort encrypted session.

Terminates the current secure session with the chip.

Returns:

True on success

Return type:

bool

Raises:

TropicSquareError – If chip status is not ready

sleep_req(sleep_mode)[source]

Put chip to sleep.

Parameters:

sleep_mode (int) – Sleep mode (SLEEP_MODE_SLEEP or SLEEP_MODE_DEEP_SLEEP)

Returns:

True on success

Return type:

bool

Raises:
startup_req(startup_id)[source]

Startup/reboot chip.

Parameters:

startup_id (int) – Startup mode (STARTUP_REBOOT or STARTUP_MAINTENANCE_REBOOT)

Returns:

True on success

Return type:

bool

Raises:

Protocol Overview

The L2 protocol provides:

  • CRC validation - Data integrity checking

  • Encrypted sessions - Secure communication using X25519 key exchange and AES-GCM

  • Command framing - Proper command structure and response parsing

  • Status handling - Chip status and error code processing

Session Management

Before executing L3 commands, a secure session must be established using the start_secure_session() method.

See Also