mirrors/pico-hsm
1
0
Fork 0
mirror of https://github.com/polhenarejos/pico-hsm.git synced 2026-01-17 09:28:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Update README.

Browse source 
Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es>
This commit is contained in:
Pol Henarejos 2023-03-07 23:16:01 +01:00
parent d81b21695f
commit f8110a9d75
No known key found for this signature in database
GPG key ID: C0095B7870A4CCD3
1 changed files with 12 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
README.md
View file

@ -3,7 +3,7 @@ This is a project to create a Hardware Security Module (HSM) with a Raspberry Pi
## Capabilities
### > Key generation and encrypted storage
Private and secret keys are stored with a master AES 256 key (DKEK). The DKEK is, at the same time, encrypted with a hashed and salted version of the PIN.
Private and secret keys are stored with a master AES 256 key (MKEK). The MKEK is, at the same time, encrypted with a hashed and salted version of the PIN.
**No private/secret keys, DKEK or PIN are stored in plain text ever. Never.**
### > RSA key generation from 1024 to 4096 bits
@ -109,7 +109,7 @@ Key usage can also be used to perform and auditory and track the usage of a part
### > Public Key Authentication
Public Key Authentication (PKA) allows to authenticate by using a secondary device with a private key and a registered public key in the primary device. A challenge is generated by the primary Pico HSM and given to the secondary for signature. The secondary device signs the challenge and returns the signature. Then, the primary device verifies the signature with the registered public key and if it is valid, it grants full access, as normal PIN authentication.
In PKA, the PIN is used for protecting the DKEK, as classic method with only PIN, and PKA is used for adding an extra security layer. Therefore, this mechanism provides a higher degree of security, since it needs a secondary Pico HSM to authenticate the primary one.
In PKA, the PIN is used for protecting the MKEK, as classic method with only PIN, and PKA is used for adding an extra security layer. Therefore, this mechanism provides a higher degree of security, since it needs a secondary Pico HSM to authenticate the primary one.
### > Secure Lock
An extra layer can be added to the device by adding a private key stored on the computer to lock that Pico HSM to the specific computer. The content will be completely encrypted with a private key only available from a specific computer.
@ -126,6 +126,12 @@ It supports symmetric key derivations from different standards and RFC.
### > HMAC
It supports performing HMAC from a secret key on a arbitrary data with SHA digest algorithm.
### > XKEK
Besides DKEK, it supports a more advanced scheme to share keys. Based on private key domains, it possible to wrap and unwrap private and secret keys inside the domain to only authorized devices. If a device outside the domain tries to unwrap a key, it will fail.
### > MKEK
A Master Key Encryption Key is used to store safely all the keys. This key is also ciphered with an ephemereal key derived from the hashed PIN. Therefore, we can ensure all the keys are encrypted and stored.
[^1]: PKCS11 modules (`pkcs11-tool` and `sc-tool`) do not support CMAC and key derivation. It must be processed through raw APDU command (`opensc-tool -s`).
[^2]: Available via SCS3 tool. See [SCS3](/doc/scs3.md "SCS3") for more information.
[^3]: Imports are available only if the Pico HSM is previously initialized with a DKEK and the DKEK shares are available during the import process.
@ -150,6 +156,7 @@ Before building, ensure you have installed the toolchain for the Pico and the Pi
```
git clone https://github.com/polhenarejos/pico-hsm
git submodule update --init --recursive
cd pico-hsm
mkdir build
cd build
@ -166,9 +173,9 @@ Independent from your Linux distribution or when using another OS that supports
```
sudo docker build \
--build-arg VERSION_PICO_SDK=1.4.0 \
--build-arg VERSION_MAJOR=2 \
--build-arg VERSION_MINOR=6 \
--build-arg VERSION_PICO_SDK=1.5.0 \
--build-arg VERSION_MAJOR=3 \
--build-arg VERSION_MINOR=4 \
--build-arg PICO_BOARD=waveshare_rp2040_zero \
--build-arg USB_VID=0xfeff \
--build-arg USB_PID=0xfcfd \