Skip to content

Commit 7290234

Browse files
dgarskedgarske
authored
Merge pull request #180 from wolfSSL/devin/1708290084-add-pk-callback-docs
Add documentation for new public key callback functions
2 parents 50dd17b + 9ac0b64 commit 7290234

File tree

1 file changed

+231
-1
lines changed

1 file changed

+231
-1
lines changed

‎wolfSSL/src/chapter06.md

+231-1
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,237 @@ To use Atomic Record Layer callbacks, wolfSSL needs to be compiled using the `--
105105
106106
## Public Key Callbacks
107107
108-
wolfSSL provides Public Key callbacks for users who wish to have more control over ECC sign/verify functionality as well as RSA sign/verify and encrypt/decrypt functionality during the SSL/TLS connection.
108+
wolfSSL provides Public Key (PK) callbacks for users who wish to have more control over DH, ECC, Ed25519, X25519, Ed448, X448, and RSA operations during the SSL/TLS connection.
109+
110+
To use Public Key callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` defined. This can be done using the configure option:
111+
112+
```sh
113+
./configure --enable-pkcallbacks
114+
```
115+
116+
Additionally, each callback type requires its specific feature to be enabled (e.g., `HAVE_DH`, `HAVE_ED25519`, etc.).
117+
118+
### DH Callbacks
119+
120+
wolfSSL provides DH (Diffie-Hellman) callbacks for users who wish to have more control over DH key generation and key agreement operations during the SSL/TLS connection.
121+
122+
The user can optionally define 2 functions:
123+
1. DH key generation callback
124+
2. DH key agreement callback
125+
126+
These functions are prototyped by `CallbackDhGenerateKeyPair` and `CallbackDhAgree` in `ssl.h`:
127+
128+
```c
129+
typedef int (*CallbackDhGenerateKeyPair)(DhKey* key, WC_RNG* rng,
130+
byte* priv, word32* privSz,
131+
byte* pub, word32* pubSz);
132+
133+
typedef int (*CallbackDhAgree)(WOLFSSL* ssl, struct DhKey* key,
134+
const unsigned char* priv, unsigned int privSz,
135+
const unsigned char* otherPubKeyDer, unsigned int otherPubKeySz,
136+
unsigned char* out, word32* outlen,
137+
void* ctx);
138+
```
139+
140+
The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
141+
* `wolfSSL_CTX_SetDhGenerateKeyPair()`
142+
* `wolfSSL_CTX_SetDhAgreeCb()`
143+
144+
The user can set a context per WOLFSSL object (session) with `wolfSSL_SetDhAgreeCtx()`.
145+
146+
Example callbacks can be found in `wolfssl/test.h`, under `myDhCallback()`. Usage can be seen in the wolfSSL example client.
147+
148+
To use DH callbacks, wolfSSL needs to be compiled with `HAVE_DH` defined.
149+
150+
### Ed25519 Callbacks
151+
152+
wolfSSL provides Ed25519 callbacks for users who wish to have more control over Ed25519 sign/verify operations during the SSL/TLS connection.
153+
154+
The user can optionally define 2 functions:
155+
1. Ed25519 sign callback
156+
2. Ed25519 verify callback
157+
158+
These functions are prototyped by `CallbackEd25519Sign` and `CallbackEd25519Verify` in `ssl.h`:
159+
160+
```c
161+
typedef int (*CallbackEd25519Sign)(WOLFSSL* ssl,
162+
const unsigned char* in, unsigned int inSz,
163+
unsigned char* out, unsigned int* outSz,
164+
const unsigned char* keyDer, unsigned int keySz,
165+
void* ctx);
166+
167+
typedef int (*CallbackEd25519Verify)(WOLFSSL* ssl,
168+
const unsigned char* sig, unsigned int sigSz,
169+
const unsigned char* msg, unsigned int msgSz,
170+
const unsigned char* keyDer, unsigned int keySz,
171+
int* result, void* ctx);
172+
```
173+
174+
The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
175+
* `wolfSSL_CTX_SetEd25519SignCb()`
176+
* `wolfSSL_CTX_SetEd25519VerifyCb()`
177+
178+
The user can set a context per WOLFSSL object (session) with:
179+
* `wolfSSL_SetEd25519SignCtx()`
180+
* `wolfSSL_SetEd25519VerifyCtx()`
181+
182+
Example callbacks can be found in `wolfssl/test.h`, under `myEd25519Sign()` and `myEd25519Verify()`. Usage can be seen in the wolfSSL example client.
183+
184+
To use Ed25519 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and `HAVE_ED25519` defined.
185+
186+
### X25519 Callbacks
187+
188+
wolfSSL provides X25519 callbacks for users who wish to have more control over X25519 key generation and shared secret computation during the SSL/TLS connection.
189+
190+
The user can optionally define 2 functions:
191+
1. X25519 key generation callback
192+
2. X25519 shared secret callback
193+
194+
These functions are prototyped by `CallbackX25519KeyGen` and `CallbackX25519SharedSecret` in `ssl.h`:
195+
196+
```c
197+
typedef int (*CallbackX25519KeyGen)(WOLFSSL* ssl, struct curve25519_key* key,
198+
unsigned int keySz, void* ctx);
199+
200+
typedef int (*CallbackX25519SharedSecret)(WOLFSSL* ssl,
201+
struct curve25519_key* otherKey,
202+
unsigned char* pubKeyDer, unsigned int* pubKeySz,
203+
unsigned char* out, unsigned int* outlen,
204+
int side, void* ctx);
205+
```
206+
207+
The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
208+
* `wolfSSL_CTX_SetX25519KeyGenCb()`
209+
* `wolfSSL_CTX_SetX25519SharedSecretCb()`
210+
211+
The user can set a context per WOLFSSL object (session) with:
212+
* `wolfSSL_SetX25519KeyGenCtx()`
213+
* `wolfSSL_SetX25519SharedSecretCtx()`
214+
215+
Example callbacks can be found in `wolfssl/test.h`, under `myX25519KeyGen()` and `myX25519SharedSecret()`. Usage can be seen in the wolfSSL example client.
216+
217+
To use X25519 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and `HAVE_CURVE25519` defined.
218+
219+
### Ed448 Callbacks
220+
221+
wolfSSL provides Ed448 callbacks for users who wish to have more control over Ed448 sign/verify operations during the SSL/TLS connection.
222+
223+
The user can optionally define 2 functions:
224+
1. Ed448 sign callback
225+
2. Ed448 verify callback
226+
227+
These functions are prototyped by `CallbackEd448Sign` and `CallbackEd448Verify` in `ssl.h`:
228+
229+
```c
230+
typedef int (*CallbackEd448Sign)(WOLFSSL* ssl,
231+
const unsigned char* in, unsigned int inSz,
232+
unsigned char* out, unsigned int* outSz,
233+
const unsigned char* keyDer, unsigned int keySz,
234+
void* ctx);
235+
236+
typedef int (*CallbackEd448Verify)(WOLFSSL* ssl,
237+
const unsigned char* sig, unsigned int sigSz,
238+
const unsigned char* msg, unsigned int msgSz,
239+
const unsigned char* keyDer, unsigned int keySz,
240+
int* result, void* ctx);
241+
```
242+
243+
The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
244+
* `wolfSSL_CTX_SetEd448SignCb()`
245+
* `wolfSSL_CTX_SetEd448VerifyCb()`
246+
247+
The user can set a context per WOLFSSL object (session) with:
248+
* `wolfSSL_SetEd448SignCtx()`
249+
* `wolfSSL_SetEd448VerifyCtx()`
250+
251+
Example callbacks can be found in `wolfssl/test.h`, under `myEd448Sign()` and `myEd448Verify()`. Usage can be seen in the wolfSSL example client.
252+
253+
To use Ed448 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and `HAVE_ED448` defined.
254+
255+
### X448 Callbacks
256+
257+
wolfSSL provides X448 callbacks for users who wish to have more control over X448 key generation and shared secret operations during the SSL/TLS connection.
258+
259+
The user can optionally define 2 functions:
260+
1. X448 key generation callback
261+
2. X448 shared secret callback
262+
263+
These functions are prototyped by `CallbackX448KeyGen` and `CallbackX448SharedSecret` in `ssl.h`:
264+
265+
```c
266+
typedef int (*CallbackX448KeyGen)(WOLFSSL* ssl, struct curve448_key* key,
267+
unsigned int keySz, void* ctx);
268+
269+
typedef int (*CallbackX448SharedSecret)(WOLFSSL* ssl,
270+
struct curve448_key* otherKey,
271+
unsigned char* pubKeyDer, unsigned int* pubKeySz,
272+
unsigned char* out, unsigned int* outlen,
273+
int side, void* ctx);
274+
```
275+
276+
The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
277+
* `wolfSSL_CTX_SetX448KeyGenCb()`
278+
* `wolfSSL_CTX_SetX448SharedSecretCb()`
279+
280+
The user can set a context per WOLFSSL object (session) with:
281+
* `wolfSSL_SetX448KeyGenCtx()`
282+
* `wolfSSL_SetX448SharedSecretCtx()`
283+
284+
Example callbacks can be found in `wolfssl/test.h`, under `myX448KeyGen()` and `myX448SharedSecret()`. Usage can be seen in the wolfSSL example client.
285+
286+
To use X448 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and `HAVE_CURVE448` defined.
287+
288+
### RSA PSS Callbacks
289+
290+
wolfSSL provides RSA PSS callbacks for users who wish to have more control over RSA PSS sign/verify operations during the SSL/TLS connection.
291+
292+
The user can optionally define 4 functions:
293+
1. RSA PSS sign callback
294+
2. RSA PSS verify callback
295+
3. RSA PSS sign check callback
296+
4. RSA PSS verify check callback
297+
298+
These functions are prototyped by `CallbackRsaPssSign`, `CallbackRsaPssVerify`, and `CallbackRsaPssSignCheck` in `ssl.h`:
299+
300+
```c
301+
typedef int (*CallbackRsaPssSign)(WOLFSSL* ssl,
302+
const unsigned char* in, unsigned int inSz,
303+
unsigned char* out, unsigned int* outSz,
304+
int hash, int mgf,
305+
const unsigned char* keyDer, unsigned int keySz,
306+
void* ctx);
307+
308+
typedef int (*CallbackRsaPssVerify)(WOLFSSL* ssl,
309+
unsigned char* sig, unsigned int sigSz,
310+
unsigned char** out,
311+
int hash, int mgf,
312+
const unsigned char* keyDer, unsigned int keySz,
313+
void* ctx);
314+
315+
typedef int (*CallbackRsaPssSignCheck)(WOLFSSL* ssl,
316+
unsigned char* sig, unsigned int sigSz,
317+
unsigned char** out,
318+
const unsigned char* keyDer, unsigned int keySz,
319+
void* ctx);
320+
```
321+
322+
The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
323+
* `wolfSSL_CTX_SetRsaPssSignCb()`
324+
* `wolfSSL_CTX_SetRsaPssVerifyCb()`
325+
* `wolfSSL_CTX_SetRsaSignCheckCb()`
326+
* `wolfSSL_CTX_SetRsaPssSignCheckCb()`
327+
328+
The user can set a context per WOLFSSL object (session) with:
329+
* `wolfSSL_SetRsaPssSignCtx()`
330+
* `wolfSSL_SetRsaPssVerifyCtx()`
331+
* `wolfSSL_SetRsaSignCheckCtx()`
332+
* `wolfSSL_SetRsaPssSignCheckCtx()`
333+
334+
Example callbacks can be found in `wolfssl/test.h`, under `myRsaPssSign()`, `myRsaPssVerify()`, and `myRsaPssSignCheck()`. Usage can be seen in the wolfSSL example client.
335+
336+
To use RSA PSS callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and `WC_RSA_PSS` defined.
337+
338+
### ECC Callbacks
109339

110340
The user can optionally define 7 functions:
111341

0 commit comments

Comments
 (0)