Nitrokey 3 Firmware

The utils/test-certificates directory contains test certificates and keys used for simulating or testing Nitrokey 3 applications. These are categorized by their purpose (Root CA, FIDO, or Firmware signing) and provided in multiple formats (DER, PEM, and Trussed-compatible).

Certificate Categories

• Root CA: The Nitrokey 3 root CA (root).
• FIDO Authenticator: Intermediate CA and End Entity (EE) certificates for the fido-authenticator application (fido).
• LPC55 Firmware: Firmware signature keys for the LPC55 platform (firmware-lpc55), including one EE certificate signed by a root certificate and three standalone EE certificates.
• NRF52 Firmware: Firmware signature keys for the NRF52 platform (firmware-nrf52).

The fido-authenticator application relies on the internal filesystem for its operational state and security credentials:

• State, KEK, and Resident Keys: All stored on the internal filesystem.
• Provisioning Data: The FIDO2 attestation key and certificate are stored on the internal filesystem during provisioning.
• KEK Generation: The Key Encryption Key (KEK) is generated upon first use.

Critical Note: There must be sufficient free space on the internal filesystem to generate the KEK. If space is insufficient, the application cannot be used.

The Trussed application utilizes the internal filesystem for the following:

• RNG State: Stored via ServiceResources::rng.
• Provisioning Data: The Trussed device key and certificate are generated and stored on the internal filesystem during the provisioning process.

Nitrokey 3 utilizes three distinct storage types:

1. Internal Storage: Uses on-chip flash memory. The available size depends on the hardware variant:
   • lpc55: 42 KiB
   • nrf52: 80 KiB
2. External Storage: Uses a separate flash chip. While the chip capacity is 2 MiB, only 1920 KiB is available for littlefs2 usage, as the final 128 KiB is reserved for future use cases.
3. Volatile Storage: Uses RAM.

To build the Nitrokey 3 firmware, ensure you have the following dependencies installed on your development system:

• Rust: The current stable release must include the thumbv8m.main-none-eabi target and the llvm-tools-preview component.
• Clang: Must be installed with development headers.
• flip-link: A linker wrapper for stack overflow protection.
• cargo-binutils: A collection of utilities for working with Rust binaries.

To flash the compiled firmware onto a Nitrokey 3 device, you must use one of the following tools:

• mboot (pyMBoot)
• lpc55 (lpc55-host)

To execute a complete deployment cycle (building all components, flashing the bootloader, flashing the provisioner, provisioning keys, flashing the firmware, and running the full deployment sequence), follow these steps:

1. Build all artifacts: make build
2. Flash bootloader: make flash-bootloader
3. Flash provisioner: make flash-provisioner
4. Provision keys: make provision-keys
5. Flash firmware: make flash-firmware
6. Run full deploy: make full-deploy

The SSH tests suite validates the interaction between a FIDO2 device and an OpenSSH server. It performs the following tasks:

• Runs a preconfigured OpenSSH server based on Debian via Docker.
• Generates FIDO2 device-based OpenSSH keys for multiple algorithms (ed25519-sk, ecdsa-sk) and storage types (resident and non-resident).
• Executes connection tests using the generated FIDO2 device.

Use the following Makefile commands to manage the test lifecycle.

# Build the test environment
make build

# Run the SSH authentication tests
make test

# Clean up: remove generated keys and built images
make clean

To release a test version, create a signed Git tag using the following naming pattern: v<major>.<minor>.<patch>-test.<yyyy><mm><dd>.

Example: v1.5.0-test.20231106.

Documentation is split into two categories:

• User Documentation: For general usage and instructions, visit the Nitrokey 3 section on docs.nitrokey.com.
• Developer Documentation: For technical details regarding the firmware implementation, refer to the ./docs directory within this repository.

To view real-time RTT (Real Time Transfer) logs, follow these steps in separate terminal windows:

1. Flash the device using the nrf-builder: make -C ../nrf-builder flash-develop.
2. In the first terminal, connect to the debugger: make ocd.
3. In a second terminal, view the RTT outputs: make rtt.

# Terminal 1: Flash and connect
make -C ../nrf-builder flash-develop
make ocd

# Terminal 2: Show outputs
make rtt