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