diff --git a/doc/public_key_authentication.md b/doc/public_key_authentication.md index a24c4cf..5a9055b 100644 --- a/doc/public_key_authentication.md +++ b/doc/public_key_authentication.md @@ -18,8 +18,8 @@ To enable PKA, the device must be initialized beforehand. In case the device has To take advantage of PKA, the following is required: 1. Two Pico HSM: one will be used only for authentication (it can be any device able to generate a private key and sign arbitrary data). -2. [SCS3](/doc/scs3.md "SCS3") tool to authenticate the user. At this time, OpenSC does not support PKA. -3. A secret key of ECC 256 bits. SCS3 does not support other curves. +2. [SCS3](/doc/scs3.md "SCS3") tool to authenticate the user. At this time, OpenSC does not support PKA, only initialization. +3. A secret key of ECC 256 bits. ## Usage @@ -29,35 +29,57 @@ Before using SCS3, it must be patched [scs3.patch.txt](https://github.com/polhen On a secondary device, generate a private key, on the ECC 256 bits (`brainpoolP256r1` or `secp192r1`). Label it with an easy name, such as "Authentication". -Captura de Pantalla 2022-06-13 a les 12 11 00 + Once finished, export the public key. -Captura de Pantalla 2022-06-13 a les 12 11 39 + ### Initialization On the primary device, initialize it. When prompting for an authentication mechanism, select "Public Key Authentication". -Captura de Pantalla 2022-06-13 a les 12 05 09Captura de Pantalla 2022-06-13 a les 12 14 48 +Captura de Pantalla 2022-06-13 a les 12 14 48 Once finished, register the exported public key. A message of `0 authenticated public key(s) in 1 of 1 scheme` will appear if it is properly registered. -Captura de Pantalla 2022-06-13 a les 12 15 44Captura de Pantalla 2022-06-13 a les 12 16 17 - +Captura de Pantalla 2022-06-13 a les 12 16 17 ### Authentication Plug the secondary device that stores the private key (do not load the device in the SCS3 tool) and initiate the public key authentication. -Captura de Pantalla 2022-06-13 a les 12 19 47 + Select the secondary card and the Authentication private key (or the name you labeled it). -Captura de Pantalla 2022-06-13 a les 14 25 25 + Introduce the PIN of the secondary device. If the private key matches with the registered public key, the primary device will grant access and it will display `User PIN authenticated (9000)` (despite no PIN is provided). From now on, you have full access and can operate normally with the primary device. + +## Notes on DKEK + +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. +Otherwise, it will not be possible to operate with private/secret keys despite the user will be logged in. + +Unfortunately, SCS3 does not supports the combination of both schemes during the initialization. Fortunately, OpenSC does. + +To initialize the device with PKA *and* PIN use the following command (or similar), which accepts the use of PIN parameter *and* PKA configuration: + +``` +sc-hsm-tool -X --so-pin 1234567890123456 --pin 648219 -K 1 -n 1 -s 1 +``` + +where PKA and PIN are enabled, jointly with DKEK protection. + +Therefore, with this scheme, multiple custodians may authenticate the device individually and, when fully authenticated, the master user can unlock the DKEK with the PIN. + +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.