From 4b0a218e089b5ad0b7c762ad27faf23c55453bbd Mon Sep 17 00:00:00 2001 From: David Garske Date: Wed, 13 Feb 2019 13:41:52 -0800 Subject: [PATCH] Updates to README.md and PKCS11.md documents. Cleanup to use sizeof for `privKeyId` in TLS server example. --- pkcs11/PKCS11.md | 101 ++++++++-------- pkcs11/README.md | 238 ++++++++++++++++++++++--------------- pkcs11/server-tls-pkcs11.c | 3 +- 3 files changed, 196 insertions(+), 146 deletions(-) diff --git a/pkcs11/PKCS11.md b/pkcs11/PKCS11.md index e7564af8..746efc13 100644 --- a/pkcs11/PKCS11.md +++ b/pkcs11/PKCS11.md @@ -1,15 +1,12 @@ +# Using PKCS #11 with wolfSSL +## Initializing PKCS #11 library -## Using PKCS #11 with wolfSSL +In order to use a PKCS #11 device it is necessary to load the device specific PKCS #11 shared (or dynamic) library. -# Initializing PKCS #11 library - -In order to use a PKCS #11 device it is necessary to load the device specific -PKCS #11 shared (or dynamic) library. - -The wolfSSL API wc_Pkcs11_Initialize() takes the path to the library and -initializes a Pkcs11Dev instance for accessing tokens. +The wolfSSL API `wc_Pkcs11_Initialize()` takes the path to the library and initializes a Pkcs11Dev instance for accessing tokens. +``` /** * Load library, get function list and initialize PKCS#11. * @@ -23,29 +20,34 @@ initializes a Pkcs11Dev instance for accessing tokens. * 0 on success. */ int wc_Pkcs11_Initialize(Pkcs11Dev* dev, const char* library, void* heap); +``` -# Finalizing PKCS #11 library +## Finalizing PKCS #11 library When the device is not longer required then Pkcs11Dev instance can be finalized. + This unloads the shared library. +``` /** * Close the Pkcs#11 library. * * @param dev [in] Device object. */ void wc_Pkcs11_Finalize(Pkcs11Dev* dev); +``` -# Initializing a token +## Initializing a token -PKCS #11 defines tokens to be in slots. wolfSSL assumes that the token is in a -slot and abstracts slots away. +PKCS #11 defines tokens to be in slots. wolfSSL assumes that the token is in a slot and abstracts slots away. + +To initialize a token instance using the API `wc_Pkcs11Token_Init()`. + +The slot number of the token need not be supplied if the token name is unique. Pass -1 for the slotId to find token by name on any slot. -To initialize a token instance using the API wc_Pkcs11Token_Init(). -The slot number of the token need not be supplied if the token name is unique. -Pass -1 for the slotId to find token by name on any slot. The userPin must be supplied to login into a session. +``` /** * Set up a token for use. * @@ -64,11 +66,13 @@ The userPin must be supplied to login into a session. */ int wc_Pkcs11Token_Init(Pkcs11Token* token, Pkcs11Dev* dev, int slotId, const char* tokenName, const unsigned char* userPin, int userPinSz); +``` -# Finalize token +## Finalize token Finalizing a token will close all session on the token and zeroize any User PIN. +``` /** * Finalize token. * Closes all sessions on token. @@ -76,16 +80,17 @@ Finalizing a token will close all session on the token and zeroize any User PIN. * @param token [in] Token object. */ void wc_Pkcs11Token_Final(Pkcs11Token* token); +``` -# Open Session +## Open Session A session needs to be opened on a token in order for operations to be performed. -If keys need to persist across operations in a session or you need to manage -sessions in the application then opening a session using the API -wc_Pkcs11Token_Open(). + +If keys need to persist across operations in a session or you need to manage sessions in the application then opening a session using the API `wc_Pkcs11Token_Open()`. A session can be opened for reading and writing by setting the flag to 1. +``` /** * Open a session on the token to be used for all operations. * @@ -96,15 +101,17 @@ A session can be opened for reading and writing by setting the flag to 1. * 0 on success. */ int wc_Pkcs11Token_Open(Pkcs11Token* token, int readWrite); +``` - -# Close Session +## Close Session If you opened a session in your application then you should close it too. -Use the API wc_Pkcs11Token_Close() to close the session. wolfSSL will create -a session to perform any new cryptographic operations. + +Use the API `wc_Pkcs11Token_Close()` to close the session. wolfSSL will create a session to perform any new cryptographic operations. + Any keys in the session will be lost. +``` /** * Close the token's session. * All object, like keys, will be destoyed. @@ -112,15 +119,15 @@ Any keys in the session will be lost. * @param token [in] Token object. */ void wc_Pkcs11Token_Close(Pkcs11Token* token); +``` -# Registering a PKCS #11 device +## Registering a PKCS #11 device -Cryptographic operations will be performed on a PKCS #11 device when initialized -with a device identifier associated with a token. -An application chooses a number that will be the device identifier and -associates the PKCS #11 callback and Pkcs11Token pointer using the API -wc_CryptoDev_RegisterDevice(). +Cryptographic operations will be performed on a PKCS #11 device when initialized with a device identifier associated with a token. +An application chooses a number that will be the device identifier and associates the PKCS #11 callback and Pkcs11Token pointer using the API `wc_CryptoDev_RegisterDevice()`. + +``` e.g.: int ret; int devId = 1; @@ -129,36 +136,32 @@ e.g.: ret = wc_CryptoDev_RegisterDevice(devId, wc_Pkcs11_CryptoDevCb, &token); if (ret != 0) fprintf(stderr, "Failed to register token"); +``` -# Initializing ECDSA Cryptographic Operation +## Initializing ECDSA Cryptographic Operation -To initialize ECC signing or verification operration to use the PKCS #11 token, -use the API wc_ecc_init_ex(). +To initialize ECC signing or verification operation to use the PKCS #11 token, use the API `wc_ecc_init_ex()`. +``` e.g: int ret; ecc_key key; int devId = 1; ret = wc_ecc_init_ex(&key, NULL, devId); +``` + +## Using a Private Key + +To use an EC private key, load as normal. (Keys can be generated on the device and the private key will not come off.) + +Perform the cryptographic operation as normal and the private key will be loaded onto the token in the session if required. -# Using a Private Key +## Performing other PKCS #11 operations -To use an EC private key, load as normal. -(Keys can be generated on the device and the private key will not come off.) - -Perform the cryptographic operation as normal and the private key will be loaded -onto the token in the session if required. - - -# Performing other PKCS #11 operations - -The function list is available as the field func in Pkcs11Dev, Pkcs11Token and -Pkcs11Session. - -The Slot Id is availabe in Pkcs11Token and Pkcs11Session as slotId. - -The session handle is available in Pkcs11Token and Pkcs11Session aa handle. +The function list is available as the field `func` in Pkcs11Dev, Pkcs11Token and Pkcs11Session. +The Slot Id is available in Pkcs11Token and Pkcs11Session as `slotId`. +The session handle is available in Pkcs11Token and Pkcs11Session as `handle`. diff --git a/pkcs11/README.md b/pkcs11/README.md index 83098b21..a2b2240c 100644 --- a/pkcs11/README.md +++ b/pkcs11/README.md @@ -1,118 +1,164 @@ +# Examples for PKCS #11 with wolfSSL + +These examples demonstrate using wolfSSL's PKCS #11 feature for the following algorithms: + +* ECC Key Gen, Sign/Verify and ECDHE (Shared Secret) +* RSA Key Gen and Sign/Verify +* AES GCM + +This also includes a TLS server example using a PKCS 11 based key. + +## API Reference + +See [PKCS11.md](./PKCS11.md) in this folder. + +## Setting up and testing SoftHSM version 2 + +1. Change to source code directory of SoftHSM version 2 + + This tool can be found here: https://github.com/opendnssec/SoftHSMv2 + + ``` + ./autogen.sh + ./configure --disable-gost + sudo make install + ``` + + *Note: May need to install pkg-config and libssl-dev* + +2. Change to wolfssl directory + + ``` + ./autogen.sh + ./configure --enable-pkcs11 + make + sudo make install + ``` + +3. Change to wolfssl-examples/pkcs11 directory + + ``` + ./mksofthsm2_conf.sh + export SOFTHSM2_CONF=$PWD/softhsm2.conf + ``` + +4. Running tests + + `softhsm2-util --init-token --slot 0 --label SoftToken` + + * Use PIN: cryptoki + * Use User PIN: cryptoki + + Use the slot id from the output: + + `export SOFTHSM2_SLOTID=` + + Run the examples: + + `./softhsm2.sh` -### Setting up and testing SoftHSM version 2 - -# Change to source code directory of SoftHSM version 2 - -sh ./autogen.sh -# (May need to install pkg-config and libssl-dev) - -./configure --disable-gost - -sudo make install +## Setting up and testing openCryptoki -# Change to wolfssl-examples/pkcs11 directory +1. Change to source code directory of openCryptoki -./mksofthsm2_conf.sh + This tool can be found here: https://github.com/opencryptoki/opencryptoki -export SOFTHSM2_CONF=$PWD/softhsm2.conf + ``` + ./bootstrap.sh + ./configure + make + ``` + + *Note: May need to install flex, bison and openldap-devel [or libldap2-dev]* + +2. Setup pkcs11 group and put current user into it + + ``` + sudo groupadd pkcs11 + sudo usermod -a -G pkcs11 $USER + ``` + +3. Install library + + ``` + sudo make install + sudo ldconfig /usr/local/lib + ``` + +4. Start the daemon + + `sudo /usr/local/sbin/pkcsslotd` + + *Note: May need to logout and login to be able to use pkcsconf.* + +5. Setup token + + ``` + echo "87654321 + SoftToken" | pkcsconf -I -c 3 + ``` + + ``` + echo "87654321 + cryptoki + cryptoki" | pkcsconf -P -c 3 + ``` + + ``` + echo "cryptoki + cryptoki + cryptoki" | pkcsconf -u -c 3 + ``` + +6. Start daemon if not running already: + + `sudo /usr/local/sbin/pkcsslotd` + +7. Build and install wolfSSL + + Change to wolfssl directory and run: + + ``` + ./autogen.sh + ./configure --enable-pkcs11 + make + sudo make install + ``` -# Running tests +8. Running tests -softhsm2-util --init-token --slot 0 --label SoftToken -# Use PIN: cryptoki -# Use User PIN: cryptoki - -# Use the slot id from the output - -export SOFTHSM2_SLOTID= - -./softhsm2.sh + Change to wolfssl-examples/pkcs11 directory: + + `./opencryptoki.sh` +## TLS Server Example with PKCS #11 -### Setting up and testing openCryptoki +The example `server-tls-pkcs11` is a server that uses a private key that has been stored on the PKCS #11 device. - -# Change to source code directory of openCryptoki - -./bootstrap.sh - -./configure -# (May need to install flex, bison and openldap-devel [or libldap2-dev].) - -make - -# Setup pkcs11 group and put current user into it -sudo groupadd pkcs11 -sudo usermod -a -G pkcs11 $USER - -# Install library -sudo make install - -sudo ldconfig /usr/local/lib - -# Start the daemon -sudo /usr/local/sbin/pkcsslotd - -# (May need to logout and login to be able to use pkcsconf) - -# Setup token -echo "87654321 -SoftToken" | pkcsconf -I -c 3 - -echo "87654321 -cryptoki -cryptoki" | pkcsconf -P -c 3 - -echo "cryptoki -cryptoki -cryptoki" | pkcsconf -u -c 3 - - -# Running tests - -# Start daemon if not running already -sudo /usr/local/sbin/pkcsslotd - -# Change to wolfssl-examples/pkcs11 directory - -./opencryptoki.sh - - - -### Server TLS PKCS #11 - -The example server-tls-pkcs11 is a server that uses a private key that has been -stored on the PKCS #11 device. - -The id of the private key is two hex bytes: 0x00, 0x01 +The id of the private key is two hex bytes: `0x00, 0x01` Change this to be the id that you set when importing the key. -## SoftHSM version 2 +1. SoftHSM version 2 -# Import private key + Import private key: + + `softhsm2-util --import ../certs/server-keyPkcs8.pem --slot $SOFTHSM2_SLOTID --id 0001 --label rsa2048` -softhsm2-util --import ../certs/server-keyPkcs8.pem --slot $SOFTHSM2_SLOTID --id 0001 --label rsa2048 + Enter PIN: cryptoki -## Run server and client +2. Run server and client -### Build wolfSSL - -./autogen.sh -./configure --enable-pkcs11 -make -sudo make install - -### Build Server Example - -make -./server-tls-pkcs11 $SOFTHSM2_SLOTID SoftToken cryptoki - -### Run Client -./examples/client/client + `./server-tls-pkcs11 /usr/local/lib/softhsm/libsofthsm2.so $SOFTHSM2_SLOTID SoftToken cryptoki` + + From wolfssl root: + `./examples/client/client` +## Support + +For questions please contact wolfSSL support by email at [support@wolfssl.com](mailto:support@wolfssl.com) diff --git a/pkcs11/server-tls-pkcs11.c b/pkcs11/server-tls-pkcs11.c index 592bce1f..463280da 100644 --- a/pkcs11/server-tls-pkcs11.c +++ b/pkcs11/server-tls-pkcs11.c @@ -95,7 +95,8 @@ int server_tls(int devId) } /* Load server key into WOLFSSL_CTX */ - if (wolfSSL_CTX_use_PrivateKey_id(ctx, privKeyId, 2, devId, 2048) != SSL_SUCCESS) { + if (wolfSSL_CTX_use_PrivateKey_id(ctx, privKeyId, sizeof(privKeyId), devId, + 2048) != SSL_SUCCESS) { fprintf(stderr, "ERROR: failed to set id.\n"); return -1; }