CryptoCorner YubiKey 5 - pkcs11-tool

Simple start with Yubico PKCS#11 library

In this demo I will use a fresh installed YubiKey 5 NFC token, using YubiKey Manager for Windows you easily can change token settings and modify the configuration of the token.

With the same tool you can change the PIN and PUK of the token. The default PIN is “123456” and the default PUK for YubiKey PIV token is “12345678”. In this demo I will not change the default values.

First, list objects on a fresh initalized YubiKey 5 NFC token with PIV module enabled:

$ pkcs11-tool --module /usr/local/lib/libykcs11.so -L -l -p 123456 -O

 Available slots:
 Slot 0 (0x0): Yubico YubiKey OTP+FIDO+CCID 01 00
   token label        : YubiKey PIV #12042794
   token manufacturer : Yubico (www.yubico.com)
   token model        : YubiKey YK5
   token flags        : login required, rng, token initialized, PIN initialized
   hardware version   : 1.0
   firmware version   : 5.24
   serial num         : 12042794
   pin min/max        : 6/48
 Using slot 0 with a present token (0x0)
 Data object 24
   label:          'X.509 Certificate for PIV Attestation'
   application:    'X.509 Certificate for PIV Attestation'
   app_id:         1.3.6.1.4.1.41482.3
   flags:          
 Data object 31
   label:          'Discovery Object'
   application:    'Discovery Object'
   app_id:         2.16.840.1.101.3.7.2.96.80
   flags:          
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Attestation
   subject:    DN: CN=Yubico PIV Attestation
   ID:         19
 Private Key Object; RSA
   label:      Private key for PIV Attestation
   ID:         19
   Usage:      none
 Public Key Object; RSA 2048 bits
   label:      Public key for PIV Attestation
   ID:         19
   Usage:      encrypt, verify

Generate RSA key pairs on YubiKey 5 PIV

To generate a key pair on the YubiKey 5 NFC token you can use yubico-piv-tool with option “generate”. The tool answers that a private key is generated, but technically a private key and a public key is generated.

yubico-piv-tool -s 9a -a generate -o pubkey.pem
 Successfully generated a new private key.

Let’s see what is new on the token after generating the key pair:

$ pkcs11-tool --module /usr/local/lib/libykcs11.so -L -l -p 123456 -O

 Available slots:
 Slot 0 (0x0): Yubico YubiKey OTP+FIDO+CCID 01 00
   token label        : YubiKey PIV #12042794
   token manufacturer : Yubico (www.yubico.com)
   token model        : YubiKey YK5
   token flags        : login required, rng, token initialized, PIN initialized
   hardware version   : 1.0
   firmware version   : 5.24
   serial num         : 12042794
   pin min/max        : 6/48
 Using slot 0 with a present token (0x0)
 Data object 24
   label:          'X.509 Certificate for PIV Attestation'
   application:    'X.509 Certificate for PIV Attestation'
   app_id:         1.3.6.1.4.1.41482.3
   flags:          
 Data object 31
   label:          'Discovery Object'
   application:    'Discovery Object'
   app_id:         2.16.840.1.101.3.7.2.96.80
   flags:          
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Attestation
   subject:    DN: CN=Yubico PIV Attestation
   ID:         19
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Attestation 9a
   subject:    DN: CN=YubiKey PIV Attestation 9a
   ID:         01
 Private Key Object; RSA
   label:      Private key for PIV Authentication
   ID:         01
   Usage:      decrypt, sign
 Private Key Object; RSA
   label:      Private key for PIV Attestation
   ID:         19
   Usage:      none
 Public Key Object; RSA 2048 bits
   label:      Public key for PIV Authentication
   ID:         01
   Usage:      encrypt, verify
 Public Key Object; RSA 2048 bits
   label:      Public key for PIV Attestation
   ID:         19
   Usage:      encrypt, verify

The marked objects in red are the new generated objects:

  1. a private RSA key for signing and decryption, identifyable by ID 01 and type private key
  2. a corresponding public RSA key for encryption and verification, also identifyable by ID 01 but of type public-key

Start with X.509 certificates

Now we can generate a self-signed certificate with this key pair. In this example I use yubico-piv-tool, but you also can use OpenSSL.

$ yubico-piv-tool -a verify-pin -a selfsign-certificate -s 9a -S "/CN=aschuster/" -i pubkey.pem -o X509_certificate.pem
 Enter PIN:
 Successfully verified PIN.
 Successfully generated a new self signed certificate.

The result is a X.509 certificate that is saved in file X509_certificate.pem but not yet stored on the YubiKey 5 NFC token.

Again we check the objects (option -O) on the token:

$ pkcs11-tool --module /usr/local/lib/libykcs11.so -L -l -p 123456 -O

 Available slots:
 Slot 0 (0x0): Yubico YubiKey OTP+FIDO+CCID 01 00
   token label        : YubiKey PIV #12042794
   token manufacturer : Yubico (www.yubico.com)
   token model        : YubiKey YK5
   token flags        : login required, rng, token initialized, PIN initialized
   hardware version   : 1.0
   firmware version   : 5.24
   serial num         : 12042794
   pin min/max        : 6/48
 Using slot 0 with a present token (0x0)
 Data object 24
   label:          'X.509 Certificate for PIV Attestation'
   application:    'X.509 Certificate for PIV Attestation'
   app_id:         1.3.6.1.4.1.41482.3
   flags:          
 Data object 31
   label:          'Discovery Object'
   application:    'Discovery Object'
   app_id:         2.16.840.1.101.3.7.2.96.80
   flags:          
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Attestation
   subject:    DN: CN=Yubico PIV Attestation
   ID:         19
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Attestation 9a
   subject:    DN: CN=YubiKey PIV Attestation 9a
   ID:         01
 Private Key Object; RSA
   label:      Private key for PIV Authentication
   ID:         01
   Usage:      decrypt, sign
 Private Key Object; RSA
   label:      Private key for PIV Attestation
   ID:         19
   Usage:      none
 Public Key Object; RSA 2048 bits
   label:      Public key for PIV Authentication
   ID:         01
   Usage:      encrypt, verify
 Public Key Object; RSA 2048 bits
   label:      Public key for PIV Attestation
   ID:         19
   Usage:      encrypt, verify

The content of the .pem file is suitable for any openssl or yubico-piv-tool operation.

$ more X509_certificate.pem

 -----BEGIN CERTIFICATE-----
 MIIC/jCCAeagAwIBAgIJAOz1FJ4XD+VIMA0GCSqGSIb3DQEBCwUAMBQxEjAQBgNV
 BAMMCWFzY2h1c3RlcjAeFw0yMDEyMjIyMjQ5MzdaFw0yMTEyMjIyMjQ5MzdaMBQx
 EjAQBgNVBAMMCWFzY2h1c3RlcjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC
 ggEBALYCwGHN0kmUrCS71esfAqs1rHrVuK9e9RguNq36OC9+50xUGyygS37QfIsE
 yIdWLu2gWS9sG7gyY5wnfJnfizlvzRiZih8DR4wXq89SOziLM/q8vO7zxbKOT4up
 UonfJm6VNg5u3grr4fZ2vmjD1iSllnfHEVNjt0LQ4+cRY9oolCYnTQ/2XuIM++ws
 hYogfuLkNw3KF9gVU0uhms0gkw8t9IOEoz7GkyoFMyKaW0Amvfz7nFPSWCbx+91M
 9Jj0Dw/4uiy3v16HVfqUCiLy3pwTAiDYg0k5mUfiSwEw95XzxbuR5zBEs5S2sHaO
 DooRCqZxdozgy4uu1eZPEYRNtsECAwEAAaNTMFEwHQYDVR0OBBYEFNRsh69kq2oZ
 D/I6rCgzWjmXCCu0MB8GA1UdIwQYMBaAFNRsh69kq2oZD/I6rCgzWjmXCCu0MA8G
 A1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBADtWqlnFDRLPJJci4dEX
 d4ODbqjIGueRMVT3LXJ0XOS3BuWF0/OtBUOmOtGvoBtSd8cs7QIIJZ/4ShY7h4ci
 raXDCWT6mGPr0RSsyG3pVrqnJMivdseeWMJCRWm/ewOu6q/kHb3DE1NEOgI3Vcfe
 dNnjOjyTFNZyXR05mZKuBSgAvcVQ4k5CKH132aOB2NRfjRjITMVwbtz33L0VftYP
 ufgOIvGRsTvdWriOhJsRurc4+Q7MDUOQbL5XgrF5u3SEttljHnDQ+c3UyYBAqwUw
 wogetOJfKFBl09oT7YV7C7rFu7KjtcUpsxdX3wGiuS90pemtGzDNiXJOTp2v/aYa
 9vs=
 -----END CERTIFICATE-----

Now import the certificate file to the YubiKey 5 token:

$ yubico-piv-tool -a import-certificate -s 9a -i X509_certificate.pem
 Successfully imported a new certificate.

Now we can re-check the objects on the token:

$ pkcs11-tool --module /usr/local/lib/libykcs11.so -L -l -p 123456 -O

 Available slots:
 Slot 0 (0x0): Yubico YubiKey OTP+FIDO+CCID 01 00
   token label        : YubiKey PIV #12042794
   token manufacturer : Yubico (www.yubico.com)
   token model        : YubiKey YK5
   token flags        : login required, rng, token initialized, PIN initialized
   hardware version   : 1.0
   firmware version   : 5.24
   serial num         : 12042794
   pin min/max        : 6/48
 Using slot 0 with a present token (0x0)
 Data object 0
   label:          'X.509 Certificate for PIV Authentication'
   application:    'X.509 Certificate for PIV Authentication'
   app_id:         2.16.840.1.101.3.7.2.1.1
   flags:          
 Data object 24
   label:          'X.509 Certificate for PIV Attestation'
   application:    'X.509 Certificate for PIV Attestation'
   app_id:         1.3.6.1.4.1.41482.3
   flags:          
 Data object 31
   label:          'Discovery Object'
   application:    'Discovery Object'
   app_id:         2.16.840.1.101.3.7.2.96.80
   flags:          
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Authentication
   subject:    DN: CN=aschuster
   ID:         01
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Attestation
   subject:    DN: CN=Yubico PIV Attestation
   ID:         19
 Certificate Object; type = X.509 cert
   label:      X.509 Certificate for PIV Attestation 9a
   subject:    DN: CN=YubiKey PIV Attestation 9a
   ID:         01
 Private Key Object; RSA
   label:      Private key for PIV Authentication
   ID:         01
   Usage:      decrypt, sign
 Private Key Object; RSA
   label:      Private key for PIV Attestation
   ID:         19
   Usage:      none
 Public Key Object; RSA 2048 bits
   label:      Public key for PIV Authentication
   ID:         01
   Usage:      encrypt, verify
 Public Key Object; RSA 2048 bits
   label:      Public key for PIV Attestation
   ID:         19
   Usage:      encrypt, verify

The X.509 certificate is marked in blue. We are ready to use many different tools with the newly generated keys and the X.509 certificate. You also can manage the certificate on a token using the YubiKey Manager tool.

More information

This post is part of #CryptoCorner my contribution to open source cryptography and secure hardware key storage to reduce risks from misunderstood and unsecure implemented key management.

Please see my previous and related posts how to compile PKCS#11 libraries and configure cryptographic modules like OpenSC to be used.

The most common open source PKCS#11 libraries are found at this locations:

/usr/local/lib/softhsm/libsofthsm2.so
/usr/local/lib/libykcs11.so
/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

libsofthsm2.so – The PKCS#11 library of SoftHSM2 a popular software defines key store. You need to install or compile SoftHSM2 to get this library.

libykcs11.so – The Yubico PKCS#11 library for all YubiKey token with smart card PIV functionallity. Install and compile Yubico yubico-piv-tool to use.

opensc-pkcs11.so – The popular OpenSC PKCS#11 library supporting many smart cards and PKI token. Install or compile package opensc to use this software interface.

Related Posts

Ein Gedanke zu „Simple start with Yubico PKCS#11 library“

  1. It is very clearly written.

    Windows 10 opensc-pkcs11.dll can no longer access the certificate.

    I checked with smartcard at https://www.softether.org/ and it is no longer accessible.
    I had to rename opensc-pkcs11.dll to P11STD9A.dll to access it.

    yubikey4 was accessible.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert