WolfSSL
/
wolfssl-examples
mirror of https://github.com/wolfSSL/wolfssl-examples.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Updates to README.md and PKCS11.md documents. Cleanup to use sizeof for `privKeyId` in TLS server example.

pull/120/head
David Garske 2019-02-13 13:41:52 -08:00
parent 10bf5d543b
commit 4b0a218e08
3 changed files with 196 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
pkcs11/PKCS11.md
View File

@ -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`.

238
pkcs11/README.md
View File

@ -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=<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=<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 <Path to SoftHSMv2 library> $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)

3
pkcs11/server-tls-pkcs11.c
View File

@ -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;
}