diff --git a/wolfHSM/Makefile b/wolfHSM/Makefile index 7bd5db91..c0559538 100644 --- a/wolfHSM/Makefile +++ b/wolfHSM/Makefile @@ -118,6 +118,10 @@ html-prep: api # 4. Three regexes to remove metadata which outputs in the PDF text # 5. Fix titles of the header files Markdown # 6. Two regexes to handle bad Doxygen that didn't convert and the LaTeX processor thinks is LaTeX commands +# NOTE: The `cat` commands below assemble the Client (10) and Server (11) API +# References for the PDF from hardcoded lists. They mirror the API Reference nav +# sections in mkdocs.yml (which drive the HTML build); the PDF build does not +# read that nav. Keep both locations in sync. .PHONY: pdf-prep pdf-prep: api $(Q)cp -a api/md/*8h* build/pdf/ diff --git a/wolfHSM/mkdocs.yml b/wolfHSM/mkdocs.yml index ac0e3947..b25cc798 100644 --- a/wolfHSM/mkdocs.yml +++ b/wolfHSM/mkdocs.yml @@ -14,6 +14,9 @@ nav: - "7. Examples": 7-Examples.md - "8. Integration": 8-Integration.md - "9. Configuration": 9-Configuration.md + # NOTE: The PDF build (see Makefile, pdf-prep target) assembles the Client + # (10) and Server (11) API References from hardcoded `cat` lists. It does not + # read this nav, so keep those `cat` commands in sync with these sections. - "10. Client API Reference": - Overview: 10-API-docs-client.md - Client API: wh__client_8h.md diff --git a/wolfMQTT/Makefile b/wolfMQTT/Makefile index c9830004..b018a960 100644 --- a/wolfMQTT/Makefile +++ b/wolfMQTT/Makefile @@ -57,6 +57,9 @@ html-prep: api # 4. Three regexes to remove metadata which outputs in the PDF text # 5. Fix titles of the header files Markdown # 6. Two regexes to handle bad Doxygen that didn't convert and the LaTeX processor thinks is LaTeX commands +# NOTE: The final `cat` assembles the API Reference for the PDF from a hardcoded +# list. It mirrors the "5. API Reference" nav in mkdocs.yml (which drives the +# HTML build); the PDF build does not read that nav. Keep both lists in sync. .PHONY: pdf-prep pdf-prep: api $(Q)perl -i -pe "s/# /## /g" api/md/*.md @@ -75,4 +78,4 @@ pdf-prep: api $(Q)perl -i -pe "s/(?<=md\#enum\-)(.*)(?=\))/\$$1=~s#-#_#gr/ge" api/md/*.md $(Q)rm -rf build/pdf/chapter05.md $(Q)echo '# API Reference' >> build/pdf/chapter05.md - $(Q)cat api/md/mqtt__client_8h.md api/md/mqtt__socket_8h.md api/md/mqtt__socket_8h.md api/md/mqtt__types_8h.md >> build/pdf/chapter05.md + $(Q)cat api/md/mqtt__client_8h.md api/md/mqtt__packet_8h.md api/md/mqtt__socket_8h.md api/md/mqtt__types_8h.md >> build/pdf/chapter05.md diff --git a/wolfMQTT/mkdocs.yml b/wolfMQTT/mkdocs.yml index 69832e7b..74b2cab2 100644 --- a/wolfMQTT/mkdocs.yml +++ b/wolfMQTT/mkdocs.yml @@ -8,6 +8,9 @@ nav: - "2. Building wolfMQTT": chapter02.md - "3. Getting Started": chapter03.md - "4. Library Design": chapter04.md + # NOTE: The PDF build (see Makefile, pdf-prep target) assembles the API + # Reference from a hardcoded `cat` list. It does not read this nav, so keep + # that `cat` in sync when modifying the header list below. - "5. API Reference": - mqtt__client_8h.md - mqtt__packet_8h.md diff --git a/wolfSSL/Makefile b/wolfSSL/Makefile index c6fe1245..5272d105 100644 --- a/wolfSSL/Makefile +++ b/wolfSSL/Makefile @@ -29,7 +29,8 @@ APPENDIX= appendix01.md \ appendix07.md \ appendix08.md \ appendix09.md \ - appendix10.md + appendix10.md \ + appendix11.md ifeq ($(DOC_LANG),JA) PDF = wolfSSL-Manual-jp.pdf @@ -77,6 +78,14 @@ html-prep: api # 4. Three regexes to remove metadata which outputs in the PDF text # 5. Fix titles of the header files Markdown # 6. Two regexes to handle bad Doxygen that didn't convert and the LaTeX processor thinks is LaTeX commands +# Cat: +# A. wolfSSL API Reference +# B. wolfCrypt API Reference -> Utilities / basic items, then Algorithms +# C. API Header Files +# NOTE: The `cat` commands below assemble the wolfSSL (A), wolfCrypt (B), and +# API Header File (C) references for the PDF from hardcoded lists. They mirror +# the API Reference nav sections in mkdocs.yml (which drive the HTML build); the +# PDF build does not read that nav. Keep both locations in sync. .PHONY: pdf-prep pdf-prep: api $(Q)cp src/*.png build/pdf/ @@ -89,12 +98,12 @@ pdf-prep: api $(Q)perl -i -pe "s/^-(-)+$$//" build/pdf/group* build/pdf/*8h* $(Q)perl -i -pe "s/^title:.*//" build/pdf/group* build/pdf/*8h* $(Q)perl -i -pe "s/^Updated on.*//" build/pdf/group* build/pdf/*8h* - $(Q)perl -i -pe "s/dox_comments\/$(HEADER_fFILES)\///" build/pdf/*8h* + $(Q)perl -i -pe "s/dox_comments\/$(HEADER_FILES)\///" build/pdf/*8h* $(Q)perl -i -pe "s/^\\\\//" build/pdf/group* build/pdf/*8h* $(Q)perl -i -pe "s/\\\\par/par/g" build/pdf/group* build/pdf/*8h* $(Q)perl -i -pe "s/group__.*.md//g" build/pdf/*8h* build/pdf/chapter* $(Q)perl -i -pe "s/(ssl|wolfio|cryptocb|types|hash)_8h.md//g" build/pdf/chapter* $(Q)cat build/pdf/group__CertManager.md build/pdf/group__Memory.md build/pdf/group__openSSL.md build/pdf/group__CertsKeys.md build/pdf/group__IO.md build/pdf/group__Setup.md build/pdf/group__Debug.md build/pdf/group__TLS.md >> build/pdf/appendix01.md - $(Q)cat build/pdf/group__ASN.md build/pdf/group__Base__Encoding.md build/pdf/group__Compression.md build/pdf/group__Error.md build/pdf/group__IoTSafe.md build/pdf/group__Logging.md build/pdf/group__Math.md build/pdf/group__Random.md build/pdf/group__Signature.md build/pdf/group__wolfCrypt.md build/pdf/group__DES.md build/pdf/group__AES.md build/pdf/group__ARC4.md build/pdf/group__BLAKE2.md build/pdf/group__Camellia.md build/pdf/group__ChaCha.md build/pdf/group__ChaCha20Poly1305.md build/pdf/group__Crypto.md build/pdf/group__Curve25519.md build/pdf/group__Curve448.md build/pdf/group__DSA.md build/pdf/group__Diffie-Hellman.md build/pdf/group__ECC.md build/pdf/group__ED25519.md build/pdf/group__ED448.md build/pdf/group__PSA.md build/pdf/group__SipHash.md >> build/pdf/appendix02.md - $(Q)cat build/pdf/aes_8h.md build/pdf/arc4_8h.md build/pdf/asn_8h.md build/pdf/asn__public_8h.md build/pdf/blake2_8h.md build/pdf/bn_8h.md build/pdf/camellia_8h.md build/pdf/chacha20__poly1305_8h.md build/pdf/chacha_8h.md build/pdf/cmac_8h.md build/pdf/coding_8h.md build/pdf/compress_8h.md build/pdf/cryptocb_8h.md build/pdf/curve25519_8h.md build/pdf/curve448_8h.md build/pdf/des3_8h.md build/pdf/dh_8h.md build/pdf/doxygen__groups_8h.md build/pdf/doxygen__pages_8h.md build/pdf/dsa_8h.md build/pdf/ecc_8h.md build/pdf/eccsi_8h.md build/pdf/ed25519_8h.md build/pdf/ed448_8h.md build/pdf/error-crypt_8h.md build/pdf/evp_8h.md build/pdf/hash_8h.md build/pdf/hmac_8h.md build/pdf/iotsafe_8h.md build/pdf/logging_8h.md build/pdf/md2_8h.md build/pdf/md4_8h.md build/pdf/md5_8h.md build/pdf/memory_8h.md build/pdf/pem_8h.md build/pdf/pkcs11_8h.md build/pdf/pkcs7_8h.md build/pdf/poly1305_8h.md build/pdf/psa_8h.md build/pdf/pwdbased_8h.md build/pdf/quic_8h.md build/pdf/random_8h.md build/pdf/ripemd_8h.md build/pdf/rsa_8h.md build/pdf/sakke_8h.md build/pdf/sha256_8h.md build/pdf/sha512_8h.md build/pdf/sha_8h.md build/pdf/signature_8h.md build/pdf/siphash_8h.md build/pdf/srp_8h.md build/pdf/ssl_8h.md build/pdf/tfm_8h.md build/pdf/types_8h.md build/pdf/wc__encrypt_8h.md build/pdf/wc__port_8h.md build/pdf/wolfio_8h.md >> build/pdf/appendix03.md + $(Q)cat build/pdf/group__ASN.md build/pdf/group__Base__Encoding.md build/pdf/group__Compression.md build/pdf/group__Error.md build/pdf/group__IoTSafe.md build/pdf/group__Logging.md build/pdf/group__Math.md build/pdf/group__Random.md build/pdf/group__Signature.md build/pdf/group__wolfCrypt.md build/pdf/group__DES.md build/pdf/group__AES.md build/pdf/group__ARC4.md build/pdf/group__BLAKE2.md build/pdf/group__Camellia.md build/pdf/group__ChaCha.md build/pdf/group__ChaCha20Poly1305.md build/pdf/group__CMAC.md build/pdf/group__Crypto.md build/pdf/group__Curve25519.md build/pdf/group__Curve448.md build/pdf/group__DSA.md build/pdf/group__Diffie-Hellman.md build/pdf/group__ECC.md build/pdf/group__ED25519.md build/pdf/group__ED448.md build/pdf/group__ECCSI__Overview.md build/pdf/group__ECCSI__Setup.md build/pdf/group__ECCSI__Operations.md build/pdf/group__SAKKE__Overview.md build/pdf/group__SAKKE__Setup.md build/pdf/group__SAKKE__RSK.md build/pdf/group__SAKKE__Operations.md build/pdf/group__HMAC.md build/pdf/group__LMS.md build/pdf/group__MD2.md build/pdf/group__MD4.md build/pdf/group__MD5.md build/pdf/group__ML__DSA.md build/pdf/group__ML__KEM.md build/pdf/group__Password.md build/pdf/group__PKCS7.md build/pdf/group__PKCS11.md build/pdf/group__Poly1305.md build/pdf/group__PSA.md build/pdf/group__PUF.md build/pdf/group__RIPEMD.md build/pdf/group__RSA.md build/pdf/group__SHA.md build/pdf/group__SHE.md build/pdf/group__SipHash.md build/pdf/group__SLH__DSA.md build/pdf/group__SrtpKdf.md build/pdf/group__SRP.md build/pdf/group__XMSS.md >> build/pdf/appendix02.md + $(Q)cat build/pdf/aes_8h.md build/pdf/arc4_8h.md build/pdf/ascon_8h.md build/pdf/asn_8h.md build/pdf/asn__public_8h.md build/pdf/blake2_8h.md build/pdf/bn_8h.md build/pdf/camellia_8h.md build/pdf/chacha20__poly1305_8h.md build/pdf/chacha_8h.md build/pdf/cmac_8h.md build/pdf/coding_8h.md build/pdf/compress_8h.md build/pdf/cryptocb_8h.md build/pdf/curve25519_8h.md build/pdf/curve448_8h.md build/pdf/des3_8h.md build/pdf/dh_8h.md build/pdf/doxygen__groups_8h.md build/pdf/doxygen__pages_8h.md build/pdf/dsa_8h.md build/pdf/ecc_8h.md build/pdf/eccsi_8h.md build/pdf/ed25519_8h.md build/pdf/ed448_8h.md build/pdf/error-crypt_8h.md build/pdf/evp_8h.md build/pdf/hash_8h.md build/pdf/hmac_8h.md build/pdf/iotsafe_8h.md build/pdf/kdf_8h.md build/pdf/logging_8h.md build/pdf/md2_8h.md build/pdf/md4_8h.md build/pdf/md5_8h.md build/pdf/memory_8h.md build/pdf/ocsp_8h.md build/pdf/pem_8h.md build/pdf/pkcs11_8h.md build/pdf/pkcs7_8h.md build/pdf/poly1305_8h.md build/pdf/psa_8h.md build/pdf/puf_8h.md build/pdf/pwdbased_8h.md build/pdf/quic_8h.md build/pdf/random_8h.md build/pdf/ripemd_8h.md build/pdf/rsa_8h.md build/pdf/sakke_8h.md build/pdf/sha256_8h.md build/pdf/sha3_8h.md build/pdf/sha512_8h.md build/pdf/sha_8h.md build/pdf/signature_8h.md build/pdf/siphash_8h.md build/pdf/srp_8h.md build/pdf/ssl_8h.md build/pdf/tfm_8h.md build/pdf/types_8h.md build/pdf/wc__encrypt_8h.md build/pdf/wc__lms_8h.md build/pdf/wc__mldsa_8h.md build/pdf/wc__mlkem_8h.md build/pdf/wc__port_8h.md build/pdf/wc__she_8h.md build/pdf/wc__slhdsa_8h.md build/pdf/wc__xmss_8h.md build/pdf/wolfio_8h.md >> build/pdf/appendix03.md diff --git a/wolfSSL/mkdocs.yml b/wolfSSL/mkdocs.yml index 71cc14f6..8765fec9 100644 --- a/wolfSSL/mkdocs.yml +++ b/wolfSSL/mkdocs.yml @@ -20,6 +20,10 @@ nav: - "14. Licensing": chapter14.md - "15. Support and Consulting": chapter15.md - "16. wolfSSL Updates": chapter16.md + # NOTE: The PDF build (see Makefile, pdf-prep target) assembles the wolfSSL + # (A), wolfCrypt (B), and API Header File (C) references from hardcoded `cat` + # lists. It does not read this nav, so keep those `cat` commands in sync with + # these sections. - "A. wolfSSL API Reference": - "CertManager API": group__CertManager.md - "Memory Handling": group__Memory.md @@ -47,7 +51,7 @@ nav: - "Algorithms - Camellia": group__Camellia.md - "Algorithms - ChaCha": group__ChaCha.md - "Algorithms - ChaCha20_Poly1305": group__ChaCha20Poly1305.md - - "Algorithms - CMAC ": group__CMAC.md + - "Algorithms - CMAC": group__CMAC.md - "Callbacks - CryptoCb": group__Crypto.md - "Algorithms - Curve25519": group__Curve25519.md - "Algorithms - Curve448": group__Curve448.md @@ -66,21 +70,27 @@ nav: - "Operations on/with SAKKE RSK": group__SAKKE__RSK.md - "Operations using SAKKE Key": group__SAKKE__Operations.md - "Algorithms - HMAC": group__HMAC.md + - "Algorithms - LMS / HSS (RFC 8554)": group__LMS.md - "Algorithms - MD2": group__MD2.md - "Algorithms - MD4": group__MD4.md - "Algorithms - MD5": group__MD5.md + - "Algorithms - ML-DSA (FIPS 204)": group__ML__DSA.md + - "Algorithms - ML-KEM (FIPS 203)": group__ML__KEM.md - "Algorithms - Password Based": group__Password.md - "Algorithms - PKCS7": group__PKCS7.md - "Algorithms - PKCS11": group__PKCS11.md - "Algorithms - Poly1305": group__Poly1305.md - "Algorithms - PSA": group__PSA.md + - "Algorithms - PUF": group__PUF.md - "Algorithms - RIPEMD": group__RIPEMD.md - "Algorithms - RSA": group__RSA.md - "Algorithms - SHA 128/224/256/384/512": group__SHA.md - "Algorithms - SHE": group__SHE.md - "Algorithms - SipHash": group__SipHash.md + - "Algorithms - SLH-DSA (FIPS 205)": group__SLH__DSA.md - "Algorithms - SrtpKdf": group__SrtpKdf.md - "Algorithms - SRP": group__SRP.md + - "Algorithms - XMSS / XMSS^MT (RFC 8391)": group__XMSS.md - "C. API Header Files": - aes_8h.md - arc4_8h.md @@ -124,6 +134,7 @@ nav: - pkcs7_8h.md - poly1305_8h.md - psa_8h.md + - puf_8h.md - pwdbased_8h.md - quic_8h.md - random_8h.md @@ -138,11 +149,16 @@ nav: - siphash_8h.md - srp_8h.md - ssl_8h.md - - wc__she_8h.md - tfm_8h.md - types_8h.md - wc__encrypt_8h.md + - wc__lms_8h.md + - wc__mldsa_8h.md + - wc__mlkem_8h.md - wc__port_8h.md + - wc__she_8h.md + - wc__slhdsa_8h.md + - wc__xmss_8h.md - wolfio_8h.md - "D. SSL/TLS Overview": appendix04.md - "E. RFCs, Specifications, and Reference": appendix05.md diff --git a/wolfSSL/src/appendix06.md b/wolfSSL/src/appendix06.md index e62b1770..985cba6d 100644 --- a/wolfSSL/src/appendix06.md +++ b/wolfSSL/src/appendix06.md @@ -92,7 +92,7 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `UNKNOWN_MAX_FRAG_LEN_E` | -382 | Unrecognized max frag len Error | | `KEYUSE_SIGNATURE_E` | -383 | KeyUse digSignature error | | `KEYUSE_ENCIPHER_E` | -385 | KeyUse KeyEncipher error | -| `EXTKEYUSE_AUTH_E` | -386 | ExtKeyUse server|client_auth | +| `EXTKEYUSE_AUTH_E` | -386 | ExtKeyUse server\|client_auth | | `SEND_OOB_READ_E` | -387 | Send Cb out of bounds read | | `SECURE_RENEGOTIATION_E` | -388 | Invalid renegotiation info | | `SESSION_TICKET_LEN_E` | -389 | Session Ticket too large | diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index 557c6d97..95376388 100644 --- a/wolfSSL/src/chapter02.md +++ b/wolfSSL/src/chapter02.md @@ -1185,7 +1185,7 @@ Enables TLS session ticket support (RFC 5077). Allows the server to issue sessio #### HAVE_TRUSTED_CA -Enables the Trusted CA Indication TLS extension (RFC 4366). Allows the client to indicate which CA certificates it trusts, helping the server select the appropriate certificate chain. +Enables the Trusted CA Indication TLS extension (RFC 6066). Allows the client to indicate which CA certificates it trusts, helping the server select the appropriate certificate chain. #### HAVE_RPK @@ -1801,7 +1801,7 @@ Enables debug logging for the OpenSSL compatibility layer functions. Helps trace #### HAVE_BLAKE2 -Enables Blake2s algorithm support +Enables Blake2b algorithm support #### HAVE_FALLBACK_SCSV @@ -2506,7 +2506,7 @@ This extension allows debugging callbacks through the use of signals in an envir #### WOLF_CRYPTO_CB - Enable crypto callback support. This feature is also enabled automatically when [`--enable-cryptocb`](#enable-cryptocb) is used. + Enable crypto callback support. This feature is also enabled automatically when [`--enable-cryptocb`](#--enable-cryptocb) is used. #### WOLF_CRYPTO_CB_FIND @@ -2562,7 +2562,7 @@ Allow allocation of subjectCN and publicKey fields when parsing certificates eve #### WOLFSSL_USER_IO -Allows the user to remove automatic setting of the default I/O functions [`EmbedSend()`](wolfio_8h.md#function-embedsend) and [`EmbedReceive()`](wolfio_8h.md#function-embedrecieve). Used for custom I/O abstraction layer (see [Abstraction Layers](chapter05.md#abstraction-layers) for more details). +Allows the user to remove automatic setting of the default I/O functions [`EmbedSend()`](wolfio_8h.md#function-embedsend) and [`EmbedReceive()`](wolfio_8h.md#function-embedreceive). Used for custom I/O abstraction layer (see [Abstraction Layers](chapter05.md#abstraction-layers) for more details). #### NO_FILESYSTEM @@ -4766,7 +4766,7 @@ Enables RSA verify only support (**note** requires [`--enable-cryptonly`](#--ena ### `--enable-rsapub` -Default value: Enabled RSA public key only support (**note** requires [`--enable-cryptonly`](#--enable-cryptonly)) +Enables RSA public key only support (**note** requires [`--enable-cryptonly`](#--enable-cryptonly)) ### `--enable-armasm` @@ -4782,7 +4782,7 @@ Disable TLS 1.2 support Enable TLS 1.3 support -This build option can be combined with [`--disable-tlsv12`](#--disable-tlsv12) and [`--disable-oldtls`](#--disable-oldtlx) to produce a wolfSSL build that is only TLS 1.3. +This build option can be combined with [`--disable-tlsv12`](#--disable-tlsv12) and [`--disable-oldtls`](#--disable-oldtls) to produce a wolfSSL build that is only TLS 1.3. ### `--enable-all` @@ -4851,7 +4851,7 @@ The following two defines can be used with `--enable-cryptocb` to complie out RS * WOLF_CRYPTO_CB_ONLY_RSA - compiles out RSA software crypto fallback * WOLF_CRYPTO_CB_ONLY_ECC - compiles out ECC software crypto fallback -Use of the WOLF_CRYPTO_CB_ONLY_* options requires disabling the examples. See [`--disable-examples`](#disable-examples) +Use of the WOLF_CRYPTO_CB_ONLY_* options requires disabling the examples. See [`--disable-examples`](#--disable-examples) ### `--enable-reproducible-build` diff --git a/wolfSSL/src/chapter03.md b/wolfSSL/src/chapter03.md index 7690e365..91fc1284 100644 --- a/wolfSSL/src/chapter03.md +++ b/wolfSSL/src/chapter03.md @@ -216,7 +216,7 @@ Returns: wolfSSL_connect avg took: 296.417 milliseconds ``` -If you'd like to change the default host from localhost, or the default port from 11111, you can change these settings in `/wolfssl/test.h`. The variables wolfSSLIP and wolfSSLPort control these settings. Re-build all of the examples including testsuite when changing these settings otherwise the test programs won't be able to connect to each other. +If you'd like to change the default host from localhost, or the default port from 11111, you can change these settings in `wolfssl/test.h`. The variables wolfSSLIP and wolfSSLPort control these settings. Re-build all of the examples including testsuite when changing these settings otherwise the test programs won't be able to connect to each other. By default, the wolfSSL example client tries to connect to the specified server using TLS 1.2. The user is able to change the SSL/TLS version which the client uses by passing the `-v` command line option. The following values are available for this option: @@ -454,7 +454,7 @@ There are several build options available to make building the benchmark applica #### BENCH_EMBEDDED -Enabling this define will switch the benchmark application from using Megabytes to using Kilobytes, therefore reducing the memory usage. By default, when using this define, ciphers and algorithms will be benchmarked with 25kB. Public key algorithms will only be benchmarked over 1 iteration (as public key operations on some embedded processors can be fairly slow). These can be adjusted in `benchmark.c` by altering the variables `numBlocks` and `times` located inside the `BENCH_EMBEDDED` define. +Enabling this define will switch the benchmark application from using Megabytes to using Kilobytes, therefore reducing the memory usage. By default, when using this define, ciphers and algorithms will be benchmarked with 25kB. Public key algorithms will only be benchmarked over 1 iteration (as public key operations on some embedded processors can be fairly slow). These can be adjusted in `benchmark.c` by altering the variables `numBlocks` and `ntimes` located inside the `BENCH_EMBEDDED` define. #### USE_CERT_BUFFERS_1024 @@ -552,7 +552,7 @@ calling: wolfSSL_Cleanup(); ``` - For an example of a client application using wolfSSL, see the client example located in the `/examples/client.c` file. + For an example of a client application using wolfSSL, see the client example located in the `/examples/client/client.c` file. ## Changing a Server Application to Use wolfSSL @@ -594,4 +594,4 @@ This section will explain the basic steps needed to add wolfSSL to a server appl It is possible to load certificates and keys from buffers as well if there is no filesystem available. In this case, see the [`wolfSSL_CTX_use_certificate_buffer()`](group__CertsKeys.md#function-wolfssl_ctx_use_certificate_buffer) and [`wolfSSL_CTX_use_PrivateKey_buffer()`](group__CertsKeys.md#function-wolfssl_ctx_use_privatekey_buffer) API documentation, linked here, for more information. -For an example of a server application using wolfSSL, see the server example located in the `/examples/server.c` file. +For an example of a server application using wolfSSL, see the server example located in the `/examples/server/server.c` file. diff --git a/wolfSSL/src/chapter04.md b/wolfSSL/src/chapter04.md index 115ef1ae..0a25073e 100644 --- a/wolfSSL/src/chapter04.md +++ b/wolfSSL/src/chapter04.md @@ -357,11 +357,11 @@ PKCS #5 is a password-based key derivation method which combines a password, a s wolfSSL also supports the PBKDF function from PKCS #12 in addition to PBKDF1 and PBKDF2. The function prototypes look like this: ```c -int PBKDF2(byte* output, const byte* passwd, int pLen, +int wc_PBKDF2(byte* output, const byte* passwd, int pLen, const byte* salt, int sLen, int iterations, int kLen, int hashType); -int PKCS12_PBKDF(byte* output, const byte* passwd, int pLen, +int wc_PKCS12_PBKDF(byte* output, const byte* passwd, int pLen, const byte* salt, int sLen, int iterations, int kLen, int hashType, int purpose); ``` @@ -410,7 +410,7 @@ For streaming when decoding/verifying bundles the following functions are suppor 1. `wc_PKCS7_DecodeEncryptedData()` 2. [`wc_PKCS7_VerifySignedData()`](group__PKCS7.md#function-wc_pkcs7_verifysigneddata) 3. [`wc_PKCS7_VerifySignedData_ex()`](group__PKCS7.md#function-wc_pkcs7_verifysigneddata_ex) -4. [`wc_PKCS7_DecodeEnvelopedData()`](group__PKCS7.md#function-wc_pkcs7_decodeenvelopeddate) +4. [`wc_PKCS7_DecodeEnvelopedData()`](group__PKCS7.md#function-wc_pkcs7_decodeenvelopeddata) 5. `wc_PKCS7_DecodeAuthEnvelopedData()` **Note**: that when calling [`wc_PKCS7_VerifySignedData_ex`](group__PKCS7.md#function-wc_pkcs7_verifysigneddata_ex) it is expected that the argument pkiMsgFoot is the full buffer. The internal structure only supports streaming of one buffer, which in this case would be `pkiMsgHead`. @@ -432,7 +432,7 @@ wolfSSL_CTX_set_cipher_list(ctx, "AES128-SHA"); ### OpenQuantumSafe's liboqs Integration -Please see the appendix [Experimenting with Post-Quantum Cryptography](appendix07.md#experimenting-with-post-quantum-cryptography) in this document for more details. +Please see the appendix [Experimenting with Post-Quantum Cryptography](appendix09.md#experimenting-with-post-quantum-cryptography) in this document for more details. ## Hardware Accelerated Crypto @@ -897,7 +897,7 @@ For DTLS server: |API|description| |:---|:---| -|[`wolfSSL_CTX_load_static_memory`](group__Memory.md#function-wolfSSL_CTX_static_memory)| Set buffer for WOLFSSL_CTX as a heap memory. | +|[`wolfSSL_CTX_load_static_memory`](group__Memory.md#function-wolfssl_ctx_load_static_memory)| Set buffer for WOLFSSL_CTX as a heap memory. | |[`wolfSSL_CTX_is_static_memory`](group__Memory.md#function-wolfSSL_CTX_is_static_memory)| Returns whether "Static buffer Allocation" is used. If it is the case, gets usage report. | |[`wolfSSL_is_static_memory`](group__Memory.md#function-wolfSSL_is_static_memory)| Returns whether "Static buffer Allocation" is used. If it is the case, gets usage report. | |[`wc_LoadStaticMemory`](group__Memory.md#function-wc_LoadStaticMemory)| Used to set aside static memory for wolfCrypt use. | @@ -1007,7 +1007,7 @@ On the server side one of the same function calls is required. Since the wolfSSL ### Grouping Handshake Messages -wolfSSL has the ability to group handshake messages if the user desires. This can be done at the context level with [`wolfSSL_CTX_set_group_messages(ctx);`](group__Setup.md#function-wolfssl_ct_set_group_messages) or at the SSL object level with [`wolfSSL_set_group_messages(ssl);`](group__Setup.md#function-wolfssl_set_group_messages). +wolfSSL has the ability to group handshake messages if the user desires. This can be done at the context level with [`wolfSSL_CTX_set_group_messages(ctx);`](group__Setup.md#function-wolfssl_ctx_set_group_messages) or at the SSL object level with [`wolfSSL_set_group_messages(ssl);`](group__Setup.md#function-wolfssl_set_group_messages). ## Truncated HMAC @@ -1022,7 +1022,7 @@ Using Truncated HMAC on the client side requires an additional function call, wh * [`wolfSSL_CTX_UseTruncatedHMAC()`](ssl_8h.md#function-wolfssl_ctx_usetruncatedhmac) * [`wolfSSL_UseTruncatedHMAC()`](ssl_8h.md#function-wolfssl_usetruncatedhmac) -[`wolfSSL_CTX_UseTruncatedHMAC()`](ssl_8h.md#function-wolfssl_ctx_usetrunctatedhmac) is most recommended when the client would like to enable Truncated HMAC for all sessions. Setting the Truncated HMAC extension at context level will enable it in all SSL objects created from that same context from the moment of the call forward. +[`wolfSSL_CTX_UseTruncatedHMAC()`](ssl_8h.md#function-wolfssl_ctx_usetruncatedhmac) is most recommended when the client would like to enable Truncated HMAC for all sessions. Setting the Truncated HMAC extension at context level will enable it in all SSL objects created from that same context from the moment of the call forward. [`wolfSSL_UseTruncatedHMAC()`](ssl_8h.md#function-wolfssl_usetruncatedhmac) will enable it for one SSL object only, so it's recommended to use this function when there is no need for Truncated HMAC on all sessions. diff --git a/wolfSSL/src/chapter05.md b/wolfSSL/src/chapter05.md index ea384772..92303c24 100644 --- a/wolfSSL/src/chapter05.md +++ b/wolfSSL/src/chapter05.md @@ -37,7 +37,7 @@ After defining `STRING_USER` you could do: Or if you prefer to avoid macros: ```c -external void* my_memcpy(void* d, const void* s, size_t n); +extern void* my_memcpy(void* d, const void* s, size_t n); ``` to set wolfSSL’s abstraction layer to point to your version `my_memcpy()`. @@ -59,7 +59,7 @@ The user will need to define two functions: 1. The network Send function 2. The network Receive function -These two functions are prototyped by `CallbackIOSend` and `CallbackIORecv` in `ssl.h`: +These two functions are prototyped by `CallbackIOSend` and `CallbackIORecv` in `wolfssl/wolfio.h`: ```c typedef int (*CallbackIORecv)(WOLFSSL *ssl, char *buf, int sz, void *ctx); diff --git a/wolfSSL/src/chapter06.md b/wolfSSL/src/chapter06.md index f2cd745e..384dd4c5 100644 --- a/wolfSSL/src/chapter06.md +++ b/wolfSSL/src/chapter06.md @@ -2,7 +2,7 @@ ## HandShake Callback -wolfSSL (formerly CyaSSL) has an extension that allows a HandShake Callback to be set for connect or accept. This can be useful in embedded systems for debugging support when another debugger isn’t available and sniffing is impractical. To use wolfSSL HandShake Callbacks, use the extended functions, [`wolfSSL_connect_ex()`](ssl_8h.md#function_wolfssl_connect_ex) and [`wolfSSL_accept_ex()`](ssl_8h.md#function-wolfssl_accept_ex): +wolfSSL (formerly CyaSSL) has an extension that allows a HandShake Callback to be set for connect or accept. This can be useful in embedded systems for debugging support when another debugger isn’t available and sniffing is impractical. To use wolfSSL HandShake Callbacks, use the extended functions, [`wolfSSL_connect_ex()`](ssl_8h.md#function-wolfssl_connect_ex) and [`wolfSSL_accept_ex()`](ssl_8h.md#function-wolfssl_accept_ex): ```c int wolfSSL_connect_ex(WOLFSSL*, HandShakeCallBack, TimeoutCallBack, @@ -147,7 +147,7 @@ The user can set a context per WOLFSSL object (session) with `wolfSSL_SetDhAgree Example callbacks can be found in `wolfssl/test.h`, under `myDhCallback()`. Usage can be seen in the wolfSSL example client. -To use DH callbacks, wolfSSL needs to be compiled with `HAVE_DH` defined. +To use DH callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and `HAVE_DH` defined. ### Ed25519 Callbacks @@ -397,7 +397,7 @@ typedef int (*CallbackRsaVerify)(WOLFSSL* ssl, typedef int (*CallbackRsaEnc)(WOLFSSL* ssl, const unsigned char* in, unsigned int inSz, - Unsigned char* out, unsigned int* outSz, + unsigned char* out, unsigned int* outSz, const unsigned char* keyDer, unsigned int keySz, void* ctx); @@ -584,7 +584,7 @@ when `info->algo_type == WC_ALGO_TYPE_RNG` is a memory error and can result in u ### Troubleshooting -Some older compilers don't allow "anonymous inline aggregates", which wolfCrypt uses when defining the nested `wcCryptoInfo` anonymous unions in order to save space. To disable the use of anonymous inline aggregates, define the `HAVE_ANONYMOUS_INLINE_AGGREGATES` preprocessor macro as `0`. This will allow crypto callbacks to be used, but will dramatically increase the size of the `wcCryptoInfo` structure. +Some older compilers don't allow "anonymous inline aggregates", which wolfCrypt uses when defining the nested `wc_CryptoInfo` anonymous unions in order to save space. To disable the use of anonymous inline aggregates, define the `HAVE_ANONYMOUS_INLINE_AGGREGATES` preprocessor macro as `0`. This will allow crypto callbacks to be used, but will dramatically increase the size of the `wc_CryptoInfo` structure. ### Examples diff --git a/wolfSSL/src/chapter07.md b/wolfSSL/src/chapter07.md index 62c44fc1..579de75a 100644 --- a/wolfSSL/src/chapter07.md +++ b/wolfSSL/src/chapter07.md @@ -186,7 +186,7 @@ Following this model, as long as root cert "A" has been loaded as a trusted root ## Domain Name Check for Server Certificates -wolfSSL has an extension on the client that automatically checks the domain of the server certificate. In OpenSSL mode nearly a dozen function calls are needed to perform this. wolfSSL checks that the date of the certificate is in range, verifies the signature, and additionally verifies the domain if you call [`wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn)`](group__Setup.md#function-wolfssl_check_domain_name) before calling [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect). wolfSSL will match the X.509 issuer name of peer's server certificate against `dn` (the expected domain name). If the names match [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect) will proceed normally, however if there is a name mismatch, [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect) will return a fatal error and [`wolfSSL_get_error()`](group__Debug.md#function-wolfssl_get_error) will return `DOMAIN_NAME_MISMATCH`. +wolfSSL has an extension on the client that automatically checks the domain of the server certificate. In OpenSSL mode nearly a dozen function calls are needed to perform this. wolfSSL checks that the date of the certificate is in range, verifies the signature, and additionally verifies the domain if you call [`wolfSSL_check_domain_name(WOLFSSL* ssl, const char* dn)`](group__Setup.md#function-wolfssl_check_domain_name) before calling [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect). wolfSSL will match the X.509 subject name of peer's server certificate against `dn` (the expected domain name). If the names match [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect) will proceed normally, however if there is a name mismatch, [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect) will return a fatal error and [`wolfSSL_get_error()`](group__Debug.md#function-wolfssl_get_error) will return `DOMAIN_NAME_MISMATCH`. Checking the domain name of the certificate is an important step that verifies the server is actually who it claims to be. This extension is intended to ease the burden of performing the check. @@ -222,7 +222,7 @@ int wolfSSL_X509_get_serial_number(WOLFSSL_X509* x509, wolfSSL supports RSA key generation of varying lengths up to 4096 bits. Key generation is off by default but can be turned on during the `./configure` process with `--enable-keygen` or by defining `WOLFSSL_KEY_GEN` in Windows or non-standard environments. Creating a key is easy, only requiring one function from `rsa.h`: ```c -int MakeRsaKey(RsaKey* key, int size, long e, RNG* rng); +int wc_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: @@ -232,19 +232,19 @@ RsaKey genKey; RNG rng; int ret; -InitRng(&rng); -InitRsaKey(&genKey, 0); +wc_InitRng(&rng); +wc_InitRsaKey(&genKey, 0); -ret = MakeRsaKey(&genKey, 1024, 65537, &rng); +ret = wc_MakeRsaKey(&genKey, 1024, 65537, &rng); if (ret != 0) /* ret contains error */; ``` -The RsaKey `genKey` can now be used like any other RsaKey. If you need to export the key, wolfSSL provides both DER and PEM formatting in asn.h. Always convert the key to DER format first, and then if you need PEM use the generic `DerToPem()` function like this: +The RsaKey `genKey` can now be used like any other RsaKey. If you need to export the key, wolfSSL provides both DER and PEM formatting in asn.h. Always convert the key to DER format first, and then if you need PEM use the generic `wc_DerToPem()` function like this: ```c byte der[4096]; -int derSz = RsaKeyToDer(&genKey, der, sizeof(der)); +int derSz = wc_RsaKeyToDer(&genKey, der, sizeof(der)); if (derSz < 0) /* derSz contains error */; ``` @@ -253,7 +253,7 @@ The buffer `der` now holds a DER format of the key. To convert the DER buffer to ```c byte pem[4096]; -int pemSz = DerToPem(der, derSz, pem, sizeof(pem), +int pemSz = wc_DerToPem(der, derSz, pem, sizeof(pem), PRIVATEKEY_TYPE); if (pemSz < 0) /* pemSz contains error */; @@ -285,7 +285,7 @@ The last argument of _DerToPem()_ takes a type parameter, usually either `PRIVAT The RSA private key contains the public key as well. The private key can be used as both a private and public key by wolfSSL as used in test.c. The private key and the public key (in the form of a certificate) is all that is typically needed for SSL. -A separate public key can be loaded into wolfSSL manually using the RsaPublicKeyDecode() function if need be. Additionally, the [`wc_RsaKeyToPublicDer()`](group__RSA.md#function-wc_rsakeytopublicder) function can be used to export the public RSA key. +A separate public key can be loaded into wolfSSL manually using the wc_RsaPublicKeyDecode() function if need be. Additionally, the [`wc_RsaKeyToPublicDer()`](group__RSA.md#function-wc_rsakeytopublicder) function can be used to export the public RSA key. ## Certificate Generation @@ -334,7 +334,7 @@ Before filling in the subject information an initialization function needs to be ```c Cert myCert; -InitCert(&myCert); +wc_InitCert(&myCert); ``` `InitCert()` sets defaults for some of the variables including setting the version to **3** (0x02), the serial number to **0** (randomly generated), the sigType to `CTC_SHAwRSA`, the daysValid to **500**, and selfSigned to **1** (TRUE). Supported signature types include: @@ -368,17 +368,17 @@ Then, a self-signed certificate can be generated using the variables genKey and ```c byte derCert[4096]; -int certSz = MakeSelfCert(&myCert, derCert, sizeof(derCert), &key, &rng); +int certSz = wc_MakeSelfCert(&myCert, derCert, sizeof(derCert), &key, &rng); if (certSz < 0) /* certSz contains the error */; ``` -The buffer `derCert` now contains a DER format of the certificate. If you need a PEM format of the certificate you can use the generic `DerToPem()` function and specify the type to be `CERT_TYPE` like this: +The buffer `derCert` now contains a DER format of the certificate. If you need a PEM format of the certificate you can use the generic `wc_DerToPem()` function and specify the type to be `CERT_TYPE` like this: ```c -byte* pem; +byte* pemCert[4096]; -int pemSz = DerToPem(derCert, certSz, pem, sizeof(pemCert), CERT_TYPE); +int pemCertSz = wc_DerToPem(derCert, certSz, pemCert, sizeof(pemCert), CERT_TYPE); if (pemCertSz < 0) /* pemCertSz contains error */; ``` @@ -407,24 +407,24 @@ Supported types are: Now the buffer `pemCert` holds the PEM format of the certificate. -If you wish to create a CA signed certificate then a couple of steps are required. After filling in the subject information as before, you’ll need to set the issuer information from the CA certificate. This can be done with `SetIssuer()` like this: +If you wish to create a CA signed certificate then a couple of steps are required. After filling in the subject information as before, you’ll need to set the issuer information from the CA certificate. This can be done with `wc_SetIssuer()` like this: ```c -ret = SetIssuer(&myCert, "ca-cert.pem"); +ret = wc_SetIssuer(&myCert, "ca-cert.pem"); if (ret < 0) /* ret contains error */; ``` -Then you’ll need to perform the two-step process of creating the certificate and then signing it (`MakeSelfCert()` does these both in one step). You’ll need the private keys from both the issuer (`caKey`) and the subject (`key`). Please see the example in `test.c` for complete usage. +Then you’ll need to perform the two-step process of creating the certificate and then signing it (`wc_MakeSelfCert()` does these both in one step). You’ll need the private keys from both the issuer (`caKey`) and the subject (`key`). Please see the example in `test.c` for complete usage. ```c byte derCert[4096]; -int certSz = MakeCert(&myCert, derCert, sizeof(derCert), &key, NULL, &rng); +int certSz = wc_MakeCert(&myCert, derCert, sizeof(derCert), &key, NULL, &rng); if (certSz < 0); /*certSz contains the error*/; -certSz = SignCert(myCert.bodySz, myCert.sigType, derCert, +certSz = wc_SignCert(myCert.bodySz, myCert.sigType, derCert, sizeof(derCert), &caKey, NULL, &rng); if (certSz < 0); /*certSz contains the error*/; @@ -444,7 +444,7 @@ Before filling in the subject information an initialization function needs to be ```c Cert request; -InitCert(&request); +wc_InitCert(&request); ``` `InitCert()` sets defaults for some of the variables including setting the version to **3** (0x02), the serial number to **0** (randomly generated), the sigType to `CTC_SHAwRSA`, the daysValid to **500**, and selfSigned to **1** (TRUE). Supported signature types include: @@ -511,7 +511,7 @@ There are fields that are mandatory in a certificate that are excluded in a CSR. With our recently added support for raw ECC key import comes the ability to convert an ECC key from PEM to DER. Use the following with the specified arguments to accomplish this: ```c -EccKeyToDer(ecc_key*, byte* output, word32 inLen); +wc_EccKeyToDer(ecc_key*, byte* output, word32 inLen); ``` ### Example @@ -521,5 +521,5 @@ EccKeyToDer(ecc_key*, byte* output, word32 inLen); byte der[FOURK_BUF]; ecc_key userB; -EccKeyToDer(&userB, der, FOURK_BUF); +wc_EccKeyToDer(&userB, der, FOURK_BUF); ``` diff --git a/wolfSSL/src/chapter10.md b/wolfSSL/src/chapter10.md index 206a0420..eeea9403 100644 --- a/wolfSSL/src/chapter10.md +++ b/wolfSSL/src/chapter10.md @@ -224,7 +224,7 @@ CTR mode is available for both encryption and decryption through the [`wc_AesCtr #### DES and 3DES -wolfCrypt provides support for DES and 3DES (Des3 since 3 is an invalid leading C identifier). To use these include the header `wolfssl/wolfcrypt/des.h`. The structures you can use are `Des` and `Des3`. Initialization is done through [`wc_Des_SetKey()`](group__DES.md#function-wc_des_setkey) or [`wc_Des3_SetKey()`](group__DES.md#function-wc_des3_setkey). CBC encryption/decryption is provided through [`wc_Des_CbcEnrypt()`](group__DES.md#function-wc_des_cbcencrypt) / [`wc_Des_CbcDecrypt()`](group__DES.md#function-wc_dec_cbcdecrypt) and [`wc_Des3_CbcEncrypt()`](group__DES.md#function-wc_des3_cbcencrypt) / [`wc_Des3_CbcDecrypt()`](group__DES.md#function-wc_des3_cbcdecrypt). Des has a key size of 8 bytes (24 for 3DES) and the block size is 8 bytes, so only pass increments of 8 bytes to encrypt/decrypt functions. If your data isn't in a block size increment you'll need to add padding to make sure it is. Each `SetKey()` also takes an IV (an initialization vector that is the same size as the key size). Usage is usually like the following: +wolfCrypt provides support for DES and 3DES (Des3 since 3 is an invalid leading C identifier). To use these include the header `wolfssl/wolfcrypt/des.h`. The structures you can use are `Des` and `Des3`. Initialization is done through [`wc_Des_SetKey()`](group__DES.md#function-wc_des_setkey) or [`wc_Des3_SetKey()`](group__DES.md#function-wc_des3_setkey). CBC encryption/decryption is provided through [`wc_Des_CbcEncrypt()`](group__DES.md#function-wc_des_cbcencrypt) / [`wc_Des_CbcDecrypt()`](group__DES.md#function-wc_des_cbcdecrypt) and [`wc_Des3_CbcEncrypt()`](group__DES.md#function-wc_des3_cbcencrypt) / [`wc_Des3_CbcDecrypt()`](group__DES.md#function-wc_des3_cbcdecrypt). Des has a key size of 8 bytes (24 for 3DES) and the block size is 8 bytes, so only pass increments of 8 bytes to encrypt/decrypt functions. If your data isn't in a block size increment you'll need to add padding to make sure it is. Each `SetKey()` also takes an IV (an initialization vector that is the same size as the key size). Usage is usually like the following: ```c Des3 enc; @@ -253,7 +253,7 @@ wc_Des3_CbcDecrypt(&dec, plain, cipher, sizeof(cipher)); #### Camellia -wolfCrypt provides support for the Camellia block cipher. To use Camellia include the header `wolfssl/wolfcrypt/camellia.h`. The structure you can use is called `Camellia`. Initialization is done through [`wc_CamelliaSetKey()`](group__Camellia.md#function-wc_camelliasetkey). CBC encryption/decryption is provided through [`wc_CamelliaCbcEnrypt()`](group__Camellia.md#function-wc_CamelliacbcEncrypt) and [`wc_CamelliaCbcDecrypt()`](group__Camellia.md#function-wc_camelliacbcdecrypt) while direct encryption/decryption is provided through [`wc_CamelliaEncryptDirect()`](group__Camellia.md#function-wc_camelliaencryptdirect) and [`wc_CamelliaDecryptDirect()`](group__Camellia.md#function-wc_camelliadecryptdirect). +wolfCrypt provides support for the Camellia block cipher. To use Camellia include the header `wolfssl/wolfcrypt/camellia.h`. The structure you can use is called `Camellia`. Initialization is done through [`wc_CamelliaSetKey()`](group__Camellia.md#function-wc_camelliasetkey). CBC encryption/decryption is provided through [`wc_CamelliaCbcEncrypt()`](group__Camellia.md#function-wc_CamelliacbcEncrypt) and [`wc_CamelliaCbcDecrypt()`](group__Camellia.md#function-wc_camelliacbcdecrypt) while direct encryption/decryption is provided through [`wc_CamelliaEncryptDirect()`](group__Camellia.md#function-wc_camelliaencryptdirect) and [`wc_CamelliaDecryptDirect()`](group__Camellia.md#function-wc_camelliadecryptdirect). For usage examples please see the camellia_test() function in `/wolfcrypt/test/test.c`. @@ -294,8 +294,8 @@ wc_Arc4Process(&dec, plain, cipher, sizeof(cipher)); ChaCha with 20 rounds is slightly faster than ARC4 while maintaining a high level of security. To use it with wolfCrypt, please include the header `wolfssl/wolfcrypt/chacha.h`. ChaCha typically uses 32 byte keys (256 bit) but can also use 16 byte keys (128 bits). ```c -CHACHA enc; -CHACHA dec; +ChaCha enc; +ChaCha dec; const byte key[] = { /*some key 32 bytes*/}; const byte iv[] = { /*some iv 12 bytes*/ }; @@ -336,7 +336,7 @@ byte publicKeyBuffer[] = { /*holds the raw data from the key, maybe from a file like RsaPublicKey.der*/ }; word32 idx = 0; /*where to start reading into the buffer*/ -RsaPublicKeyDecode(publicKeyBuffer, &idx, &rsaPublicKey, sizeof(publicKeyBuffer)); +wc_RsaPublicKeyDecode(publicKeyBuffer, &idx, &rsaPublicKey, sizeof(publicKeyBuffer)); byte in[] = { /*plain text to encrypt*/ }; byte out[128]; @@ -344,18 +344,18 @@ RNG rng; wc_InitRng(&rng); -word32 outLen = RsaPublicEncrypt(in, sizeof(in), out, sizeof(out), &rsaPublicKey, &rng); +word32 outLen = wc_RsaPublicEncrypt(in, sizeof(in), out, sizeof(out), &rsaPublicKey, &rng); ``` -Now `out` holds the ciphertext from the plain text `in`. [`wc_RsaPublicEncrypt()`](group__RSA.md#function-wc_rsapublicencrypt) will return the length in bytes written to out or a negative number in case of an error. [`wc_RsaPublicEncrypt()`](group__RSA.md#function-wc_rsapublicencrypt) needs a RNG (Random Number Generator) for the padding used by the encryptor and it must be initialized before it can be used. To make sure that the output buffer is large enough to pass you can first call [`wc_RsaEncryptSize()`](group__RSA.md#function-wc_rsaencryptsize) which will return the number of bytes that a successful call to [`wc_RsaPublicEnrypt()`](group__RSA.md#function-wc_rsapublicencrypt) will write. +Now `out` holds the ciphertext from the plain text `in`. [`wc_RsaPublicEncrypt()`](group__RSA.md#function-wc_rsapublicencrypt) will return the length in bytes written to out or a negative number in case of an error. [`wc_RsaPublicEncrypt()`](group__RSA.md#function-wc_rsapublicencrypt) needs a RNG (Random Number Generator) for the padding used by the encryptor and it must be initialized before it can be used. To make sure that the output buffer is large enough to pass you can first call [`wc_RsaEncryptSize()`](group__RSA.md#function-wc_rsaencryptsize) which will return the number of bytes that a successful call to [`wc_RsaPublicEncrypt()`](group__RSA.md#function-wc_rsapublicencrypt) will write. -In the event of an error, a negative return from [`wc_RsaPublicEnrypt()`](group__RSA.md#function-wc_rsapublicencrypt), or [`wc_RsaPublicKeyDecode()`](group__RSA.md#function-wc_rsapublickeydecode) for that matter, you can call [`wc_ErrorString()`](group__Error.md#function-wc_errorstring) to get a string describing the error that occurred. +In the event of an error, a negative return from [`wc_RsaPublicEncrypt()`](group__RSA.md#function-wc_rsapublicencrypt), or [`wc_RsaPublicKeyDecode()`](group__RSA.md#function-wc_rsapublickeydecode) for that matter, you can call [`wc_ErrorString()`](group__Error.md#function-wc_errorstring) to get a string describing the error that occurred. ```c void wc_ErrorString(int error, char* buffer); ``` -Make sure that buffer is at least `MAX_ERROR_SZ` bytes (80). +Make sure that buffer is at least `WOLFSSL_MAX_ERROR_SZ` bytes (80). Now to decrypt out: @@ -378,7 +378,7 @@ Now plain will hold plainSz bytes or an error code. For complete examples of eac ### DH (Diffie-Hellman) -wolfCrypt provides support for Diffie-Hellman through the header `wolfssl/wolfrypt/dh.h`. The Diffie-Hellman key exchange algorithm allows two parties to establish a shared secret key. Usage is usually similar to the following example, where **sideA** and **sideB** designate the two parties. +wolfCrypt provides support for Diffie-Hellman through the header `wolfssl/wolfcrypt/dh.h`. The Diffie-Hellman key exchange algorithm allows two parties to establish a shared secret key. Usage is usually similar to the following example, where **sideA** and **sideB** designate the two parties. In the following example, `dhPublicKey` contains the Diffie-Hellman public parameters signed by a Certificate Authority (or self-signed). `privA` holds the generated private key for sideA, `pubA` holds the generated public key for sideA, and `agreeA` holds the mutual key that both sides have agreed on. @@ -398,8 +398,8 @@ wc_InitDhKey(&dhPublicKey); byte publicKeyBuffer[] = { /*holds the raw data from the public key parameters, maybe from a file like - dh1024.der*/ } -wc_DhKeyDecode(tmp, &idx, &dhPublicKey, publicKeyBuffer); + dh1024.der*/ }; +wc_DhKeyDecode(publicKeyBuffer, &idx, &dhPublicKey, sizeof(publicKeyBuffer)); wc_InitRng(&rng); /*Initialize random number generator*/ ``` diff --git a/wolfSSL/src/chapter11.md b/wolfSSL/src/chapter11.md index f81fadd8..2bad93d4 100644 --- a/wolfSSL/src/chapter11.md +++ b/wolfSSL/src/chapter11.md @@ -555,6 +555,6 @@ For production applications, you should obtain correct and legitimate certificat This tutorial walked through the process of integrating the wolfSSL embedded SSL/TLS library into a simple client and server application. Although this example is simple, the same principles may be applied for adding SSL or TLS into your own application. The wolfSSL embedded SSL/TLS library provides all the features you would need in a compact and efficient package that has been optimized for both size and speed. -Being dual licensed under GPLv2 and standard commercial licensing, you are free to download the wolfSSL source code directly from our website. Feel free to post to our support forums () with any questions or comments you might have. If you would like more information about our products, please contact [facts@wolfssl.com](mailto:facts@wolfssl.com). +Being dual licensed under GPLv3 and standard commercial licensing, you are free to download the wolfSSL source code directly from our website. Feel free to post to our support forums () with any questions or comments you might have. If you would like more information about our products, please contact [facts@wolfssl.com](mailto:facts@wolfssl.com). We welcome any feedback you have on this SSL tutorial. If you believe it could be improved or enhanced in order to make it either more useful, easier to understand, or more portable, please let us know at [support@wolfssl.com](mailto:support@wolfssl.com). diff --git a/wolfSSL/src/chapter13.md b/wolfSSL/src/chapter13.md index d9a67c90..8ad7636d 100644 --- a/wolfSSL/src/chapter13.md +++ b/wolfSSL/src/chapter13.md @@ -30,7 +30,7 @@ The points below outline several of the main differences between wolfSSL and Ope 1. With a 20-100 kB build size, wolfSSL is up to 20 times smaller than OpenSSL. wolfSSL is a better choice for resource constrained environments – where every byte matters. 2. wolfSSL is up to date with the most current standards of TLS 1.3 with DTLS. The wolfSSL team is dedicated to continually keeping wolfSSL up-to-date with current standards. 3. wolfSSL offers the best current ciphers and standards available today, including ciphers for streaming media support. In addition, the recently-introduced liboqs integration allows for you to start experimenting with post-quantum cryptography. -4. wolfSSL is dual licensed under both the GPLv2 as well as a commercial license, where OpenSSL is available only under their unique license from multiple sources. +4. wolfSSL is dual licensed under both the GPLv3 as well as a commercial license, where OpenSSL is available only under their unique license from multiple sources. 5. wolfSSL is backed by an outstanding company who cares about its users and about their security, and is always willing to help. The team actively works to improve and expand wolfSSL. The wolfSSL team is based primarily out of Bozeman, MT, Portland, OR, and Seattle, WA, along with other team members located around the globe. 6. wolfSSL is the leading SSL/TLS library for real time, mobile, and embedded systems by virtue of its breadth of platform support and successful implementations on embedded environments. Chances are we’ve already been ported to your environment. If not, let us know and we’ll be glad to help. 7. wolfSSL offers several abstraction layers to make integrating SSL into your environment and platform as easy as possible. With an OS layer, a custom I/O layer, and a C Standard Library abstraction layer, integration has never been so easy. diff --git a/wolfSSL/src/chapter14.md b/wolfSSL/src/chapter14.md index 53095294..70f12721 100644 --- a/wolfSSL/src/chapter14.md +++ b/wolfSSL/src/chapter14.md @@ -2,7 +2,7 @@ ## Open Source -wolfSSL, wolfCrypt, wolfMQTT, wolfTPM, wolfBoot, and wolfSentry are free software downloads and may be modified to the needs of the user as long as the user adheres to version two of the GPL License. The GPLv2 license can be found on the gnu.org website . +wolfSSL, wolfCrypt, wolfMQTT, wolfTPM, wolfBoot, and wolfSentry are free software downloads and may be modified to the needs of the user as long as the user adheres to version three of the GPL License. The GPLv3 license can be found on the gnu.org website . wolfSSH software is a free software download and may be modified to the needs of the user as long as the user adheres to version three of the GPL license. The GPLv3 license can be found on the gnu.org website (). diff --git a/wolfTPM/Makefile b/wolfTPM/Makefile index fb949b7c..523bb59f 100644 --- a/wolfTPM/Makefile +++ b/wolfTPM/Makefile @@ -66,6 +66,9 @@ html-prep: api # 7. For oversized enum table rows (>2000 chars), keep table formatting intact # by splitting enum values across continuation rows to avoid LaTeX # "Dimension too large" errors in longtable +# NOTE: The final `cat` assembles the API Reference for the PDF from a hardcoded +# list. It mirrors the "5. API Reference" nav in mkdocs.yml (which drives the +# HTML build); the PDF build does not read that nav. Keep both lists in sync. .PHONY: pdf-prep pdf-prep: api $(Q)perl -i -pe "s/# /## /g" api/md/*.md diff --git a/wolfTPM/mkdocs.yml b/wolfTPM/mkdocs.yml index 28a467a6..ef6cfebb 100644 --- a/wolfTPM/mkdocs.yml +++ b/wolfTPM/mkdocs.yml @@ -8,6 +8,9 @@ nav: - "2. Building wolfTPM": chapter02.md - "3. Getting Started": chapter03.md - "4. wolfTPM Library Design": chapter04.md + # NOTE: The PDF build (see Makefile, pdf-prep target) assembles the API + # Reference from a hardcoded `cat` list. It does not read this nav, so keep + # that `cat` in sync when modifying the header list below. - "5. API Reference": - "TPM2 API": group__TPM2__Proprietary.md - "TPM2 Wrapper API": group__wolfTPM2__Wrappers.md