1 2 3wolfSSL using libkcapi 4====================== 5 6## Overview 7 8wolfSSL can be configured to use libkcapi for the following operations: 9* hashes: SHA-224, SHA-256, SHA-384, SHA-512 10* HMAC: HMAC-SHA1, HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, HMAC-SHA512 11* AES: AES-ECB, AES-CBC, AES-CTR, AES-GCM 12* RSA PKCS 1.5, PSS and OAEP padding (raw encrypt/decrypt used with libkcapi) 13* DH 14* ECDH (P-192, P-256, P-384, P-521) 15* ECDSA (P-192, P-256, P-384, P-521) 16 17Note: Linux kernel does not support public key operations without patching. 18 19 20## Build 21 22#### Basic configuration 23 24To enable libkcapi support in wolfSSL for non-public key algorithms: 25 26``` 27./configure --enable-kcapi 28``` 29 30The following defines are added to the compile line: 31 - WOLFSSL_KCAPI_AES 32 - WOLFSSL_KCAPI_HASH 33 - WOLFSSL_KCAPI_HMAC 34 35If AES-CCM is enabled then the following define is also added: 36 - WOLFSSL_AES_DIRECT 37 38 39#### Other defines 40 41If 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: 42 43``` 44./configure --enable-kcapi C_EXTRA_FLAGS=-DWOLFSSL_KCAPI_HASH_KEEP 45``` 46 47Note: This is required for TLS. 48 49 50#### RSA configuration 51 52To enable libkcapi support in wolfSSL for RSA: 53 54``` 55./configure --enable-kcapi --enable-kcapi-rsa 56``` 57 58This adds 'WOLFSSL_KCAPI_RSA' to the compile line. 59 60#### DH configuration 61 62To enable libkcapi support in wolfSSL for DH: 63 64``` 65./configure --enable-kcapi --enable-kcapi-dh 66``` 67 68#### ECC configuration 69 70To enable libkcapi support in wolfSSL for ECC: 71 72``` 73./configure --enable-kcapi --enable-kcapi-ecc 74``` 75 76This enanbles support for ECDH and ECDSA. 77 78#### Make 79 80Ensure libkcapi is installed. 81 82``` 83make 84``` 85 86 87#### Testing 88 89Testing is only supported for the basic configuration. 90 91``` 92./configure --enable-kcapi C_EXTRA_FLAGS=-DWOLFSSL_KCAPI_HASH_KEEP --disable-md5 --disable-sha3 93make check 94``` 95 96Disabling MD5 and SHA-3 allows all HMAC tests to pass. 97 98 99#### Install 100 101``` 102make install 103``` 104 105 106## Basic Algorithms with libkcapi 107 108The basic algorithms include all those supported by the Linux kernel. 109 110#### Hash 111 112Cipher Name: "sha224", "sha256", "sha384", "sha512" 113 114When partial results are needed from a hash then define: WOLFSSL_KCAPI_HASH_KEEP 115 116This will keep a copy of all the message data. When a hash result is required, 117the 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) 118 119#### HMAC 120 121Cipher Name: "hmac(sha1)", "hmac(sha224)", "hmac(sha256)", "hmac(sha384)", "hmac(sha512)" 122 123#### AES 124 125Cipher Name: "ecb(aes)", "cbc(aes)", "gcm(aes)", "ctr(aes)" 126 127AES-CCM is supported through the support of AES-ECB in libkcapi. 128 129 130## Public Key Algorithms with libkcapi 131 132The Linux kernel must be patched in order for the public key algorithms to be 133available. (See libkcapi README.md) 134 135Algorithms available in the Linux kernel: DH, RSA, ECDH 136 137wolfSSL supports ECDSA for specific hardware through libkcapi. 138 139#### RSA 140 141Cipher Name: "rsa" 142 143RSA operations are supported by using the raw RSA encrypt/decrypt operations 144through libkcapi. 145This means that wolfSSL performs the padding. Therefore the following padding schemes are supported: 146* PKCS 1.5 for sign/verify and encrypt/decrypt 147* PSS for sign/verify 148* OAEP for encrypt/decrypt 149 150#### ECDH 151 152Cipher Name: "ecdh" 153 154The Linux kernel only supports the curves P-192 and P-256. 155 156The following curves have been added for hardware specific use: 157* P-384 using value of 3 158* P-521 using value of 4 159 160The curve is set using kcapi_kpp_ecdh_setcurve(). 161 162#### ECDSA 163 164The Linux kernel does not support ECDSA operations. 165 166Support for specific harware has been added with the following details. 167 168Cipher Name: "ecdsa" 169 170Private Key format: version|curve-id|private-key 171Public Key format: version|curve-id|x-ord|y-ord 172 173version - one byte and has a value of 1. 174curve-id - one byte and has the same value as used by ECDH. 175private-key - big-endian encoded number the length of the curve. 176x-ord - big-endian encoded number the length of the curve in bytes. 177y-ord - big-endian encoded number the length of the curve in bytes. 178 179