Merge pull request #213 from holtrop/wolfssl-manual-fixes-and-updates

JacobBarthelmeh · web-flow · commit b610e83aa254 · 2025-07-30T10:30:08.000-06:00
Update and fix various wolfSSL user manual chapters
diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md
@@ -2443,6 +2443,8 @@ Enabling this option will turn on User Atomic Record Layer Processing callbacks.
 
 Enable Public Key Callbacks
 
+Eabling this option will turn on Public Key callbacks, allowing the application to register its own ECC sign/verify and RSA sign/verify and encrypt/decrypt callbacks.
+
 ### `--enable-sniffer`
 
 Enable wolfSSL sniffer support.
@@ -2465,14 +2467,12 @@ Stream ciphers:
 
 Enable AES-GCM support.
 
-Eabling this option will turn on Public Key callbacks, allowing the application to register its own ECC sign/verify and RSA sign/verify and encrypt/decrypt callbacks.
+Enabling AES-GCM will add these cipher suites to wolfSSL.  wolfSSL offers four different implementations of AES-GCM balancing speed versus memory consumption. If available, wolfSSL will use 64-bit or 32-bit math. For embedded applications, there is a speedy 8-bit version that uses RAM-based lookup tables (8KB per session) which is speed comparable to the 64-bit version and a slower 8-bit version that doesn't take up any additional RAM. The --enable-aesgcm configure option may be modified with the options `=word32`, `=table`, or `=small`, i.e. `--enable-aesgcm=table`.
 
 ### `--enable-aesccm`
 
 Enable AES-CCM support
 
-Enabling AES-GCM will add these cipher suites to wolfSSL.  wolfSSL offers four different implementations of AES-GCM balancing speed versus memory consumption. If available, wolfSSL will use 64-bit or 32-bit math. For embedded applications, there is a speedy 8-bit version that uses RAM-based lookup tables (8KB per session) which is speed comparable to the 64-bit version and a slower 8-bit version that doesn't take up any additional RAM. The --enable-aesgcm configure option may be modified with the options `=word32`, `=table`, or `=small`, i.e. `--enable-aesgcm=table`.
-
 ### `--disable-aescbc`
 
 Used to with [`--disable-aescbc`](#--disable-aescbc) to compile out AES-CBC
diff --git a/wolfSSL/src/chapter03.md b/wolfSSL/src/chapter03.md
@@ -496,7 +496,7 @@ This section will explain the basic steps needed to add wolfSSL to a client appl
 
     ```c
     /*after connecting to socket fd*/
-    WOLF SSL* ssl;
+    WOLFSSL* ssl;
     if ((ssl = wolfSSL_new(ctx)) == NULL) {
         fprintf(stderr, "wolfSSL_new error.\n");
         exit(EXIT_FAILURE);
@@ -558,7 +558,7 @@ calling:
 
 This section will explain the basic steps needed to add wolfSSL to a server application using the wolfSSL native API. For a client explanation, please see [Changing a Client Application to Use wolfSSL](#changing-a-client-application-to-use-wolfssl). A more complete walk-through, with example code, is located in the [SSL Tutorial](chapter11.md#ssl-tutorial) chapter.
 
-1. Follow the instructions above for a client, except change the client method call in step 5 to a server one, so:
+1. Follow the instructions above for a client, except change the client method call in step 2 to a server one, so:
 
     ```c
     wolfSSL_CTX_new(wolfTLSv1_client_method());
diff --git a/wolfSSL/src/chapter04.md b/wolfSSL/src/chapter04.md
diff --git a/wolfSSL/src/chapter06.md b/wolfSSL/src/chapter06.md
@@ -120,6 +120,7 @@ Additionally, each callback type requires its specific feature to be enabled (e.
 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.
 
 The user can optionally define 2 functions:
+
 1. DH key generation callback
 2. DH key agreement callback
 
@@ -138,6 +139,7 @@ typedef int (*CallbackDhAgree)(WOLFSSL* ssl, struct DhKey* key,
 ```
 
 The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
+
 * `wolfSSL_CTX_SetDhGenerateKeyPair()`
 * `wolfSSL_CTX_SetDhAgreeCb()`
 
@@ -152,6 +154,7 @@ To use DH callbacks, wolfSSL needs to be compiled with `HAVE_DH` defined.
 wolfSSL provides Ed25519 callbacks for users who wish to have more control over Ed25519 sign/verify operations during the SSL/TLS connection.
 
 The user can optionally define 2 functions:
+
 1. Ed25519 sign callback
 2. Ed25519 verify callback
 
@@ -172,10 +175,12 @@ typedef int (*CallbackEd25519Verify)(WOLFSSL* ssl,
 ```
 
 The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
+
 * `wolfSSL_CTX_SetEd25519SignCb()`
 * `wolfSSL_CTX_SetEd25519VerifyCb()`
 
 The user can set a context per WOLFSSL object (session) with:
+
 * `wolfSSL_SetEd25519SignCtx()`
 * `wolfSSL_SetEd25519VerifyCtx()`
 
@@ -188,6 +193,7 @@ To use Ed25519 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS`
 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.
 
 The user can optionally define 2 functions:
+
 1. X25519 key generation callback
 2. X25519 shared secret callback
 
@@ -205,10 +211,12 @@ typedef int (*CallbackX25519SharedSecret)(WOLFSSL* ssl,
 ```
 
 The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
+
 * `wolfSSL_CTX_SetX25519KeyGenCb()`
 * `wolfSSL_CTX_SetX25519SharedSecretCb()`
 
 The user can set a context per WOLFSSL object (session) with:
+
 * `wolfSSL_SetX25519KeyGenCtx()`
 * `wolfSSL_SetX25519SharedSecretCtx()`
 
@@ -221,6 +229,7 @@ To use X25519 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` a
 wolfSSL provides Ed448 callbacks for users who wish to have more control over Ed448 sign/verify operations during the SSL/TLS connection.
 
 The user can optionally define 2 functions:
+
 1. Ed448 sign callback
 2. Ed448 verify callback
 
@@ -241,10 +250,12 @@ typedef int (*CallbackEd448Verify)(WOLFSSL* ssl,
 ```
 
 The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
+
 * `wolfSSL_CTX_SetEd448SignCb()`
 * `wolfSSL_CTX_SetEd448VerifyCb()`
 
 The user can set a context per WOLFSSL object (session) with:
+
 * `wolfSSL_SetEd448SignCtx()`
 * `wolfSSL_SetEd448VerifyCtx()`
 
@@ -257,6 +268,7 @@ To use Ed448 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` an
 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.
 
 The user can optionally define 2 functions:
+
 1. X448 key generation callback
 2. X448 shared secret callback
 
@@ -274,10 +286,12 @@ typedef int (*CallbackX448SharedSecret)(WOLFSSL* ssl,
 ```
 
 The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
+
 * `wolfSSL_CTX_SetX448KeyGenCb()`
 * `wolfSSL_CTX_SetX448SharedSecretCb()`
 
 The user can set a context per WOLFSSL object (session) with:
+
 * `wolfSSL_SetX448KeyGenCtx()`
 * `wolfSSL_SetX448SharedSecretCtx()`
 
@@ -290,6 +304,7 @@ To use X448 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and
 wolfSSL provides RSA PSS callbacks for users who wish to have more control over RSA PSS sign/verify operations during the SSL/TLS connection.
 
 The user can optionally define 4 functions:
+
 1. RSA PSS sign callback
 2. RSA PSS verify callback
 3. RSA PSS sign check callback
@@ -320,12 +335,14 @@ typedef int (*CallbackRsaPssSignCheck)(WOLFSSL* ssl,
 ```
 
 The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with:
+
 * `wolfSSL_CTX_SetRsaPssSignCb()`
 * `wolfSSL_CTX_SetRsaPssVerifyCb()`
 * `wolfSSL_CTX_SetRsaSignCheckCb()`
 * `wolfSSL_CTX_SetRsaPssSignCheckCb()`
 
 The user can set a context per WOLFSSL object (session) with:
+
 * `wolfSSL_SetRsaPssSignCtx()`
 * `wolfSSL_SetRsaPssVerifyCtx()`
 * `wolfSSL_SetRsaSignCheckCtx()`
@@ -432,7 +449,7 @@ The high level steps use crypto callbacks are:
 
 
 #### 1. Compile wolfSSL with crypto callback support
-Support for crypto callbacks is enabled in wolfSSL via the `–enable-cryptocb` configure option, or `#define WOLF_CRYPTO_CB`.
+Support for crypto callbacks is enabled in wolfSSL via the `–-enable-cryptocb` configure option, or `#define WOLF_CRYPTO_CB`.
 
 #### 2. Register your callback and unique devID with wolfCrypt
 
@@ -467,6 +484,7 @@ wc_InitCmac_ex
 This will cause wolfCrypt to invoke the crypto callback in place of the default implementation. This is not an exhaustive API list. Please refer to the wolfCrypt API documentation to see if a particular algorithm supports crypto callbacks.
 
 #### 4. (TLS only): associate the devId with a wolfSSL context
+
 To enable use of a crypto callback when using TLS, you must supply the `devId` arguments on initialization of a `WOLFSSL_CTX` or `WOLFSSL` struct.
 ```c
 wolfSSL_CTX_SetDevId(ctx, devId);
diff --git a/wolfSSL/src/chapter07.md b/wolfSSL/src/chapter07.md
@@ -174,7 +174,7 @@ int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX *ctx,
 
 ## Certificate Chain Verification
 
-wolfSSL requires that only the top or “root” certificate in a chain to be loaded as a trusted certificate in order to verify a certificate chain. This means that if you have a certificate chain (A -\> B -\> C), where C is signed by B, and B is signed by A, wolfSSL only requires that certificate A be loaded as a trusted certificate in order to verify the entire chain (A-\>B-\>C).
+wolfSSL requires only the top or “root” certificate in a chain to be loaded as a trusted certificate in order to verify a certificate chain. This means that if you have a certificate chain (A -\> B -\> C), where C is signed by B, and B is signed by A, wolfSSL only requires that certificate A be loaded as a trusted certificate in order to verify the entire chain (A-\>B-\>C).
 
 For example, if a server certificate chain looks like:
 
@@ -192,7 +192,7 @@ Checking the domain name of the certificate is an important step that verifies t
 
 ## No File System and using Certificates
 
-Normally a file system is used to load private keys, certificates, and CAs. Since wolfSSL is sometimes used in environments without a full file system an extension to use memory buffers instead is provided. To use the extension define the constant `NO_FILESYSTEM` and the following functions will be made available:
+Normally a file system is used to load private keys, certificates, and CAs. Since wolfSSL is sometimes used in environments without a full file system, an extension to use memory buffers instead is provided. To use the extension define the constant `NO_FILESYSTEM` and the following functions will be made available:
 
 * [`int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,long sz, int format);`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_buffer)
 * [`int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX* ctx, const unsigned char* in, long sz, int format);`](group__CertsKeys.md#function-wolfssl_ctx_use_certificate_buffer)
@@ -204,7 +204,7 @@ Use these functions exactly like their counterparts that are named `*_file` inst
 
 ### Test Certificate and Key Buffers
 
-wolfSSL has come bundled with test certificate and key files in the past.  Now it also comes bundled with test certificate and key buffers for use in environments with no filesystem available.  These buffers are available in `certs_test.h` when defining one or more of `USE_CERT_BUFFERS_1024`, `USE_CERT_BUFFERS_2048`, or `USE_CERT_BUFFERS_256`.
+wolfSSL comes bundled with test certificate and key files.  Additionally, it also comes bundled with test certificate and key buffers for use in environments with no filesystem available.  These buffers are available in `certs_test.h` when defining one or more of `USE_CERT_BUFFERS_1024`, `USE_CERT_BUFFERS_2048`, or `USE_CERT_BUFFERS_256`.
 
 ## Serial Number Retrieval
 
@@ -225,7 +225,7 @@ wolfSSL supports RSA key generation of varying lengths up to 4096 bits. Key gene
 int MakeRsaKey(RsaKey* key, int size, long e, RNG* rng);
 ```
 
-Where `size` is the length in bits and `e` is the public exponent, using 65537 is usually a good choice for `e`. The following from `wolfcrypt/test/test.c` gives an example creating an RSA key of 1024 bits:
+Where `size` is the length in bits and `e` is the public exponent (using 65537 is usually a good choice for `e`). The following from `wolfcrypt/test/test.c` gives an example creating an RSA key of 1024 bits:
 
 ```c
 RsaKey genKey;
diff --git a/wolfSSL/src/chapter09.md b/wolfSSL/src/chapter09.md
@@ -52,7 +52,7 @@ wolfSSL (formerly CyaSSL) is thread safe by design. Multiple threads can enter t
 
 ## Input and Output Buffers
 
-wolfSSL now uses dynamic buffers for input and output. They default to 0 bytes and are controlled by the `RECORD_SIZE` define in `wolfssl/internal.h`. If an input record is received that is greater in size than the static buffer, then a dynamic buffer is temporarily used to handle the request and then freed. You can set the static buffer size up to the `MAX_RECORD_SIZE` which is 2^16 or 16,384.
+wolfSSL now uses dynamic buffers for input and output. They default to 0 bytes and are controlled by the `RECORD_SIZE` define in `wolfssl/internal.h`. If an input record is received that is greater in size than the static buffer, then a dynamic buffer is temporarily used to handle the request and then freed. You can set the static buffer size up to the `MAX_RECORD_SIZE` which is 2^14 or 16,384.
 
 If you prefer the previous way that wolfSSL operated, with 16Kb static buffers that will never need dynamic memory, you can still get that option by defining `LARGE_STATIC_BUFFERS`.
 
diff --git a/wolfSSL/src/chapter10.md b/wolfSSL/src/chapter10.md
@@ -263,7 +263,7 @@ For usage examples please see the camellia_test() function in `<wolfssl_root>/wo
 
 **NOTE**: ARC4 is outdated and considered insecure. Please consider using a different stream cipher.
 
-The most common stream cipher used on the Internet is ARC4. wolfCrypt supports it through the header `wolfssl/wolfcrypt/arc4.h`.  Usage is simpler than block ciphers because there is no block size and the key length can be any length. The following is a typical usage of ARC4.
+wolfCrypt supports ARC4 through the header `wolfssl/wolfcrypt/arc4.h`.  Usage is simpler than block ciphers because there is no block size and the key length can be any length. The following is a typical usage of ARC4.
 
 ```c
 Arc4 enc;
diff --git a/wolfSSL/src/chapter11.md b/wolfSSL/src/chapter11.md
@@ -256,7 +256,7 @@ EchoServer:
 * [`wolfDTLSv1_2_server_method();`](ssl_8h.md#function-wolfdtlsv1_2_server_method) - DTLS 1.2
 * [`wolfDTLSv1_3_server_method();`](ssl_8h.md#function-wolfdtlsv1_3_server_method) - DTLS 1.3
 
-We need to load our CA (Certificate Authority) certificate into the `WOLFSSL_CTX` so that the when the echoclient connects to the echoserver, it is able to verify the server’s identity. To load the CA certificates into the `WOLFSSL_CTX`, use [`wolfSSL_CTX_load_verify_locations()`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations). This function requires three arguments: a `WOLFSSL_CTX` pointer, a certificate file, and a path value. The path value points to a directory which should contain CA certificates in PEM format. When looking up certificates, wolfSSL will look at the certificate file value before looking in the path location. In this case, we don’t need to specify a certificate path because we will specify one CA file - as such we use the value 0 for the path argument. The [`wolfSSL_CTX_load_verify_locations`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations) function returns either `SSL_SUCCESS` or `SSL_FAILURE`:
+We need to load our CA (Certificate Authority) certificate into the `WOLFSSL_CTX` so that the when the echoclient connects to the echoserver, it is able to verify the server’s identity. To load the CA certificates into the `WOLFSSL_CTX`, use [`wolfSSL_CTX_load_verify_locations()`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations). This function requires three arguments: a `WOLFSSL_CTX` pointer, a certificate file, and a path value. The path value points to a directory which should contain CA certificates in PEM format. When looking up certificates, wolfSSL will look at the certificate file value before looking in the path location. In this case, we don’t need to specify a certificate path because we will specify one CA file - as such we use NULL for the path argument. The [`wolfSSL_CTX_load_verify_locations`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations) function returns either `SSL_SUCCESS` or `SSL_FAILURE`:
 
 ```c
 wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX* ctx, const char* file, const char* path)
@@ -278,10 +278,10 @@ EchoClient:
     }
 
     /* Load CA certificates into WOLFSSL_CTX */
-    if (wolfSSL_CTX_load_verify_locations(ctx,"../certs/ca-cert.pem",0) !=
+    if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", NULL) !=
         SSL_SUCCESS) {
-        fprintf(stderr, "Error loading ../certs/ca-cert.pem, please check"
-            "the file.\n");
+        fprintf(stderr, "Error loading ../certs/ca-cert.pem, "
+            "please check the file.\n");
         exit(EXIT_FAILURE);
     }
 ```
@@ -304,23 +304,23 @@ if ( (ctx = wolfSSL_CTX_new(wolfTLSv1_2_server_method())) == NULL) {
 }
 
 /* Load CA certificates into WOLFSSL_CTX */
-if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", 0) !=
+if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", NULL) !=
          SSL_SUCCESS) {
     fprintf(stderr, "Error loading ../certs/ca-cert.pem, "
         "please check the file.\n");
     exit(EXIT_FAILURE);
 }
 
 /* Load server certificates into WOLFSSL_CTX */
-if (wolfSSL_CTX_use_certificate_file(ctx,"../certs/server-cert.pem",
+if (wolfSSL_CTX_use_certificate_file(ctx, "../certs/server-cert.pem",
         SSL_FILETYPE_PEM) != SSL_SUCCESS) {
     fprintf(stderr, "Error loading ../certs/server-cert.pem, please"
         "check the file.\n");
     exit(EXIT_FAILURE);
 }
 
 /* Load keys */
-if (wolfSSL_CTX_use_PrivateKey_file(ctx,"../certs/server-key.pem",
+if (wolfSSL_CTX_use_PrivateKey_file(ctx, "../certs/server-key.pem",
         SSL_FILETYPE_PEM) != SSL_SUCCESS) {
     fprintf(stderr, "Error loading ../certs/server-key.pem, please check"
         "the file.\n");
@@ -341,11 +341,11 @@ wolfSSL_Cleanup();
 
 ### EchoClient
 
-A WOLFSSL object needs to be created after each TCP Connect and the socket file descriptor needs to be associated with the session. In the echoclient example, we will do this after the call to `Connect()`, shown below:
+A WOLFSSL object needs to be created after each TCP connect and the socket file descriptor needs to be associated with the session. In the echoclient example, we will do this after the call to `connect()`, shown below:
 
 ```c
 /* Connect to socket file descriptor */
-Connect(sockfd, (SA *) &servaddr, sizeof(servaddr));
+connect(sockfd, (SA *) &servaddr, sizeof(servaddr));
 ```
 
 Directly after connecting, create a new `WOLFSSL` object using the [`wolfSSL_new()`](group__Setup.md#function-wolfssl_new) function. This function returns a pointer to the `WOLFSSL` object if successful or `NULL` in the case of failure. We can then associate the socket file descriptor (`sockfd`) with the new `WOLFSSL` object (`ssl`):
@@ -497,7 +497,7 @@ while(cleanup != 1)
 }
 ```
 
-For the echoserver we need to disable the operating system from restarting calls which were being executed before the signal was handled after our handler has finished. By disabling these, the operating system will not restart calls to `accept()` after the signal has been handled. If we didn’t do this, we would have to wait for another client to connect and disconnect before the echoserver would clean up resources and exit. To define the signal handler and turn off `SA_RESTART`, first define act and oact structures in the echoserver’s `main()` function:
+For the echoserver we need to disable the operating system from restarting calls which were being executed before the signal was handled after our handler has finished. By disabling these, the operating system will not restart calls to `accept()` after the signal has been handled. If we didn’t do this, we would have to wait for another client to connect and disconnect before the echoserver would clean up resources and exit. To define the signal handler and turn off `SA_RESTART`, first define `act` and `oact` structures in the echoserver’s `main()` function:
 
 ```c
 struct sigaction     act, oact;
