Installation¶
Do this part as the root user
Install needed packages
# apk add ccid opensc pcsc-lite-libs
Enable and start pcscd
# rc-update add pcscd # service pcscd start
NOTE The pcscd service must be restarted after plugging in the Nitrokey to the computer
Check the reader and SmartCard¶
The Nitrokey HSM contains a tamper resistant smart card mounted in an usb attached smart card reader.
Do this section, and the following sections, as an unprivileged user!
You should now be able to find your NitroKey HSM
$ opensc-tool --list-readers # Detected readers (pcsc) Nr. Card Features Name 0 Yes Nitrokey Nitrokey HSM (DENK0nnnnnnnnnn ) 00 00
Make sure we can talk to the card by listing supported algorithms
$ opensc-tool --reader 0 --list-algorithms Algorithm: rsa Key length: 1024 Flags: onboard key generation padding ( pss ) hashes ( ) Algorithm: rsa Key length: 1536 Flags: onboard key generation padding ( pss ) hashes ( ) Algorithm: rsa Key length: 2048 Flags: onboard key generation padding ( pss ) hashes ( ) Algorithm: rsa Key length: 3072 Flags: onboard key generation padding ( pss ) hashes ( ) Algorithm: rsa Key length: 4096 Flags: onboard key generation padding ( pss ) hashes ( ) Algorithm: ec Key length: 192 Flags: onboard key generation Algorithm: ec Key length: 224 Flags: onboard key generation Algorithm: ec Key length: 256 Flags: onboard key generation Algorithm: ec Key length: 320 Flags: onboard key generation Algorithm: ec Key length: 384 Flags: onboard key generation Algorithm: ec Key length: 512 Flags: onboard key generation Algorithm: ec Key length: 521 Flags: onboard key generation
Initialize the SmartCard¶
When you initialize the card you choose a so-pin (Security Officer (SO) PIN) and a pin (but first turn off command history logging...)
Example (set so-pin and pin to your choosen values)
$ set +o history $ sc-hsm-tool --initialize --so-pin <16-hexadecimal-digit-SO-PIN> --pin <6-digit-PIN>
More info here OpenSC initialize
Generate first key-pair¶
Use pin used when the card was initialized
Example creating a nistp521 / secp521r1 curve key (will prompt for pin)
$ pkcs11-tool --module /usr/lib/opensc-pkcs11.so --login --keypairgen --key-type EC:nistp521 --label mykey sing slot 0 with a present token (0x0) Logging in to "SmartCard-HSM (UserPIN)". Please enter User PIN: ****** Key pair generated: Private Key Object; EC label: mykey .....
NOTE The key with label mykey is used in all examples below, but for production, give the key a label that
indicates what the key is used for e.g. ssh-ca if the key is used for an SSH Certificate Authority.
Extract the public key and convert to a pem file with openssl
$ pkcs11-tool --module /usr/lib/opensc-pkcs11.so --label mykey --read-object --type pubkey --output-file /tmp/mykey-pub.spki $ openssl ec -inform DER -outform PEM -in /tmp/mykey-pub.spki -pubin > /tmp/mykey-pub.pem
Or use pkcs15-tool
$ pkcs15-tool --list-public-keys Using reader with a card: Nitrokey Nitrokey HSM (DENK0nnnnnnnnnn ) 00 00 Public EC Key [mykey] Object Flags : [0x0] Usage : [0x40], verify Access Flags : [0x2], extract FieldLength : 528 Key ref : 0 (0x0) Native : no ID : nnnannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn DirectValue : <present> $ pkcs15-tool --read-public-key nnnannnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn > /tmp/mykey-pub.pem
Check the public key pem file
$ openssl asn1parse -in /tmp/mykey-pub.pem -inform pem 0:d=0 hl=3 l= 155 cons: SEQUENCE 3:d=1 hl=2 l= 16 cons: SEQUENCE 5:d=2 hl=2 l= 7 prim: OBJECT :id-ecPublicKey 14:d=2 hl=2 l= 5 prim: OBJECT :secp521r1 21:d=1 hl=3 l= 134 prim: BIT STRING
Sign a text file with the SmartCard¶
$ cd /tmp $ echo "test test" > textfile $ pkcs11-tool --module /usr/lib/opensc-pkcs11.so --label mykey --hash -m SHA384 --input-file textfile --output-file textfile.hash Using slot 0 with a present token (0x0) Using digest algorithm SHA384 $ pkcs11-tool --module /usr/lib/opensc-pkcs11.so --label mykey --sign -m ECDSA --signature-format openssl --input-file textfile.hash --output-file textfile.sig Using slot 0 with a present token (0x0) Logging in to "UserPIN (SmartCard-HSM)". Please enter User PIN: ****** Using signature algorithm ECDSA
Verify the signed hash signature with openssl
$ openssl dgst -sha384 -verify mykey-pub.pem -signature textfile.sig textfile Verified OK
Use as a SSH CA¶
More info on OpenSSH setup with a CA here: OpenSSH setup
Extract the public key for the private key that will be used as your CA key
$ ssh-keygen -D /usr/lib/pkcs11/opensc-pkcs11.so | fgrep "mykey" > /tmp/myCAkey.pub
Change the comment in the public key file, to a name that better describe the public key:
$ sed -i 's/mykey/ca_key-example.com/' /tmp/myCAkey.pub
Issue a certificate for the public key of a server sys1 stored in /tmp/sys1_ecdsa_key.pub. Lets
give the certificate a validity time of 90 days and limit it to principal sys1.example.com.
$ ssh-keygen -s /tmp/myCAkey.pub -D /usr/lib/pkcs11/opensc-pkcs11.so -V +90d -I sys1 -n sys1.example.com -h /tmp/sys1_ecdsa_key.pub Enter PIN for 'SmartCard-HSM (UserPIN)': Signed host key /tmp/sys1_ecdsa_key-cert.pub: id "sys1" serial 0 for sys1.example.com valid from 2020-10-20T21:39:00 to 2021-01-18T20:40:53
The certificate will be stored in /tmp/sys1_ecdsa_key-cert.pub, lets check it
$ ssh-keygen -L -f /tmp/sys1_ecdsa_key-cert.pub
sys1_ecdsa_key-cert.pub:
Type: ecdsa-sha2-nistp256-cert-v01@openssh.com host certificate
Public key: ECDSA-CERT SHA256:......
Signing CA: ECDSA SHA256:.... (using ecdsa-sha2-nistp521)
Key ID: "sys1"
Serial: 0
Valid: from 2020-10-20T21:39:00 to 2021-01-18T20:40:53
Principals:
sys1.example.com
Critical Options: (none)
Extensions: (none)
Epilogue¶
Turn on command history logging ... or do a plain exit from shell
$ set -o history
Or
$ exit