OpenSSL PKCS#11 Engine
Engine_pkcs11 is an implementation of an engine for OpenSSL. It can beloaded using code, a configuration file, or the command line and passesany function call by openssl to a PKCS#11 module. Engine_pkcs11 ismeant to be used with smart cards and software for using smart cards inPKCS#11 format, such as OpenSC. Originally, this engine was part ofOpenSC until OpenSC was split into several small projects to improveflexibility.
Enginepkcs11 is an implementation of an engine for OpenSSL. It can be loaded using code, a configuration file, or the command line and passes any function call by openssl to a PKCS#11 module. Enginepkcs11 is meant to be used with smart cards and software for using smart cards in PKCS#11 format, such as OpenSC. PKCS#11 API model defines a specific terminology which needs to be understood in order to use the PKCS#11 API model in your applications. Cryptoki (Cryptographic Token Interface) is a library (DLL or SO file) that is provided by the cryptographic device vendors. It contains an implementation of the PKCS#11 C header files. Sudo apt install libengine-pkcs11-openssl suisseid-pkcs11 opensc openssl osslsigncode swisssign-init. If you haven't initialized your SuisseID, do it now. You should have received a TIN / PUK Sheet from SwissSign with the transport PIN (TIN). Run swisssign-init and follow the instructions. Set a PIN, that you will need below. OpenSSL req -engine pkcs11 -new -key id45 -keyform engine -text -config openssl.cnf initializing engine engine 'pkcs11 ' set. Found 8 slots 0 AKS ifdh 0 login. I have softhsm-v2.5.0-rc1 which has ec keys imported in it. Now, when I try to use these keys from openssl CLI using the pkcs11 engine, it fails. SoftHSM version :$ softhsm2-util -version 2.5.0rc1 SoftHSM token init.
There is no official package available for openSUSE Leap 15.2Distributions
openSUSE Tumbleweed
SUSE SLE-11 SP 4
Unsupported distributions
openSUSE:11.4
openSUSE:12.1
openSUSE:12.2
openSUSE:12.3
openSUSE:13.1
openSUSE:13.2
openSUSE:Leap:42.1
openSUSE:Leap:42.2
openSUSE:Leap:42.3
openSUSE:11.1
SUSE:SLE-12:SLE-Module-Toolchain
SUSE:SLE-11:SP3
DISCONTINUED:openSUSE:11.1
[UPDATED 2020.06.29]
I already covered how baffling smart cards hardware and standards can be:
But now that you - and presumably I - are no longer in a state of utterhelplessness when confronted by smart cards mumbo jumbo, let's see whatclever things we can do with them. Coming to mind:
Two-factor authentication: PAM, Kerberos, SSH, VPN, web, etc.
E-mail: signature and encryption
Now, each of those buzzwords may be familiar to the Linux layman. But - oh dear! -what intricacies, pitfalls, frustrations and sense of despair they entice whensmart cards come into play!
Here be dragons!
Some background
For the sake of the examples below, we'll assume the following:
a PKI smart card from Aventra (MyEID 4.0.0)
used with two PIN codes
one for each purpose: login (authentication) and e-mail
along a card reader from HID Global (Omnikey 3x21 or 5422)
And for the sake of completeness, we'll use:
a smart card-generated login keypair
(you loose your card, you're out, you dumbass!)an externally-generated (and backed-up!) e-mail keypair(better still be able to decrypt those e-mails, though, huh?!)
Software versions
Although all necessary packages are readily available in Debian/Stretch, ourchosen use case and hardware requires that we use packages from Debian/Buster:
for the Aventra MyEID (4.0.0) smart card (using multiple PINs):
opensc>= 0.18.0for the HID Omnikey 5422 card reader:
libccid>= 1.4.27
PKCS#15
The first step is to initalize the smart card and create the necessary PKCS#15structure, along the PIN codes - aka. tokens/slots - for our declared purposes.
Install the required Debian packages:
PKCS#15 initialization:
PINs/PUKs (tokens/slots) creation:
Key pairs and (X.509) certificates
Next, we need to generate/import the required PKI material in each token/slot.
Login keypair generation:
Login certificate import (after having its CSR properly signed; see the OpenSSL section further below):
E-mail key/certificate import (externally-generated and exported into aPKCS#12 bundle; see the OpenSSL section further below):
Smart card preparation finalization
Now that we're done with the smart card itself, we can 'finalize' its preparation:
The exact meaning of this step depends on the actual smart card vendor.
- on the Aventra MyEID, this switches the card from Creation State to OperationalState; PINs creation are then no longer possible and all access conditions areenforced
PKCS#11
Using smart cards for our purposes will in all cases be achieved thanks to thePKCS#11 software API/stack.
Install the required Debian packages:
Harden the default OpenSC configuration, in
/etc/opensc/opensc.conf
:And test its functioning:
WARNINGS:
- Aventra MyEID smart cards are known to raise (PKCS#11) issues with multiple PINs, unless OpenSC >= 0.18 is used(REF)
PKCS#11 URI
Some libraries and utilities may require you to provide so-called PKCS#11 URIas private key or certificate parameters. Those URIs are standardized by theRFC 7512 and look like:
LibNSS (Thunderbird/Firefox/Chromium)
PKCS#11 support is implemented in Mozilla Thunderbird, Firefox and GoogleChromium thanks to the libnss3
Network Security Services (NSS) library:
Add OpenSC driver to NSSDB:
NOTE: For Thunderbird and Firefox, you may need to specify the path to your profile instead of the home directory ~/.pki/nssdb
location. Look fora pkcs11.txt
file, where modutil
will actually have added its magic.
WARNING: For Thunderbird, make sure the emailAddress
attribute is includedin the certificate DN
(as opposed to theRFC 3850, §.3recommendation) or it will complain about not being able to find the certificateat the moment the message is sent (albeit being correctly configured in theAccount Settings
>Security
section).
OpenSSL
OpenSSL shall be required to generate the Certificate Signing Request (CSR)corresponding to our login key, as well as issuing the CA-signed X.509certificates for both login and email purposes. Generally speaking, thisimplies:
Install the required Debian packages:
Create the PKCS#11-friendly
openssl.conf
:Check the engine is properly configured
Create a CSR from a smart card private key:
Create a self-signed certificate from a smart card private key:
CA-signing a certificate, with the CA private key stored on a smart card:
OpenSSL being the horrifying piece of software that it is (at least to my simpleself), I invite you to discover OpenSSL-Easy, my humble and certainly poorattempt at making one's OpenSSL life easier:
cURL
cURL relies on OpenSSL engine to perform its PKCS#11 magic. Once the engineinstalled (see above), it is just a matter of using the proper PKCS#11 URIsas private key and certificate arguments:
Secure Shell (SSH)
Openssl Pkcs11 Engine Slots
Using the smart card along SSH for RSA-based authentication is straight-forward,except for one BIG gotcha (see the WARNINGS further below).
Export the public key to your SSH authorized keys:
Login using your smart card:
Optionally temporarily storing your key in the SSH agent:
And correctly removing it from the SSH agent once done with it:
WARNINGS:
- When using multiple PINs and until the changes proposed by RedHat/Fedora areintegrated in OpenSSH:Fedora 28: Better smart card support in OpenSSH
One MUST use OpenSC'sonepin-opensc-pkcs11.so
library to prevent the SSHagent from attempting to unlock all tokens/slots with the same PIN andeventually locking those tokens/slots that do not match.This is also the reason why one MUST create the login token/slot as thefirst one on the smart card.
MIT Kerberos V
Openssl Engine
Using public key material instead of passwords for Kerberos authenticationis known as PKINIT:
Setting it up is rather straight-forward, albeit not devoid of gotchas (seethe WARNINGS further below).
Install the required Debian packages (on both servers and clients):
Generating the required servers certificates implies delving into OpenSSL;once again, one's life may be easier thanks to OpenSSL-Easy:
OpenSSL-Easy (Authentication section)Debug the Kerberos-specific ASN.1 Subject Alternative Name (SAN) with:
Configure the Kerberos Key Distribution Center (KDC) servers;in
/etc/krb5kdc/kdc.conf
:Configure the Kerberos clients; in
/etc/krb5.conf
:
WARNINGS:
MIT Kerberos V does not allow to enforce PKINIT; if it fails, it willautomatically revert to password-based authentication
If one is willing to enforce smart card-based authentication, one shouldlook into using the PAM PKCS#11 module instead of PKINIT (see section below)
Pluggable Authentication Module (PAM)
Using the smart card for authenticating on a Linux box implies adding the PKCS#11module - pam_pkcs11
- to the PAM stack. Again, nothing particularly complicated,except a few gotchas (see the WARNINGS further below).
Install the required Debian packages:
Configure the PAM PKCS#11 module; in
/etc/pam_pkcs11/pam_pkcs11.conf
:Configure the PAM authentication stack, in
/etc/pam.d/common-auth
:
WARNINGS:
If MIT Kerberos V is configured for PKINIT (in
/etc/krb5.conf
),pam_krb5
will attempt PKINIT authentication, when password-based fails, even iftry_pkinit
is not specifiedAt the time of writing, PAM PKCS#11 module will segfault if any form ofCRL check is attempted
The smart card PIN code will be stored by
pam_pkcs11
and used as 'password'by subsequent modules (e.g.pam_gnome_keyring
); this can lead to akward - ifnot unsecure - results; thus our mandating password (Kerberos/LDAP)authentication once PKCS#11's succeeded
(see this as 'two+'-factor authentication)
Apache (client) authentication
Using the smart card for (client) authentication on the Apache web server in aLDAP-centric environment is far - very far! - from trivial.
I invite you to read the article dedicated on the subject:
OpenVPN
Naively, one would think that using the smart card with OpenVPN would be assimple as:
Recovering the PKCS#11 ID(s) for use by OpenVPN:
And adding the relevant PKCS#11 stanza to OpenVPN (client) configuration:
Poor you! Nope! Not that easy! Well… Yes… That easy, provided you takeinto account the following well-(and-longime)-known bugs:
Shortly put, you will just need to:
retrieve OpenVPN and PKCS#11 helper source packages
apply the patches mentioned in the two above bug reports
make sure to disable PKCS#11 helper (multi-)threading
build the corresponding new Debian packages
and install them
… what!?!…
GNU Privacy Guard (GnuPG)
GnuPG is expected to be natively used along ad-hoc OpenPGP cards, totallydifferent beasts from the PKCS#15 and X.509-oriented smart cards we're nowgrowing accustomed to.
Howevever, GnuPG can be made to work with those, again via the PKCS#11 interfaceand some additional trickery:
Install the required Debian package:
Configure the GnuPG Agent, in
~/.gnupg/gpg-agent.conf
:Configure the GnuPG PKCS#11 Smart Card Daemon (SCD), in
~/.gnupg/gnupg-pkcs11-scd.conf
:Where the
and
are recovered with:
Reload the GnuPG Agent and verify everything is ready:
openSUSE:13.2
openSUSE:Leap:42.1
openSUSE:Leap:42.2
openSUSE:Leap:42.3
openSUSE:11.1
SUSE:SLE-12:SLE-Module-Toolchain
SUSE:SLE-11:SP3
DISCONTINUED:openSUSE:11.1
[UPDATED 2020.06.29]
I already covered how baffling smart cards hardware and standards can be:
But now that you - and presumably I - are no longer in a state of utterhelplessness when confronted by smart cards mumbo jumbo, let's see whatclever things we can do with them. Coming to mind:
Two-factor authentication: PAM, Kerberos, SSH, VPN, web, etc.
E-mail: signature and encryption
Now, each of those buzzwords may be familiar to the Linux layman. But - oh dear! -what intricacies, pitfalls, frustrations and sense of despair they entice whensmart cards come into play!
Here be dragons!
Some background
For the sake of the examples below, we'll assume the following:
a PKI smart card from Aventra (MyEID 4.0.0)
used with two PIN codes
one for each purpose: login (authentication) and e-mail
along a card reader from HID Global (Omnikey 3x21 or 5422)
And for the sake of completeness, we'll use:
a smart card-generated login keypair
(you loose your card, you're out, you dumbass!)an externally-generated (and backed-up!) e-mail keypair(better still be able to decrypt those e-mails, though, huh?!)
Software versions
Although all necessary packages are readily available in Debian/Stretch, ourchosen use case and hardware requires that we use packages from Debian/Buster:
for the Aventra MyEID (4.0.0) smart card (using multiple PINs):
opensc>= 0.18.0for the HID Omnikey 5422 card reader:
libccid>= 1.4.27
PKCS#15
The first step is to initalize the smart card and create the necessary PKCS#15structure, along the PIN codes - aka. tokens/slots - for our declared purposes.
Install the required Debian packages:
PKCS#15 initialization:
PINs/PUKs (tokens/slots) creation:
Key pairs and (X.509) certificates
Next, we need to generate/import the required PKI material in each token/slot.
Login keypair generation:
Login certificate import (after having its CSR properly signed; see the OpenSSL section further below):
E-mail key/certificate import (externally-generated and exported into aPKCS#12 bundle; see the OpenSSL section further below):
Smart card preparation finalization
Now that we're done with the smart card itself, we can 'finalize' its preparation:
The exact meaning of this step depends on the actual smart card vendor.
- on the Aventra MyEID, this switches the card from Creation State to OperationalState; PINs creation are then no longer possible and all access conditions areenforced
PKCS#11
Using smart cards for our purposes will in all cases be achieved thanks to thePKCS#11 software API/stack.
Install the required Debian packages:
Harden the default OpenSC configuration, in
/etc/opensc/opensc.conf
:And test its functioning:
WARNINGS:
- Aventra MyEID smart cards are known to raise (PKCS#11) issues with multiple PINs, unless OpenSC >= 0.18 is used(REF)
PKCS#11 URI
Some libraries and utilities may require you to provide so-called PKCS#11 URIas private key or certificate parameters. Those URIs are standardized by theRFC 7512 and look like:
LibNSS (Thunderbird/Firefox/Chromium)
PKCS#11 support is implemented in Mozilla Thunderbird, Firefox and GoogleChromium thanks to the libnss3
Network Security Services (NSS) library:
Add OpenSC driver to NSSDB:
NOTE: For Thunderbird and Firefox, you may need to specify the path to your profile instead of the home directory ~/.pki/nssdb
location. Look fora pkcs11.txt
file, where modutil
will actually have added its magic.
WARNING: For Thunderbird, make sure the emailAddress
attribute is includedin the certificate DN
(as opposed to theRFC 3850, §.3recommendation) or it will complain about not being able to find the certificateat the moment the message is sent (albeit being correctly configured in theAccount Settings
>Security
section).
OpenSSL
OpenSSL shall be required to generate the Certificate Signing Request (CSR)corresponding to our login key, as well as issuing the CA-signed X.509certificates for both login and email purposes. Generally speaking, thisimplies:
Install the required Debian packages:
Create the PKCS#11-friendly
openssl.conf
:Check the engine is properly configured
Create a CSR from a smart card private key:
Create a self-signed certificate from a smart card private key:
CA-signing a certificate, with the CA private key stored on a smart card:
OpenSSL being the horrifying piece of software that it is (at least to my simpleself), I invite you to discover OpenSSL-Easy, my humble and certainly poorattempt at making one's OpenSSL life easier:
cURL
cURL relies on OpenSSL engine to perform its PKCS#11 magic. Once the engineinstalled (see above), it is just a matter of using the proper PKCS#11 URIsas private key and certificate arguments:
Secure Shell (SSH)
Openssl Pkcs11 Engine Slots
Using the smart card along SSH for RSA-based authentication is straight-forward,except for one BIG gotcha (see the WARNINGS further below).
Export the public key to your SSH authorized keys:
Login using your smart card:
Optionally temporarily storing your key in the SSH agent:
And correctly removing it from the SSH agent once done with it:
WARNINGS:
- When using multiple PINs and until the changes proposed by RedHat/Fedora areintegrated in OpenSSH:Fedora 28: Better smart card support in OpenSSH
One MUST use OpenSC'sonepin-opensc-pkcs11.so
library to prevent the SSHagent from attempting to unlock all tokens/slots with the same PIN andeventually locking those tokens/slots that do not match.This is also the reason why one MUST create the login token/slot as thefirst one on the smart card.
MIT Kerberos V
Openssl Engine
Using public key material instead of passwords for Kerberos authenticationis known as PKINIT:
Setting it up is rather straight-forward, albeit not devoid of gotchas (seethe WARNINGS further below).
Install the required Debian packages (on both servers and clients):
Generating the required servers certificates implies delving into OpenSSL;once again, one's life may be easier thanks to OpenSSL-Easy:
OpenSSL-Easy (Authentication section)Debug the Kerberos-specific ASN.1 Subject Alternative Name (SAN) with:
Configure the Kerberos Key Distribution Center (KDC) servers;in
/etc/krb5kdc/kdc.conf
:Configure the Kerberos clients; in
/etc/krb5.conf
:
WARNINGS:
MIT Kerberos V does not allow to enforce PKINIT; if it fails, it willautomatically revert to password-based authentication
If one is willing to enforce smart card-based authentication, one shouldlook into using the PAM PKCS#11 module instead of PKINIT (see section below)
Pluggable Authentication Module (PAM)
Using the smart card for authenticating on a Linux box implies adding the PKCS#11module - pam_pkcs11
- to the PAM stack. Again, nothing particularly complicated,except a few gotchas (see the WARNINGS further below).
Install the required Debian packages:
Configure the PAM PKCS#11 module; in
/etc/pam_pkcs11/pam_pkcs11.conf
:Configure the PAM authentication stack, in
/etc/pam.d/common-auth
:
WARNINGS:
If MIT Kerberos V is configured for PKINIT (in
/etc/krb5.conf
),pam_krb5
will attempt PKINIT authentication, when password-based fails, even iftry_pkinit
is not specifiedAt the time of writing, PAM PKCS#11 module will segfault if any form ofCRL check is attempted
The smart card PIN code will be stored by
pam_pkcs11
and used as 'password'by subsequent modules (e.g.pam_gnome_keyring
); this can lead to akward - ifnot unsecure - results; thus our mandating password (Kerberos/LDAP)authentication once PKCS#11's succeeded
(see this as 'two+'-factor authentication)
Apache (client) authentication
Using the smart card for (client) authentication on the Apache web server in aLDAP-centric environment is far - very far! - from trivial.
I invite you to read the article dedicated on the subject:
OpenVPN
Naively, one would think that using the smart card with OpenVPN would be assimple as:
Recovering the PKCS#11 ID(s) for use by OpenVPN:
And adding the relevant PKCS#11 stanza to OpenVPN (client) configuration:
Poor you! Nope! Not that easy! Well… Yes… That easy, provided you takeinto account the following well-(and-longime)-known bugs:
Shortly put, you will just need to:
retrieve OpenVPN and PKCS#11 helper source packages
apply the patches mentioned in the two above bug reports
make sure to disable PKCS#11 helper (multi-)threading
build the corresponding new Debian packages
and install them
… what!?!…
GNU Privacy Guard (GnuPG)
GnuPG is expected to be natively used along ad-hoc OpenPGP cards, totallydifferent beasts from the PKCS#15 and X.509-oriented smart cards we're nowgrowing accustomed to.
Howevever, GnuPG can be made to work with those, again via the PKCS#11 interfaceand some additional trickery:
Install the required Debian package:
Configure the GnuPG Agent, in
~/.gnupg/gpg-agent.conf
:Configure the GnuPG PKCS#11 Smart Card Daemon (SCD), in
~/.gnupg/gnupg-pkcs11-scd.conf
:Where the
and
are recovered with:
Reload the GnuPG Agent and verify everything is ready:
Jupiter's casino gold coast entertainment guide. We can therefrom coerce GnuPG into being more X.509 (and S/MIME) friendly:
Import our CA root (and intermediate) certificate(s):
Import our smart cards certificates:
And associate the corresponding (smart card) private keys:
(TODO: unravel the misteries of using the smart card with gpg
itself)
WARNINGS:
- At the time of writing, all of this will only work with RSA keys!
Python requests library
Python requests is nowadays the most ubiquitouslibrary for doing HTTP(S).
However, PKCS#11 isn't natively supported and requires leveraging theM2Crypto library to hook the necessarygear work in, by replacing the https://
adapter (handler) by theM2HttpsAdapter
found in:
Which is as simple as it gets:
Encrypt/Decrypt data
Should you need to encrypt/decrypt data using your SmartCard:
Debugging
If you run into troubles, you can easily debug PKCS#11 interactions thanks toOpenSC's OPENSC_DEBUG
or PKCS11SPY
environment variables:
Shortcoming: Probabilistic Signature Scheme (PSS) not supported
Probabilistic Signature Scheme (PSS),now creeps in TLS connections relying on OpenSSL 1.1.1 or above. This mayprevent you to use your credentials on websites that moved on to TLS 1.3 or withOpenVPN (which stubbornly refuses to stick to TLS 1.2 and not use PSS),unless you use:
OpenSC 0.20.0 or above
Openssl Pkcs11
LibP11 0.4.8 or above (<-> OpenSSL engine)
Openssl Pkcs11 Engine Slot Machine
PKCS#11 Helper patch (forecoming 1.26.0 release <-> OpenVPN)
Openssl Pkcs11 Engine Slot Cars
Smart card?!? Easy!!!