wolfSSL using libkcapi
======================
## Overview
wolfSSL can be configured to use libkcapi for the following operations:
* hashes: SHA-224, SHA-256, SHA-384, SHA-512
* HMAC: HMAC-SHA1, HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, HMAC-SHA512
* AES: AES-ECB, AES-CBC, AES-CTR, AES-GCM
* RSA PKCS 1.5, PSS and OAEP padding (raw encrypt/decrypt used with libkcapi)
* DH
* ECDH (P-192, P-256, P-384, P-521)
* ECDSA (P-192, P-256, P-384, P-521)
Note: Linux kernel does not support public key operations without patching.
## Building libkcapi
Based on README from https://github.com/smuellerDD/libkcapi
```sh
git clone https://github.com/smuellerDD/libkcapi
cd libkcapi
autoreconf -i
./configure --enable-kcapi-test \
--enable-kcapi-speed \
--enable-kcapi-hasher \
--enable-kcapi-rngapp \
--enable-kcapi-encapp \
--enable-kcapi-dgstapp \
--enable-lib-asym \
--enable-lib-kpp \
--prefix=/usr/
make
sudo make install
# Optional testing
cd test
./test.sh
```
## Building wolfSSL
#### Basic configuration
To enable libkcapi support in wolfSSL for non-public key algorithms:
```
./configure --enable-kcapi
```
The following defines are added to the compile line:
- WOLFSSL_KCAPI_AES
- WOLFSSL_KCAPI_HASH
- WOLFSSL_KCAPI_HMAC
If AES-CCM is enabled then the following define is also added:
- WOLFSSL_AES_DIRECT
#### Other defines
If hash operations need to be copied or have an intermediate hash result
returned then add 'WOLFSSL_KCAPI_HASH_KEEP' to the compile line.
For example:
```
./configure --enable-kcapi C_EXTRA_FLAGS=-DWOLFSSL_KCAPI_HASH_KEEP
```
Note: This is required for TLS.
#### RSA configuration
To enable libkcapi support in wolfSSL for RSA:
```
./configure --enable-kcapi --enable-kcapi-rsa
```
This adds 'WOLFSSL_KCAPI_RSA' to the compile line.
#### DH configuration
To enable libkcapi support in wolfSSL for DH:
```
./configure --enable-kcapi --enable-kcapi-dh
```
#### ECC configuration
To enable libkcapi support in wolfSSL for ECC:
```
./configure --enable-kcapi --enable-kcapi-ecc
```
This enables support for ECDH and ECDSA.
#### Make
Ensure libkcapi is installed.
```
make
```
#### Testing
Testing is only supported for the basic configuration.
```
./configure --enable-kcapi C_EXTRA_FLAGS=-DWOLFSSL_KCAPI_HASH_KEEP --disable-md5 --disable-sha3
make check
```
Disabling MD5 and SHA-3 allows all HMAC tests to pass.
#### Install
```
make install
```
## Basic Algorithms with libkcapi
The basic algorithms include all those supported by the Linux kernel.
#### Hash
Cipher Name: "sha224", "sha256", "sha384", "sha512"
When partial results are needed from a hash then define: WOLFSSL_KCAPI_HASH_KEEP
This will keep a copy of all the message data. When a hash result is required,
the data is passed to libkcapi to perform the operation. When the final hash is
requested (eg wc_Sha256Final) then the message data is disposed of. (Required for TLS)
#### HMAC
Cipher Name: "hmac(sha1)", "hmac(sha224)", "hmac(sha256)", "hmac(sha384)", "hmac(sha512)"
#### AES
Cipher Name: "ecb(aes)", "cbc(aes)", "gcm(aes)", "ctr(aes)"
AES-CCM is supported through the support of AES-ECB in libkcapi.
## Public Key Algorithms with libkcapi
The Linux kernel must be patched in order for the public key algorithms to be
available. (See libkcapi README.md)
Algorithms available in the Linux kernel: DH, RSA, ECDH
wolfSSL supports ECDSA for specific hardware through libkcapi.
#### RSA
Cipher Name: "rsa"
RSA operations are supported by using the raw RSA encrypt/decrypt operations
through libkcapi.
This means that wolfSSL performs the padding. Therefore the following padding schemes are supported:
* PKCS v1.5 for sign/verify and encrypt/decrypt
* PSS for sign/verify
* OAEP for encrypt/decrypt
#### ECDH
Cipher Name: "ecdh"
The Linux kernel only supports the curves P-192 and P-256.
The following curves have been added for hardware specific use:
* P-384 using value of 3
* P-521 using value of 4
The curve is set using kcapi_kpp_ecdh_setcurve().
#### ECDSA
The Linux kernel does not support ECDSA operations.
Support for specific hardware has been added with the following details.
Cipher Name: "ecdsa"
version - one byte and has a value of 1.
curve-id - one byte and has the same value as used by ECDH.
private-key - big-endian encoded number the length of the curve.
x-ord - big-endian encoded number the length of the curve in bytes.
y-ord - big-endian encoded number the length of the curve in bytes.