From 9dbd764c8c366b5a6cd782f6e643415af3245822 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Sat, 13 Dec 2025 21:12:45 +0100 Subject: [PATCH 01/11] Reset by recopying memory file. Signed-off-by: Pol Henarejos --- tests/scripts/func.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/scripts/func.sh b/tests/scripts/func.sh index e081224..b9764ea 100755 --- a/tests/scripts/func.sh +++ b/tests/scripts/func.sh @@ -37,7 +37,9 @@ gen_and_delete() { test $? -eq 0 && echo -n "." || exit $? } reset() { - python3 tools/pico-hsm-tool.py --pin 648219 initialize --so-pin 57621880 --silent --no-dev-cert > /dev/null 2>&1 + #python3 tools/pico-hsm-tool.py --pin 648219 initialize --so-pin 57621880 --silent --no-dev-cert > /dev/null 2>&1 + rm -f memory.flash + tar -xf tests/memory.tar.gz test $? -eq 0 || exit $? } From 710eb70af7e8d74dde1f59b5e891dbb340faa376 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Sat, 13 Dec 2025 23:36:43 +0100 Subject: [PATCH 02/11] Update reamde & usage. Signed-off-by: Pol Henarejos --- README.md | 10 ++-------- doc/usage.md | 4 ++-- 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3acccca..18b80c8 100644 --- a/README.md +++ b/README.md @@ -162,10 +162,10 @@ Secure Lock restricts the device to the manufacturer’s firmware only, locking Pico HSM also supports ESP32-S3 boards, which add secure storage, flash encryption and secure boot. ### > Dynamic VID/PID -Supports setting VID & PID on-the-fly. Use `pico-hsm-tool.py` or [Pico Commissioner](https://www.picokeys.com/pico-commissioner/ "Pico Commissioner") for specify VID/PID values and reboot the device. +Supports setting VID & PID on-the-fly. U ### > Rescue Pico HSM Tool and Commissioner -Pico HSM Tool implements a new CCID stack to rescue the Pico HSM in case it has wrong VID/PID values and it is not recognized by the OS. It can be accessed through `pico-hsm-tool.py` or [Pico Commissioner](https://www.picokeys.com/pico-commissioner/ "Pico Commissioner"). +Pico HSM Tool implements a new CCID stack to rescue the Pico HSM in case it has wrong VID/PID values and it is not recognized by the OS. ## Security considerations All secret keys (both asymmetric and symmetric) are encrypted and stored in the flash memory. The MKEK, a 256-bit AES key, is used to protect these private and secret keys. Keys are held in RAM only during signature and decryption operations, and are loaded and cleared each time to avoid potential security vulnerabilities. @@ -345,12 +345,6 @@ Communication with the Pico HSM follows the same protocols and methods used with For advanced usage scenarios, refer to the documentation and examples provided. Additionally, the Pico HSM supports the SCS3 tool for more sophisticated operations and includes features like multiple key domains. For detailed information on SCS3 usage, refer to [SCS3 documentation](/doc/scs3.md). -### Important -OpenSC relies on PCSC driver, which reads a list (`Info.plist`) that contains a pair of VID/PID of supported readers. In order to be detectable, you have several options: -- Use `pico-hsm-tool.py` to modify VID/PID on-the-fly. -- Use the pure-browser online [Pico Commissioner](https://www.picokeys.com/pico-commissioner/ "Pico Commissioner") that commissions the Pico Key on-the-fly without external tools. -- Build and configure the project with the proper VID/PID with `USB_VID` and `USB_PID` parameters in `CMake` (see [Build section](#build "Build section")). Note that you cannot distribute the patched/compiled binary if you do not own the VID/PID or have an explicit authorization. - ## License and Commercial Use This project is available under two editions: diff --git a/doc/usage.md b/doc/usage.md index 49cb297..1ed2d85 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -28,9 +28,9 @@ PIN=648219 [^1]: `openssl version -a` will return the `OPENSSLDIR`, which contains `openssl.cnf` file and `ENGINESDIR`, which contains the p11 engine. ## Initialization -The first step is to initialize the HSM. To do so, use the `pico-hsm-tool.py` in `tools` folder: +The first step is to initialize the HSM. To do so, use: ``` -$ python3 tools/pico-hsm-tool.py --pin 648219 initialize --so-pin 57621880 +$ sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 ``` The PIN number is used to manage all private keys in the device. It supports three attemps. After the third PIN failure, it gets blocked. The PIN accepts from 6 to 16 characters. From e41f2ba7122502737c1b8d0a727b24e545d4203d Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Fri, 26 Dec 2025 19:54:15 +0100 Subject: [PATCH 03/11] Releaser is available up to 6.7.0 Signed-off-by: Pol Henarejos --- .github/workflows/nightly.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 3c60421..fcf7dd9 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -34,7 +34,7 @@ jobs: - name: Delete private key run: rm private.pem - name: Update nightly release - uses: pyTooling/Actions/releaser@main + uses: pyTooling/Actions/releaser@v6.7.0 with: tag: nightly-${{ matrix.refs }} rm: true From 97e73035052f68f36af4977bf841e0dfc836d719 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Fri, 26 Dec 2025 20:00:59 +0100 Subject: [PATCH 04/11] Move pointer Signed-off-by: Pol Henarejos --- pico-keys-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pico-keys-sdk b/pico-keys-sdk index 05fe059..7dc7be0 160000 --- a/pico-keys-sdk +++ b/pico-keys-sdk @@ -1 +1 @@ -Subproject commit 05fe0596ef004313e166b1e2f900e9af351dd26c +Subproject commit 7dc7be090919e7638616e93f21ff4c10c1373dec From d3a7ff425a09e5118dca668e8c9ba622f3b10523 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Sat, 27 Dec 2025 22:03:47 +0100 Subject: [PATCH 05/11] Fix pimoroni led Signed-off-by: Pol Henarejos --- pico-keys-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pico-keys-sdk b/pico-keys-sdk index 7dc7be0..4df6160 160000 --- a/pico-keys-sdk +++ b/pico-keys-sdk @@ -1 +1 @@ -Subproject commit 7dc7be090919e7638616e93f21ff4c10c1373dec +Subproject commit 4df616082ece2683d0a55745e2f69727072b6385 From 7d551f6feac56273283c3f0bff769c6f5a9c5b6e Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Mon, 29 Dec 2025 20:17:03 +0100 Subject: [PATCH 06/11] Blink led three times to acknowledge proper commissioning. Signed-off-by: Pol Henarejos --- pico-keys-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pico-keys-sdk b/pico-keys-sdk index 4df6160..6305ea1 160000 --- a/pico-keys-sdk +++ b/pico-keys-sdk @@ -1 +1 @@ -Subproject commit 4df616082ece2683d0a55745e2f69727072b6385 +Subproject commit 6305ea11abe6f6e2c42b72c4305bd14af6855ba9 From 6914be4fea41b153540f8e49b772b89bcfa1d798 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Mon, 29 Dec 2025 20:36:55 +0100 Subject: [PATCH 07/11] Fix build. Signed-off-by: Pol Henarejos --- pico-keys-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pico-keys-sdk b/pico-keys-sdk index 6305ea1..7e6e3c8 160000 --- a/pico-keys-sdk +++ b/pico-keys-sdk @@ -1 +1 @@ -Subproject commit 6305ea11abe6f6e2c42b72c4305bd14af6855ba9 +Subproject commit 7e6e3c8f3c7d4f7e9aa5f7f94de4a3560fbf59cb From 3207fe3451a6da0f42be5f8dd4c6661c4c1c8b40 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Mon, 5 Jan 2026 19:40:50 +0100 Subject: [PATCH 08/11] Disable button press by default since LED may not be properly configured until it is commissioned. Signed-off-by: Pol Henarejos --- pico-keys-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pico-keys-sdk b/pico-keys-sdk index 7e6e3c8..7de9855 160000 --- a/pico-keys-sdk +++ b/pico-keys-sdk @@ -1 +1 @@ -Subproject commit 7e6e3c8f3c7d4f7e9aa5f7f94de4a3560fbf59cb +Subproject commit 7de98552d1003de077fde1e644cd610c0b95b614 From 60dafec2e85536ebbb233934d8b88d475db8e3fb Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Mon, 5 Jan 2026 19:51:51 +0100 Subject: [PATCH 09/11] Upgrade Pico Keys SDK to v8.2 Signed-off-by: Pol Henarejos --- pico-keys-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pico-keys-sdk b/pico-keys-sdk index 7de9855..263e554 160000 --- a/pico-keys-sdk +++ b/pico-keys-sdk @@ -1 +1 @@ -Subproject commit 7de98552d1003de077fde1e644cd610c0b95b614 +Subproject commit 263e554cc6c59a5f168f8589c4bdabe6e1e64c25 From 380ff7afa45d04f70187c43e2364f07a92dad020 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Mon, 5 Jan 2026 19:54:07 +0100 Subject: [PATCH 10/11] Upgrade to v6.2 Signed-off-by: Pol Henarejos --- build_pico_hsm.sh | 2 +- src/hsm/version.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/build_pico_hsm.sh b/build_pico_hsm.sh index c139980..98d0dd3 100755 --- a/build_pico_hsm.sh +++ b/build_pico_hsm.sh @@ -1,7 +1,7 @@ #!/bin/bash VERSION_MAJOR="6" -VERSION_MINOR="0" +VERSION_MINOR="2" SUFFIX="${VERSION_MAJOR}.${VERSION_MINOR}" #if ! [[ -z "${GITHUB_SHA}" ]]; then # SUFFIX="${SUFFIX}.${GITHUB_SHA}" diff --git a/src/hsm/version.h b/src/hsm/version.h index 880a245..a55ec03 100644 --- a/src/hsm/version.h +++ b/src/hsm/version.h @@ -18,7 +18,7 @@ #ifndef __VERSION_H_ #define __VERSION_H_ -#define HSM_VERSION 0x0600 +#define HSM_VERSION 0x0602 #define HSM_VERSION_MAJOR ((HSM_VERSION >> 8) & 0xff) #define HSM_VERSION_MINOR (HSM_VERSION & 0xff) From 16d4d0d26ef5470d5c7159ec5060cd0d199a4ea3 Mon Sep 17 00:00:00 2001 From: Pol Henarejos Date: Tue, 6 Jan 2026 21:20:13 +0100 Subject: [PATCH 11/11] Update README with up-to-date info. Signed-off-by: Pol Henarejos --- README.md | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 18b80c8..b41c1ab 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ Pico HSM also supports ESP32-S3 boards, which add secure storage, flash encrypti ### > Dynamic VID/PID Supports setting VID & PID on-the-fly. U -### > Rescue Pico HSM Tool and Commissioner +### > Rescue Pico HSM Pico HSM Tool implements a new CCID stack to rescue the Pico HSM in case it has wrong VID/PID values and it is not recognized by the OS. ## Security considerations @@ -179,26 +179,16 @@ In the event that the Pico is stolen, the private and secret key contents cannot ### RP2350 and ESP32-S3 RP2350 and ESP32-S3 microcontrollers are equipped with advanced security features, including Secure Boot and Secure Lock, ensuring that firmware integrity and authenticity are tightly controlled. Both devices support the storage of the Master Key Encryption Key (MKEK) in an OTP (One-Time Programmable) memory region, making it permanently inaccessible for external access or tampering. This secure, non-volatile region guarantees that critical security keys are embedded into the hardware, preventing unauthorized access and supporting robust defenses against code injection or firmware modification. Together, Secure Boot and Secure Lock enforce firmware authentication, while the MKEK in OTP memory solidifies the foundation for secure operations. -### Secure Boot -Secure Boot is a security feature that ensures that only trusted firmware, verified through digital signatures, can be loaded onto the device during the boot process. Once enabled, Secure Boot checks every piece of firmware against a cryptographic signature before execution, rejecting any unauthorized or modified code. This prevents malicious firmware from compromising the device’s operation and integrity. With Secure Boot activated, only firmware versions signed by a trusted authority, such as the device manufacturer, will be accepted, ensuring the device remains protected from unauthorized software modifications. **This is irreversible. Once enabled, it CANNOT be disabled.** - -**IMPORTANT:** For users wishing to develop and compile custom firmware, a private-public key pair is essential. Activating Secure Boot requires users to generate and manage their own unique private-public key pair. The public key from this pair must be embedded into the device to validate all firmware. Firmware will not boot without a proper digital signature from this key pair. This means that users must sign all future firmware versions with their private key and embed the public key in the device to ensure compatibility. - -### Secure Lock -Secure Lock builds on Secure Boot by imposing an even stricter security model. Once activated, Secure Lock prevents any further installation of new boot keys, effectively locking the device to only run firmware that is authorized by the device's primary vendor—in this case, Pico Keys. In addition to preventing additional keys, Secure Lock disables debugging interfaces and puts additional safeguards in place to resist tampering and intrusion attempts. This ensures that the device operates exclusively with the original vendor’s firmware and resists unauthorized access, making it highly secure against external threats. **This is irreversible. Once enabled, it CANNOT be disabled.** - -**IMPORTANT:** Activating Secure Lock not only enables Secure Boot but also invalidates all keys except the official Pico Key. This means that only firmware signed by Pico Key will be recognized, and custom code will no longer be allowed. Once enabled, the Pico Key device will run solely on the official firmware available on the website, with no option for generating or compiling new code for the device. - ## Download **If you own an ESP32-S3 board, go to [ESP32 Flasher](https://www.picokeys.com/esp32-flasher/) for flashing your Pico HSM.** -If you own a Raspberry Pico (RP2040 or RP2350), go to [Download page](https://www.picokeys.com/getting-started/), select your vendor and model and download the proper firmware; or go to [Release page](https://www.github.com/polhenarejos/pico-hsm/releases/) and download the UF2 file for your board. +If you own a Raspberry Pico (RP2040 or RP2350), go to [Download page](https://www.picokeys.com/getting-started/). If your board is mounted with the RP2040, then select Pico. If your board is mounted with the RP2350 or RP2354, select Pico2. -Note that UF2 files are shiped with a dummy VID/PID to avoid license issues (FEFF:FCFD). If you plan to use it with OpenSC or similar tools, you should modify Info.plist of CCID driver to add these VID/PID or use the [Pico Commissioner](https://www.picokeys.com/pico-commissioner/ "Pico Commissioner"). +Note that UF2 files are shiped with a dummy VID/PID to avoid license issues (FEFF:FCFD). If you plan to use it with OpenSC or similar tools, you should modify Info.plist of CCID driver to add these VID/PID or use the [PicoKey App](https://www.picokeys.com/picokeyapp/ "PicoKey App"). You can use whatever VID/PID (i.e., 234b:0000 from FISJ), but remember that you are not authorized to distribute the binary with a VID/PID that you do not own. -Note that the pure-browser option [Pico Commissioner](https://www.picokeys.com/pico-commissioner/ "Pico Commissioner") is the most recommended. +Note that the [PicoKey App](https://www.picokeys.com/picokeyapp/ "PicoKey App") is the most recommended. ## Build for Raspberry Pico Before building, ensure you have installed the toolchain for the Pico and the Pico SDK is properly located in your drive.