From 5fb35530f7979aa3d9dbe5fcd28740145989910f Mon Sep 17 00:00:00 2001 From: Andrew Hutchings Date: Fri, 6 Nov 2026 08:56:50 +0000 Subject: [PATCH 01/25] wolfSSL manual: build: fix API link rewriting, add missing API pages - html-prep/pdf-prep: the regex that converts Doxybook2 function anchors was greedy, so every function link after the first on a line was rewritten to "#function_xxx" and broke. Match up to the closing paren only, and apply the same dash to underscore fix to typedef and variable anchors. - Links to the top of a header page ("#file-types.h") matched no heading id. Drop the anchor in the HTML build and point it at the header page's heading id in the PDF build. - pdf-prep: also strip group__*.md and *_8h.md link prefixes in the appendices (links from appendix pages into the API reference were left as dead file links in the PDF), and strip any *_8h.md prefix rather than a fixed list of five header pages. - Add the generated API pages that were missing from the mkdocs nav and the PDF: Argon2, Falcon, FrodoKEM, HPKE, STM32, TSP and wolfEntropy groups plus ten header pages. These only exist in the English Doxygen input, so they are filtered out of the Japanese PDF build. - Doxyfile: remove ten tags current doxygen reports as obsolete. - Update the copyright year. --- wolfSSL/Doxyfile | 95 ---------------------------------------------- wolfSSL/Makefile | 29 ++++++++++---- wolfSSL/mkdocs.yml | 19 +++++++++- 3 files changed, 39 insertions(+), 104 deletions(-) diff --git a/wolfSSL/Doxyfile b/wolfSSL/Doxyfile index 0a807d5f..f9f8e883 100644 --- a/wolfSSL/Doxyfile +++ b/wolfSSL/Doxyfile @@ -1207,15 +1207,6 @@ HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the @@ -1484,17 +1475,6 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANSPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES - # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # https://www.mathjax.org) which uses client side Javascript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX @@ -1773,16 +1753,6 @@ LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source -# code with syntax highlighting in the LaTeX output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_SOURCE_CODE = NO - # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See # https://en.wikipedia.org/wiki/BibTeX and \cite for more info. @@ -1791,14 +1761,6 @@ LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- @@ -1855,16 +1817,6 @@ RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = -# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code -# with syntax highlighting in the RTF output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_RTF is set to YES. - -RTF_SOURCE_CODE = NO - #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- @@ -1954,15 +1906,6 @@ GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the -# program listings (including syntax highlighting and cross-referencing -# information) to the DOCBOOK output. Note that enabling this will significantly -# increase the size of the DOCBOOK output. -# The default value is: NO. -# This tag requires that the tag GENERATE_DOCBOOK is set to YES. - -DOCBOOK_PROGRAMLISTING = NO - #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- @@ -2141,15 +2084,6 @@ EXTERNAL_PAGES = YES # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = YES - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. @@ -2182,23 +2116,6 @@ HAVE_DOT = NO DOT_NUM_THREADS = 0 -# When you want a differently looking font in the dot files that doxygen -# generates you can specify the font name using DOT_FONTNAME. You need to make -# sure dot is able to find the font, which can be done by putting it in a -# standard location or by setting the DOTFONTPATH environment variable or by -# setting DOT_FONTPATH to the directory containing the font. -# The default value is: Helvetica. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_FONTNAME = Helvetica - -# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of -# dot graphs. -# Minimum value: 4, maximum value: 24, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_FONTSIZE = 10 - # By default doxygen will tell dot to use the default font as specified with # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set # the path where dot can find it using this tag. @@ -2411,18 +2328,6 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not seem -# to support this out of the box. -# -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_TRANSPARENT = NO - # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support diff --git a/wolfSSL/Makefile b/wolfSSL/Makefile index d4d8660c..335ef25c 100644 --- a/wolfSSL/Makefile +++ b/wolfSSL/Makefile @@ -32,10 +32,20 @@ APPENDIX= appendix01.md \ appendix10.md \ appendix11.md +# API reference pages that only the English Doxygen input (header_files) +# generates. header_files-ja does not document these yet, so the Japanese PDF +# leaves them out (see the cat commands in pdf-prep). +API_EN_ONLY_PAGES = group__ARGON2.md group__Falcon.md group__FRODO__KEM.md \ + group__HPKE.md group__STM32.md group__TSP.md group__wolfEntropy.md \ + argon2_8h.md falcon_8h.md hpke_8h.md rng__bank_8h.md rng__noisesrc_8h.md \ + stm32_8h.md tsp_8h.md wc__frodokem_8h.md wc__keystore_8h.md \ + wolfentropy_8h.md + ifeq ($(DOC_LANG),JA) PDF = wolfSSL-Manual-jp.pdf HEADER_FILES = header_files-ja DOXYFILE = Doxyfile-ja + PDF_API_SKIP = $(addprefix build/pdf/,$(API_EN_ONLY_PAGES)) else PDF = wolfSSL-Manual.pdf HEADER_FILES = header_files @@ -66,9 +76,10 @@ html-prep: api $(Q)cp -a api/md/group* build/html/ $(Q)cp -a api/md/*8h* build/html/ $(Q)rm -f build/html/appendix01.md build/html/appendix02.md build/html/appendix03.md - $(Q)perl -i -pe "s/(?<=md\#function\-)(.*)(?=\))/\$$1=~s#-#_#gr/ge" build/html/group* build/html/*8h* + $(Q)perl -i -pe "s/md\#(?:function|typedef|variable)-\K([^)]*)(?=\))/\$$1=~s#-#_#gr/ge" build/html/group* build/html/*8h* $(Q)perl -i -pe "s/\/group_/group_/g" build/html/group* build/html/*8h* $(Q)perl -i -pe 's#\]\(/#](#g' build/html/group* build/html/*8h* + $(Q)perl -i -pe 's#(_8h\.md)\#file-[^)]*#$$1#g' build/html/group* build/html/*8h* $(Q)perl -i -pe "s/dox_comments\/$(HEADER_FILES)\///" build/html/*8h* # Set input format to gfm to fix issues with converted API docs @@ -86,25 +97,27 @@ html-prep: api # 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. +# PDF build does not read that nav. Keep both locations in sync. Pages listed in +# API_EN_ONLY_PAGES are filtered out of the Japanese build. .PHONY: pdf-prep pdf-prep: api $(Q)cp src/*.png build/pdf/ $(Q)cp -a api/md/group* build/pdf/ $(Q)cp -a api/md/*8h* build/pdf/ $(Q)perl -i -pe "s/^(#+ )/#\$$1/g" build/pdf/group* build/pdf/*8h* - $(Q)perl -i -pe "s/(?<=md\#function\-)(.*)(?=\))/\$$1=~s#-#_#gr/ge" build/pdf/group* build/pdf/*8h* + $(Q)perl -i -pe "s/md\#(?:function|typedef|variable)-\K([^)]*)(?=\))/\$$1=~s#-#_#gr/ge" build/pdf/group* build/pdf/*8h* + $(Q)perl -i -pe 's#/([A-Za-z0-9_-]+)_8h\.md\#file-[^)]*#"\#".($$1=~s/__/_/gr).".h"#ge' build/pdf/group* build/pdf/*8h* $(Q)perl -i -pe "s/\/group_.*?\.md//g" build/pdf/group* build/pdf/*8h* - $(Q)perl -i -pe "s/\/(ssl|wolfio|cryptocb|types|hash)_8h.md//g" build/pdf/group* build/pdf/*8h* + $(Q)perl -i -pe "s/\/[A-Za-z0-9_-]+_8h\.md//g" build/pdf/group* build/pdf/*8h* $(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_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)perl -i -pe "s/group__.*?\.md//g" build/pdf/*8h* build/pdf/chapter* build/pdf/appendix* + $(Q)perl -i -pe "s/[A-Za-z0-9_-]+_8h\.md//g" build/pdf/chapter* build/pdf/appendix* $(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__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__PKCS12.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/pkcs12_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 + $(Q)cat $(filter-out $(PDF_API_SKIP),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__wolfEntropy.md build/pdf/group__Signature.md build/pdf/group__STM32.md build/pdf/group__TSP.md build/pdf/group__wolfCrypt.md build/pdf/group__DES.md build/pdf/group__AES.md build/pdf/group__ARC4.md build/pdf/group__ARGON2.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__Falcon.md build/pdf/group__FRODO__KEM.md build/pdf/group__HMAC.md build/pdf/group__HPKE.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__PKCS12.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 $(filter-out $(PDF_API_SKIP),build/pdf/aes_8h.md build/pdf/arc4_8h.md build/pdf/argon2_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/falcon_8h.md build/pdf/hash_8h.md build/pdf/hmac_8h.md build/pdf/hpke_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/pkcs12_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/rng__bank_8h.md build/pdf/rng__noisesrc_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/stm32_8h.md build/pdf/tfm_8h.md build/pdf/tsp_8h.md build/pdf/types_8h.md build/pdf/wc__encrypt_8h.md build/pdf/wc__frodokem_8h.md build/pdf/wc__keystore_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/wolfentropy_8h.md build/pdf/wolfio_8h.md) >> build/pdf/appendix03.md diff --git a/wolfSSL/mkdocs.yml b/wolfSSL/mkdocs.yml index 139f92c8..5d83849c 100644 --- a/wolfSSL/mkdocs.yml +++ b/wolfSSL/mkdocs.yml @@ -2,7 +2,7 @@ site_name: wolfSSL Manual site_url: https://wolfssl.com/ docs_dir: build/html/ site_dir: html/ -copyright: Copyright © 2025 wolfSSL Inc. +copyright: Copyright © 2026 wolfSSL Inc. nav: - "1. Introduction": index.md - "2. Building wolfSSL": chapter02.md @@ -42,11 +42,15 @@ nav: - "Logging": group__Logging.md - "Math API": group__Math.md - "Random Number Generation": group__Random.md + - "Entropy Source - wolfEntropy (MemUse)": group__wolfEntropy.md - "Signature API": group__Signature.md + - "STM32 Hardware Crypto Port": group__STM32.md + - "Time-Stamp Protocol (RFC 3161)": group__TSP.md - "wolfCrypt Init and Cleanup": group__wolfCrypt.md - "Algorithms - 3DES": group__DES.md - "Algorithms - AES": group__AES.md - "Algorithms - ARC4": group__ARC4.md + - "Algorithms - Argon2": group__ARGON2.md - "Algorithms - BLAKE2": group__BLAKE2.md - "Algorithms - Camellia": group__Camellia.md - "Algorithms - ChaCha": group__ChaCha.md @@ -69,7 +73,10 @@ nav: - "Setup SAKKE Key": group__SAKKE__Setup.md - "Operations on/with SAKKE RSK": group__SAKKE__RSK.md - "Operations using SAKKE Key": group__SAKKE__Operations.md + - "Algorithms - Falcon": group__Falcon.md + - "Algorithms - FrodoKEM": group__FRODO__KEM.md - "Algorithms - HMAC": group__HMAC.md + - "Algorithms - HPKE (RFC 9180)": group__HPKE.md - "Algorithms - LMS / HSS (RFC 8554)": group__LMS.md - "Algorithms - MD2": group__MD2.md - "Algorithms - MD4": group__MD4.md @@ -95,6 +102,7 @@ nav: - "C. API Header Files": - aes_8h.md - arc4_8h.md + - argon2_8h.md - ascon_8h.md - asn_8h.md - asn__public_8h.md @@ -120,8 +128,10 @@ nav: - ed448_8h.md - error-crypt_8h.md - evp_8h.md + - falcon_8h.md - hash_8h.md - hmac_8h.md + - hpke_8h.md - iotsafe_8h.md - kdf_8h.md - logging_8h.md @@ -141,6 +151,8 @@ nav: - quic_8h.md - random_8h.md - ripemd_8h.md + - rng__bank_8h.md + - rng__noisesrc_8h.md - rsa_8h.md - sakke_8h.md - sha256_8h.md @@ -151,9 +163,13 @@ nav: - siphash_8h.md - srp_8h.md - ssl_8h.md + - stm32_8h.md - tfm_8h.md + - tsp_8h.md - types_8h.md - wc__encrypt_8h.md + - wc__frodokem_8h.md + - wc__keystore_8h.md - wc__lms_8h.md - wc__mldsa_8h.md - wc__mlkem_8h.md @@ -161,6 +177,7 @@ nav: - wc__she_8h.md - wc__slhdsa_8h.md - wc__xmss_8h.md + - wolfentropy_8h.md - wolfio_8h.md - "D. SSL/TLS Overview": appendix04.md - "E. RFCs, Specifications, and Reference": appendix05.md From 468a2dea62143ec3ae1cd02f1b6b865d0f7f53cf Mon Sep 17 00:00:00 2001 From: Andrew Hutchings Date: Fri, 6 Nov 2026 09:15:16 +0000 Subject: [PATCH 02/25] wolfSSL manual: chapter02: fix and regroup Removing Features macros - Keep only removal macros under "Removing Features"; move the enabling, tuning and relaxing macros into new subsections (symmetric/hash/KDF, RSA, hardware and async, PKCS, certificate and ASN.1, OCSP, post-quantum, TLS, debugging) - Add NO_DES3_TLS_SUITES, NO_PKCS8, NO_PKCS12, NO_CODING, WOLFSSL_NO_PEM and WOLFSSL_DTLS_NO_HVR_ON_RESUME - Drop NO_WOLFSSL_SHA256 and WOLFSSL_ASN_KEY_SIZE_ENUM (no longer used) and the duplicate WOLFSSL_HAVE_SP_RSA / WOLFSSL_SP_ASM entries - Rename the Dilithium entries to WOLFSSL_MLDSA_NO_ASN1 and WOLFSSL_MLDSA_FIPS204_DRAFT - Correct stale or wrong descriptions (NO_DES3, NO_RC4, NO_PSK, NO_TLS, session cache sizes, WOLFSSL_RSA_VERIFY_INLINE, WOLFSSL_NO_CLIENT_AUTH, WOLFSSL_ALLOW_NO_CN_IN_SAN, ALLOW_SELFSIGNED_INVALID_CERTSIGN, SLH-DSA parameter sets, ASN template and one-time-auth defaults, etc.) --- wolfSSL/src/chapter02.md | 773 ++++++++++++++++++++------------------- 1 file changed, 404 insertions(+), 369 deletions(-) diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index 8be0ffc2..7b13115b 100644 --- a/wolfSSL/src/chapter02.md +++ b/wolfSSL/src/chapter02.md @@ -348,7 +348,7 @@ You can find detailed instructions and tips for building wolfSSL on Keil MDK-ARM **Note**: If MDK-ARM is not installed in the default installation location, you need to change all of the referencing path definitions in the project file to the install location. -## Features Defined as C Pre-processor Macro +## Features Defined as C Pre-processor Macros ### Removing Features @@ -364,19 +364,11 @@ Likewise removes calls specific to the server side. #### NO_DES3 -Removes the use of DES3 encryptions. DES3 is built-in by default because some older servers still use it and it's required by SSL 3.0. `NO_DH` and `NO_AES` are the same as the two above, they are widely used. +Removes 3DES (Triple-DES) support. 3DES is disabled by default when building with `./configure` (enable it with `--enable-des3`) or CMake (`WOLFSSL_DES3` defaults to `no`). When building with user_settings.h it is compiled in unless `NO_DES3` is defined. Defining `NO_DES3` also defines [`NO_DES3_TLS_SUITES`](#no_des3_tls_suites). -#### WOLFSSL_DES_ECB - -Enables DES-ECB (Electronic Codebook) mode. Off by default. Used by some legacy protocols. - -#### WC_ASYNC_ENABLE_3DES - -Enables asynchronous 3DES operations via the wolfSSL async crypto framework. - -#### FREESCALE_LTC_DES +#### NO_DES3_TLS_SUITES -Enables Freescale/NXP LTC hardware DES/3DES acceleration. +Removes the 3DES TLS cipher suites while keeping 3DES available in wolfCrypt. `./configure` and CMake define it by default unless `--enable-des3-tls-suites` (CMake `WOLFSSL_DES3_TLS_SUITES=yes`) is given, and it is defined automatically when `NO_DES3` is set. #### NO_DSA @@ -384,37 +376,13 @@ Removes DSA since it's being phased out of popular use. #### NO_ERROR_STRINGS -Disables error strings. Error strings are located in `src/internal.c` for wolfSSL or `wolfcrypt/src/asn.c` for wolfCrypt. +Disables error strings. Error strings are located in `src/internal.c` for wolfSSL or `wolfcrypt/src/error.c` for wolfCrypt. #### NO_HMAC Removes HMAC from the build. -**NOTE**: SSL/TLS depends on HMAC but if you are only using wolfCrypt IE build option `WOLFCRYPT_ONLY` then HMAC can be disabled in this case. - -#### HAVE_HKDF - -Enables HKDF (HMAC-based Extract-and-Expand Key Derivation Function) per RFC 5869. Used for TLS 1.3 key derivation and general-purpose key derivation from shared secrets. - -#### WOLFSSL_HMAC_COPY_HASH - -Copies the hash state instead of re-initializing for each HMAC operation. Improves performance when the same key is used for multiple HMAC computations. - -#### STM32_HMAC - -Enables STM32 hardware HMAC acceleration using the STM32 HASH peripheral. - -#### WC_ASYNC_ENABLE_HMAC - -Enables asynchronous HMAC operations via the wolfSSL async crypto framework. - -#### WOLFSSL_DEVCRYPTO_HMAC - -Enables HMAC acceleration via the Linux `/dev/crypto` interface. - -#### WOLFSSL_KCAPI_HMAC - -Enables HMAC operations through the Linux kernel crypto API (AF_ALG). +**NOTE**: SSL/TLS depends on HMAC but if you are only using wolfCrypt, i.e. with the build option `WOLFCRYPT_ONLY`, then HMAC can be disabled in this case. #### NO_MD4 @@ -424,18 +392,10 @@ Removes MD4 from the build, MD4 is broken and shouldn't be used. Removes MD5 from the build. -#### HAVE_MD5_CUST_API - -Enables a custom MD5 API. Allows user-provided MD5 implementation. - #### STM32_NOMD5 Disables STM32 hardware MD5 acceleration. Use when STM32 crypto is enabled but MD5 should use the software implementation. -#### WC_ASYNC_ENABLE_MD5 - -Enables asynchronous MD5 operations via the wolfSSL async crypto framework. - #### NO_SHA Removes SHA-1 from the build. @@ -446,16 +406,12 @@ Removes SHA-256 from the build. #### NO_PSK -Turns off the use of the pre-shared key extension. It is built-in by default. +Removes pre-shared key (PSK) support: the PSK cipher suites and the TLS 1.3 external PSK callbacks. `./configure` defines `NO_PSK` unless `--enable-psk` is given (PSK is off by default); with user_settings.h PSK is compiled in unless `NO_PSK` is defined. #### NO_PWDBASED Disables password-based key derivation functions such as PBKDF1, PBKDF2, and PBKDF from PKCS #12. -#### HAVE_PKCS7 - -Enables PKCS#7 (Cryptographic Message Syntax) support for signed data, enveloped data, encrypted data, and compressed data content types. - #### NO_PKCS7_STREAM Disables PKCS#7 streaming mode. Streaming mode allows processing PKCS#7 data incrementally. @@ -466,43 +422,31 @@ Disables the PKCS#7 EncryptedData content type. Reduces code size when only Sign #### NO_PKCS7_COMPRESSED_DATA -Disables the PKCS#7 CompressedData content type. When CompressedData support is enabled (i.e., this macro is not defined), zlib ([`HAVE_LIBZ`](#have_libz)) is required. +Disables the PKCS#7 CompressedData content type. CompressedData support is only compiled in when zlib support ([`HAVE_LIBZ`](#have_libz)) is also defined; without `HAVE_LIBZ` it is silently omitted. -#### WC_PKCS7_STREAM_DEBUG - -Enables debug output for PKCS#7 streaming operations. - -#### WOLFSSL_PKCS7_MAX_DECOMPRESSION - -Sets the maximum size for PKCS#7 decompression output. Prevents memory exhaustion from maliciously crafted compressed data. +#### NO_PKCS8 -#### HAVE_PKCS7_RSA_RAW_SIGN_CALLBACK - -Enables a custom callback for raw RSA signing in PKCS#7. Allows HSM or external signing integration. +Removes PKCS#8 key package support (`--disable-pkcs8`). PKCS#12 needs PKCS#8, so [`HAVE_PKCS8`](#have_pkcs8) stays defined unless [`NO_PKCS12`](#no_pkcs12) is also defined. -#### HAVE_PKCS7_ECC_RAW_SIGN_CALLBACK +#### NO_PKCS12 -Enables a custom callback for raw ECC signing in PKCS#7. Allows HSM or external signing integration. - -#### HAVE_X963_KDF - -Enables ANSI X9.63 Key Derivation Function. Used for ECC-based key agreement in PKCS#7 EnvelopedData. +Removes PKCS#12 support (`--disable-pkcs12`). See [`HAVE_PKCS12`](#have_pkcs12). #### NO_RC4 -Removes the use of the ARC4 stream cipher from the build. ARC4 is built-in by default because it is still popular and widely used. +Removes the ARC4 (RC4) stream cipher. RC4 is deprecated (RFC 7465), so `NO_RC4` is forced on in every build unless `WOLFSSL_ALLOW_RC4` is defined (`--enable-arc4` sets it). #### NO_SESSION_CACHE -Can be defined when a session cache is not needed. This should reduce memory use by nearly 3 kB. +Can be defined when a session cache is not needed. This removes the session cache and the client session cache, which by default hold 33 sessions and take about 13 kB and 17 kB of memory respectively (estimates from the comments in `wolfssl/ssl_sess.h`; the exact size depends on the build options). #### NO_TLS -Turns off TLS. We do not recommend turning off TLS. +Builds without the TLS protocol while keeping the rest of libwolfssl (for example the certificate manager and the OpenSSL compatibility layer), for a smaller library when TLS is not needed. Set by `--disable-tls`. Unlike [`WOLFCRYPT_ONLY`](#wolfcrypt_only), which builds only wolfCrypt, the non-TLS parts of the SSL layer are still compiled. #### SMALL_SESSION_CACHE -Can be defined to limit the size of the SSL session cache used by wolfSSL. This will reduce the default session cache from 33 sessions to 6 sessions and save approximately 2.5 kB. +Can be defined to limit the size of the SSL session cache used by wolfSSL. This will reduce the default session cache from 33 sessions to 6 sessions. According to the comments in `wolfssl/ssl_sess.h`, the session cache shrinks from about 13 kB to about 2 kB and the client session cache from about 17 kB to about 3 kB. #### NO_RSA @@ -514,7 +458,283 @@ Removes code for OAEP padding. #### WOLFSSL_RSA_VERIFY_INLINE -Enables inline RSA verify, returning a pointer into the input buffer rather than copying the output. Reduces memory usage for RSA verify operations. +Removes the copying RSA verify functions (`wc_RsaSSL_Verify()`, `wc_RsaSSL_Verify_ex()` and `wc_RsaSSL_Verify_ex2()`), leaving only the in-place `wc_RsaSSL_VerifyInline()`, which returns a pointer into the input buffer instead of copying the output. Reduces code size and memory usage. + +#### NO_RSA_BOUNDS_CHECK + +Disables bounds checking on RSA input data. By default, wolfSSL checks that the input value c satisfies `1 < c < n - 1`, as required by NIST SP 800-56B. + +#### WC_RSA_NO_FERMAT_CHECK + +Disables the Fermat factorization proximity check during RSA key generation. By default, wolfSSL verifies that `p` and `q` are not too close together, which would make the key vulnerable to Fermat's factorization method. + +#### WOLFSSL_SE050_NO_RSA + +Disables RSA through the NXP SE050 secure element. Other SE050 operations remain available. + +#### NO_AES_CBC + +Turns off AES-CBC algorithm support. + +#### NO_AES_DECRYPT + +Can be set to reduce code size. Set to disable the decrypt and only support encryption. + +#### WOLFCRYPT_ONLY + +Enables wolfCrypt only while disabling TLS. + +#### NO_CAMELLIA_CBC + +Disables the Camellia-CBC TLS cipher suites only; Camellia remains available in wolfCrypt. + +#### NO_AES + +Disables AES algorithm support. + +#### NO_AES_128 + +Removes support for 128-bit AES keys (`WOLFSSL_AES_128` is not defined). + +#### NO_AES_192 + +Removes support for 192-bit AES keys (`WOLFSSL_AES_192` is not defined). + +#### NO_AES_256 + +Removes support for 256-bit AES keys (`WOLFSSL_AES_256` is not defined). + +#### NO_AESGCM_AEAD + +Internal flag, defined automatically when no AES-GCM TLS cipher suite is built. Defining it yourself does not remove the AES-GCM cipher suites; to do that, leave out AES-GCM (`HAVE_AESGCM`) or restrict the cipher list at run time, for example with `wolfSSL_CTX_set_cipher_list()`. + +#### NO_ASN_TIME + +Disables time checking for ASN. Note: This should be used with caution because all certificate begin/end date checking will be skipped. + +#### NO_BIO + +Disables the BIO (Basic I/O) abstraction layer. Reduces code size when BIO functionality such as `BIO_new()`, `BIO_read()`, `BIO_write()` is not needed. + +#### NO_VERIFY_OID + +Disables OID verification during certificate parsing. + +#### NO_SKID + +Disables Subject Key Identifier extension processing. + +#### NO_STRICT_ECDSA_LEN + +Relaxes strict ECDSA signature length checking. Allows non-minimal DER encoding of ECDSA signatures for interoperability. + +#### NO_WOLFSSL_SKIP_TRAILING_PAD + +Disables stripping of the block cipher padding from a decrypted traditional encrypted PEM private key (DES3 or AES-CBC, with a DEK-Info header). + +#### NO_WOLFSSL_STUB + +Disables stub implementations of unimplemented OpenSSL compatibility functions. Without stubs, calling unimplemented functions will result in a linker error rather than a runtime failure. + +#### WOLFSSL_MLDSA_NO_ASN1 + +Disables ASN.1 encoding/decoding for ML-DSA keys and signatures. Uses raw format instead. The legacy name `WOLFSSL_DILITHIUM_NO_ASN1` is still accepted as an alias. + +#### WOLFSSL_DISABLE_EARLY_SANITY_CHECKS + +Disables early sanity checks on incoming TLS messages. May be needed for interoperability with non-compliant TLS implementations. + +#### NO_CHECK_PRIVATE_KEY + +Removes the check that a private key matches the public key of its certificate, for example `wolfSSL_CTX_check_private_key()` and `wolfSSL_check_private_key()`, which is compiled in by default. The check supports RSA, ECDSA, Ed25519, Ed448, Falcon, ML-DSA and SLH-DSA keys. + +#### NO_CIPHER_SUITE_ALIASES + +Disables cipher suite name aliases. Only the primary cipher suite name will be recognized, not alternative names. + +#### NO_CHAPOL_AEAD + +Disables ChaCha20-Poly1305 AEAD cipher suites. Use when ChaCha20-Poly1305 support is not desired even though the algorithms are compiled in. + +#### NO_DH + +Disables Diffie-Hellman (DH) support. + +#### NO_ED25519_CLIENT_AUTH + +Disables TLS client authentication support for ED25519. It is used to reduce memory usage during TLS if ED25519 is not used, since it requires caching messages. + +#### NO_ED448_CLIENT_AUTH + +Disables client authentication for ED448. + +#### NO_FORCE_SCR_SAME_SUITE + +By default secure renegotiation requires using the same cipher suite. This disables that requirement. + +#### NO_MULTIBYTE_PRINT + +Used for compiling out special characters that embedded devices may have problems with. + +#### NO_OLD_SSL_NAMES + +This disables some of the old OpenSSL compatibility macros for using wolfSSL and OpenSSL together. + +#### NO_OLD_WC_NAMES + +Removes the legacy wolfCrypt names without the `wc_`/`WC_` prefix (for example `Md5`, `MD5_DIGEST_SIZE` and `Sha256`) to avoid symbol clashes, for example with OpenSSL headers. Defined automatically with [`OPENSSL_COEXIST`](#openssl_coexist). + +#### NO_OLD_POLY1305 + +This disables support for the old ChaCha20/Poly1305 TLS 1.2 cipher suite that is typically used for interop. + +#### NO_HANDSHAKE_DONE_CB + +Disables support for the handshake callback set with `wolfSSL_SetHsDoneCb`. This option is useful for reducing code size. + +#### NO_STDIO_FILESYSTEM + +This disables include of stdio.h. Used with portability. + +#### NO_TLS_DH + +Excludes TLS DH. Should not negotiate cipher suites based on ephemeral finite-field Diffie-Hellman key agreement. + +#### NO_WOLFSSL_CM_VERIFY + +Disables the Certificate Manager verify callback. The verify callback allows intercepting errors and overriding them. This option is useful for reducing code size. + +#### NO_WOLFSSL_DIR + +Disable directory support. + +#### NO_WOLFSSL_RENESAS_TSIP_TLS_SESSION + +For disabling only the TSIP TLS-linked Common key encryption method. Note: This is a Renesas RX TSIP specific define. + +#### WOLFSSL_DTLS13_NO_HRR_ON_RESUME + +If defined, a DTLS server will not do a cookie exchange on successful client resumption: the resumption will be faster (one RTT less) and will consume less bandwidth (one ClientHello and one HelloVerifyRequest/HelloRetryRequest less). On the other hand, if a valid SessionID/ticket/psk is collected, forged clientHello messages will consume resources on the server. For DTLS 1.3, using this option also allows for the server to process Early Data/0-RTT Data. Without this, the Early Data would be dropped since the server doesn't enter stateful processing until receiving a verified ClientHello with the cookie. For the DTLS 1.2 equivalent, see [`WOLFSSL_DTLS_NO_HVR_ON_RESUME`](#wolfssl_dtls_no_hvr_on_resume). + +To allow DTLS 1.3 resumption without the cookie exchange: + +- Compile wolfSSL with `WOLFSSL_DTLS13_NO_HRR_ON_RESUME` defined +- Call `wolfSSL_dtls13_no_hrr_on_resume(ssl, 1)` on the WOLFSSL object to disable the cookie exchange on resumption +- Continue like with a normal connection. + +#### WOLFSSL_DTLS_NO_HVR_ON_RESUME + +The DTLS 1.2 counterpart of [`WOLFSSL_DTLS13_NO_HRR_ON_RESUME`](#wolfssl_dtls13_no_hrr_on_resume): a DTLS 1.2 server skips the HelloVerifyRequest cookie exchange when the ClientHello resumes a valid session (by session ID or session ticket). No run-time call is needed. The same trade-off applies: resumption is one round trip faster, but forged ClientHello messages that carry a valid session ID or ticket will consume resources on the server. + +#### WOLFSSL_NO_CLIENT_AUTH + +Removes TLS client certificate authentication (TLS 1.2 and TLS 1.3). A client no longer sends Certificate and CertificateVerify messages in reply to a CertificateRequest. On the server, the checks that fail the handshake when a required client certificate was not sent are removed (an empty client Certificate message is still rejected). In a server-only build (`NO_WOLFSSL_CLIENT`) the server also cannot process a client Certificate message. This also removes the handshake message caching needed for Ed25519 and Ed448 client authentication; to remove only that caching, use [`NO_ED25519_CLIENT_AUTH`](#no_ed25519_client_auth) and [`NO_ED448_CLIENT_AUTH`](#no_ed448_client_auth). + +#### WOLFSSL_NO_CURRDIR + +Portability macro for platforms that do not support ./ for test paths in wolfssl/test.h. Applies to testing tools only. + +#### WOLFSSL_NO_DEF_TICKET_ENC_CB + +No default ticket encryption callback, server only. The application must set its own callback to use session tickets. + +#### WOLFSSL_NO_DTLS_SIZE_CHECK + +Changes how `wolfSSL_write()` handles DTLS application data that does not fit in one record (because of the MTU or the maximum fragment length). By default wolfSSL fails with `DTLS_SIZE_ERROR`; with this macro it splits the data into several records instead. It does not affect checks on received records. + +#### WOLFSSL_NO_ETM_ALERT + +When [`WOLFSSL_EXTRA_ALERTS`](#wolfssl_extra_alerts) is defined, suppresses the fatal `bad_record_mac` or `record_overflow` alert that is sent when an Encrypt-Then-MAC record fails MAC verification or is too long. The connection still fails (with `DECRYPT_ERROR` or `BUFFER_ERROR`); there is no fallback to MAC-then-encrypt. + +#### WOLFSSL_NO_SOCK + +Portability macro for disabling built-in socket support. If using TLS without sockets typically `WOLFSSL_USER_IO` would be defined and callbacks used for send/recv. + +#### WOLFSSL_NO_STRICT_CIPHER_SUITE + +On a TLS 1.2 (or older) client, skips the check that the cipher suite chosen in the ServerHello is one that was offered in the ClientHello and, with secure renegotiation, that it did not change during renegotiation. Not recommended: it weakens protection against a misbehaving or malicious server. + +#### WOLFSSL_NO_TICKET_EXPIRE + +Disables session ticket expiration checking. Session tickets will be accepted regardless of their age. + +#### WOLFSSL_NO_TLS12 + +Define to exclude TLS 1.2. The TLS 1.2 code is compiled out, so peers can no longer negotiate it. wolfSSL 5.9.4 and later set this macro when [`--disable-tlsv12`](#--disable-tlsv12) is given. + +#### WOLFSSL_NO_SIGALG + +Disables the signature algorithms extension. + +#### NO_RESUME_SUITE_CHECK + +Disables the check that a resumed session uses the same cipher suite. + +#### NO_ASN + +Removes support for ASN formatted certificate processing. + +#### NO_CODING + +Removes Base64 and Base16 encoding and decoding (`--disable-coding`). This also removes PEM support, because [`WOLFSSL_PEM_TO_DER`](#wolfssl_pem_to_der) is not defined without it. + +#### WOLFSSL_NO_PEM + +Removes PEM support: [`WOLFSSL_PEM_TO_DER`](#wolfssl_pem_to_der) is not defined, so the PEM to DER conversion functions are not built and certificates and keys can only be loaded in DER format (`WOLFSSL_FILETYPE_ASN1`). There is no configure option for it; define it in user_settings.h or in `CFLAGS`. + +#### NO_OLD_TLS + +Removes support for SSLv3, TLSv1.0 and TLSv1.1. `./configure` and CMake define this macro by default; it is only left undefined when old TLS support is explicitly requested (for example with `--enable-oldtls`, `--enable-tlsv10` or `--enable-sslv3`). With user_settings.h it is not defined automatically, so define `NO_OLD_TLS` yourself. In a build without `NO_OLD_TLS`, TLS 1.0 and SSL 3.0 additionally need `WOLFSSL_ALLOW_TLSV10` and `WOLFSSL_ALLOW_SSLV3`. + +**Warning:** Leaving `NO_OLD_TLS` undefined produces a build that is **not conformant** with RFC 9846, RFC 8996 or RFC 9325. RFC 8996 deprecates TLS 1.0 and TLS 1.1, and RFC 9846 states that SSL 2.0, SSL 3.0, TLS 1.0 and TLS 1.1 "MUST NOT be negotiated for any reason". Only build without `NO_OLD_TLS` when legacy interoperability requires it, and do not claim conformance with those RFCs for such a build. + +#### WOLFSSL_AEAD_ONLY + +Removes the non-AEAD TLS cipher suites (CBC and stream ciphers with HMAC, including Encrypt-Then-MAC); the algorithms themselves stay in wolfCrypt. AEAD stands for "authenticated encryption with associated data" which means these algorithms (such as AES-GCM) do not just encrypt and decrypt data, they also assure the integrity and authenticity of that data. + +#### WOLFSSL_SP_NO_2048 + +Removes RSA/DH 2048-bit Single-Precision (SP) optimization. + +#### WOLFSSL_SP_NO_3072 + +Removes RSA/DH 3072-bit Single-Precision (SP) optimization. + +#### WOLFSSL_SP_NO_256 + +Removes the SP P-256 (SECP256R1) implementation when `WOLFSSL_HAVE_SP_ECC` is used. With `WOLFSSL_SP_MATH` (SP-only math), it also removes P-256 from the curve table (`NO_ECC256`). + +### Symmetric Cipher, Hash and KDF Options + +The following defines enable optional or legacy symmetric cipher, hash and key derivation features. + +#### WOLFSSL_DES_ECB + +Enables DES-ECB (Electronic Codebook) mode. Off by default. Used by some legacy protocols. + +#### HAVE_HKDF + +Enables HKDF (HMAC-based Extract-and-Expand Key Derivation Function) per RFC 5869. Used for TLS 1.3 key derivation and general-purpose key derivation from shared secrets. + +#### WOLFSSL_HMAC_COPY_HASH + +Copies the hash state instead of re-initializing for each HMAC operation. Improves performance when the same key is used for multiple HMAC computations. + +#### HAVE_X963_KDF + +Enables ANSI X9.63 Key Derivation Function. Used for ECC-based key agreement in PKCS#7 EnvelopedData. + +#### WC_RC2 + +Enables RC2 cipher support. Primarily needed for legacy PKCS#12 file compatibility. + +#### WOLFSSL_MD2 + +Enables MD2 hash algorithm support. Only needed for legacy certificate compatibility. Not recommended for new applications. + +### RSA Options + +The following defines enable or adjust optional RSA behavior. #### WC_RSA_DIRECT @@ -536,10 +756,6 @@ Validates the RSA private exponent `d` before each decrypt operation. Provides a Allows RSA decrypt operations to return a zero-length result (empty plaintext). By default, a zero-length decryption result is treated as an error. -#### NO_RSA_BOUNDS_CHECK - -Disables bounds checking on RSA input data. By default, wolfSSL validates that the input value is less than the RSA modulus. - #### SHOW_GEN Enables progress indicator (dots) during RSA key generation. Useful for user feedback during long key generation operations. @@ -550,7 +766,7 @@ Allows RSA-PSS signatures to use a salt length longer than the hash output lengt #### WOLFSSL_PSS_SALT_LEN_DISCOVER -Enables automatic discovery of the PSS salt length during RSA-PSS signature verification. Tries different salt lengths to find a match. +Adds `RSA_PSS_SALT_LEN_DISCOVER` as a salt length value for RSA-PSS verification. When it is passed, the verifier recovers the salt length from the decoded PSS padding (the position of the 0x01 separator) instead of requiring the caller to supply it. #### WC_RSA_NONBLOCK_TIME @@ -558,23 +774,47 @@ Enables time-based non-blocking RSA operations. Allows RSA operations to yield a #### WOLFSSL_MP_INVMOD_CONSTANT_TIME -Uses constant-time modular inverse computation. Protects against timing side-channel attacks during RSA private key operations. - -#### WC_RSA_NO_FERMAT_CHECK - -Disables the Fermat factorization proximity check during RSA key generation. By default, wolfSSL verifies that `p` and `q` are not too close together, which would make the key vulnerable to Fermat's factorization method. +Declares that the math library's `mp_invmod()` is constant time, so wolfCrypt calls it directly instead of using a side-channel-safe workaround: in RSA key generation `u = q^-1 mod p` is computed with `mp_invmod()` instead of as `q^(p-2) mod p`, and DSA signing skips the extra blinding of the inverse. Only define it when the `mp_invmod()` of the math backend really is constant time. #### FP_MAX_BITS Sets the maximum key size in bits when using fast math (`USE_FAST_MATH`). The value should be set to key size times 2. For example, for RSA 3072 set to 6144. Default is 4096 (supporting up to RSA 2048). -#### WOLFSSL_HAVE_SP_RSA +### Hardware and Asynchronous Crypto Options -Enables Single Precision (SP) math optimizations for RSA operations. SP math provides significant performance improvements for common key sizes (2048, 3072, 4096). +The following defines enable hardware acceleration or asynchronous operation for specific algorithms. -#### WOLFSSL_SP_ASM +#### WC_ASYNC_ENABLE_3DES -Enables assembly-optimized SP math routines. Provides maximum performance for RSA, ECC, and DH operations on supported platforms (x86_64, ARM, RISC-V). +Enables asynchronous 3DES operations via the wolfSSL async crypto framework. + +#### FREESCALE_LTC_DES + +Enables Freescale/NXP LTC hardware DES/3DES acceleration. + +#### STM32_HMAC + +Enables STM32 hardware HMAC acceleration using the STM32 HASH peripheral. + +#### WC_ASYNC_ENABLE_HMAC + +Enables asynchronous HMAC operations via the wolfSSL async crypto framework. + +#### WOLFSSL_DEVCRYPTO_HMAC + +Enables HMAC acceleration via the Linux `/dev/crypto` interface. + +#### WOLFSSL_KCAPI_HMAC + +Enables HMAC operations through the Linux kernel crypto API (AF_ALG). + +#### HAVE_MD5_CUST_API + +Internal flag set by `wolfcrypt/src/md5.c` when a hardware port (STM32 HASH, PIC32MZ, i.MX6 CAAM) supplies its own `wc_InitMd5_ex()`, `wc_Md5Update()` and `wc_Md5Final()`. If you define it yourself, the software MD5 API is omitted and the application must provide these functions. + +#### WC_ASYNC_ENABLE_MD5 + +Enables asynchronous MD5 operations via the wolfSSL async crypto framework. #### WC_ASYNC_ENABLE_RSA @@ -588,58 +828,45 @@ Enables RSA operations through the Linux kernel crypto API (AF_ALG). Offloads RS Enables RSA acceleration through AF_ALG on Xilinx platforms using Xilinx crypto hardware. -#### WOLFSSL_SE050_NO_RSA - -Disables RSA through the NXP SE050 secure element. Other SE050 operations remain available. - #### WOLFSSL_XILINX_CRYPT Enables Xilinx hardware crypto acceleration for RSA and other algorithms on Xilinx FPGA/SoC platforms. -#### NO_AES_CBC - -Turns off AES-CBC algorithm support. - -#### NO_AES_DECRYPT - -Can be set to reduce code size. Set to disable the decrypt and only support encryption. - -#### WOLFCRYPT_ONLY +### PKCS#7, PKCS#8 and PKCS#12 Options -Enables wolfCrypt only while disabling TLS. +The following defines enable or adjust PKCS#7 (CMS), S/MIME, PKCS#8 and PKCS#12 support. -#### NO_CAMELLIA_CBC - -Disables Camellia CBC support but only applies to TLS cipher suites only. +#### HAVE_PKCS7 -#### NO_AES +Enables PKCS#7 (Cryptographic Message Syntax) support for signed data, enveloped data, encrypted data, and compressed data content types. -Disables AES algorithm support. +#### WOLFSSL_PKCS7_MAX_DECOMPRESSION -#### NO_AES_128 +Sets the maximum decompression ratio for PKCS#7 CompressedData: the decompressed output may be at most this many times the size of the compressed input. The default is 1031 (the maximum compression factor of zlib). Prevents memory exhaustion from maliciously crafted compressed data. -Used for AES key size selection at compile time. +#### HAVE_PKCS7_RSA_RAW_SIGN_CALLBACK -#### NO_AES_192 +Enables a custom callback for raw RSA signing in PKCS#7. Allows HSM or external signing integration. -Used for AES key size selection at compile time. +#### HAVE_PKCS7_ECC_RAW_SIGN_CALLBACK -#### NO_AES_256 +Enables a custom callback for raw ECC signing in PKCS#7. Allows HSM or external signing integration. -Used for AES key size selection at compile time. +#### HAVE_SMIME -#### NO_AESGCM_AEAD +Enables S/MIME (Secure/Multipurpose Internet Mail Extensions) support for email signing and encryption. -Used for disabliing TLS cipher suites that use AES GCM. It is used internally when no AES GCM cipher suites are enabled, but can also be used to limit cipher suites. +#### HAVE_PKCS8 -#### NO_ASN_TIME +Enables PKCS#8 private key format support for importing and exporting encrypted and unencrypted private keys. On by default: it is defined automatically unless [`NO_PKCS8`](#no_pkcs8) is defined, and always when `HAVE_PKCS12` is defined. -Disables time checking for ASN. Note: This should be used with caution because all certificate begin/end date checking will be skipped. +#### HAVE_PKCS12 +Enables PKCS#12 (PFX) format support for bundling private keys, certificates, and CA chains into a single encrypted file. On by default: it is defined automatically unless [`NO_PKCS12`](#no_pkcs12) is defined. -#### NO_BIO +### Certificate and ASN.1 Options -Disables the BIO (Basic I/O) abstraction layer. Reduces code size when BIO functionality such as `BIO_new()`, `BIO_read()`, `BIO_write()` is not needed. +The following defines enable or relax optional certificate generation, parsing and validation features. #### WOLFSSL_CERT_PIV @@ -647,7 +874,7 @@ Enables PIV (Personal Identity Verification) certificate support for government #### WOLFSSL_CERT_GEN_CACHE -Caches the DER encoding during certificate generation for reuse without re-encoding. +Keeps the certificate decoded by `wc_SetIssuerBuffer()`, `wc_SetSubjectBuffer()`, `wc_SetAltNamesBuffer()`, `wc_SetDatesBuffer()` and similar functions cached in the `Cert` structure between calls, instead of decoding it again each time. The application must then free it with `wc_SetCert_Free()`, which becomes a public API. #### WOLFSSL_CERT_SIGN_CB @@ -661,6 +888,10 @@ Stores all certificate name components including initials, given name, and DN qu Enables multi-valued Relative Distinguished Name (RDN) attributes in certificates. +#### WOLFSSL_PEM_TO_DER + +Enables the PEM to DER conversion functions (`wc_PemToDer()`, `wc_KeyPemToDer()`, `wc_CertPemToDer()`, `wc_PemPubKeyToDer()` and others) and the loading of PEM format certificates and keys. Defined by default unless [`WOLFSSL_NO_PEM`](#wolfssl_no_pem) or [`NO_CODING`](#no_coding) is defined. + #### WOLFSSL_DER_TO_PEM Enables DER to PEM format conversion functions. @@ -671,7 +902,7 @@ Enables public key PEM to DER format conversion. #### WOLFSSL_KEY_TO_DER -Enables key to DER encoding functions for RSA and ECC private keys. +Enables `wc_RsaKeyToDer()` (RSA private key to DER) and the RSA public key DER encoding used by `wc_RsaKeyToPublicDer()`. Defined automatically when RSA is enabled together with `WOLFSSL_KEY_GEN`, `WOLFSSL_CERT_GEN`, `OPENSSL_EXTRA`, `WOLFSSL_KCAPI_RSA` or `WOLFSSL_SE050` (in FIPS and self-test builds only with `WOLFSSL_KEY_GEN`). ECC keys use `wc_EccKeyToDer()`, which does not depend on this macro. #### ASN_BER_TO_DER @@ -681,21 +912,9 @@ Enables BER (Basic Encoding Rules) to DER (Distinguished Encoding Rules) convers Allows duplicate certificate policy OIDs in the certificate policies extension. By default, duplicates cause a validation error. -#### NO_VERIFY_OID - -Disables OID verification during certificate parsing. - -#### NO_SKID - -Disables Subject Key Identifier extension processing. - -#### NO_STRICT_ECDSA_LEN - -Relaxes strict ECDSA signature length checking. Allows non-minimal DER encoding of ECDSA signatures for interoperability. - #### ALLOW_SELFSIGNED_INVALID_CERTSIGN -Allows self-signed certificates that do not have the keyCertSign bit set in the Key Usage extension. +Allows a self-issued certificate that is not a CA (no cA basic constraint) to assert keyCertSign in its Key Usage extension. By default this violates RFC 5280 section 4.2.1.9 and is rejected with `KEYUSAGE_E`. This is a narrower opt-in than `ALLOW_INVALID_CERTSIGN`, which accepts such certificates whether or not they are self-issued. #### ALLOW_V1_EXTENSIONS @@ -705,7 +924,6 @@ Allows X.509 v1 certificates to contain extensions. Per RFC 5280, extensions are Uses wolfSSL's own date validation implementation instead of the platform's. - #### USE_WOLF_TM Uses wolfSSL's own `struct tm` definition instead of the system-provided one. Needed on platforms without a standard `struct tm`. @@ -722,15 +940,6 @@ Sets the clock skew tolerance (in seconds) for certificate not-after date checki Sets the clock skew tolerance (in seconds) for certificate not-before date checking. Allows certificates to be accepted slightly before their validity period. -#### NO_WOLFSSL_SKIP_TRAILING_PAD - -Disables skipping of trailing padding bytes in ASN.1 parsing. - - -#### NO_WOLFSSL_STUB - -Disables stub implementations of unimplemented OpenSSL compatibility functions. Without stubs, calling unimplemented functions will result in a linker error rather than a runtime failure. - #### WOLFSSL_ALT_NAMES Enables Subject Alternative Name (SAN) support in certificate generation and parsing. @@ -739,23 +948,13 @@ Enables Subject Alternative Name (SAN) support in certificate generation and par Stores Subject Alternative Names without reversing the order. By default, SANs are stored in reverse order. - -#### WOLFSSL_ALTERNATIVE_DOWNGRADE - -Uses an alternative protocol downgrade detection mechanism instead of the standard approach. - #### WOLFSSL_IP_ALT_NAME -Enables IP address entries in Subject Alternative Names. - - -#### WOLFSSL_JNI - -Enables APIs and behaviors needed for Java JNI (wolfSSL JNI/JSSE) compatibility. +Generates a human-readable string form (`ipString`) of iPAddress Subject Alternative Name entries. It is needed to match an IP address against the iPAddress SAN entries during peer certificate verification, and is used by the compatibility layer and printing functions. The raw iPAddress entries are parsed (for example for name constraint checks) without this macro. #### WOLFSSL_RID_ALT_NAME -Enables Registered ID entries in Subject Alternative Names. +Generates a human-readable string form (`ridString`) of registeredID Subject Alternative Name entries, used by the compatibility layer and printing functions. The raw registeredID entries are parsed without this macro. #### WOLFSSL_EKU_OID @@ -781,20 +980,9 @@ Allows the Authority Key Identifier extension to be marked as critical. Allows the Subject Key Identifier extension to be marked as critical. - -#### WOLFSSL_ALLOW_MAX_FRAGMENT_ADJUST - -Allows runtime adjustment of the maximum fragment size after the initial TLS negotiation has completed. - - -#### WOLFSSL_ALLOW_NO_SUITES - -Allows creation of SSL/CTX objects even when no cipher suites are available. Normally an error is raised if no suites match the build configuration. - - #### WOLFSSL_ALLOW_NO_CN_IN_SAN -Allows certificates that have a Subject Alternative Name (SAN) extension but no Common Name (CN) in the subject. +Restores the old hostname check: the subject CN is matched first, and the Subject Alternative Name (SAN) entries are tried only if that fails, even when the certificate has a SAN extension. By default, when a certificate has a SAN extension only the SAN entries are checked (RFC 5280 section 4.2.1.6) and the CN is ignored. #### WC_ASN_UNKNOWN_EXT_CB @@ -836,10 +1024,25 @@ Enables OID (Object Identifier) encoding support for generating ASN.1 OIDs from Uses the old OID sum calculation method. For backwards compatibility with applications that depend on specific OID sum values. +#### WC_ENABLE_ASYM_KEY_IMPORT -#### WOLFSSL_OPENVPN +Enables the generic RFC 5958 asymmetric key package import helpers. Defined automatically when any of Ed25519, Curve25519, Ed448 or Curve448 (with key import), Falcon, ML-DSA, ML-KEM, FrodoKEM, SLH-DSA, LMS or XMSS is enabled (LMS and XMSS only when not verify-only), so there is normally no need to define it manually. -Enables OpenVPN compatibility behaviors in wolfSSL. Required when using wolfSSL as the TLS provider for OpenVPN. +#### WC_ENABLE_ASYM_KEY_EXPORT + +Enables the generic RFC 5958 asymmetric key package export helpers. Defined automatically when any of Ed25519, Curve25519, Ed448 or Curve448 (with key export), Falcon, ML-DSA, ML-KEM, FrodoKEM, SLH-DSA, LMS or XMSS is enabled (LMS and XMSS only when not verify-only), so there is normally no need to define it manually. + +#### WOLFSSL_X509_NAME_AVAILABLE + +Internal flag used only inside `wolfcrypt/src/asn.c`; it makes the certificate parser also build the `WOLFSSL_X509_NAME` subject and issuer objects used by the compatibility layer. It is defined automatically when `OPENSSL_EXTRA` or `OPENSSL_EXTRA_X509_SMALL` is set without `WOLFCRYPT_ONLY`, so do not define it yourself; enable the X509_NAME API with [`OPENSSL_EXTRA`](#openssl_extra) instead. + +#### WOLFSSL_HAVE_ISSUER_NAMES + +Stores pointers to issuer name components, their lengths and encodings for efficient access. + +### OCSP Options + +The following options adjust OCSP support. #### HAVE_OCSP_RESPONDER @@ -857,26 +1060,13 @@ An OCSP hardening option. Responder hosts taken from the Authority Information A A runtime OCSP hardening option, not a build macro. Pass it in the options argument of `wolfSSL_CTX_EnableOCSP()`, `wolfSSL_EnableOCSP()`, or `wolfSSL_CertManagerEnableOCSP()`. With it set, a certificate that advertises no OCSP responder is refused with `OCSP_NEED_URL` instead of the default soft-fail behavior. Without this option, a missing responder only gives the `OCSP_NO_URL` result, and any CRL check that is enabled still runs. -#### HAVE_PKCS8 - -Enables PKCS#8 private key format support for importing and exporting encrypted and unencrypted private keys. - -#### HAVE_PKCS12 - -Enables PKCS#12 (PFX) format support for bundling private keys, certificates, and CA chains into a single encrypted file. +### Post-Quantum Options -#### WOLFSSL_DILITHIUM_NO_ASN1 +The following defines control optional post-quantum algorithm features. -Disables ASN.1 encoding/decoding for Dilithium keys and signatures. Uses raw format instead. +#### WOLFSSL_MLDSA_FIPS204_DRAFT - -#### WOLFSSL_DISABLE_EARLY_SANITY_CHECKS - -Disables early sanity checks on incoming TLS messages. May be needed for interoperability with non-compliant TLS implementations. - -#### WOLFSSL_DILITHIUM_FIPS204_DRAFT - -Enables FIPS 204 draft version of Dilithium parameters. +Adds the FIPS 204 draft versions of the ML-DSA parameter sets (for example `WC_ML_DSA_44_DRAFT`) in addition to the final FIPS 204 ones, and enables the no-context sign/verify API (`WOLFSSL_MLDSA_NO_CTX`) needed for draft-format signatures. Set by adding `draft` to `--enable-mldsa` (for example `--enable-mldsa=yes,draft`). The legacy name `WOLFSSL_DILITHIUM_FIPS204_DRAFT` is still accepted as an alias. #### HAVE_SPHINCS @@ -884,209 +1074,63 @@ Obsolete. This macro enabled pre-standardization SPHINCS+ through the liboqs int #### WOLFSSL_HAVE_SLHDSA -Turns on the SLH-DSA stateless hash-based signature scheme (FIPS 205, the standardized form of SPHINCS+) in wolfCrypt. All twelve parameter sets are included: SHA2 and SHAKE at levels 128, 192 and 256, in small and fast variants. The configure flag is [`--enable-slhdsa`](#--enable-slhdsa). If TLS 1.3 or DTLS 1.3 is enabled, the draft-reddy-tls-slhdsa signature schemes can sign the handshake; the code points are in the signature algorithm reference of [Appendix G](appendix07.md#c-9-slh-dsa-fips-205). `WOLFSSL_SLHDSA_VERIFY_ONLY` (from `--enable-slhdsa=verify-only`) keeps verification only, and `WOLF_CRYPTO_CB_ONLY_SLHDSA` removes the software implementation for setups that offload the algorithm to a crypto callback device. +Turns on the SLH-DSA stateless hash-based signature scheme (FIPS 205, the standardized form of SPHINCS+) in wolfCrypt. By default only the six SHAKE parameter sets (levels 128, 192 and 256, in small and fast variants) are built. The six SHA2 parameter sets also need `WOLFSSL_SLHDSA_SHA2`: `--enable-slhdsa=yes,sha2` builds all twelve, and options such as `sha2-128s` select individual sets. The configure flag is [`--enable-slhdsa`](#--enable-slhdsa). If TLS 1.3 or DTLS 1.3 is enabled, the draft-reddy-tls-slhdsa signature schemes can sign the handshake; the code points are in the signature algorithm reference of [Appendix G](appendix07.md#c-9-slh-dsa-fips-205). `WOLFSSL_SLHDSA_VERIFY_ONLY` (from `--enable-slhdsa=verify-only`) keeps verification only, and `WOLF_CRYPTO_CB_ONLY_SLHDSA` removes the software implementation for setups that offload the algorithm to a crypto callback device. #### WOLFSSL_HAVE_FRODOKEM Enables the FrodoKEM key encapsulation mechanism in wolfCrypt. It is experimental and needs `--enable-experimental`. The implementation includes fast, small and small-stack C code, assembly for x86_64, AArch64, AArch32 and Thumb2, plus ASN.1 keys and X.509 certificates. Enable it with [`--enable-frodokem`](#--enable-frodokem). -#### WC_ENABLE_ASYM_KEY_IMPORT - -Enables generic asymmetric key import functions for Ed25519, Ed448, Curve25519, and Curve448. - -#### WC_ENABLE_ASYM_KEY_EXPORT - -Enables generic asymmetric key export functions for Ed25519, Ed448, Curve25519, and Curve448. - -#### WOLFSSL_X509_NAME_AVAILABLE - -Enables the X509_NAME API for OpenSSL-compatible certificate name access. - -#### WOLFSSL_HAVE_ISSUER_NAMES - -Stores pointers to issuer name components, their lengths and encodings for efficient access. - -#### WOLFSSL_ASN_KEY_SIZE_ENUM - -Uses an enum for AES key size representation in ASN.1 processing instead of raw integers. - -#### HAVE_SMIME - -Enables S/MIME (Secure/Multipurpose Internet Mail Extensions) support for email signing and encryption. - -#### WC_RC2 - -Enables RC2 cipher support. Primarily needed for legacy PKCS#12 file compatibility. - -#### WOLFSSL_MD2 - -Enables MD2 hash algorithm support. Only needed for legacy certificate compatibility. Not recommended for new applications. - -#### NO_CHECK_PRIVATE_KEY - -This macro disables additional private key checking that is on by default. This enables checking to validate the private key is a pair for the public key. It is supported for RSA, ECDSA, ED25519, ED448, Falcon, Dilithium and Sphincs. - -#### NO_CIPHER_SUITE_ALIASES - -Disables cipher suite name aliases. Only the primary cipher suite name will be recognized, not alternative names. - -#### NO_CHAPOL_AEAD - -Disables ChaCha20-Poly1305 AEAD cipher suites. Use when ChaCha20-Poly1305 support is not desired even though the algorithms are compiled in. - -#### NO_DH - -Disables Diffie-Hellman (DH) support. - -#### NO_ED25519_CLIENT_AUTH - -Disables TLS client authentication support for ED25519. It is used to reduce memory usage during TLS if ED25519 is not used, since it requires caching messages. - -#### NO_ED448_CLIENT_AUTH - -Disables client authentication for ED448. - -#### NO_FORCE_SCR_SAME_SUITE - -By default secure renegotiation requires using the same cipher suite. This disables that requirement. - -#### NO_MULTIBYTE_PRINT - -Used for compiling out special characters that embedded devices may have problems with. - -#### NO_OLD_SSL_NAMES - -This disables some of the old OpenSSL compatibility macros for using wolfSSL and OpenSSL together. - -#### NO_OLD_WC_NAMES - -Removes unneeded namespace. - -#### NO_OLD_POLY1305 - -This disables support for the old ChaCha20/Poly1305 TLS 1.2 cipher suite that is typically used for interop. - -#### NO_HANDSHAKE_DONE_CB - -Disables support for the handshake callback set with `wolfSSL_SetHsDoneCb`. This option is useful for reducing code size. - -#### NO_STDIO_FILESYSTEM +### TLS Options -This disables include of stdio.h. Used with portability. - -#### NO_TLS_DH - -Excludes TLS DH. Should not negotiate cipher suites based on ephemeral finite-field Diffie-Hellman key agreement. - -#### NO_WOLFSSL_CM_VERIFY - -Disables the Certificate Manager verify callback. The verify callback allows intercepting errors and overriding them. This option is useful for reducing code size. - -#### NO_WOLFSSL_DIR - -Disable directory support. - -#### NO_WOLFSSL_RENESAS_TSIP_TLS_SESSION - -For disabling only the TSIP TLS-linked Common key encryption method. Note: This is a Renesas RX TSIP specific define. - -#### NO_WOLFSSL_SHA256 +The following defines enable or adjust optional TLS behavior. -This applies to TLS 1.3 only. It allows SHA2-256 to be enabled and usable from wolfCrypt, but exclude it from TLS 1.3. +#### WOLFSSL_ALTERNATIVE_DOWNGRADE -#### WOLFSSL_BLIND_PRIVATE_KEY +On a client that allows a version downgrade (for example with `wolfSSLv23_client_method()`), sets the record layer version of the initial ClientHello to the minimum allowed downgrade version instead of the highest supported version. Useful with servers that reject records with a newer version. -Used as a mask to blind the private key. The blinding is used to protect against Rowhammer attacks. +#### WOLFSSL_ALLOW_MAX_FRAGMENT_ADJUST -#### WOLFSSL_DTLS13_NO_HRR_ON_RESUME +Allows runtime adjustment of the maximum fragment size after the initial TLS negotiation has completed. -If defined, a DTLS server will not do a cookie exchange on successful client resumption: the resumption will be faster (one RTT less) and will consume less bandwidth (one ClientHello and one HelloVerifyRequest/HelloRetryRequest less). On the other hand, if a valid SessionID/ticket/psk is collected, forged clientHello messages will consume resources on the server. For DTLS 1.3, using this option also allows for the server to process Early Data/0-RTT Data. Without this, the Early Data would be dropped since the server doesn't enter stateful processing until receiving a verified ClientHello with the cookie. To allow DTLS 1.3 resumption without the cookie exchange:- Compile wolfSSL with `WOLFSSL_DTLS13_NO_HRR_ON_RESUME` defined - Call wolfSSL_dtls13_no_hrr_on_resume(ssl, 1) on the WOLFSSL object to disable the cookie exchange on resumption - Continue like with a normal connection. +#### WOLFSSL_ALLOW_NO_SUITES +Allows creation of SSL/CTX objects even when no cipher suites are available. Normally an error is raised if no suites match the build configuration. #### WOLFSSL_DTLS13_SEND_MOREACK_DEFAULT -Enables sending more ACK messages by default in DTLS 1.3 for improved reliability on lossy networks. - -#### WOLFSSL_NO_CLIENT_AUTH - -Disables the caching code required for using Ed25519 and Ed448. - -#### WOLFSSL_NO_CURRDIR - -Portability macro for platforms that do not support ./ for test paths in wolfssl/test.h. Applies to testing tools only. - -#### WOLFSSL_NO_DEF_TICKET_ENC_CB - -No default ticket encryption callback, server only. The application must set its own callback to use session tickets. - - -#### WOLFSSL_NO_DTLS_SIZE_CHECK - -Disables DTLS record size validation checks. May be needed for interoperability with implementations that send non-standard record sizes. - - -#### WOLFSSL_NO_ETM_ALERT - -Suppresses the alert message when Encrypt-Then-MAC extension negotiation fails. Silently falls back to MAC-then-encrypt. - -#### WOLFSSL_NO_SOCK - -Portability macro for disabling built-in socket support. If using TLS without sockets typically `WOLFSSL_USER_IO` would be defined and callbacks used for send/recv. - - -#### WOLFSSL_NO_STRICT_CIPHER_SUITE - -Relaxes strict cipher suite validation requirements. Allows cipher suites that may not perfectly match the negotiated protocol version. - - -#### WOLFSSL_NO_TICKET_EXPIRE - -Disables session ticket expiration checking. Session tickets will be accepted regardless of their age. - -#### WOLFSSL_NO_TLS12 - -Define to exclude TLS 1.2. The TLS 1.2 code is compiled out, so peers can no longer negotiate it. wolfSSL 5.9.4 and later set this macro when [`--disable-tlsv12`](#--disable-tlsv12) is given. - -#### WOLFSSL_PEM_TO_DER - -Key and cert generation feature support for disabling PEM to DER. +Sets the default for whether DTLS 1.3 sends ACKs to the peer immediately when it detects a disruption during the handshake: 0 (the default) or 1. Sending ACKs immediately gives minimum latency but may use more bandwidth than necessary. The macro takes a value, for example `#define WOLFSSL_DTLS13_SEND_MOREACK_DEFAULT 1`; defining it without a value does not compile. The setting can be changed per connection with [`wolfSSL_dtls13_set_send_more_acks()`](group__Setup.md#function-wolfssl_dtls13_set_send_more_acks). -#### WOLFSSL_NO_SIGALG - -Disables the signature algorithms extension - -#### NO_RESUME_SUITE_CHECK +#### WOLFSSL_BLIND_PRIVATE_KEY -Disables the check of cipher suite when resuming a TLS connection +Stores the private key held by a `WOLFSSL_CTX` or `WOLFSSL` object XOR'd with a random mask and unmasks it only while it is being used, to protect it against memory attacks such as Rowhammer. -#### NO_ASN +#### WOLFSSL_JNI -Removes support for ASN formatted certificate processing. +Enables APIs and behaviors needed for Java JNI (wolfSSL JNI/JSSE) compatibility. -#### NO_OLD_TLS +#### WOLFSSL_OPENVPN -Removes support for SSLv3, TLSv1.0 and TLSv1.1. This macro is defined by -default; it is only left undefined when old TLS support is explicitly requested -(for example with `--enable-oldtls`, `--enable-tlsv10` or `--enable-sslv3`). +Enables OpenVPN compatibility behaviors in wolfSSL. Required when using wolfSSL as the TLS provider for OpenVPN. -**Warning:** Leaving `NO_OLD_TLS` undefined produces a build that is **not conformant** with RFC 9846, RFC 8996 or RFC 9325. RFC 8996 deprecates TLS 1.0 and TLS 1.1, and RFC 9846 states that SSL 2.0, SSL 3.0, TLS 1.0 and TLS 1.1 "MUST NOT be negotiated for any reason". Only build without `NO_OLD_TLS` when legacy interoperability requires it, and do not claim conformance with those RFCs for such a build. +### Debugging Options -#### WOLFSSL_AEAD_ONLY +The following defines enable extra debugging output or checks for development and testing. -Removes support for non-AEAD algorithms. AEAD stands for “authenticated encryption with associated data” which means these algorithms (such as AES-GCM) do not just encrypt and decrypt data, they also assure confidentiality and authenticity of that data. +#### WC_PKCS7_STREAM_DEBUG -#### WOLFSSL_SP_NO_2048 +Enables debug output for PKCS#7 streaming operations. -Removes RSA/DH 2048-bit Single-Precision (SP) optimization. +#### WOLFSSL_DEBUG_ASN_TEMPLATE -#### WOLFSSL_SP_NO_3072 +Enables debugging output when using ASN.1 templates. Only relevant when used with `WOLFSSL_ASN_TEMPLATE`. -Removes RSA/DH 3072-bit Single-Precision (SP) optimization. +#### WOLFSSL_DEBUG_CERTS -#### WOLFSSL_SP_NO_256 +Enables debug logging for certificate processing operations including parsing, validation, and chain building. It is turned on automatically with [`DEBUG_WOLFSSL`](#debug_wolfssl) unless `WOLFSSL_NO_DEBUG_CERTS` is defined. -Removes ECC Single-Precision (SP) optimization for SECP256R1. Only applies to `WOLFSSL_SP_MATH`. +#### WOLFSSL_ASN_TEMPLATE_TYPE_CHECK +Use ASN functions to better test compiler type issues for testing. Only relevant when used with `WOLFSSL_ASN_TEMPLATE`. ### Enabling Features macros (on by default) @@ -1108,20 +1152,11 @@ Enables encrypt-then-mac support to perform mac after encryption with block ciph #### HAVE_ONE_TIME_AUTH -Required if using Chacha20/Poly1305 with TLS v1.2 for setting up Poly authentication. This is on by default with ChaCha20/Poly1305 if using `./configure`, but needs to be manually defined if building with `WOLFSSL_USER_SETTINGS`. +Required if using Chacha20/Poly1305 with TLS v1.2 for setting up Poly authentication. It is defined automatically whenever `HAVE_POLY1305` is defined, in both `./configure` and user_settings.h builds. #### WOLFSSL_ASN_TEMPLATE -Enables the new version of ASN parsing code that uses template-based ASN.1 processing. This parsing adheres to standard ASN.1 rules and uses a template structure to dictate encoding and decoding, allowing the parser code to generalize across templates. This is on by default if using `./configure`, but needs to be manually defined if building with `WOLFSSL_USER_SETTINGS`. - -#### WOLFSSL_DEBUG_ASN_TEMPLATE -Enables debugging output when using ASN.1 templates. Only relevant when used with `WOLFSSL_ASN_TEMPLATE`. -#### WOLFSSL_DEBUG_CERTS - -Enables debug logging for certificate processing operations including parsing, validation, and chain building. - -#### WOLFSSL_ASN_TEMPLATE_TYPE_CHECK -Use ASN functions to better test compiler type issues for testing. Only relevant when used with `WOLFSSL_ASN_TEMPLATE` +Enables the new version of ASN parsing code that uses template-based ASN.1 processing. This parsing adheres to standard ASN.1 rules and uses a template structure to dictate encoding and decoding, allowing the parser code to generalize across templates. This is the default for every build, including user_settings.h builds, unless `WOLFSSL_ASN_ORIGINAL` (`--enable-asn=original`) or `NO_ASN` is defined. ### Enabling Features Disabled by Default From 2942911e0e59e6f31803feca7b830a87db5feb2b Mon Sep 17 00:00:00 2001 From: Andrew Hutchings Date: Fri, 6 Nov 2026 09:19:42 +0000 Subject: [PATCH 03/25] wolfSSL manual: ch02 enabling features: fix defaults and descriptions - Add a note that some entries are on by default and state the default and opt-out for each such entry (SNI, AES-GCM, ChaCha/Poly, ECC, SHA, TLS 1.3, RSA blinding/PSS, AES sizes/CBC/decrypt, PRF, async I/O, etc.) - Correct descriptions that did not match the source (DTLS future records, keep SNI, TCA, DH extra, X25519 blinding, GCM tables, session export nopeer, webserver, write dup, cert setup cb, AEAD limits, etc.) - Add WOLFSSL_HAVE_MLKEM, WOLFSSL_HAVE_MLDSA, WOLFSSL_HAVE_LMS, WOLFSSL_HAVE_XMSS, WOLFSSL_NO_ECDHX_SHARED_ZERO_CHECK, HAVE_ED448, WOLFSSL_SHA224, HAVE_BLAKE2B/S and the HAVE_FFDHE_ macros - Rename WOLFSSL_APPLE_NATIVE_CERT_VALIDATION; mark obsolete or internal macros; drop GCM_GMULT_LEN, WOLFSSL_MEM_GUARD, WOLFSSL_PSK_ID_PROTECTION, WOLFSSL_CLIENT_SESSION_DEFINED and WOLFSSL_USE_POPEN_HOST - Fix typos, list formatting and an unbalanced code span --- wolfSSL/src/chapter02.md | 283 +++++++++++++++++++++------------------ 1 file changed, 152 insertions(+), 131 deletions(-) diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index 7b13115b..58a6876d 100644 --- a/wolfSSL/src/chapter02.md +++ b/wolfSSL/src/chapter02.md @@ -1160,9 +1160,11 @@ Enables the new version of ASN parsing code that uses template-based ASN.1 proce ### Enabling Features Disabled by Default +**NOTE**: Some of the macros in this section are turned on by default in `./configure` builds, or are always defined by `wolfssl/wolfcrypt/settings.h` unless explicitly disabled. Where that is the case, the entry states the default and how to turn the feature off. With `WOLFSSL_USER_SETTINGS`, configure defaults do not apply, so macros that configure sets must be defined manually. + #### WOLFSSL_CERT_GEN -Turns on wolfSSL’s certificate generation functionality. See [Keys and Certificates](chapter07.md#keys-and-certificates) for more information. +Turns on wolfSSL's certificate generation functionality. See [Keys and Certificates](chapter07.md#keys-and-certificates) for more information. #### WOLFSSL_DER_LOAD @@ -1170,7 +1172,7 @@ Allows loading DER-formatted CA certs into the wolfSSL context (`WOLFSSL_CTX`) u #### WOLFSSL_DTLS -Turns on the use of DTLS, or datagram TLS. This isn't widely supported or used. +Turns on DTLS (datagram TLS) 1.2 support; DTLS 1.3 also needs [`WOLFSSL_DTLS13`](#wolfssl_dtls13). Enabled with `--enable-dtls`. #### WOLFSSL_DTLS_CID @@ -1184,24 +1186,24 @@ Enables tracking of DTLS packet drop statistics for monitoring and debugging DTL #### WOLFSSL_DTLS_DISALLOW_FUTURE -Rejects DTLS records that have a future epoch number. Provides stricter epoch validation during DTLS communication. +Rejects DTLS records whose sequence number is more than the replay window size (`DTLS_SEQ_BITS`) ahead of the next expected sequence number. By default such records are accepted and the window slides forward. #### WOLFSSL_ALLOW_TLSV10 -Allows TLS 1.0 connections. TLS 1.0 is disabled by default for security reasons. Only enable when legacy compatibility is required. Implies that `NO_OLD_TLS` is not defined. +Allows TLS 1.0 connections. TLS 1.0 is disabled by default for security reasons. Only enable when legacy compatibility is required. Requires that `NO_OLD_TLS` is not defined; `--enable-tlsv10` arranges this by turning old TLS on. **Warning:** Defining `WOLFSSL_ALLOW_TLSV10` produces a build that is **not conformant** with RFC 9846, RFC 8996 or RFC 9325. TLS 1.0 is deprecated by RFC 8996, and RFC 9846 states it "MUST NOT be negotiated for any reason". #### WOLFSSL_ALLOW_SSLV3 -Allows SSL 3.0 connections. SSL 3.0 is disabled by default for security reasons. Only enable when legacy compatibility is required. Implies that `NO_OLD_TLS` is not defined. +Allows SSL 3.0 connections. SSL 3.0 is disabled by default for security reasons. Only enable when legacy compatibility is required. Requires that `NO_OLD_TLS` is not defined; `--enable-sslv3` arranges this by turning old TLS on. -**Warning:** Building with `--enable-sslv3` violates RFC 7568. SSL 3.0 is deprecated by RFC 7568 and states "SSLv3 MUST NOT be used." +**Warning:** Building with `--enable-sslv3` violates RFC 7568 and produces a build that is **not conformant** with RFC 9846, RFC 8996 or RFC 9325. RFC 7568 deprecates SSL 3.0 and states "SSLv3 MUST NOT be used." #### WOLFSSL_ALLOW_TLS_SHA1 -Allows SHA-1 based cipher suites and signatures in TLS, even when SHA-1 is otherwise restricted by security policy. +Lets SHA-1 signature algorithms (for example rsa_pkcs1_sha1 and ecdsa_sha1) be offered and used in TLS 1.2 and later handshakes. By default they are only offered for TLS 1.0 and 1.1, because RFC 9155 deprecates them for TLS 1.2. Cipher suites are not affected. #### WOLFSSL_EITHER_SIDE @@ -1214,11 +1216,11 @@ Enables non-blocking EGD (Entropy Gathering Daemon) support for random number ge #### HAVE_SNI -Enables Server Name Indication (SNI) TLS extension support (RFC 6066). Allows clients to indicate which hostname they are connecting to, enabling virtual hosting over TLS. +Enables Server Name Indication (SNI) TLS extension support (RFC 6066). Allows clients to indicate which hostname they are connecting to, enabling virtual hosting over TLS. Enabled by default in `./configure` builds on x86, x86_64 and aarch64; disable with `--disable-sni`. #### WOLFSSL_ALWAYS_KEEP_SNI -Keeps the SNI value in the SSL session after the handshake completes. By default, the SNI data is freed after the handshake to save memory. +On the server, stores the SNI host name the client sent even when the server has not set one with `wolfSSL_UseSNI()`, so the application can read it with `wolfSSL_SNI_GetRequest()` (status `WOLFSSL_SNI_FORCE_KEEP`). The same thing happens when an SNI receive callback is registered. #### WOLFSSL_ALWAYS_VERIFY_CB @@ -1232,7 +1234,7 @@ Enables the Truncated HMAC TLS extension (RFC 6066). Allows using 80-bit HMAC ta #### HAVE_TIME_T_TYPE -Indicates the platform provides a `time_t` type definition. Set automatically on most platforms. +Define when using `USER_TIME`, `TIME_OVERRIDES` or a similar custom time port on a platform that already has a `time_t` type. Without it wolfSSL supplies its own `time_t` (`USE_WOLF_TIME_T`, `typedef long time_t`) in those configurations. Neither configure nor CMake sets it. #### HAVE_SECURE_RENEGOTIATION @@ -1240,7 +1242,7 @@ Enables secure renegotiation support (RFC 5746). Allows TLS connections to reneg #### HAVE_SERVER_RENEGOTIATION_INFO -Enables the server-side renegotiation info extension. Indicates secure renegotiation support in server hello messages. +Enables the server-side renegotiation info extension. Indicates secure renegotiation support in server hello messages. Enabled by default in `./configure` builds; disable with `--disable-secure-renegotiation-info`. #### HAVE_SESSION_TICKET @@ -1268,7 +1270,11 @@ Prevents the server from sending its supported groups in a TLS extension when th #### HAVE_FFDHE -Enables Finite Field Diffie-Hellman Ephemeral (FFDHE) key exchange using standardized groups from RFC 7919. +Enables Finite Field Diffie-Hellman Ephemeral (FFDHE) key exchange using standardized groups from RFC 7919. You do not normally define this macro yourself: settings.h defines it automatically when DH is enabled and any of the group size macros below is defined. + +#### HAVE_FFDHE_2048, HAVE_FFDHE_3072, HAVE_FFDHE_4096, HAVE_FFDHE_6144, HAVE_FFDHE_8192 + +Each macro enables one RFC 7919 FFDHE group (ffdhe2048 to ffdhe8192) and, through it, [`HAVE_FFDHE`](#have_ffdhe). `./configure` defines `HAVE_FFDHE_2048` by default when DH is enabled together with TLS 1.3 or the supported curves extension; disable it with `--disable-dh`. The other group sizes are off by default. #### HAVE_SECRET_CALLBACK @@ -1284,7 +1290,7 @@ Enables TLS packet sniffing support. Allows decrypting and inspecting TLS traffi #### HAVE_WEBSERVER -Enables web server-oriented features in wolfSSL, such as additional HTTP helper functions. +Enables the small subset of the OpenSSL compatibility layer that embedded web servers need (for example the `wolfSSL_CTX_ctrl()` options, the locking callback functions and the X.509 verify error codes), and turns on [`WOLFSSL_ENCRYPTED_KEYS`](#wolfssl_encrypted_keys). Set by `--enable-webserver`. #### HAVE_WOLF_EVENT @@ -1292,7 +1298,7 @@ Enables wolf event-driven processing support for async operations. Provides an e #### HAVE_WRITE_DUP -Enables write duplication support, allowing separate threads to perform SSL read and write operations simultaneously on the same SSL object. +Enables `wolfSSL_write_dup()`, which makes a second, write-only `WOLFSSL` object from an established connection, so one thread can read on the original while another writes on the duplicate. Set by `--enable-writedup`. #### NO_CERTS @@ -1305,23 +1311,23 @@ Disables the client-side session cache. Only the server session cache will be us #### WOLFSSL_HAVE_PRF -Enables access to the TLS Pseudo-Random Function (PRF). Allows applications to derive additional keying material using the TLS PRF. +Enables access to the TLS Pseudo-Random Function (PRF). Allows applications to derive additional keying material using the TLS PRF. Exposes `wc_PRF()`, `wc_PRF_TLS()` and `wc_PRF_TLSv1()`. Defined automatically by settings.h unless `NO_KDF` or `NO_HMAC` is set. #### WOLFSSL_REQUIRE_TCA -Requires that the client send the Trusted CA extension. If the extension is missing, the handshake will fail. +Client side: when the client sent the trusted_ca_keys extension and the server does not acknowledge it, fail the handshake with `TCA_ABSENT_ERROR`. RFC 6066 makes the server response optional, so by default the client continues. #### WOLFSSL_DH_EXTRA -Stores additional DH key information in the SSL object. Provides access to DH parameters and keys after the handshake. +Adds the public and private key values to the wolfCrypt `DhKey` structure and enables `wc_DhImportKeyPair()`, `wc_DhExportKeyPair()` and DH key copy, which the OpenSSL compatibility DH APIs use. Defined automatically with `WOLFSSL_QT`, `OPENSSL_ALL`, `WOLFSSL_OPENSSH` or `WOLFSSL_STATIC_EPHEMERAL`. #### WOLFSSL_CURVE25519_BLINDING -Enables blinding for Curve25519 operations during TLS key exchange. Protects against timing side-channel attacks. +Enables scalar blinding of X25519 private key operations in wolfCrypt, to protect against timing side-channel attacks. It applies to all use of the key, not just TLS. An RNG must be set on the key with `wc_curve25519_set_rng()`. On by default for the C implementation (not `CURVE25519_SMALL` or assembly) when an RNG is available; turn it off with `NO_CURVE25519_BLINDING`. #### WOLFSSL_KEY_GEN -Turns on wolfSSL’s RSA key generation functionality. See [Keys and Certificates](chapter07.md#keys-and-certificates) for more information. +Turns on wolfSSL's RSA key generation functionality. See [Keys and Certificates](chapter07.md#keys-and-certificates) for more information. #### WOLF_PRIVATE_KEY_ID @@ -1341,11 +1347,11 @@ Certificate request, key, and cert generation feature. #### WOLFSSL_SSLKEYLOGFILE -This enables the key logging used by Wireshark. It does produce a compiler warning since the master secret and client random are written to a file. This is useful for testing and not recommended for production. +This enables the key logging used by Wireshark. It does produce a compiler warning since the master secret and client random are written to a file. This is useful for testing and not recommended for production. Enabled with `--enable-keylog-export`, which also sets `SHOW_SECRETS` and `HAVE_SECRET_CALLBACK`. #### WOLFSSL_SSLKEYLOGFILE_OUTPUT -This macro defines the filename for the key logging. It is used with `WOLFSSL_SSLKEYLOGFILE`. +This macro defines the filename for the key logging. It is used with `WOLFSSL_SSLKEYLOGFILE`. The default is `sslkeylog.log`. Define `WOLFSSL_SSLKEYLOGFILE_USE_ENV` to prefer the path in the `SSLKEYLOGFILE` environment variable when it is set. #### WOLFSSL_HAVE_WOLFSCEP @@ -1361,7 +1367,7 @@ Keeps the "Finished" messages after a TLS handshake for use as the "tls-unique" #### WOLFSSL_ENCRYPTED_KEYS -Enable for encrypted keys PKCS8 support. This macro enables PKCS8 password based key encryption. Here is a link to RFC PKCS8 documentation (https://datatracker.ietf.org/doc/html/rfc5208). +Enables loading and writing password-encrypted PEM private keys: traditional encrypted PEM (`Proc-Type` / `DEK-Info` headers), and encrypted PKCS#8 PEM through the password callback. The PKCS#8 encrypt/decrypt API itself (`wc_EncryptPKCS8Key()`) comes from [`HAVE_PKCS8`](#have_pkcs8). Set by `--enable-enckeys`, and automatically with `OPENSSL_EXTRA`, `OPENSSL_EXTRA_X509_SMALL` or `HAVE_WEBSERVER`. Here is a link to RFC PKCS8 documentation (https://datatracker.ietf.org/doc/html/rfc5208). #### WOLFSSL_CUSTOM_OID @@ -1371,17 +1377,21 @@ Certificate feature that enables custom OID support for subject and request exte Enables RIPEMD-160 support. +#### WOLFSSL_SHA224 + +Enables SHA-224 support. Enabled by default in `./configure` builds on x86_64 and aarch64; disable with `--disable-sha224`. + #### WOLFSSL_SHA384 -Enables SHA-384 support. +Enables SHA-384 support. Enabled by default in `./configure` builds; disable with `--disable-sha384`. #### WOLFSSL_SHA512 -Enables SHA-512 support. +Enables SHA-512 support. Enabled by default in `./configure` builds; disable with `--disable-sha512`. #### WOLFSSL_AES_DIRECT -Enables direct AES ECB mode support. On its own ECB mode is not considered secure. This feature is required for PKCS7. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible. +Enables the single-block AES API `wc_AesEncryptDirect()` / `wc_AesDecryptDirect()` (the multi-block ECB API is [`HAVE_AES_ECB`](#have_aes_ecb)). On its own ECB mode is not considered secure. Needed by AES key wrap (and so PKCS#7), CMAC, CTR, CFB, OFB and XTS; settings.h turns it on automatically for CTR, CFB, OFB and XTS. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API's directly whenever possible. #### DEBUG_WOLFSSL @@ -1393,7 +1403,7 @@ Enables AES-CCM support. #### HAVE_AESGCM -Enables AES-GCM support. +Enables AES-GCM support. Enabled by default in `./configure` builds; disable with `--disable-aesgcm`. #### WOLFSSL_AES_XTS @@ -1401,15 +1411,15 @@ Enables AES-XTS support. #### WOLFSSL_AES_128 -Enables AES-128 key size support. Enabled by default. Disable to remove AES-128 and reduce code size when only larger key sizes are needed. +Enables AES-128 key size support. Always defined by settings.h when AES is enabled; define [`NO_AES_128`](#no_aes_128) to remove AES-128 and reduce code size when only larger key sizes are needed. #### WOLFSSL_AES_192 -Enables AES-192 key size support. Enabled by default. Disable to remove AES-192 and reduce code size. +Enables AES-192 key size support. Always defined by settings.h when AES is enabled and `AES_MAX_KEY_SIZE` is at least 192; define [`NO_AES_192`](#no_aes_192) to remove AES-192 and reduce code size. #### WOLFSSL_AES_256 -Enables AES-256 key size support. Enabled by default. Disable to remove AES-256 when not needed. +Enables AES-256 key size support. Always defined by settings.h when AES is enabled and `AES_MAX_KEY_SIZE` is 256; define [`NO_AES_256`](#no_aes_256) to remove AES-256 when not needed. #### AES_MAX_KEY_SIZE @@ -1421,7 +1431,7 @@ Enables AES-ECB (Electronic Codebook) mode. Off by default. ECB mode encrypts ea #### HAVE_AES_DECRYPT -Enables AES decryption support. On by default. Can be disabled to save code size on platforms that only need AES encryption (e.g., GCM encryption-only). +Enables AES decryption support. Always defined by settings.h when AES is enabled; define [`NO_AES_DECRYPT`](#no_aes_decrypt) to save code size on platforms that only need AES encryption (e.g., GCM encryption-only). #### WOLFSSL_AES_COUNTER @@ -1461,7 +1471,7 @@ Enables strict validation of input data length for AES-CBC operations. When enab #### HAVE_AESGCM_DECRYPT -Enables AES-GCM decryption support. On by default when [`HAVE_AESGCM`](#have_aesgcm) is enabled. Can be disabled on constrained devices that only need GCM encryption. +Keeps AES-GCM decryption when AES block decryption is removed. Nothing defines this macro by default: GCM decryption is built whenever [`HAVE_AES_DECRYPT`](#have_aes_decrypt) or `HAVE_AESGCM_DECRYPT` is defined, so leaving it undefined does not remove GCM decryption. Define it together with [`NO_AES_DECRYPT`](#no_aes_decrypt) to keep AES-GCM decryption while removing the rest of AES decryption. #### WOLFSSL_AESGCM_STREAM @@ -1473,20 +1483,16 @@ Authenticates the GCM tag before performing decryption. Provides fail-fast behav #### GCM_TABLE -Use a pre-computed 4-bit lookup table for AES-GCM Galois field multiplication. Faster than [`GCM_SMALL`](#gcm_small) but uses more memory. See also [`GCM_TABLE_4BIT`](#gcm_table_4bit) and [`GCM_WORD32`](#gcm_word32). +Use a pre-computed 8-bit (256-entry, 4 KB per key) lookup table for AES-GCM (GHASH) Galois field multiplication. Faster than [`GCM_SMALL`](#gcm_small) but uses more memory. Selected with `--enable-aesgcm=table`. See also [`GCM_TABLE_4BIT`](#gcm_table_4bit) and [`GCM_WORD32`](#gcm_word32). #### GCM_TABLE_4BIT -Explicit option for 4-bit GCM lookup table mode. Functions similarly to [`GCM_TABLE`](#gcm_table). +Use a 4-bit (512 bytes per key) lookup table for AES-GCM (GHASH) Galois field multiplication. Smaller than [`GCM_TABLE`](#gcm_table). This is the default with `./configure` (`--enable-aesgcm` selects `4bit` unless told otherwise) and with `WOLFSSL_ARMASM`. #### GCM_WORD32 Use a 32-bit word implementation for AES-GCM Galois field multiplication. An alternative to [`GCM_SMALL`](#gcm_small) and [`GCM_TABLE`](#gcm_table) that works well on platforms without 64-bit support. -#### GCM_GMULT_LEN - -Enables GCM GMULT length optimization for processing multiple blocks of AAD or ciphertext in a single GMULT call. - #### WOLFSSL_AESXTS_STREAM Enables streaming AES-XTS API. Allows processing AES-XTS data incrementally across multiple update calls rather than a single operation. @@ -1505,11 +1511,11 @@ Enables Camellia support. #### HAVE_CHACHA -Enables ChaCha20 support. +Enables ChaCha20 support. Enabled by default in `./configure` builds (except FIPS builds); disable with `--disable-chacha`. #### HAVE_POLY1305 -Enables Poly1305 support. +Enables Poly1305 support. Enabled by default in `./configure` builds (except FIPS builds); disable with `--disable-poly1305`. #### POLY130564 @@ -1517,7 +1523,7 @@ Uses the 64-bit Poly1305 implementation for better performance on 64-bit platfor #### USE_INTEL_POLY1305_SPEEDUP -Enables Intel AVX/AVX2 optimized Poly1305 implementation for maximum throughput on Intel/AMD processors. +Enables Intel AVX/AVX2 optimized Poly1305 implementation for maximum throughput on Intel/AMD processors. Set automatically on x86_64 when [`USE_INTEL_SPEEDUP`](#use_intel_speedup) (`--enable-intelasm`) is defined, unless `NO_POLY1305_ASM` is defined. Includes AVX-512 code paths unless `WOLFSSL_POLY1305_NO_AVX512` is defined. Define `USE_INTEL_SPEEDUP` rather than this macro. #### HAVE_CRL @@ -1529,7 +1535,7 @@ Enables blocking inline HTTP request on the CRL URL. It will load the CRL into t #### HAVE_ECC -Enables Elliptical Curve Cryptography (ECC) support. +Enables Elliptic Curve Cryptography (ECC) support. Enabled by default in `./configure` builds; disable with `--disable-ecc`. #### HAVE_LIBZ @@ -1541,7 +1547,7 @@ Builds even more OpenSSL compatibility into the library, and enables the wolfSSL #### HAVE_EXT_CACHE -Enables a feature support use of an external session cache (vs an internal one). +Enables support for an external session cache (instead of the internal one). #### WOLFSSL_WPAS_SMALL @@ -1571,20 +1577,23 @@ OpenSSL compatibility application specific. Use, nginx `(--enable-nginx) WOLFSSL #### WOLFSSL_ERROR_CODE_OPENSSL OpenSSL compatibility API wolfSSL_EVP_PKEY_cmp returns 0 on success and -1 on failure. This behavior is different from OpenSSL. EVP_PKEY_cmp returns: -1: two keys match -0: do not match --1: key types are different --2: the operation is not supported + +- `1`: the two keys match +- `0`: the keys do not match +- `-1`: the key types are different +- `-2`: the operation is not supported + If you want this function to behave the same as openSSL, define WOLFSSL_ERROR_CODE_OPENSSL so that WS_RETURN_CODE translates return codes to match OpenSSL equivalent behavior. #### WOLFSSL_HARDEN_TLS -Implement the recommendations specified in RFC9325. This macro needs to be defined to the desired number of bits of security. The currently implemented values are 112 and 128 bits. The following macros disable certain checks. -- WOLFSSL_HARDEN_TLS_ALLOW_TRUNCATED_HMAC -- WOLFSSL_HARDEN_TLS_ALLOW_OLD_TLS -- WOLFSSL_HARDEN_TLS_NO_SCR_CHECK -- WOLFSSL_HARDEN_TLS_NO_PKEY_CHECK -- WOLFSSL_HARDEN_TLS_ALLOW_ALL_CIPHERSUITES +Implement the recommendations specified in RFC9325. This macro needs to be defined to the desired number of bits of security. The currently implemented values are 112 and 128 bits. Enabled with `--enable-harden-tls[=112|128]` (`yes` is the same as `112`). The following macros disable certain checks. + +- `WOLFSSL_HARDEN_TLS_ALLOW_TRUNCATED_HMAC` +- `WOLFSSL_HARDEN_TLS_ALLOW_OLD_TLS` +- `WOLFSSL_HARDEN_TLS_NO_SCR_CHECK` +- `WOLFSSL_HARDEN_TLS_NO_PKEY_CHECK` +- `WOLFSSL_HARDEN_TLS_ALLOW_ALL_CIPHERSUITES` #### WOLFSSL_ASIO @@ -1592,7 +1601,7 @@ OpenSSL compatibility specific macro. #### WOLFSSL_QT -OpenSSL compatibility specific. Enable DH Extra for QT, OpenSSL all, OpenSSH, and static ephemeral. +Enables the OpenSSL compatibility APIs and behaviors that the Qt framework needs (`--enable-qt`). It also turns on [`WOLFSSL_DH_EXTRA`](#wolfssl_dh_extra). #### WOLFSSL_QNX_CAAM @@ -1605,7 +1614,7 @@ OpenSSL compatibility specific macro. #### WOLFSSL_ASYNC_IO -Used in async cleanup. +Lets TLS functions resume after a non-blocking I/O return (`WANT_READ` / `WANT_WRITE`), a pending OCSP lookup, a deferred chain verify callback, or asynchronous crypto. Defined by default by settings.h; [`WOLFSSL_NO_ASYNC_IO`](#wolfssl_no_async_io) turns it off unless async crypto, `WOLFSSL_NONBLOCK_OCSP` or `WOLFSSL_CHAIN_VERIFY_CB` needs it. #### WOLFSSL_ASYNC_CRYPT_SW @@ -1634,7 +1643,7 @@ Used only for testing a non-blocking OCSP response. Enabled with `WOLFSSL_NONBLO #### TEST_OPENSSL_COEXIST -Use when enabling the build option: `./configure --enable-opensslcoexist`. +Test-only. Makes `wolfssl/ssl.h` also include the real OpenSSL headers, to check that an `--enable-opensslcoexist` build has no symbol clashes. Pass it in CFLAGS along with the OpenSSL include path; configure does not set it. #### TEST_PK_PRIVKEY @@ -1674,28 +1683,28 @@ Defines max quic capacity as 1024*1024 -- 1 MB. #### WOLFSSL_RENESAS_FSPSM_TLS -Not yet supported TLS related capabilities. +Enables the TLS-layer offload to the Renesas FSP Security Module (for example certificate verification, master secret generation and TLS HMAC), on top of `WOLFSSL_RENESAS_FSPSM`. Not every board supports it; see the board's `user_settings.h` under `IDE/Renesas/e2studio`. #### WOLFSSL_REFCNT_ERROR_RETURN -Returns errors on reference counting failures in SSL objects instead of silently continuing. Helps detect resource management issues. +Internal. `wolfssl/wolfcrypt/wc_port.h` defines it when reference counts are protected by a mutex (no atomic operations), so that callers check the error the reference count functions can return. Do not define it yourself. #### WOLFSSL_RENESAS_TSIP_TLS -This is for disabling only the TSIP TLS-linked common key encryption method. +Enables the TLS-layer use of Renesas TSIP (for example TLS 1.3 key exchange and key derivation, TLS HMAC and certificate verification), on top of `WOLFSSL_RENESAS_TSIP`. Leave it undefined, and define `WOLFSSL_RENESAS_TSIP_CRYPTONLY`, for wolfCrypt-only acceleration. #### WOLFSSL_SM2 -Define to use SM ciphers. +Enables SM2 elliptic curve signatures and key exchange (`--enable-sm2`, which needs ECC). The SM2, SM3 and SM4 implementations are in the separate wolfSM package (https://github.com/wolfSSL/wolfsm). #### WOLFSSL_SM3 -Define to use SM ciphers. +Enables the SM3 hash (`--enable-sm3`). Needs the wolfSM package. #### WOLFSSL_SM4 -Define to use SM ciphers. +Enables the SM4 block cipher. Set when any of the `--enable-sm4-ecb`, `--enable-sm4-cbc`, `--enable-sm4-ctr`, `--enable-sm4-gcm` or `--enable-sm4-ccm` options is used. Needs the wolfSM package. #### WOLFSSL_SM4_CBC @@ -1745,13 +1754,17 @@ Turns on the use of curve25519 algorithm. Turns on use of the ed25519 algorithm. +#### HAVE_ED448 + +Enables Ed448 signatures. Enabled with `--enable-ed448`. + #### WOLFSSL_DH_CONST Turns off use of floating point values when performing Diffie Hellman operations and uses tables for `XPOW()` and `XLOG()`. Removes dependency on external math library. #### WOLFSSL_TRUST_PEER_CERT -Turns on the use of trusted peer certificates. This allows for loading in a peer certificate to match with a connection rather than using a CA. When turned on if a trusted peer certificate is matched than the peer cert chain is not loaded and the peer is considered verified. Using CAs is preferred. +Turns on the use of trusted peer certificates. This allows for loading in a peer certificate to match with a connection rather than using a CA. When turned on, if a trusted peer certificate is matched then the peer cert chain is not loaded and the peer is considered verified. Using CAs is preferred. #### WOLFSSL_STATIC_MEMORY @@ -1763,7 +1776,7 @@ It requires `WOLFSSL_STATIC_MEMORY` to be defined. It uses smaller type sizes fo #### WOLFSSL_SESSION_EXPORT -Turns on the use of DTLS session export and import. This allows for serializing and sending/receiving the current state of a DTLS session. +Turns on session export and import for TLS (`wolfSSL_tls_export()` / `wolfSSL_tls_import()`) and DTLS (`wolfSSL_dtls_export()` / `wolfSSL_dtls_import()`). This allows for serializing and sending/receiving the current state of a session. Enabled with `--enable-sessionexport`. #### WOLFSSL_SESSION_EXPORT_DEBUG @@ -1773,7 +1786,7 @@ Enables debug logging for session export and import operations. Helps diagnose i #### WOLFSSL_SESSION_EXPORT_NOPEER -Exports sessions without including peer certificate information. Reduces exported session size when peer cert is not needed. +Leaves the peer's network address (IP address, port and address family) out of the exported session. Without this macro, export and import save and restore the peer address through the get/set peer I/O callbacks (`wolfSSL_CTX_SetIOGetPeer()` / `wolfSSL_CTX_SetIOSetPeer()`). Set by `--enable-sessionexport=nopeer`. #### WOLFSSL_ARMASM @@ -1781,15 +1794,15 @@ Turns on the use of ARMv8 hardware acceleration. #### WC_RSA_NONBLOCK -Turns on fast math RSA non-blocking support for splitting RSA operations into smaller chunks of work. Feature is enabled by calling [`wc_RsaSetNonBlock()`](group__RSA.md#function-wc_rsasetnonblock) and checking for `FP_WOULDBLOCK` return code. +Turns on non-blocking RSA support for splitting RSA operations into smaller chunks of work. It is backed either by fast math (`fp_exptmod_nb`, needs `TFM_TIMING_RESISTANT`) or by SP small non-blocking math (`WOLFSSL_SP_NONBLOCK` with `WOLFSSL_SP_SMALL`, `WOLFSSL_SP_NO_MALLOC` and `RSA_LOW_MEM`). Enabled with `--enable-rsa=nonblock`. Feature is enabled by calling [`wc_RsaSetNonBlock()`](group__RSA.md#function-wc_rsasetnonblock) and checking for the `FP_WOULDBLOCK` / `MP_WOULDBLOCK` return code. #### WC_RSA_BLINDING -Used to enable timing resistance. +Used to enable timing resistance (RSA private key blinding). Enabled by default in `./configure` builds through `--enable-harden` when the RNG is enabled; disable with `--disable-harden`. #### WC_RSA_PSS -Enables RSA PSS padding. The only TLS 1.3 RSA padding scheme supported is PSS (per specification). PSS padding uses random padding. +Enables RSA PSS padding. The only TLS 1.3 RSA padding scheme supported is PSS (per specification). PSS padding uses random padding. `./configure` turns it on whenever RSA and TLS 1.3 are enabled (the default), so it can only be left out of such a build together with TLS 1.3 (`--disable-tls13`); otherwise enable it with `--enable-rsapss`. #### WOLFSSL_RSA_VERIFY_ONLY @@ -1801,7 +1814,7 @@ Turns on small build for RSA public key only use. Should be used with the macro #### WOLFSSL_SHA3 -Turns on build for SHA3 use. This is support for SHA3 Keccak for the sizes SHA3-224, SHA3-256, SHA3-384 and SHA3-512. In addition `WOLFSSL_SHA3_SMALL` can be used to trade off performance for resource use. +Turns on build for SHA3 use. This is support for SHA3 Keccak for the sizes SHA3-224, SHA3-256, SHA3-384 and SHA3-512. In addition `WOLFSSL_SHA3_SMALL` can be used to trade off performance for resource use. Enabled by default in `./configure` builds: directly on x86_64 and aarch64, and on other hosts because the default [`WOLFSSL_HAVE_MLKEM`](#wolfssl_have_mlkem) build needs it. Disable with `--disable-sha3`, which also turns off the default ML-KEM build. #### USE_ECDSA_KEYSZ_HASH_ALGO @@ -1813,16 +1826,16 @@ Allows CA's to be presented by peer, but not part of a valid chain. Default wolf #### WOLFSSL_SYS_CA_CERTS -Allows wolfSSL to use trusted system CA certificates for verification when [`wolfSSL_CTX_load_system_CA_certs()`](group__CertsKeys.html#function-wolfssl_ctx_load_system_ca_certs) is called, either by loading them into wolfSSL certificate manager, or by invoking system authentication APIs. See [`wolfSSL_CTX_load_system_CA_certs()`](group__CertsKeys.html#function-wolfssl_ctx_load_system_ca_certs) for more details. This preprocessor macro is automatically set by the `--enable-sys-ca-certs` configure option. +Allows wolfSSL to use trusted system CA certificates for verification when [`wolfSSL_CTX_load_system_CA_certs()`](group__CertsKeys.md#function-wolfssl_ctx_load_system_ca_certs) is called, either by loading them into wolfSSL certificate manager, or by invoking system authentication APIs. See [`wolfSSL_CTX_load_system_CA_certs()`](group__CertsKeys.md#function-wolfssl_ctx_load_system_ca_certs) for more details. This preprocessor macro is automatically set by the `--enable-sys-ca-certs` configure option, which is enabled by default; disable it with `--disable-sys-ca-certs`. #### WOLFSSL_SYS_CRYPTO_POLICY Honors system-level crypto policy settings (e.g., `/etc/crypto-policies`) for restricting available algorithms and key sizes. -#### WOLFSSL_APPLE_NATIVE_CERT_VERIFICATION +#### WOLFSSL_APPLE_NATIVE_CERT_VALIDATION -Enables the use of Apple's native trust APIs when authenticating TLS peer certificates. Requires [WOLFSSL_SYS_CA_CERTS](#WOLFSSL_SYS_CA_CERTS) to be defined. This macro does not need to be set by the user if building with `configure` or `CMake` on iOS or other apple devices, but should be explicitly set on MacOS if you wish to use the native verification methods. +Enables the use of Apple's native trust APIs when authenticating TLS peer certificates. Requires [WOLFSSL_SYS_CA_CERTS](#wolfssl_sys_ca_certs) to be defined. This macro does not need to be set by the user if building with `configure` or `CMake` on iOS or other apple devices, but should be explicitly set on MacOS if you wish to use the native verification methods. #### WOLFSSL_TEST_APPLE_NATIVE_CERT_VALIDATION @@ -1844,7 +1857,7 @@ Enables additional alerts to be sent during a TLS connection. This feature is al #### WOLFSSL_EXTRA -Enables extra SSL session information tracking and APIs beyond the standard set. Provides additional session details for debugging and monitoring. +Enables a few APIs without the full OpenSSL compatibility layer: `wolfSSL_get_keys()`, `wolfSSL_set_quiet_shutdown()` / `wolfSSL_CTX_set_quiet_shutdown()` and `wolfSSL_set_accept_state()`. #### WOLFSSL_DEBUG_TLS @@ -1866,25 +1879,33 @@ Enables debug logging for the OpenSSL compatibility layer functions. Helps trace Lets the highest-volume trace messages (`WOLFSSL_MSG_VERBOSE()`, `WOLFSSL_ENTER_VERBOSE()`, `WOLFSSL_LEAVE_VERBOSE()`) into a `DEBUG_WOLFSSL` build. Traces on this tier can be emitted thousands of times by a single API call, so they are compiled out of a normal debug build, which keeps the debug output volume down by roughly 62%. Defined alone it does nothing; `DEBUG_WOLFSSL` is still required. See [Verbose Logging](chapter08.md#verbose-logging). +#### HAVE_BLAKE2B + +Enables BLAKE2b algorithm support. Enabled with `--enable-blake2b` (`--enable-blake2` is an alias). + +#### HAVE_BLAKE2S + +Enables BLAKE2s algorithm support. Enabled with `--enable-blake2s`. + #### HAVE_BLAKE2 -Enables Blake2b algorithm support +Legacy name for [`HAVE_BLAKE2B`](#have_blake2b). settings.h maps it to `HAVE_BLAKE2B`. #### HAVE_FALLBACK_SCSV -Enables Signaling Cipher Suite Value(SCSV) support on the server side. This handles the cipher suite 0x56 0x00 sent from a client to signal that no downgrade of TLS version should be allowed. +Has no effect. This used to enable Signaling Cipher Suite Value (SCSV) support on the server side, which handles the cipher suite 0x56 0x00 sent from a client to signal that no downgrade of TLS version should be allowed. Since wolfSSL 5.9.4 the server always checks TLS_FALLBACK_SCSV (RFC 7507). #### HAVE_AEAD -Implements the use of AEAD and is required for TLS 1.3. +Internal. `wolfssl/internal.h` defines it automatically when an AEAD cipher is built (AES-GCM, AES-CCM, ChaCha20-Poly1305, ARIA, SM4-GCM/CCM, or the TLS 1.3 NULL ciphers). Do not define it directly. #### HAVE_AES_CBC -Enable option for AES CBC. +Enable option for AES CBC. Always defined by settings.h when AES is enabled; define [`NO_AES_CBC`](#no_aes_cbc) to remove it. #### HAVE_ALPN -Crypto enables the option for application-layer protocol negotiation. +Enables the Application-Layer Protocol Negotiation (ALPN) TLS extension (RFC 7301). Enabled with `--enable-alpn`. #### HAVE_CAVIUM_OCTEON_SYNC @@ -1892,11 +1913,11 @@ This enables the blocking (synchronous) version of the Marvell Cavium/Octeon har #### HAVE_CERTIFICATE_STATUS_REQUEST -Used for Certificate revocation as a cert status request feature. +Enables OCSP stapling with the status_request TLS extension (RFC 6066). Enabled with `--enable-ocspstapling`. #### HAVE_CERTIFICATE_STATUS_REQUEST_V2 -Used for Certificate revocation as a cert status request feature. +Enables OCSP stapling with the status_request_v2 TLS extension, which can carry multiple OCSP responses (RFC 6961). Enabled with `--enable-ocspstapling2`. #### HAVE_CURL @@ -1918,17 +1939,25 @@ Enables Curve448 public key export. On by default when [`HAVE_CURVE448`](#have_c Enables Curve448 public key import. On by default when [`HAVE_CURVE448`](#have_curve448) is enabled. -#### WOLFSSL_ECDHX_SHARED_NOT_ZERO +#### WOLFSSL_NO_ECDHX_SHARED_ZERO_CHECK -Validates that ECDH shared secrets are not all zeros. Provides protection against invalid curve attacks. +Since wolfSSL 5.9.2, Curve25519 and Curve448 shared secret computation rejects an all-zero result with `ECC_OUT_OF_RANGE_E` by default (RFC 7748 section 6.1, small-order peer points). Define `WOLFSSL_NO_ECDHX_SHARED_ZERO_CHECK` to skip this check. #### HAVE_DANE -This option is only supported with `HAVE_RPK` (Raw Public Keys) and is a placeholder for when it might be added in the future. +Placeholder for DANE (RFC 6698) support. No code references it, so defining it currently has no effect. + +#### WOLFSSL_HAVE_MLKEM + +Enables ML-KEM (FIPS 203) key encapsulation in wolfCrypt, and the ML-KEM and hybrid key exchange groups for TLS 1.3. Enabled by default in `./configure` builds (it turns on SHA-3 and SHAKE), unless SHA-3 or SHAKE is explicitly disabled or the build is FIPS older than v7; disable with `--disable-mlkem` (`--enable-kyber` is an alias for `--enable-mlkem`). + +#### WOLFSSL_HAVE_MLDSA + +Enables ML-DSA (FIPS 204) signatures in wolfCrypt. Set by [`--enable-mldsa`](#--enable-mldsa) (`--enable-dilithium` is an alias). #### HAVE_DILITHIUM -Enable to include DILITHIUM post quantum cryptography/signature algo. This is the macro [`--enable-mldsa`](#--enable-mldsa) sets, for ML-DSA (FIPS 204). +Legacy name for [`WOLFSSL_HAVE_MLDSA`](#wolfssl_have_mldsa). settings.h maps `HAVE_DILITHIUM` to `WOLFSSL_HAVE_MLDSA`, and also defines `HAVE_DILITHIUM` whenever `WOLFSSL_HAVE_MLDSA` is set, unless `WOLFSSL_NO_DILITHIUM_LEGACY_GATES` is defined. #### WOLFSSL_MLDSA_VERIFY_ONLY @@ -1938,14 +1967,22 @@ Keeps only ML-DSA signature verification and drops key generation and signing. T Uses the ML-DSA verification path with the smallest memory usage, aimed at very constrained targets like the TI C2000 C28x. +#### WOLFSSL_HAVE_LMS + +Enables the LMS/HSS stateful hash-based signature scheme (RFC 8554) in wolfCrypt. Set by `--enable-lms`, which also accepts `verify-only` (`WOLFSSL_LMS_VERIFY_ONLY`) and `small` (`WOLFSSL_WC_LMS_SMALL`). The private key changes with every signature, so signing needs the key state callbacks set with `wc_LmsKey_SetWriteCb()` and `wc_LmsKey_SetReadCb()`. + +#### WOLFSSL_HAVE_XMSS + +Enables the XMSS/XMSS^MT stateful hash-based signature scheme (RFC 8391) in wolfCrypt. Set by `--enable-xmss`, which also accepts `verify-only` (`WOLFSSL_XMSS_VERIFY_ONLY`) and `small` (`WOLFSSL_WC_XMSS_SMALL`). The private key changes with every signature, so signing needs the key state callbacks set with `wc_XmssKey_SetWriteCb()` and `wc_XmssKey_SetReadCb()`. + #### HAVE_DH_DEFAULT_PARAMS -Includes default DH parameters for key exchange when the application does not explicitly load its own DH parameters. +No effect; kept for build compatibility. `--enable-defaultdhparams` (on by default) and the CMake option `WOLFSSL_DH_DEFAULT_PARAMS` still define it, but no library code reads it. #### HAVE_ED25519_KEY_IMPORT -ED25519 config. Enables Ed255519 and Curve25519 options for granular control of sign, verify, shared secret, import, and export. +Enables Ed25519 key import. On by default when [`HAVE_ED25519`](#have_ed25519) is enabled; define `NO_ED25519_KEY_IMPORT` to remove it. Related macros `HAVE_ED25519_MAKE_KEY`, `HAVE_ED25519_SIGN`, `HAVE_ED25519_VERIFY` and `HAVE_ED25519_KEY_EXPORT` work the same way, each with a matching `NO_ED25519_*` macro. #### HAVE_EX_DATA @@ -1953,7 +1990,7 @@ Enable "extra" EX data APIs for user information in CTX/WOLFSSL. #### HAVE_EX_DATA_CLEANUP_HOOKS -Set the extra data and cleanup callback against the RSA key at an index. +Adds `*_set_ex_data_with_cleanup()` variants that register a cleanup callback for ex_data on SSL, CTX, SESSION, X509, X509_STORE, X509_STORE_CTX, BIO and RSA objects (plus the generic `wolfSSL_CRYPTO_set_ex_data_with_cleanup()`). #### HAVE_EX_DATA_CRYPTO @@ -1962,7 +1999,7 @@ Enables extra data (ex_data) support for wolfCrypt objects such as RSA and ECC k #### HAVE_FALCON -Enables the Falcon post-quantum signature scheme (levels 1 and 5). wolfSSL 5.9.4 replaced the old liboqs wrapper with a native wolfCrypt implementation that supports crypto callbacks and ARM DSP / AArch64 NEON acceleration. [`--enable-falcon`](#--enable-falcon) turns the scheme on and also picks the floating point / FFT backend and memory profile. +Enables the Falcon post-quantum signature scheme (levels 1 and 5). wolfSSL 5.9.4 replaced the old liboqs wrapper with a native wolfCrypt implementation that supports crypto callbacks and ARM DSP / AArch64 NEON acceleration. [`--enable-falcon`](#--enable-falcon) turns the scheme on and also picks the floating point / FFT backend and memory profile. Falcon is not standardized, so `--enable-falcon` also needs `--enable-experimental`. #### HAVE_FIPS @@ -2060,13 +2097,9 @@ Lets maxq10xx know what TLS version we are using. Enables the ability to override maximum signature algorithms. -#### WOLFSSL_MEM_GUARD - -Can assign a specified memory guard. - #### WOLFSSL_STATIC_EPHEMERAL -TLS sniffer support. +Lets a fixed ("static") ephemeral (EC)DH key be loaded with [`wolfSSL_CTX_set_ephemeral_key()`](group__SSL.md#function-wolfssl_ctx_set_ephemeral_key) or `wolfSSL_set_ephemeral_key()`, so the sniffer can decrypt traffic that uses ephemeral key exchange. Reusing one ephemeral key across connections gives up forward secrecy; use it only for testing, inspection or debugging. Set automatically by `--enable-sniffer`. #### SSL_SNIFFER_EXPORTS @@ -2074,7 +2107,7 @@ WIN32 sniffer export. #### WOLFSSL_SNIFFER_KEYLOGFILE -The SSL Keylog file option enables the sniffer to decrypt TLS traffic using the master secret obtained from a [NSS keylog file](https://web.archive.org/web/20220531072242/https://firefox-source-docs.mozilla.org/security/nss/legacy/key_log_format/index.html). This allows the sniffer to decrypt all TLS traffic, even for TLS connections using ephemeral cipher suites. Keylog file sniffing is supported for TLS versions 1.2 and 1.3. WolfSSL can be configured to export a keylog file using the `--enable-keylog-export` configure option, independently from the sniffer feature (NOTE: never do this in a production environment, as it is inherently insecure). To enable sniffer support for keylog files, use the following configure command line and build as before: ./configure --enable-sniffer CPPFLAGS=-DWOLFSSL_SNIFFER_KEYLOGFILE`. +The SSL Keylog file option enables the sniffer to decrypt TLS traffic using the master secret obtained from a [NSS keylog file](https://web.archive.org/web/20220531072242/https://firefox-source-docs.mozilla.org/security/nss/legacy/key_log_format/index.html). This allows the sniffer to decrypt all TLS traffic, even for TLS connections using ephemeral cipher suites. Keylog file sniffing is supported for TLS versions 1.2 and 1.3. wolfSSL can be configured to export a keylog file using the `--enable-keylog-export` configure option, independently from the sniffer feature (NOTE: never do this in a production environment, as it is inherently insecure). To enable sniffer support for keylog files, use the following configure command line and build as before: `./configure --enable-sniffer CPPFLAGS=-DWOLFSSL_SNIFFER_KEYLOGFILE`. #### WOLFSSL_SNIFFER_STORE_DATA_CB @@ -2086,7 +2119,7 @@ The Session Watching option allows the sniffer to watch any packet provided with #### STATIC_BUFFER_LEN -Don't fragment memory from the record header. Expands to: `RECORD_HEADER_SZ`. +Size of the static input and output buffers in each SSL object. You can override it. By default it is `RECORD_HEADER_SZ`, so only the record header is held statically and larger buffers are allocated as needed; with [`LARGE_STATIC_BUFFERS`](#large_static_buffers) it is a full record plus overhead. #### STATIC_CHUNKS_ONLY @@ -2094,7 +2127,7 @@ The user has the option to turn off the 16K output option if we are using small #### WOLFSSL_DEF_PSK_CIPHER -Enables user-defined PSK cipher. +Second byte of the TLS 1.3 cipher suite (the first byte is `TLS13_BYTE`) used with an external PSK when the PSK callback does not name a cipher suite, for example with the callbacks set by `wolfSSL_CTX_set_psk_client_callback()` and `wolfSSL_CTX_set_psk_server_callback()` rather than their TLS 1.3 variants. Defaults to `TLS_AES_128_GCM_SHA256`; define it at compile time to override. #### WOLFSSL_OLD_PRIME_CHECK @@ -2146,7 +2179,7 @@ Turns on support for anonymous cipher suites. (Never recommended, some valid use #### HAVE_ATEXIT -Registers `wolfSSL_Cleanup()` as an `atexit()` handler for automatic cleanup when the program exits. +Registers `wolfSSL_Cleanup()` as an `atexit()` handler for automatic cleanup when the program exits. Only takes effect with `OPENSSL_EXTRA`. #### HAVE_LIBOQS @@ -2163,7 +2196,7 @@ Enable RSA/DH 4096-bit Single-Precision (SP) support. #### WOLFSSL_SP_384 -Enable ECC SECP384R1 Single-Precision (SP) support. Only applies to `WOLFSSL_SP_MATH`. +Enable ECC SECP384R1 Single-Precision (SP) support. Requires the SP ECC implementation (`WOLFSSL_HAVE_SP_ECC`, from `--enable-sp`). configure also defines `HAVE_ECC384` with it, and with [`WOLFSSL_SP_MATH`](#wolfssl_sp_math) settings.h does so automatically. #### WOLFSSL_SP_1024 @@ -2183,11 +2216,11 @@ Function TimeNowInMilliseconds() returns an unsigned 32-bit value. The default b #### WOLFSSL_MAX_DHKEY_BITS -DH maximum bit size must be a multiple of 8. DH maximum bit size must not exceed 16384 or greater than `WOLFSSL_MIN_DHKEY_BITS`. +Maximum DH key size in bits accepted in TLS. Must be a multiple of 8, at most 16384, and not less than [`WOLFSSL_MIN_DHKEY_BITS`](#wolfssl_min_dhkey_bits). The default depends on the math library: `SP_INT_BITS` with SP math, `FP_MAX_BITS / 2` with fast math (when `FP_MAX_BITS` is at least 16384), otherwise 4096. #### WOLFSSL_MIN_DHKEY_BITS -The DH minimum bit size must be a multiple of 8. For 112 bits of security, DH needs at least 2048-bit keys, and the minimum bit size must not be greater than 16000. +Minimum DH key size in bits accepted in TLS. Defaults to `DH_MIN_SIZE` (1024, or 2048 for FIPS builds). With [`WOLFSSL_HARDEN_TLS`](#wolfssl_harden_tls) set to 112 or 128 the default is 2048 or 3072, and a value below 2048 is rejected because 112 bits of security needs at least 2048-bit DH keys. Must be a multiple of 8, at most 16000, and at least `DH_MIN_SIZE`. #### WOLFSSL_MAX_MTU @@ -2195,7 +2228,7 @@ Max expected MTU. 1500 - 100 bytes to account for UDP and IP headers. #### IGNORE_NETSCAPE_CERT_TYPE -Define to input netscape cert type but holds a place. +Skip decoding of the Netscape Certificate Type certificate extension. #### SESSION_CERTS @@ -2203,7 +2236,7 @@ TLS session cache for certs. #### WOLFSSL_DUAL_ALG_CERTS -Dual algorithm certificate required feature. +Enables X9.146 dual key/signature (hybrid) certificates and their use in TLS 1.3. Set by `--enable-dual-alg-certs`, which needs `--enable-experimental`. #### CRL_MAX_REVOKED_CERTS @@ -2227,11 +2260,11 @@ Enable wolfSSL DTLS 1.3. #### WOLFSSL_TLS13 -Enable TLS 1.3 protocol implementation. +Enable TLS 1.3 protocol implementation. Enabled by default in `./configure` builds; disable with `--disable-tls13`. #### WOLFSSL_TLS13_IGNORE_AEAD_LIMITS -Limits specified by https://www.rfc-editor.org/rfc/rfc9147.html#name-aead-limits. We specify the limit by which we need to do a key update as the halfway point to the hard decryption fail limit. +Turns off enforcement of the TLS 1.3 and DTLS 1.3 AEAD usage limits (RFC 9846 section 5.5, RFC 9147 section 4.5.3). By default wolfSSL updates the keys once the number of records sent with one key reaches the limit for the cipher. For DTLS 1.3 it also counts records that fail decryption (limits specified by https://www.rfc-editor.org/rfc/rfc9147.html#name-aead-limits): it requests a key update at the halfway point to the hard decryption fail limit, and fails the connection when the hard limit is reached. #### WOLFSSL_TLS13_DRAFT @@ -2292,13 +2325,9 @@ Verifies the ECC signature after signing to detect fault injection attacks. Usef Uses wolfSSL internal cipher suite names instead of IANA-standard names when reporting cipher suite information through the API. -#### WOLFSSL_PSK_ID_PROTECTION - -Enables PSK identity protection in TLS 1.3. Encrypts the PSK identity to prevent passive observers from tracking clients by their PSK identity. - #### WOLFSSL_NO_CLIENT_CERT_ERROR -When enabled, the server requires the client to send a valid certificate. If the client does not provide one, the handshake fails with an error. +TLS 1.3 client side: when the server requests a certificate and the client has none, abort the handshake with a `certificate_required` alert and `NO_CERT_ERROR` (or with an `unsupported_certificate` alert when its certificate chain uses signature algorithms the server does not accept). By default the client sends an empty Certificate message (RFC 8446 section 4.4.2). Server-side enforcement is `WOLFSSL_VERIFY_FAIL_IF_NO_PEER_CERT`. #### WOLFSSL_NONBLOCK_OCSP @@ -2310,7 +2339,7 @@ Enables support for multiple OCSP responses in TLS, allowing stapling of OCSP re #### WOLFSSL_CERT_SETUP_CB -Enables a certificate setup callback that is invoked during the TLS 1.3 handshake. Allows dynamic certificate and key selection based on the ClientHello contents. +Enables a certificate setup callback, set with `wolfSSL_CTX_set_cert_cb()`, that allows dynamic certificate and key selection during the handshake. A server invokes it while processing the ClientHello (TLS 1.2 and TLS 1.3), before cipher suite matching, so the choice can be based on the ClientHello contents; a client invokes it when it receives a CertificateRequest. Also adds `wolfSSL_get_client_suites_sigalgs()`. Set by `--enable-cert-setup-cb`. #### WOLFSSL_RW_THREADED @@ -2330,7 +2359,7 @@ Specifies Max ticket age. For TLS 1.3, this is 7 days. #### TLS13_TICKET_NONCE_STATIC_SZ -TLS13_TICKET_NONCE_STATIC_SZ is not supported in this `FIPS_VERSION_GE`. +Size of the static buffer that holds a TLS 1.3 ticket nonce (default 8, maximum 255). Not supported with FIPS builds older than v5.3. #### TIME_OVERRIDES @@ -2343,7 +2372,7 @@ Defines version max size for ticket nonce. Max size is defined as 255 bytes. #### WOLFSSL_TICKET_ENC_AES128_GCM -Use AES128-GCM to encrypt/decrypt session tickets in the default callback. This is server-only. If ChaCha20/Poly1305 is not compiled, this is the default algorithm. +Use AES128-GCM to encrypt/decrypt session tickets in the default callback. This is server-only. The default ticket cipher is ChaCha20-Poly1305 when it is compiled in and neither AES-GCM ticket macro is defined. Otherwise it is AES-256-GCM when `WOLFSSL_AES_256` is available, and AES-128-GCM only when it is not. #### WOLFSSL_TICKET_ENC_AES256_GCM @@ -2351,7 +2380,7 @@ Use AES256-GCM to encrypt/decrypt session tickets in default callback. Server on #### WOLFSSL_TICKET_ENC_CHACHA20_POLY1305 -Use ChaCha20-Poly1305 to encrypt/decrypt session tickets in the default callback. If none are defined, the default algorithm is used, and algorithms are compiled. This is server-only. +Use ChaCha20-Poly1305 to encrypt/decrypt session tickets in the default callback. This is also the default when ChaCha20-Poly1305 is compiled in and neither `WOLFSSL_TICKET_ENC_AES128_GCM` nor `WOLFSSL_TICKET_ENC_AES256_GCM` is defined. This is server-only. #### WOLFSSL_TICKET_ENC_CBC_HMAC @@ -2417,7 +2446,7 @@ Defined as cipher check size which needs 64-bits to confirm encrypt operation wo #### DTLS_CID_MAX_SIZE -DTLS 1.3 parsing code copies the record header in a static buffer to decrypt the record. Increasing the CID max size also increases this buffer, impacting the per-session runtime memory footprint. The max size for DTLS CID is 255 bytes. +Largest connection ID wolfSSL asks to receive (and, for DTLS 1.2, sends). Default 10 bytes, maximum 255. Applies to DTLS 1.2 and 1.3 with [`WOLFSSL_DTLS_CID`](#wolfssl_dtls_cid). The DTLS parsing code copies the record header in a static buffer to decrypt the record, so increasing the CID max size also increases this buffer, impacting the per-session runtime memory footprint. #### DTLS13_EPOCH_SIZE @@ -2430,24 +2459,20 @@ Portability improvement with DTLS 1.3. Used in DTLS 1.3 to identify size before #### WOLFSSL_DTLS_FRAG_POOL_SZ -Defines the allowed number of fragments per specified time. +Maximum number of separate fragment buckets buffered while reassembling one DTLS handshake message. Default 10, maximum 255. #### WOLFSSL_DTLS_MTU Enables DTLS MTU (Maximum Transmission Unit) management APIs for controlling the maximum datagram size during DTLS communication. -#### WOLFSSL_CLIENT_SESSION_DEFINED - -Declare opaque struct for API to use. - #### WOLFSSL_COND Defined if this system supports signaling COND_TYPE - type that should be passed into the signaling API. #### WOLFSSL_DTLS_CH_FRAG -Allows a server to process a fragmented second/verified (one containing a valid cookie response) ClientHello message. The first/unverified (one without a cookie extension) ClientHello MUST be unfragmented so that the DTLS server can process it statelessly. This is only implemented for DTLS 1.3. The user MUST call `wolfSSL_dtls13_allow_ch_frag()` on the server to explicitly enable this during runtime (it defaults to on in ML-KEM builds only). Note: Using DTLS 1.3 + pqc without `WOLFSSL_DTLS_CH_FRAG` will probably fail In this case use `--enable-dtls-frag-ch` to enable it (ML-KEM builds get it automatically). With cookies disabled through `wolfSSL_disable_cookie()`, a DTLS 1.3 server can process a fragmented first ClientHello only if it was built with this macro and `wolfSSL_dtls13_allow_ch_frag()` is on; otherwise the fragments are dropped. +Allows a server to process a fragmented second/verified (one containing a valid cookie response) ClientHello message. The first/unverified (one without a cookie extension) ClientHello MUST be unfragmented so that the DTLS server can process it statelessly. This is only implemented for DTLS 1.3. The user MUST call `wolfSSL_dtls13_allow_ch_frag()` on the server to explicitly enable this during runtime (it defaults to on in ML-KEM builds only). Note: Using DTLS 1.3 + pqc without `WOLFSSL_DTLS_CH_FRAG` will probably fail. In this case use `--enable-dtls-frag-ch` to enable it (ML-KEM builds get it automatically). With cookies disabled through `wolfSSL_disable_cookie()`, a DTLS 1.3 server can process a fragmented first ClientHello only if it was built with this macro and `wolfSSL_dtls13_allow_ch_frag()` is on; otherwise the fragments are dropped. #### WOLFSSL_DTLS_MTU_ADDITIONAL_READ_BUFFER @@ -2496,17 +2521,17 @@ Enables MySQL protocol compatibility behaviors in wolfSSL. Required when using w #### WOLFSSL_NAMES_STATIC -Uses static ECC structs for Position Independent Code (PIC). +Stores name strings in lookup tables (for example cipher suite names, certificate name component names, Curve25519 and LMS/XMSS parameter names) in fixed-size arrays instead of pointers, so the tables need no relocation. This is for Position Independent Code (PIC); settings.h defines it automatically for Linux kernel module builds with relocation tables (`WC_SYM_RELOC_TABLES`, from `--enable-kernel-reloc-tables`) and for IAR ROPI builds. Static ECC curve tables are `WOLFSSL_ECC_CURVE_STATIC`. #### WOLFSSL_SEND_HRR_COOKIE -Enables the TLS 1.3 / DTLS 1.3 HelloRetryRequest cookie extension on both the server (sending a cookie, selected at runtime with `wolfSSL_send_hrr_cookie()`) and the client (echoing a received cookie). Required for a stateless DTLS 1.3 server (`wolfDTLS_accept_stateless()`). +Enables the server side of the TLS 1.3 / DTLS 1.3 HelloRetryRequest cookie extension (sending a cookie, selected at runtime with `wolfSSL_send_hrr_cookie()`). The client side (echoing a received cookie) is always built into TLS 1.3 builds with client support, see [`WOLFSSL_TLS13_COOKIE`](#wolfssl_tls13_cookie). Required for a stateless DTLS 1.3 server (`wolfDTLS_accept_stateless()`). wolfSSL 5.9.4 made the DTLS cookie mode a single policy the application sets: `wolfSSL_enable_cookie()` and `wolfSSL_disable_cookie()` switch server cookies for DTLS 1.2, DTLS 1.3 and TLS 1.3, and `wolfSSL_disable_hrr_cookie()` just calls `wolfSSL_disable_cookie()`. Once the handshake has decided how to handle the ClientHello, the setters return `BAD_STATE_E`. Cookie secret changes are all or nothing: the new secret is fully built before the old one is freed. A secondary, verify-only cookie secret lets the application rotate secrets. #### WOLFSSL_TLS13_COOKIE -Enables the client side cookie echo for the TLS 1.3 cookie extension, without the server side. It was split out of `WOLFSSL_SEND_HRR_COOKIE` in wolfSSL 5.9.4, which still turns on both sides. +Enables the client side cookie echo for the TLS 1.3 cookie extension, without the server side. It was split out of `WOLFSSL_SEND_HRR_COOKIE` in wolfSSL 5.9.4. You do not need to define it: `wolfssl/internal.h` defines it automatically in every TLS 1.3 build with client support (cookie support is mandatory per RFC 8446 section 9.2) and whenever `WOLFSSL_SEND_HRR_COOKIE` is defined. #### WOLFSSL_SEP @@ -2552,11 +2577,7 @@ Define to allow this to be overridden at compile-time. ECDHE server size default #### CIPHER_NONCE -It is used as a cryptographic number, which is implemented in authentication. It is a pseudo-random number, which is an integrity-only cipher suite. - -#### WOLFSSL_USE_POPEN_HOST - -Uses popen for creating socket with host and post for wolfio.c socket open code used with CRL and OCSP. +Internal. `wolfssl/internal.h` defines it automatically when AES, AES-GCM, ARIA, ChaCha20-Poly1305 or TLS 1.3 is built. It adds the per-record nonce buffer to the cipher state. It is not a user option. #### CloseSocket @@ -2576,19 +2597,19 @@ Option for user-defined mutexes with `WOLFSSL_USER_MUTEX`. #### DEFAULT_MIN_ECCKEY_BITS -Identifies the minimum number of bits in ECCkey. +Default minimum ECC key size (224 bits, or 256 with `WOLFSSL_MAX_STRENGTH`) used by the example client and server (`wolfssl/test.h`). For the library limit see [`WOLFSSL_MIN_ECC_BITS`](#wolfssl_min_ecc_bits). #### DEFAULT_MIN_RSAKEY_BITS -Identifies the minimum number of bits in RSA key. +Default minimum RSA key size (1024 bits, or 2048 with `WOLFSSL_MAX_STRENGTH`) used by the example client and server (`wolfssl/test.h`). For the library limit see [`WOLFSSL_MIN_RSA_BITS`](#wolfssl_min_rsa_bits). #### EXTERNAL_SERIAL_SIZE -A raw serial number byte that writes X509 serial numbers in unsigned binary to a buffer. For all cases, the buffer needs to be at least `EXTERNAL_SERIAL_SIZE` (32). On success, it returns `WOLFSSL_SUCCESS`. Note: this is a internal macro that cannot be user defined. +A raw serial number byte that writes X509 serial numbers in unsigned binary to a buffer. For all cases, the buffer needs to be at least `EXTERNAL_SERIAL_SIZE` (32). On success, it returns `WOLFSSL_SUCCESS`. Note: this is an internal macro that cannot be user defined. #### LARGE_STATIC_BUFFERS -Embedded callbacks require large static buffers; make sure it gives the option to enable larger buffers to 16K. +Makes the static input and output record buffers in each SSL object big enough for a full record (`RECORD_SIZE` becomes `MAX_RECORD_SIZE`, 16 KB, plus the record header and overhead), instead of the default static buffers that only hold a record header. Forced on by [`WOLFSSL_CALLBACKS`](#wolfssl_callbacks). #### LIBWOLFSSL_VERSION_STRING From c9a30f23e49d151e97c5ec3bd59b75b13079ea15 Mon Sep 17 00:00:00 2001 From: Andrew Hutchings Date: Fri, 6 Nov 2026 09:20:41 +0000 Subject: [PATCH 04/25] wolfSSL manual: chapter 2: update build, CMake and ports sections - Document git checkout with autogen.sh, wolfssl/options.h, CMake (build, options, install, find_package, Windows, presets), vcpkg and make deb / make rpm - Replace stale VS 2008/2010/2013, TrueSTUDIO, Cygwin and Keil text with the current Visual Studio, STM32Cube and MDK5 CMSIS pack flow - Fix the vendor IDE exclude list, Yocto, IAR, Xcode, apple-universal and GCC-ARM details - Correct fastmath/SP math option descriptions and the --enable-sp macro lists, and add the missing --enable-sp values - Fix cross compile examples and update the IDE port list - NXP CAAM: fix broken shell commands, API names and code snippets, move CodeAurora URLs to GitHub, add SECO API and QNX/Linux docs - Remove general macro entries misplaced at the end of the CAAM section --- wolfSSL/src/chapter02.md | 538 +++++++++++++++++++++++++-------------- 1 file changed, 343 insertions(+), 195 deletions(-) diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index 58a6876d..9dd2514f 100644 --- a/wolfSSL/src/chapter02.md +++ b/wolfSSL/src/chapter02.md @@ -19,11 +19,19 @@ After downloading the ZIP file, unzip the file using the `unzip` command. To use > extracted as such, converting line endings, end-of-file characters > and the character set itself as necessary. [...] -**NOTE**: Beginning with the release of wolfSSL 2.0.0rc3, the directory structure of wolfSSL was changed as well as the standard install location. These changes were made to make it easier for open source projects to integrate wolfSSL. For more information on header and structure changes, please see [Library Headers](chapter09.md#library-headers) and [Structure Usage](#structure-usage). +The source code is also available from GitHub: + +```sh +git clone https://github.com/wolfSSL/wolfssl.git +``` + +A git checkout does not include the `configure` script. Generate it by running `./autogen.sh` from the wolfSSL root directory before following the steps below. This requires autoconf (2.69 or later), automake (1.13.4 or later) and libtool (2.4.2 or later). The release ZIP files already contain `configure`. + +**NOTE**: For the location of the wolfSSL header files, see [Library Headers](chapter09.md#library-headers). For the names of the native wolfSSL structures, see [Structure Usage](chapter09.md#structure-usage). ## Building on Unix-like Systems -When building wolfSSL on Linux, \*BSD, OS X, Solaris, or other \*nix-like systems, use the autoconf system. To build wolfSSL you only need to run two commands from the wolfSSL root directory, `./configure` and `make`. +When building wolfSSL on Linux, \*BSD, OS X, Solaris, or other \*nix-like systems, use the autoconf system. To build wolfSSL you only need to run two commands from the wolfSSL root directory, `./configure` and `make` (run `./autogen.sh` first if building from a git checkout). The `./configure` script sets up the build environment and you can append any number of build options to `./configure`. For a list of available build options, please see [Build Options](#build-options) or run the following command to see a list of possible options to pass to the `./configure` script: @@ -49,6 +57,8 @@ You may need superuser privileges to install, in which case precede the command sudo make install ``` +`./configure` generates the header `wolfssl/options.h`, which records the build settings. Applications must `#include ` before any other wolfSSL header (or define `WOLFSSL_USE_OPTIONS_H`, which makes the wolfSSL headers include it automatically) so that they are compiled with the same configuration as the library. + To test the build, run the testsuite program from the root wolfSSL directory: ```sh @@ -67,28 +77,79 @@ Further details about expected output of the testsuite program can be found in t make src/libwolfssl.la ``` -## Building on Windows +### Building Debian and RPM Packages -In addition to the instructions below, you can find instructions and tips for building wolfSSL with Visual Studio [here](https://wolfssl.com/wolfSSL/Docs-wolfssl-visual-studio.html). +After running `./configure` with the options you want, `make deb` builds a Debian package (Debian, Ubuntu, Linux Mint and derivatives) and `make rpm` builds an RPM package (RHEL, Fedora, CentOS, SUSE and openSUSE) with that configuration. `make deb-docker` and `make rpm-docker` build the same packages inside a Docker container. -### VS 2008 +## Building with CMake -Solutions are included for Visual Studio 2008 in the root directory of the install. For use with Visual Studio 2010 and later, the existing project files should be able to be converted during the import process. +wolfSSL can also be configured and built with CMake 3.16 or later (3.22 or later is recommended). The autoconf build is the primary build system; the CMake build supports the commonly used options, but not every `./configure` option. -**Note**: -If importing to a newer version of VS you will be asked: “Do you want to overwrite the project and its imported property sheets?” You can avoid the following by selecting “No”. Otherwise if you select “Yes”, you will see warnings about `EDITANDCONTINUE` being ignored due to `SAFESEH` specification. You will need to right click on the testsuite, sslSniffer, server, echoserver, echoclient, and client individually and modify their Properties-\>Configuration Properties-\>Linker-\>Advanced (scroll all the way to the bottom in Advanced window). Locate “Image Has Safe Exception Handlers” and click the drop down arrow on the far right. Change this to No (`/SAFESEH:NO`) for each of the aforementioned. The other option is to disable `EDITANDCONTINUE` which, we have found to be useful for debugging purposes and is therefore not recommended for production software. +CMake does not allow building in the source directory, so create a separate build directory. From the wolfSSL root directory: -### VS 2010 +```sh +mkdir build +cd build +cmake .. +cmake --build . +``` + +`cmake --build .` runs the underlying build tool (`make` by default on Unix-like systems), which can also be run directly. + +Build options are set with `-D