Updated docs.

Signed-off-by: Pol Henarejos <pol.henarejos@cttc.es>

README.md

@@ -2,38 +2,112 @@
 This is a project to create a Hardware Security Module (HSM) with a Raspberry Pico. It converts your Pico board into a HSM which is able to generate and store private keys, encrypt or decrypt with AES or signing data without to disclose the private key. In detail, the private key never leaves the board and it cannot be retrieved as it is encrypted in the flash memory.
 
 ## Capabilities
-- Key generation and encrypted storage.
-- RSA key generation from 1024 to 4096 bits.
-- ECDSA key generation from 192 to 521 bits.
-- ECC curves secp192r1, secp256r1, secp384r1, secp521r1, brainpoolP256r1, brainpoolP384r1, brainpoolP512r1, secp192k1 (insecure), secp256k1.
-- SHA1, SHA224, SHA256, SHA384, SHA512 digests.
-- RSA-PSS, RSA-PKCS and raw RSA signature.
-- ECDSA raw and hash signature.
-- ECDH key derivation.
-- EC private key derivation.[^1]
-- RSA-OEP and RSA-X-509 decryption.
-- AES key generation of 128, 192 and 256 bits.
-- AES-CBC encryption/decryption.
-- AES-CMAC authentication.[^1]
-- AES secret key derivation.[^1]
-- PIN authorization.
-- PKCS11 compliant interface.
-- HRNG (hardware random number generator).
-- Device Key Encryption Key (DKEK) shares.
-- DKEK n-of-m threshold scheme.
-- USB/CCID support with OpenSC, openssl, etc.
-- Extended APDU support.
-- Private keys and certificates import from WKY or PKCS#12 files.[^2][^3]
-- Transport PIN for provisioning and forcing to set a new PIN.[^2]
-- Press-to-confirm button optional feature to authorize operations with private/secret keys.
-- Store and retrieve binary data.
-- Real time clock with external datetime setting and getting. 
-- Secure Messaging (secure channel).
-- Session PIN.
-- PKI CVCert remote issuing for Secure Message.
+### 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.
+**No private/secret keys, DKEK or PIN are stored in plain text ever. Never.**
+
+### RSA key generation from 1024 to 4096 bits
+RSA key generation in place for 1024, 2048, 3072 and 4096 bits. Private keys never leave the device.
+
+### ECDSA key generation from 192 to 521 bits
+ECDSA key generation in place for different curves, from 192 to 521 bits.
+
+### ECC curves
+It supports secp192r1, secp256r1, secp384r1, secp521r1, brainpoolP256r1, brainpoolP384r1, brainpoolP512r1, secp192k1 (insecure), secp256k1 curves.
+
+### SHA1, SHA224, SHA256, SHA384, SHA512 digests
+ECDSA and RSA signature can be combined with SHA digest in place.
+
+### Multiple RSA signature algorithms
+It supports RSA-PSS, RSA-PKCS and raw RSA signatures.
+
+### ECDSA raw and hash signature
+ECDSA signatures can be in raw or pre-hashed formats.
+
+### ECDH key derivation
+It supports the calculation of shared secrets with ECDH algorithm.
+
+### EC private key derivation
+It allows ECDSA key derivation.[^1]
+
+### RSA-OEP and RSA-X-509 decryption
+It allows private decryption in place with RSA-OEP and RSA-X-509 algorithms.
+
+### AES key generation
+It supports AES key generation in place with keys of 128, 192 and 256 bits.
+
+### AES-CBC encryption/decryption
+AES encryption and decryption is performed in place.
+
+### CMAC
+It supports AES-CMAC authentication.[^1]
+
+### AES derivation
+It supports AES secret key derivation.[^1]
+
+### PIN authorization
+Private and secret keys cannot be used without prior PIN authentication. It supports alphanumeric PIN.
+
+### PKCS11 compliant interface
+The module can be interfaced with PKCS11 standard.
+
+### HRNG (hardware random number generator)
+It contains a harware random number generator properly modeled to guarantee maximum entropy.
+
+### Device Key Encryption Key (DKEK) shares
+It supports DKEK share imports. DKEK are used to wrap, unwrap and encrypt private and secret keys in the device.
+
+### DKEK n-of-m threshold scheme
+It supports a n-of-m threshold scheme to minimize outage when a DKEK custodian is not available during the import process.
+
+### USB/CCID support with OpenSC, openssl, etc.
+Pico HSM has a full USB CCID stack to communicate with the host via OpenSC and PCSC. It allows the use of frontend applications such as OpenSSL via PKCS11 module.
+
+### Extended APDU support
+It supports extended APDU packets, which allows up to 65535 bytes.
+
+### CVC certificates
+Pico HSM manipulates CVC certificates and requests to minimize the storage of internal certificates.
+
+### Attestation
+Every generated key is attached to a certificate, signed by an external PKI to ensure that a particular key is effectively generated by this specific device.
+
+### Import external private keys and certificates
+It allows private key and certificates import via WKY or PKCS#12 files.[^2][^3]
+
+### Tranport PIN
+It allows transport PIN for provisioning and forcing to set a new PIN.[^2] It is a tampered mechanism that ensures the device has not been unsealed during the transportation from the issuer to the legitimate user.
+
+### Press-to-confirm button
+It allows the use of BOOTSEL button to confirm operations with private/secret keys, such as signatures and decryption. When a private/secret key is loaded, the user has 15 seconds to press the button to confirm the operation.
+This feature protects the user from unwanted uses from background applications that may sign data without user notice.
+
+### Store and retrieve binary data
+It allows the storage of arbitrary files with binary data.
+
+### Real time clock (RTC)
+Pico HSM has a RTC with external datetime setting and getting. 
+
+### Secure Messaging (secure channel)
+Pico HSM supports secure channel, where the data packets between the host and device are encrypted to avoid man-in-the-middle attacks.
+
+### Session PIN
+A specific session PIN can be set during the session opening to avoid the systemmatic use of PIN.
+
+### PKI CVCert remote issuing for Secure Message
+Secure channel are secured via a certificate issued by a external PKI.
+
+### Multiple key domains
+Key domains are domains to store separate private/secret keys. Each domain is protected by a DKEK, independent from the other domains. Private/secret keys can be generated in different key domains to be used with separated DKEK. 
+Therefore, a single device may contain different domains with independent keys.
+
+### Key usage counter
+A key usage counter is a counter that is reduced by 1 everytime that the private/secret key is used for signing, decrypting, derivation, etc. When it reaches 0, the key is disabled and cannot be used anymore.
+
+Key usage can also be used to perform and auditory and track the usage of a particular key.
 
 [^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/rsa_4096.md "SCS3") for more information.
+[^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. 
 
 ## Security considerations
@@ -71,7 +145,7 @@ The firmware uploaded to the Pico contains a reader and a virtual smart card. It
 We recommend the use of [OpenSC](http://github.com/opensc/opensc/ "OpenSC") to communicate with the reader. If it is not installed, you can download and build it or install the binaries for your system. The first command is to ensure that the Pico is detected as a HSM:
 ```
 opensc-tool -an
-````
+```
 It should return a text like the following:
 ```
 Using reader with a card: Free Software Initiative of Japan Gnuk
@@ -90,7 +164,7 @@ For backup, restore and DKEK share management, check [doc/backup-and-restore.md]
 
 For AES key generation, encryption and decryption, check [doc/aes.md](/doc/aes.md).
 
-For 4096 bits RSA support, check [doc/rsa_4096_support.md](/doc/rsa_4096.md).
+For 4096 bits RSA support, check [doc/scs3.md](/doc/scs3.md).
 
 For storing and retrieving arbitrary data, check [doc/store_data.md](/doc/store_data.md).
 
@@ -154,16 +228,12 @@ The way to communicate is exactly the same as with other cards, such as OpenPGP
 
 For an advanced usage, see the docs and examples.
 
-Pico HSM also supports SCS3 tool. See [SCS3](/doc/rsa_4096.md "SCS3") for more information.
+Pico HSM also supports SCS3 tool for advanced use and multiple key domain. See [SCS3](/doc/scs3.md) for more information.
 
 ### 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 must patch the UF2 binary (if you just downloaded from the [Release section](https://github.com/polhenarejos/pico-hsm/releases "Release section")) or 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.
 
 ## Credits
 Pico HSM uses the following libraries or portion of code:
-- OpenSC for ASN1 manipulation.
 - mbedTLS for cryptographic operations.
-- gnuk for low level CCID procedures and OpenPGP support.
 - TinyUSB for low level USB procedures.
-
-In the case of gnuk, it is intended to work with STM32 processor and its family. Part of the code of CCID procedures are ported and adapted to run with Pico.

doc/aes.md

@@ -40,7 +40,7 @@ Once a secret AES key is generated, a content can be encrypted and decrypted sym
 
 ```
 $ echo "This is a text." | sc-tool -l --pin 648219 --encrypt --id 12 --mechanism aes-cbc > crypted.aes
-````
+```
 
 The file `crypted.aes` contains the ciphered string with the AES key generated previously.
 
@@ -55,4 +55,3 @@ 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. 
-

doc/extra_command.md

@@ -83,4 +83,9 @@ Sending: 80 64 06 00 01 00
 Received (SW1=0x90, SW2=0x00)
 ```
 
+### Key usage counter by default
+Pico HSM supports a key usage counter to audit the usage of a particular key. For every operation with the key, the counter is reduced by 1. When it reaches 0, the key is disabled and cannot be used.
 
+This option is disabled by default. When enabled, each generated key in the device is attached to a counter, starting at `2^32-1` (`FFFFFFFEh`). Therefore, it allows to count how many times a key is used for signing or decryption.
+
+The counter can be viewed by using the SCS3 tool. More info at [doc/scs3.md](/doc/scs3.md).

doc/scs3.md

@@ -1,8 +1,4 @@
-# RSA 4096 support
-
-Generating 4096 bits key in the Pico HSM is highly expensive. It may take minutes or hours to finish the generation. Therefore, it is extremely recommendable to generate the key in the host and import it into the Pico HSM.
-
-## SCS3 tool
+# SCS3 tool
 
 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").
 
@@ -22,7 +18,7 @@ SmartCardHSM.rootCerts = {
 	UTSRCACC100001: new CVC(new ByteString("7F218201B47F4E82016C5F290100420E55545352434143433130303030317F4982011D060A04007F000702020202038120A9FB57DBA1EEA9BC3E660A909D838D726E3BF623D52620282013481D1F6E537782207D5A0975FC2C3057EEF67530417AFFE7FB8055C126DC5C6CE94A4B44F330B5D9832026DC5C6CE94A4B44F330B5D9BBD77CBF958416295CF7E1CE6BCCDC18FF8C07B68441048BD2AEB9CB7E57CB2C4B482FFC81B7AFB9DE27E1E3BD23C23A4453BD9ACE3262547EF835C3DAC4FD97F8461A14611DC9C27745132DED8E545C1D54C72F0469978520A9FB57DBA1EEA9BC3E660A909D838D718C397AA3B561A6F7901E0E82974856A7864104A041FEB2FD116B2AD19CA6B7EACD71C9892F941BB88D67DCEEC92501F070011957E22122BA6C2CF5FF02936F482E35A6129CCBBA8E9383836D3106879C408EF08701015F200E55545352434143433130303030317F4C10060B2B0601040181C31F0301015301C05F25060102010100095F24060302010100085F3740914DD0FA00615C44048D1467435400423A4AD1BD37FD98D6DE84FD8037489582325C72956D4FDFABC6EDBA48184A754F37F1BE5142DD1C27D66569308CE19AAF", HEX)),
 	ESCVCAHSM00001: new CVC(new ByteString("7F218201657F4E82012D5F290100420E45534356434148534D30303030317F4981DD060A04007F000702020202038118FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFF8218FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFFFFFFFFFFC831864210519E59C80E70FA7E9AB72243049FEB8DEECC146B9B1843104188DA80EB03090F67CBF20EB43A18800F4FF0AFD82FF101207192B95FFC8DA78631011ED6B24CDD573F977A11E7948118518FFFFFFFFFFFFFFFFFFFFFFFF99DEF836146BC9B1B4D22831863104088FCDFCCE87EDD285920615E651D76452D857ECBB408C327ADB48A2A514C1C9BD77CC9783607A741493A742744AD1738701015F200E45534356434148534D30303030317F4C12060904007F0007030102025305C0000000045F25060202000302065F24060300010203015F37307297777664B60C57A2C45E7BFD12E520143EDE9038BFB302739106F2730D760665D74649910C519089848D4FB6E51340", HEX))
 }
-````
+```
 
 After this ammendment, the KeyManager can be invoked (CTRL+M) and it will output something similar to:
 ```
@@ -47,3 +43,6 @@ In order to perform the import, private keys must be wrapped with the same DKEK
 
 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.
 
+## RSA 4096 support
+
+Generating 4096 bits key in the Pico HSM is highly expensive. It may take minutes or hours to finish the generation. Therefore, it is extremely recommendable to generate the key in the host and import it into the Pico HSM.

doc/sign-verify.md

@@ -146,8 +146,3 @@ The signature is verified with the hash:
 $ openssl pkeyutl -verify -pubin -inkey 11.pub -in data.sha1 -sigfile data.sig                              
 Signature Verified Successfully
 ```
-
-
-
-
-