PKCS11 Linux Setup
These instructions are for building, installing and configuring cryptoauthlib as a PKCS#11 provider. These instructions are for commonly available Linux systems with package managers.
IMPORTANT NOTICE
Linux does not support baud rate switching for I2C which means the only supported I2C clock
frequency for cryptoauth devices is 100kHz. USING ANY OTHER FREQUENCY CONFIGURATION WILL NOT WORK.
Use with other devices on the same I2C channel may be unreliable when using the following devices:
ATSH204A, ATSHA206A, ATECC508A, ATECC608A
The following devices may be used with other I2C devices on the same channel:
ATECC608B, ECC204
When automatic low power modes are enabled (all devices prefixed with AT and optional for ECC204)
the user will have to manage access to the the i2c device so operations with the cryptoauth parts
are not interrupted.
If one is not able to ensure exclusive access to the i2c device during operations with the
cryptoauth component then they should provide it with an exclusive i2c channel for reliable
operation
Incase you are working on an older version of Openssl (i.e., versions before Openssl 3.0), then use engines. For this update libp11 in the system.
-
Install the build dependencies for the system:
# Debian like systems $ sudo apt-get install cmake udev-dev# RPM based systems $ yum install cmake $ yum install libudev-devel- Get the latest version of cryptoauthlib
$ git clone https://github.com/MicrochipTech/cryptoauthlib
-
Rerun the build configuration tools:
$ cd cryptoauthlib $ cmake .
-
Build the library:
$ make
-
Install the library:
$ sudo make install
By default the following files will be created.
-
/etc/cryptoauthlib/cryptoauthlib.conf
# Cryptoauthlib Configuration File filestore = /var/lib/cryptoauthlib -
/var/lib/cryptoauthlib/slot.conf.tmpl
# Reserved Configuration for a device # The objects in this file will be created and marked as undeletable # These are processed in order. Configuration parameters must be comma- # delimited and may not contain spaces interface = i2c,0xB0 freeslots = 1,2,3 # Slot 0 is the primary private key object = private,device,0 # Slot 10 is the certificate data for the device's public key #object = certificate,device,10 # Slot 12 is the intermedate/signer certificate data #object = certificate,signer,12 # Slot 15 is a public key object = public,root,15
This file provides the basic configuation information for the library. The only variable is "filestore", which is where cryptoauthlib will find device specific configuration and store object files from PKCS#11 operations.
This is a template for device configuration files that cryptoauthlib will use to map devices and their resources into PKCS#11 tokens and objects.
A device file must be named <pkcs11_slot_number>.conf
For a single device:
$ cd /var/lib/cryptoauthlib
$ cp slot.conf.tmpl 0.confThen edit 0.conf to match the device configuration being used.
Valid values: 'hid', 'i2c'
If using i2c specify the address in hex for the device. This is in the device format (upper 7 bits define the address) so will not appear the same as the i2cdetect address (lower 7 bits)
This is a list of slots that may be used by the library when a PKCS#11 operation that creates new objects is used. When the library is initialized it will scan for files of the form <pkcs11_slot_num>.<device_slot_num>.conf which defines the object using that device resource.
Providers are introduced from Openssl 3.0+ versions. If using an older version of Openssl use engines. If using Openssl 3.0+ versions, follow the below steps for installing pkcs11-provider in your system
Install the build dependendencies for pkcs11 provider in the system
-
Openssl 3.0+ libraries and development headers:
# Debian like systems $ sudo apt-get install openssl libssl-dev# RPM based systems $ sudo yum install openssl $ sudo yum install openssl-devel -
Install Meason for pkcs11 provider build
# Debian like systems $ sudo apt install build-essential $ sudo apt install meson ninja-build# RPM based systems $ sudo dnf install gcc $ sudo yum install meson ninja -
pkg-config
# Debian like systems $ sudo apt-get install pkg-config# RPM based systems # pkg-config will be already installed as part of openssl-devel
-
get the latest version of pkcs11-provider
$ git clone https://github.com/latchset/pkcs11-provider.git
-
Build pkcs11-provider
$ meson setup builddir $ meson compile -C builddir
To link with OpenSSL installed in a custom path, set PKG_CONFIG_PATH, or CFLAGS/LDFLAGS envvars accordingly at the meson setup step. For example, let's assume OpenSSL is installed under an absolute path $OPENSSL_DIR.
If you rely on pkg-config, point PKG_CONFIG_PATH to a directory where libcrypto.pc or openssl.pc can be found.
- Install pkcs11-provider
$ sudo meson install -C builddir
For using engines update libp11 tool in the system.
-
Install the build dependendencies for the system:
# Debian like systems $ sudo apt-get build-dep libengine-pkcs11-openssl1.1# RPM based systems $ yum-builddep engine-pkcs11 -
Get the latest version of libp11
$ git clone https://github.com/OpenSC/libp11.git
-
Rerun the build configuration tools:
$ cd libp11 $ ./bootstrap $ ./configure -
Build the library:
$ make
-
Install the library:
$ sudo make install
This is an optional step but is very helpful for using multiple PKCS#11 libraries in a system. Detailed setup can be found at p11-glue
# Debian like systems
$ sudo apt-get install p11-kit # RPM based systems
$ yum install p11-kit-
Create or edit the global configuration file: /etc/pkcs11/pkcs11.conf
# This setting controls whether to load user configuration from the # ~/.config/pkcs11 directory. Possible values: # none: No user configuration # merge: Merge the user config over the system configuration (default) # only: Only user configuration, ignore system configuration user-config: merge -
Create a module configuration file: User module name (only available for a single user): ~/.config/pkcs11/modules/cryptoauthlib.module Global module name (available to the whole system): /usr/share/p11-kit/modules/cryptoauthlib.module
module: /usr/lib/libcryptoauth.so critical: yes trust-policy: yes managed: yes log-calls: no
For more details on the configuration files see the configuration documentation
OpenSSL (via the pkcs11-provider or libp11 project above) and p11tool support p11-kit-proxy natively so do not require additional set up if it is being used. If p11-kit-proxy is not being used then OpenSSL will have to be manually configured to use libp11 and cryptoauthlib
This requires editing the default openssl.cnf file. To locate the file being used by the system run the following command:
$ openssl version -a | grep OPENSSLDIR:
OPENSSLDIR: "/usr/lib/ssl"This gives the default path where openssl is compiled to find the openssl.cnf file
In this case the file to edit will be /usr/lib/ssl/openssl.cnf
This line must be placed at the top, before any sections are defined:
openssl_conf = openssl_init
For OpenSSL versions with and above 3.0, to use providers this should be added to the bottom of the file:
[openssl_init]
providers = provider_sect
# List of providers to load
[provider_sect]
default = default_sect
pkcs11 = pkcs11_sect
[pkcs11_sect]
module = /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so
pkcs11-module-path = /usr/lib/libcryptoauth.so
activate = 1
[default_sect]
activate = 1
For OpenSSL versions below 3.0, to use engine this should be added to the bottom of the file:
[openssl_init]
engines=engine_section
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id = pkcs11
# Wherever the engine installed by libp11 is. For example it could be:
# /usr/lib/arm-linux-gnueabihf/engines-1.1/libpkcs11.so
dynamic_path = /usr/lib/ssl/engines/libpkcs11.so
MODULE_PATH = /usr/lib/libcryptoauth.so
init = 0
To use p11tool it has to be installed:
# Debian like systems
$ sudo apt-get install gnutls-bin # RPM based systems
$ yum install gnutls-utilsNote: If not using p11-kit-proxy then the provider has to be specified in p11tool calls:
$ p11tool --provider /usr/lib/libcryptoauth.so-
Get the public key for a private key (as defined by the 0.conf file cited above):
$ p11tool --export-pubkey "pkcs11:token=0123EE;object=device;type=private" warning: --login was not specified and it may be required for this operation. warning: no --outfile was specified and the public key will be printed on screen. -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9wzUq1EUAoNrG01rXYjNd35mxKuA Ojw/klIrNEBciSLLOTLjs/gvFS7N8AFXDK18vpxxu6ykzF2LRd7RY8yEFw== -----END PUBLIC KEY-----
-
Get the public key and decode it using OpenSSL
$ p11tool --export-pubkey "pkcs11:token=0123EE;object=device;type=private" | openssl pkey -pubin -text -noout warning: --login was not specified and it may be required for this operation. warning: no --outfile was specified and the public key will be printed on screen. Public-Key: (256 bit) pub: 04:f7:0c:d4:ab:51:14:02:83:6b:1b:4d:6b:5d:88: cd:77:7e:66:c4:ab:80:3a:3c:3f:92:52:2b:34:40: 5c:89:22:cb:39:32:e3:b3:f8:2f:15:2e:cd:f0:01: 57:0c:ad:7c:be:9c:71:bb:ac:a4:cc:5d:8b:45:de: d1:63:cc:84:17 ASN1 OID: prime256v1 NIST CURVE: P-256
-
Create a CSR for the private key using providers(OpenSSl version 3.x)
# Using pkcs11-provider $ openssl req -provider pkcs11 -key "pkcs11:token=MCHP;object=ec256pvt;type=private" -new -out new_device.csr -subj "/CN=NEW CSR EXAMPLE" $ cat new_device.csr -----BEGIN CERTIFICATE REQUEST----- MIHUMHwCAQAwGjEYMBYGA1UEAwwPTkVXIENTUiBFWEFNUExFMFkwEwYHKoZIzj0C AQYIKoZIzj0DAQcDQgAE9AmWq0Jl2bE9Gwb9dr3QzCqflqL2dxIhjvT+TzTzV3yx gC6KuE8dZ7siDw3nT+wUW+l8Qne4YOB7+RCubXk3l6AAMAoGCCqGSM49BAMCA0gA MEUCIQDrgc81yagztxoDpl0KagjZ2ZxdAszGSL7jgTpkZqzrGwIgYhD4Gj+Rt3ZD ZP+CfGX8u7QjJR6q1bqT0VIubFlDX7w= -----END CERTIFICATE REQUEST-----
-
Create a CSR for the private key using engines(OpenSSl version 1.x)
# Using engine libp11 $ openssl req -engine pkcs11 -key "pkcs11:token=0123EE;object=device;type=private" -keyform engine -new -out new_device.csr -subj "/CN=NEW CSR EXAMPLE" engine "pkcs11" set. $ cat new_device.csr -----BEGIN CERTIFICATE REQUEST----- MIHVMHwCAQAwGjEYMBYGA1UEAwwPTkVXIENTUiBFWEFNUExFMFkwEwYHKoZIzj0C AQYIKoZIzj0DAQcDQgAE9wzUq1EUAoNrG01rXYjNd35mxKuAOjw/klIrNEBciSLL OTLjs/gvFS7N8AFXDK18vpxxu6ykzF2LRd7RY8yEF6AAMAoGCCqGSM49BAMCA0kA MEYCIQDUPeLfPcOwtZxYJDYXPdl2UhpReVn6kK2lKCCX6byM8QIhAIfqfnggtcCi W21xLAzabr8A4mHyfIIQ1ofYBg8QO9jZ -----END CERTIFICATE REQUEST-----
-
-
Verify the newly created csr using providers(OpenSSl version 3.x)
# Using pkcs11-provider $ openssl req -provider pkcs11 -in new_device.csr -verify -text -noout Certificate request self-signature verify OK Certificate Request: Data: Version: 1 (0x0) Subject: CN = NEW CSR EXAMPLE Subject Public Key Info: Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit) pub: 04:f4:09:96:ab:42:65:d9:b1:3d:1b:06:fd:76:bd: d0:cc:2a:9f:96:a2:f6:77:12:21:8e:f4:fe:4f:34: f3:57:7c:b1:80:2e:8a:b8:4f:1d:67:bb:22:0f:0d: e7:4f:ec:14:5b:e9:7c:42:77:b8:60:e0:7b:f9:10: ae:6d:79:37:97 ASN1 OID: prime256v1 NIST CURVE: P-256 Attributes: (none) Requested Extensions: Signature Algorithm: ecdsa-with-SHA256 Signature Value: 30:45:02:21:00:eb:81:cf:35:c9:a8:33:b7:1a:03:a6:5d:0a: 6a:08:d9:d9:9c:5d:02:cc:c6:48:be:e3:81:3a:64:66:ac:eb: 1b:02:20:62:10:f8:1a:3f:91:b7:76:43:64:ff:82:7c:65:fc: bb:b4:23:25:1e:aa:d5:ba:93:d1:52:2e:6c:59:43:5f:bc -
Verify the newly created csr using engines(OpenSSl version 1.x)
# Using engine libp11 $ openssl req -in new_device.csr -verify -text -noout verify OK Certificate Request: Data: Version: 1 (0x0) Subject: CN = NEW CSR EXAMPLE Subject Public Key Info: Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit) pub: 04:f7:0c:d4:ab:51:14:02:83:6b:1b:4d:6b:5d:88: cd:77:7e:66:c4:ab:80:3a:3c:3f:92:52:2b:34:40: 5c:89:22:cb:39:32:e3:b3:f8:2f:15:2e:cd:f0:01: 57:0c:ad:7c:be:9c:71:bb:ac:a4:cc:5d:8b:45:de: d1:63:cc:84:17 ASN1 OID: prime256v1 NIST CURVE: P-256 Attributes: a0:00 Signature Algorithm: ecdsa-with-SHA256 30:46:02:21:00:d4:3d:e2:df:3d:c3:b0:b5:9c:58:24:36:17: 3d:d9:76:52:1a:51:79:59:fa:90:ad:a5:28:20:97:e9:bc:8c: f1:02:21:00:87:ea:7e:78:20:b5:c0:a2:5b:6d:71:2c:0c:da: 6e:bf:00:e2:61:f2:7c:82:10:d6:87:d8:06:0f:10:3b:d8:d9
