dearsky/pico-hsm
1
0
Fork 0
Code Issues 17 Pull Requests 4 Actions Packages Projects Releases 26 Wiki Activity

Removing trailing spaces.

Browse Source 
Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es>
This commit is contained in:
Pol Henarejos
2022-08-19 01:44:27 +02:00
parent 1f2ccd8c1c
commit aebb68724a
52 changed files with 583 additions and 568 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/aes.md
View File

@@ -54,4 +54,4 @@ Using decrypt algorithm AES-CBC
This is a text.
```
AES-CBC it is a block operation and it requires an input size multiple of 16 bytes. Thus, for a trivial data, a padding operation has to be performed beforehand.
AES-CBC it is a block operation and it requires an input size multiple of 16 bytes. Thus, for a trivial data, a padding operation has to be performed beforehand.

12
doc/asymmetric-ciphering.md
View File

@@ -24,12 +24,12 @@ This algorithm uses the PKCSv1.5 padding. It is considered deprecated and insecu
First, we encrypt the data with the public key:
```
$ openssl rsautl -encrypt -inkey 1.pub -in data -pubin -out data.crypt
$ openssl rsautl -encrypt -inkey 1.pub -in data -pubin -out data.crypt
```
Then, we decrypt with the private key inside the Pico HSM:
```
```
$ pkcs11-tool --id 1 --pin 648219 --decrypt --mechanism RSA-PKCS -i data.crypt
Using slot 0 with a present token (0x0)
Using decrypt algorithm RSA-PKCS
@@ -54,7 +54,7 @@ $ openssl rsautl -encrypt -inkey 1.pub -in data_pad -pubin -out data.crypt -raw
Then, we decrypt with the private key inside the Pico HSM:
```
$ cat data.crypt|pkcs11-tool --id 4 --pin 648219 --decrypt --mechanism RSA-X-509
$ cat data.crypt|pkcs11-tool --id 4 --pin 648219 --decrypt --mechanism RSA-X-509
Using slot 0 with a present token (0x0)
Using decrypt algorithm RSA-X-509
This is a test string. Be safe, be secure.
@@ -78,7 +78,7 @@ This is a test string. Be safe, be secure.
```
## ECDH-DERIVE
ECC keys do not allow ciphering operations. Instead, the ECDH scheme provides a mechanism to exchange a shared symmetric key without transmitting it to the remote part. The shared key is composed by multiplying the local private key and the remote public key.
ECC keys do not allow ciphering operations. Instead, the ECDH scheme provides a mechanism to exchange a shared symmetric key without transmitting it to the remote part. The shared key is composed by multiplying the local private key and the remote public key.
First, we create the remote part, Bob, by generating an ECC keypair and getting the public key:
```
@@ -104,8 +104,8 @@ No output is displayed if both are equal.
You can also view the contents of both keys:
```
$ xxd -p bob-mine.der
$ xxd -p bob-mine.der
9874558aefa9d92cc051e5da6d1753987e5314925d6d78bf
$ xxd -p mine-bob.der
$ xxd -p mine-bob.der
9874558aefa9d92cc051e5da6d1753987e5314925d6d78bf
```

24
doc/backup-and-restore.md
View File

@@ -29,15 +29,15 @@ symbols.
Please keep the generated DKEK share file in a safe location. We also recommend to keep a
paper printout, in case the electronic version becomes unavailable. A printable version
of the file can be generated using "openssl base64 -in <filename>".
Enter password to encrypt DKEK share :
Enter password to encrypt DKEK share :
Please retype password to confirm :
Please retype password to confirm :
Enciphering DKEK share, please wait...
DKEK share created and saved to dkek.pbe
```
The generated file `dkek.pbe` contains the DKEK. Technically, it contains a share. But if a device is initialized with one share, it is equivalent to contain the full DKEK.
The generated file `dkek.pbe` contains the DKEK. Technically, it contains a share. But if a device is initialized with one share, it is equivalent to contain the full DKEK.
Keep these file in a safe place. If this file is lost, you can export the private keys but you will not be able to import into another device or in the same device if it is initialized again.
@@ -52,7 +52,7 @@ At this moment, the Pico HSM expects the DKEK. It is loaded with the following c
```
$ sc-hsm-tool --import-dkek-share dkek.pbe
Using reader with a card: Free Software Initiative of Japan Gnuk
Enter password to decrypt DKEK share :
Enter password to decrypt DKEK share :
Deciphering DKEK share, please wait...
DKEK share imported
@@ -81,7 +81,7 @@ And finally, all are imported one after the other, without special order:
```
$ sc-hsm-tool --import-dkek-share dkek-share-1.pbe
Using reader with a card: Free Software Initiative of Japan Gnuk
Enter password to decrypt DKEK share :
Enter password to decrypt DKEK share :
Deciphering DKEK share, please wait...
DKEK share imported
@@ -90,7 +90,7 @@ DKEK import pending, 2 share(s) still missing
$ sc-hsm-tool --import-dkek-share dkek-share-2.pbe
Using reader with a card: Free Software Initiative of Japan Gnuk
Enter password to decrypt DKEK share :
Enter password to decrypt DKEK share :
Deciphering DKEK share, please wait...
DKEK share imported
@@ -99,7 +99,7 @@ DKEK import pending, 1 share(s) still missing
$ sc-hsm-tool --import-dkek-share dkek-share-1.pbe
Using reader with a card: Free Software Initiative of Japan Gnuk
Enter password to decrypt DKEK share :
Enter password to decrypt DKEK share :
Deciphering DKEK share, please wait...
DKEK share imported
@@ -110,7 +110,7 @@ DKEK key check value : 4B7DA256ACD4EF62
### DKEK n-of-m threshold scheme
This scheme provides an extra level of flexiblity, as not all custodians are necessary to import the DKEK share. For instance, with the previous schemes, if a custodian gets unavailable, the initialization will block until the missing custodian can got to finalize the initialization.
With n-of-m threshold scheme, it flexibilizes the number of required custodians to reduce failure points. If a share is lost, the DKEK can still be recovered without major implications.
With n-of-m threshold scheme, it flexibilizes the number of required custodians to reduce failure points. If a share is lost, the DKEK can still be recovered without major implications.
This scheme is not a replacement of DKEK shares. Instead, it splits the DKEK share encryption password amongst the n-of-m threshold scheme. For instance, if you define 2 shares and a scheme of 3-of-5 threshold for each share, it will imply 10 different custodians, where 6 are necessary to load both shares. You can also mix one share with traditional passphrase and the other with the n-of-m threshold scheme.
@@ -123,7 +123,7 @@ Using reader with a card:Free Software Initiative of Japan Gnuk
The DKEK will be enciphered using a randomly generated 64 bit password.
This password is split using a (3-of-5) threshold scheme.
Please keep the generated and encrypted DKEK file in a safe location. We also recommend
Please keep the generated and encrypted DKEK file in a safe location. We also recommend
to keep a paper printout, in case the electronic version becomes unavailable. A printable version
of the file can be generated using "openssl base64 -in <filename>".
@@ -191,7 +191,7 @@ Private RSA Key [Certificate]
...
```
Note that `Key ref` and `ID` may be different. Whilst different keys may share the same `ID` (highly discouraged), the `Key ref` is a value internally computed and unique.
Note that `Key ref` and `ID` may be different. Whilst different keys may share the same `ID` (highly discouraged), the `Key ref` is a value internally computed and unique.
To export and wrap the private key:
@@ -199,10 +199,10 @@ To export and wrap the private key:
$ sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
```
A file named `wrap-key.bin` is created with the private key encrypted securely with the DKEK.
A file named `wrap-key.bin` is created with the private key encrypted securely with the DKEK.
## Restore
To restore the wraped key, a device initialized with the same DKEK is mandatory.
To restore the wraped key, a device initialized with the same DKEK is mandatory.
To unwrap the key:

10
doc/extra_command.md
View File

@@ -1,6 +1,6 @@
# Extra command
Pico HSM supports a customized extra command to use with different options. Since the drivers in the market do not support the following features, a raw APDU command shall be sent.
Pico HSM supports a customized extra command to use with different options. Since the drivers in the market do not support the following features, a raw APDU command shall be sent.
To send a raw APDU command, `opensc-tool -s <APDU>` can be used. The `APDU` parameter is a string of hexadecimal numbers and it takes the following form:
```
@@ -27,7 +27,7 @@ For example, to obtain the current datetime:
```
$ opensc-tool -s 80640A0008
Using reader with a card: Free Software Initiative of Japan Gnuk
Sending: 80 64 0A 00 08
Sending: 80 64 0A 00 08
Received (SW1=0x90, SW2=0x00):
07 E6 04 06 03 13 29 1E ......).
```
@@ -49,7 +49,7 @@ To set the reference datetime, a datetime string must be provided. For example:
```
$ opensc-tool -s 80640A000807E6040603132917
Using reader with a card: Free Software Initiative of Japan Gnuk
Sending: 80 64 0A 00 08 07 E6 04 06 03 13 29 17
Sending: 80 64 0A 00 08 07 E6 04 06 03 13 29 17
Received (SW1=0x90, SW2=0x00)
```
@@ -72,7 +72,7 @@ This feature is disabled by default but can be enabled rapidly by setting the LS
```
$ opensc-tool -s 806406000101
Using reader with a card: Free Software Initiative of Japan Gnuk
Sending: 80 64 06 00 01 01
Sending: 80 64 06 00 01 01
Received (SW1=0x90, SW2=0x00)
```
@@ -99,7 +99,7 @@ This feature is disabled by default but can be enabled rapidly by setting the 2n
```
$ opensc-tool -s 806406000102
Using reader with a card: Free Software Initiative of Japan Gnuk
Sending: 80 64 06 00 01 01
Sending: 80 64 06 00 01 01
Received (SW1=0x90, SW2=0x00)
```

14
doc/public_key_authentication.md
View File

@@ -29,7 +29,7 @@ On a secondary device, generate a private key, on the ECC 256 bits (`brainpoolP2
<img width="1037" src="https://user-images.githubusercontent.com/55573252/173353764-4620ece4-0d82-4a23-a153-99bf912621a7.png">
Once finished, export the public key.
Once finished, export the public key.
<img width="350" src="https://user-images.githubusercontent.com/55573252/173353732-63f40572-a42f-4e5c-a9ab-6e52a083956b.png">
@@ -64,17 +64,17 @@ From now on, you have full access and can operate normally with the primary devi
Pico HSM uses the PIN to protect the DKEK, which is lately used to protect private/secret keys and wrap/unwrap. However, when PKA is enabled, the authentication is not performed by introducing any PIN.
Authenticated privileges are granted when PKA succeeds, regardless of PIN, which is optional.
Nevertheless, **it is extremely recommended to combine PKA with PIN**. Note that when combined, only PKA grants authenticated privileges. Therefore, if both schemes are setup, it is necessary to unlock the DKEK with PIN verification.
Nevertheless, **it is extremely recommended to combine PKA with PIN**. Note that when combined, only PKA grants authenticated privileges. Therefore, if both schemes are setup, it is necessary to unlock the DKEK with PIN verification.
Otherwise, it will not be possible to operate with private/secret keys despite the user will be logged in.
With this scheme, multiple custodians may authenticate the device individually and remotely and, when fully authenticated, the master user can unlock the DKEK with the PIN.
Moreover, with this approach the device is kept safe and neither the DKEK nor the private/secret keys are stored in plain text in the device.
Moreover, with this approach the device is kept safe and neither the DKEK nor the private/secret keys are stored in plain text in the device.
Even though the flash memory is dumped by an attacker, it will not be possible to decipher any sensitive data or key.
Initialization of the device with PKA **and** PIN can be achieved with SCS3 or OpenSC:
**Note:** do not import any DKEK share or DKEK operation before PKA and PIN setup.
**Note:** do not import any DKEK share or DKEK operation before PKA and PIN setup.
### With OpenSC
@@ -84,9 +84,9 @@ Use the following command (or similar), which accepts the use of PIN parameter *
sc-hsm-tool -X --so-pin 1234567890123456 --pin 648219 -K 1 -n 1 -s 1
```
and PKA and PIN are enabled, jointly with DKEK protection.
and PKA and PIN are enabled, jointly with DKEK protection.
### With SCS3
###<EFBFBD>With SCS3
Unfortunately, SCS3 does not allow to initialize the device with PKA and PIN at the same time, though it can be achieved in separated steps:
@@ -94,4 +94,4 @@ Unfortunately, SCS3 does not allow to initialize the device with PKA and PIN at
2. There is NO default PIN. So, DO NOT attempt to log in yet. A reset PIN shall be requested.
3. Click on ``Reset User-PIN``, introduce the SO-PIN configured during the initialization and introduce the desired User-PIN.
When done, the device will be configured with PIN **and** PKA.
When done, the device will be configured with PIN **and** PKA.

10
doc/scs3.md
View File

@@ -4,11 +4,11 @@ SCS3 tool is a specific tool developed by CardContact to manage HSM. Thanks to i
- Import PKCS12 private keys and certificates.
- Import private keys and certificates from other Pico HSM devices in WKY format.
-
-
Unfortunately, there is no pkcs11 tool or equivalent capable to perform the import. Since it uses the SC-HSM driver, it also supports the communication with the [SCS3 tool](https://www.openscdp.org/scsh3/ "SCS3 tool"). It can be downloaded from [here](https://www.openscdp.org/scsh3/download.html "here").
However, SCS3 only works with those HSM manufactured by CardContact. The check is performed by means of trust store against the manufacturing certificates. For obvious reasons, these certificates can only be signed with the private keys of the Certificate Authorities listed in the trust store.
However, SCS3 only works with those HSM manufactured by CardContact. The check is performed by means of trust store against the manufacturing certificates. For obvious reasons, these certificates can only be signed with the private keys of the Certificate Authorities listed in the trust store.
Pico HSM is shipped with its own CA certificates. To load this certificate onto the trust store of SCS3, the following line has to be appended to `SmartCardHSM.rootCerts` variable, near line `235` in the file `scs3/scsh/sc-hsm/SmartCardHSM.js`.
@@ -39,8 +39,8 @@ After this ammendment, the program can be started and the KeyManager can be invo
>load("keymanager/keymanager.js");
SmartCard-HSM Version 1.6 on JCOP Free memory 217104 byte
Issuer Certificate : CVC id-AT DV (official domestic) CAR=ESCVCAHSM00001 CHR=ESDVCAHSM00001 CED=27 / de març / 2022 CXD=31 / de desembre / 2025
Device Certificate : CVC id-AT Terminal CAR=ESDVCAHSM00001 CHR=ESTERMHSM00001 CED=27 / de març / 2022 CXD=31 / de desembre / 2023
Issuer Certificate : CVC id-AT DV (official domestic) CAR=ESCVCAHSM00001 CHR=ESDVCAHSM00001 CED=27 / de març / 2022 CXD=31 / de desembre / 2025
Device Certificate : CVC id-AT Terminal CAR=ESDVCAHSM00001 CHR=ESTERMHSM00001 CED=27 / de març / 2022 CXD=31 / de desembre / 2023
Default Key Domain : 0F89B400975EDD2D425ABF85F2FBD318779B3D85475E65D4
-------------------------------------------------------------------
Please right-click on nodes in the outline to see possible actions.
@@ -60,7 +60,7 @@ It can be executed in a Terminal via
```
## DKEK requirement
In order to perform the import, private keys must be wrapped with the same DKEK present in the Pico HSM. Thus, the Pico HSM must be previously initialized with at minimum of 1 DKEK share. This share will be used to wrap the private key before import.
In order to perform the import, private keys must be wrapped with the same DKEK present in the Pico HSM. Thus, the Pico HSM must be previously initialized with at minimum of 1 DKEK share. This share will be used to wrap the private key before import.
Note that the DKEK share shall be available before the import. In this way, all custodians must be present during the import process, since they will have to introduce their respective DKEK.

14
doc/sign-verify.md
View File

@@ -1,7 +1,7 @@
# Sign and verify
Pico HSM supports in place signature of arbitrary data. It supports the following algorithms:
* RSA-PKCS
* RSA-PKCS
* RSA-X-509
* SHA1-RSA-PKCS
* SHA256-RSA-PKCS
@@ -32,7 +32,7 @@ $ openssl rsa -inform DER -outform PEM -in 1.der -pubin > 1.pub
At this moment, you are able to verify with the public key in `1.pub`. The signature is computed inside the Pico HSM with the private key. It never leaves the device.
## RSA-PKCS
This algorithm is used to sign raw data.
This algorithm is used to sign raw data.
To sign the data:
```
@@ -91,7 +91,7 @@ This algorithm uses the RSA-PKCS with PSS salt to randomize the signature. Pico
To sign the data:
```
$ pkcs11-tool --id 1 --sign --pin 648219 --mechanism RSA-PKCS-PSS -i data.sha1 -o data.sig
```
```
To verify the signature:
```
@@ -105,7 +105,7 @@ This algorithm takes the file as the input and sends its hash for signing with t
To sign the data:
```
$ pkcs11-tool --id 1 --sign --pin 648219 --mechanism SHA1-RSA-PKCS-PSS -i data -o data.sig
```
```
To verify the signature:
```
@@ -118,14 +118,14 @@ This is a raw ECDSA signature, which is usually used to sign a hashed message. `
To sign the data:
```
$ pkcs11-tool --id 11 --sign --pin 648219 --mechanism ECDSA -i data.sha1 -o data.sig --signature-format openssl
$ pkcs11-tool --id 11 --sign --pin 648219 --mechanism ECDSA -i data.sha1 -o data.sig --signature-format openssl
Using slot 0 with a present token (0x0)
Using signature algorithm ECDSA
```
To verify the signature:
```
$ openssl pkeyutl -verify -pubin -inkey 11.pub -in data.sha1 -sigfile data.sig
$ openssl pkeyutl -verify -pubin -inkey 11.pub -in data.sha1 -sigfile data.sig
Signature Verified Successfully
```
@@ -143,6 +143,6 @@ Using signature algorithm ECDSA-SHA256
The signature is verified with the hash:
```
$ openssl pkeyutl -verify -pubin -inkey 11.pub -in data.sha1 -sigfile data.sig
$ openssl pkeyutl -verify -pubin -inkey 11.pub -in data.sha1 -sigfile data.sig
Signature Verified Successfully
```

6
doc/store_data.md
View File

@@ -9,7 +9,7 @@ Before writting a file into the Pico HSM, we generate the data file with the fol
```
$ echo 'Pico HSM is awesome!' > test
```
```
Then, we can store the data file with the following command:
@@ -43,7 +43,7 @@ Always provide a unique `--label`, as it will be used to index and reference the
To view the stored file, we can use the following command with the same label we employed:
```
$ pkcs11-tool --read-object --type data --label 'test1'
$ pkcs11-tool --read-object --type data --label 'test1'
Using slot 0 with a present token (0x0)
Pico HSM is awesome!
```
@@ -98,7 +98,7 @@ Data object 'test1'
applicationName: test1
Path: e82b0601040181c31f0201::cf00
Data (21 bytes): 5069636F2048534D20697320617765736F6D65210A
Data object 'test2'
applicationName: test2
Path: e82b0601040181c31f0201::cd01

16
doc/usage.md
View File

@@ -1,7 +1,7 @@
# Usage
## Tools
We use multiple tools and PKCS#11 drivers and modules, depending on the purpose.
We use multiple tools and PKCS#11 drivers and modules, depending on the purpose.
* **pkcs11-tool**: from OpenSC. It interfaces with the HSM via PKCS#11 interface. It supports different drivers and modules.
* **sc-tool**: an alias of pkcs11-tool with the sc-hsm-embedded module. It is mainly used for AES management and it is defined as:
```
@@ -32,10 +32,10 @@ The first step is to initialize the HSM:
```
$ 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 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.
The SO-PIN is used to unblock the PIN. It accepts 15 attemps. After 15 failed attempts, the device will be completely blocked and will be necessary to initialize again, erasing all private keys and losing the access. Therefore, keep the SO-PIN in a safe place.
The SO-PIN is used to unblock the PIN. It accepts 15 attemps. After 15 failed attempts, the device will be completely blocked and will be necessary to initialize again, erasing all private keys and losing the access. Therefore, keep the SO-PIN in a safe place.
The SO-PIN is always 16 hexadecimal characters.
## PIN and SO-PIN management
@@ -62,7 +62,7 @@ To generate a RSA 2048 bits, use the following command:
$ pkcs11-tool -l --pin 648219 --keypairgen --key-type rsa:2048 --id 1 --label "RSA2K"
Using slot 0 with a present token (0x0)
Key pair generated:
Private Key Object; RSA
Private Key Object; RSA
label: RSA2K
ID: 1
Usage: decrypt, sign
@@ -77,7 +77,7 @@ The ID parameter is an internal hexadecimal number for easy identification. The
Pico HSM accepts RSA of 1024 (`rsa:1024`), 2048 (`rsa:2048`) and 4096 bits (`rsa:4096`).
**Caution**: RSA 2048 bits may take more than 20 seconds. RSA 4096 bits may take more than 20 minutes. The Pico HSM will work as normally and neither the HSM nor the host will block. But, in the meantime, the Pico HSM will not accept any command.
**Caution**: RSA 2048 bits may take more than 20 seconds. RSA 4096 bits may take more than 20 minutes. The Pico HSM will work as normally and neither the HSM nor the host will block. But, in the meantime, the Pico HSM will not accept any command.
An alternative is to generate the private key locally and import it to the HSM. This approach, however, is less secure as it does not use a True RNG or HRNG like Pico HSM. Use this approach if you have plugged a TRNG or you are not worried about obtaining the highest entropy.
Pico HSM also accepts ECDSA keypairs:
@@ -157,9 +157,9 @@ Certificate:
a0:30:b2:ec:d3:d6:0d:58:f3
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
X509v3 Subject Key Identifier:
98:07:DA:13:B0:8E:A0:5C:97:83:68:FE:4A:25:8D:50:C4:DC:16:FA
X509v3 Authority Key Identifier:
X509v3 Authority Key Identifier:
keyid:98:07:DA:13:B0:8E:A0:5C:97:83:68:FE:4A:25:8D:50:C4:DC:16:FA
X509v3 Basic Constraints: critical
@@ -173,7 +173,7 @@ Certificate:
99:2b:b2:82:66:c1:06:a7:2c:62:af:e2:e4:93:42:36:66:8d:
c5:3f:e1:ec:5f:9a:f8:5f:b3:6a:8f:0e:12:5d:c9:46:38:ea:
0b:08
```
```
The resulting file `cert.pem` contains the signed certificate in PEM format. Convert it into DER format and load it into the Pico HSM: