diff --git a/.github/workflows/code-spell.yml b/.github/workflows/code-spell.yml index 2b828cab..fb99bb82 100644 --- a/.github/workflows/code-spell.yml +++ b/.github/workflows/code-spell.yml @@ -36,5 +36,6 @@ jobs: # Incomming - verbatim lwIP echoserver example output # psuedo - verbatim wolfSSH client --help output # fpr - assembly instruction reference - ignore_words_list: TE,Thi,inter-operability,regist,Writen,Challener,cant,mot,callin,Incomming,psuedo,fpr + # sme - Arm Scalable Matrix Extension (--enable-frodokem-sme) + ignore_words_list: TE,Thi,inter-operability,regist,Writen,Challener,cant,mot,callin,Incomming,psuedo,fpr,sme skip: '.git' 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 diff --git a/wolfSSL/src/appendix04.md b/wolfSSL/src/appendix04.md index 017b4254..15491664 100644 --- a/wolfSSL/src/appendix04.md +++ b/wolfSSL/src/appendix04.md @@ -2,9 +2,9 @@ ## General Architecture -The wolfSSL (formerly CyaSSL) embedded SSL library implements SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3 protocols. TLS 1.3 is currently the most secure and up to date version of the standard. wolfSSL does not support SSL 2.0 due to the fact that it has been insecure for several years. +The wolfSSL (formerly CyaSSL) embedded SSL library implements SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3 protocols, as well as DTLS 1.0, DTLS 1.2 and DTLS 1.3. TLS 1.3 is currently the most secure and up to date version of the standard. SSL 3.0 (RFC 7568), TLS 1.0 and TLS 1.1 (RFC 8996) are deprecated, so wolfSSL builds them out by default; they are only compiled in when explicitly enabled with `--enable-sslv3`, `--enable-tlsv10` or `--enable-oldtls`. wolfSSL does not support SSL 2.0 due to the fact that it has been insecure for several years. -The TLS protocol in wolfSSL is implemented as defined in [RFC 5246 (https://tools.ietf.org/html/rfc5246).](https://tools.ietf.org/html/rfc5246) Two record layer protocols exist within SSL - the message layer and the handshake layer. Handshake messages are used to negotiate a common cipher suite, create secrets, and enable a secure connection. The message layer encapsulates the handshake layer while also supporting alert processing and application data transfer. +TLS 1.2 is implemented in wolfSSL as defined in [RFC 5246](https://tools.ietf.org/html/rfc5246) and TLS 1.3 as defined in [RFC 8446](https://tools.ietf.org/html/rfc8446). DTLS 1.2 follows [RFC 6347](https://tools.ietf.org/html/rfc6347) and DTLS 1.3 follows [RFC 9147](https://tools.ietf.org/html/rfc9147). TLS is a layered protocol. The lower layer is the record protocol, which fragments, protects (encrypts and authenticates) and transmits the data of the higher-level protocols: the handshake protocol, the alert protocol, the change cipher spec protocol (TLS 1.2 and earlier only) and application data. Handshake messages are used to negotiate a common cipher suite, create secrets, and enable a secure connection. Alert messages report errors and the closure of the connection. A general diagram of how the SSL protocol fits into existing protocols can be seen in **Figure 1**. SSL sits in between the Transport and Application layers of the OSI model, where any number of protocols (including TCP/IP, Bluetooth, etc.) may act as the transport medium. Application protocols are layered on top of SSL (such as HTTP, FTP, and SMTP). @@ -16,9 +16,38 @@ The SSL handshake involves several steps, some of which are optional depending o ![SSL Handshake Diagram](sslhandshake.png "SSL Handshake Diagram") +**Figure 2** shows the full handshake of TLS 1.2 and earlier versions. In the actual message order, a client that is asked for a certificate sends its Certificate message before the ClientKeyExchange message, and its CertificateVerify message after the ClientKeyExchange message. + +### TLS 1.3 Handshake + +TLS 1.3 uses a different, shorter handshake. The key exchange takes place in the hello messages (`key_share` extension), so the full handshake needs only one round trip before the client can send application data. There are no ServerKeyExchange, ServerHelloDone or ClientKeyExchange messages, ChangeCipherSpec is only sent as a dummy message in middlebox compatibility mode, and everything the server sends after the ServerHello is encrypted: + +```text +Client Server + +ClientHello (key_share, supported_versions) + --------> + ServerHello (key_share) + {EncryptedExtensions} + {CertificateRequest} * + {Certificate} + {CertificateVerify} + {Finished} + <-------- +{Certificate} * +{CertificateVerify} * +{Finished} + --------> +[Application Data] <-------> [Application Data] + +* sent only when the server requests client authentication +{} encrypted with the handshake traffic keys +[] encrypted with the application traffic keys +``` + ## Differences between SSL and TLS Protocol Versions -SSL (Secure Sockets Layer) and TLS (Transport Security Layer) are both cryptographic protocols which provide secure communication over networks. These two protocols (and the several versions of each) are in widespread use today in applications ranging from web browsing to e-mail to instant messaging and VoIP. Each protocol, and the underlying versions of each, are slightly different from the other. +SSL (Secure Sockets Layer) and TLS (Transport Layer Security) are both cryptographic protocols which provide secure communication over networks. These two protocols (and the several versions of each) are in widespread use today in applications ranging from web browsing to e-mail to instant messaging and VoIP. Each protocol, and the underlying versions of each, are slightly different from the other. Below you will find both an explanation of, and the major differences between the different SSL and TLS protocol versions. For specific details about each protocol, please reference the RFC specification mentioned. @@ -48,7 +77,7 @@ This protocol was first defined in RFC 2246 in January of 1999. This was an upgr This protocol was defined in RFC 4346 in April of 2006, and is an update to TLS 1.0. The major changes are: * The Implicit Initialization Vector (IV) is replaced with an explicit IV to protect against Cipher block chaining (CBC) attacks. -* Handling of padded errors is changed to use the `bad_record_ma`c alert rather than the `decryption_failed` alert to protect against CBC attacks. +* Handling of padding errors is changed to use the `bad_record_mac` alert rather than the `decryption_failed` alert to protect against CBC attacks. * IANA registries are defined for protocol parameters * Premature closes no longer cause a session to be non-resumable. @@ -64,7 +93,7 @@ This protocol was defined in RFC 5246 in August of 2008. Based on TLS 1.1, TLS * Tighter checking of EncryptedPreMasterSecret version numbers. * Many of the requirements were tightened * `Verify_data` length depends on the cipher suite -* Description of Bleichenbacher/Dlima attack defenses cleaned up. +* Description of Bleichenbacher/Klima attack defenses cleaned up. ### TLS 1.3 @@ -76,6 +105,11 @@ This protocol was defined in RFC 8446 in August of 2018. TLS 1.3 contains improv * Key derivation functions have been re-designed, with the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) being used as a primitive. * The handshake state machine has been restructured to be more consistent and remove superfluous messages. * ECC is now in the base spec and includes new signature algorithms. Point format negotiation has been removed in favor of single point format for each curve. -* Compression, custom DHE groups, and DSA have been removed, RSA padding now uses PSS. +* Compression, custom DHE groups, and DSA have been removed, RSA signatures now use PSS padding. +* Static RSA and static Diffie-Hellman cipher suites have been removed; all public-key based key exchange mechanisms now provide forward secrecy. * TLS 1.2 version negotiation verification mechanism was deprecated in favor of a version list in an extension. * Session resumption with and without server-side state and the PSK-based ciphersuites of earlier versions of TLS have been replaced by a single new PSK exchange. + +### DTLS + +DTLS (Datagram Transport Layer Security) adapts TLS to datagram transports such as UDP. It adds explicit record sequence numbers and epochs, retransmission of lost handshake messages, and a cookie exchange that protects servers against denial of service attacks. DTLS 1.0 (RFC 4347) is based on TLS 1.1, DTLS 1.2 (RFC 6347) on TLS 1.2, and DTLS 1.3 (RFC 9147) on TLS 1.3; there is no DTLS 1.1. DTLS is disabled by default in wolfSSL. Use `--enable-dtls` for DTLS 1.2 and `--enable-dtls13` for DTLS 1.3; DTLS 1.0 also requires `--enable-oldtls`. diff --git a/wolfSSL/src/appendix05.md b/wolfSSL/src/appendix05.md index 0aa4dbc7..3b036fcd 100644 --- a/wolfSSL/src/appendix05.md +++ b/wolfSSL/src/appendix05.md @@ -2,47 +2,106 @@ ## Protocols -* SSL v3.0 - [IETF Draft](https://tools.ietf.org/id/draft-ietf-tls-ssl-version3-00.txt) +* SSL v3.0 - [RFC6101](https://datatracker.ietf.org/doc/html/rfc6101) (Historic; deprecated by [RFC7568](https://datatracker.ietf.org/doc/html/rfc7568)) * TLS v1.0 - [RFC2246](https://www.ietf.org/rfc/rfc2246.txt) * TLS v1.1 - [RFC4346](https://www.ietf.org/rfc/rfc4346.txt) +* Deprecating TLS 1.0 and TLS 1.1 - [RFC8996](https://datatracker.ietf.org/doc/html/rfc8996) * TLS v1.2 - [RFC5246](https://www.ietf.org/rfc/rfc5246.txt) -* TLS v1.3 - [RFC8446](https://www.ietf.org/rfc/rfc8446.txt) -* DTLS - [RFC9147](https://datatracker.ietf.org/doc/html/rfc9147) +* TLS v1.3 - [RFC8446](https://www.ietf.org/rfc/rfc8446.txt), revised in [RFC9846](https://datatracker.ietf.org/doc/html/rfc9846) +* DTLS v1.0 - [RFC4347](https://datatracker.ietf.org/doc/html/rfc4347) +* DTLS v1.2 - [RFC6347](https://datatracker.ietf.org/doc/html/rfc6347) +* DTLS v1.3 - [RFC9147](https://datatracker.ietf.org/doc/html/rfc9147) +* Using TLS to Secure QUIC - [RFC9001](https://datatracker.ietf.org/doc/html/rfc9001) +* Recommendations for Secure Use of TLS and DTLS (BCP 195) - [RFC9325](https://datatracker.ietf.org/doc/html/rfc9325) * IPv4 - [Wikipedia](https://en.wikipedia.org/wiki/IPv4) * IPv6 - [Wikipedia](https://en.wikipedia.org/wiki/IPv6) +## TLS Extensions and Cipher Suites + +* TLS Extensions (SNI, Maximum Fragment Length, Trusted CA Keys, Truncated HMAC, Certificate Status Request) - [RFC6066](https://datatracker.ietf.org/doc/html/rfc6066) +* Multiple Certificate Status Request (`status_request_v2`) - [RFC6961](https://datatracker.ietf.org/doc/html/rfc6961) +* Application-Layer Protocol Negotiation (ALPN) - [RFC7301](https://datatracker.ietf.org/doc/html/rfc7301) +* Renegotiation Indication - [RFC5746](https://datatracker.ietf.org/doc/html/rfc5746) +* Session Tickets - [RFC5077](https://datatracker.ietf.org/doc/html/rfc5077) +* Encrypt-then-MAC - [RFC7366](https://datatracker.ietf.org/doc/html/rfc7366) +* Extended Master Secret - [RFC7627](https://datatracker.ietf.org/doc/html/rfc7627) +* ECC Cipher Suites for TLS 1.2 and Earlier - [RFC8422](https://datatracker.ietf.org/doc/html/rfc8422) (obsoletes [RFC4492](https://datatracker.ietf.org/doc/html/rfc4492)) +* Finite Field Diffie-Hellman Ephemeral (FFDHE) Groups - [RFC7919](https://datatracker.ietf.org/doc/html/rfc7919) +* Brainpool Curves for TLS 1.3 - [RFC8734](https://datatracker.ietf.org/doc/html/rfc8734) +* Raw Public Keys - [RFC7250](https://datatracker.ietf.org/doc/html/rfc7250) +* AES-GCM Cipher Suites - [RFC5288](https://datatracker.ietf.org/doc/html/rfc5288) +* AES-CCM Cipher Suites - [RFC6655](https://datatracker.ietf.org/doc/html/rfc6655) +* ChaCha20-Poly1305 Cipher Suites - [RFC7905](https://datatracker.ietf.org/doc/html/rfc7905) +* ECDHE-PSK AEAD Cipher Suites - [RFC8442](https://datatracker.ietf.org/doc/html/rfc8442) +* Integrity-Only Cipher Suites for TLS 1.3 - [RFC9150](https://datatracker.ietf.org/doc/html/rfc9150) +* ShangMi (SM) Cipher Suites for TLS 1.3 - [RFC8998](https://datatracker.ietf.org/doc/html/rfc8998) +* Deprecating MD5 and SHA-1 Signature Hashes in TLS 1.2 and DTLS 1.2 - [RFC9155](https://datatracker.ietf.org/doc/html/rfc9155) +* DTLS Connection ID - [RFC9146](https://datatracker.ietf.org/doc/html/rfc9146) +* DTLS-SRTP - [RFC5764](https://datatracker.ietf.org/doc/html/rfc5764) +* Encrypted Client Hello (ECH) - [RFC9849](https://datatracker.ietf.org/doc/html/rfc9849) +* Certificate Authentication with External PSK (`cert_with_extern_psk`) - [RFC9973](https://datatracker.ietf.org/doc/html/rfc9973) (obsoletes [RFC8773](https://datatracker.ietf.org/doc/html/rfc8773)) +* ML-KEM for TLS 1.3 - [draft-ietf-tls-mlkem](https://datatracker.ietf.org/doc/draft-ietf-tls-mlkem/) +* Hybrid ECDHE-ML-KEM for TLS 1.3 - [draft-ietf-tls-ecdhe-mlkem](https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/) + ## Stream Ciphers * Stream Cipher Information - [Wikipedia](https://en.wikipedia.org/wiki/Stream_cipher) * RC4 / ARC4 - [IETF Draft](https://tools.ietf.org/id/draft-kaukonen-cipher-arcfour-03.txt) [Wikipedia](https://en.wikipedia.org/wiki/Rc4) +* ChaCha20 and Poly1305 - [RFC8439](https://datatracker.ietf.org/doc/html/rfc8439) ## Block Ciphers * Block Cipher Information - [Wikipedia](https://en.wikipedia.org/wiki/Block_cipher) * AES - [NIST Publication](https://csrc.nist.gov/publications/fips/fips197/fips-197.pdf) [Wikipedia](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) -* AES-GCM - [NIST Specification](https://csrc.nist.rip/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf) +* Block Cipher Modes (ECB, CBC, CFB, OFB, CTR) - [NIST SP 800-38A](https://csrc.nist.gov/pubs/sp/800/38/a/final) +* AES-CMAC - [NIST SP 800-38B](https://csrc.nist.gov/pubs/sp/800/38/b/upd1/final) +* AES-CCM - [NIST SP 800-38C](https://csrc.nist.gov/pubs/sp/800/38/c/upd1/final) +* AES-GCM - [NIST SP 800-38D](https://csrc.nist.gov/pubs/sp/800/38/d/final) +* AES-SIV - [RFC5297](https://datatracker.ietf.org/doc/html/rfc5297) +* AES-GCM-SIV - [RFC8452](https://datatracker.ietf.org/doc/html/rfc8452) +* AES Key Wrap - [RFC3394](https://datatracker.ietf.org/doc/html/rfc3394), with padding - [RFC5649](https://datatracker.ietf.org/doc/html/rfc5649) * AES-NI - [Intel Software Network](https://software.intel.com/en-us/articles/intel-advanced-encryption-standard-instructions-aes-ni/) * DES/3DES - [NIST Publication](https://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf) [Wikipedia](https://en.wikipedia.org/wiki/Data_Encryption_Standard) ## Hashing Functions -* SHA - [NIST FIPS180-1 Publication](https://www.itl.nist.gov/fipspubs/fip180-1.htm">https://www.itl.nist.gov/fipspubs/fip180-1.htm) [NIST FIPS180-2 Publication](https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf) [Wikipedia](https://en.wikipedia.org/wiki/SHA_hash_functions) +* SHA-1 and SHA-2 - [NIST FIPS 180-4](https://csrc.nist.gov/pubs/fips/180-4/upd1/final) [Wikipedia](https://en.wikipedia.org/wiki/SHA_hash_functions) +* SHA-3 and SHAKE - [NIST FIPS 202](https://csrc.nist.gov/pubs/fips/202/final) * MD4 - [RFC1320](https://tools.ietf.org/html/rfc1320) * MD5 - [RFC1321](https://tools.ietf.org/html/rfc1321) * RIPEMD-160 - [Specification document](https://homes.esat.kuleuven.be/~bosselae/ripemd160.html) +* HKDF - [RFC5869](https://datatracker.ietf.org/doc/html/rfc5869) ## Public Key Cryptography * Diffie-Hellman - [Wikipedia](https://en.wikipedia.org/wiki/Diffie-Hellman_key_exchange) * RSA - [MIT Paper](https://people.csail.mit.edu/rivest/Rsapaper.pdf) [Wikipedia](https://en.wikipedia.org/wiki/RSA) -* DSA/DSS - [NIST FIPS186-3](https://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf) -* ECDSA - [Specification Document](https://www.cs.miami.edu/home/burt/learning/Csc609.142/ecdsa-cert.pdf) -* X.509 - [RFC3279](https://www.ietf.org/rfc/rfc3279.txt) +* RSA (PKCS#1 v2.2) - [RFC8017](https://datatracker.ietf.org/doc/html/rfc8017) +* Digital Signature Standard (DSA, ECDSA, EdDSA) - [NIST FIPS 186-5](https://csrc.nist.gov/pubs/fips/186-5/final). FIPS 186-5 supersedes FIPS 186-3 and 186-4 and no longer approves DSA for signature generation. +* ECDSA - [NIST FIPS 186-5](https://csrc.nist.gov/pubs/fips/186-5/final) [SEC 1](https://www.secg.org/sec1-v2.pdf), deterministic ECDSA - [RFC6979](https://datatracker.ietf.org/doc/html/rfc6979) +* EdDSA (Ed25519, Ed448) - [RFC8032](https://datatracker.ietf.org/doc/html/rfc8032) +* X25519 and X448 - [RFC7748](https://datatracker.ietf.org/doc/html/rfc7748) +* X.509 - [RFC5280](https://datatracker.ietf.org/doc/html/rfc5280), algorithm identifiers - [RFC3279](https://www.ietf.org/rfc/rfc3279.txt) * ASN.1 - [Specification Document](https://luca.ntop.org/Teaching/Appunti/asn1.html) [Wikipedia](https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One) * PSK - [RFC4279](https://tools.ietf.org/html/rfc4279) +* HPKE - [RFC9180](https://datatracker.ietf.org/doc/html/rfc9180) + +## Post-Quantum Cryptography + +* ML-KEM - [NIST FIPS 203](https://csrc.nist.gov/pubs/fips/203/final) +* ML-DSA - [NIST FIPS 204](https://csrc.nist.gov/pubs/fips/204/final) +* SLH-DSA - [NIST FIPS 205](https://csrc.nist.gov/pubs/fips/205/final) +* LMS/HSS - [RFC8554](https://datatracker.ietf.org/doc/html/rfc8554) +* XMSS - [RFC8391](https://datatracker.ietf.org/doc/html/rfc8391) +* Stateful Hash-Based Signatures (LMS, XMSS) - [NIST SP 800-208](https://csrc.nist.gov/pubs/sp/800/208/final) ## Other -* PKCS#5, PBKDF1, PBKDF2 - [RFC2898](https://tools.ietf.org/html/rfc2898) -* PKCS#8 - [RFC5208](https://tools.ietf.org/html/rfc5208) -* PKCS#12 - [Wikipedia](https://en.wikipedia.org/wiki/PKCS_12) +* PKCS#5, PBKDF1, PBKDF2 - [RFC8018](https://datatracker.ietf.org/doc/html/rfc8018) +* PKCS#7 / CMS - [RFC5652](https://datatracker.ietf.org/doc/html/rfc5652) +* PKCS#8 - [RFC5958](https://datatracker.ietf.org/doc/html/rfc5958) +* PKCS#12 - [RFC7292](https://datatracker.ietf.org/doc/html/rfc7292) [Wikipedia](https://en.wikipedia.org/wiki/PKCS_12) +* OCSP - [RFC6960](https://datatracker.ietf.org/doc/html/rfc6960) +* Time-Stamp Protocol (TSP) - [RFC3161](https://datatracker.ietf.org/doc/html/rfc3161) +* Argon2 - [RFC9106](https://datatracker.ietf.org/doc/html/rfc9106) +* Hash DRBG - [NIST SP 800-90A Rev. 1](https://csrc.nist.gov/pubs/sp/800/90/a/r1/final) diff --git a/wolfSSL/src/appendix06.md b/wolfSSL/src/appendix06.md index 463e9868..8b8cb26f 100644 --- a/wolfSSL/src/appendix06.md +++ b/wolfSSL/src/appendix06.md @@ -2,23 +2,34 @@ ## wolfSSL Error Codes -wolfSSL (formerly CyaSSL) error codes can be found in `wolfssl/ssl.h`. For detailed descriptions of the following errors, see the OpenSSL man page for `SSL_get_error` (`man SSL_get_error`). +wolfSSL (formerly CyaSSL) error codes can be found in `wolfssl/ssl.h`. These are the values returned by [`wolfSSL_get_error()`](group__Debug.md#function-wolfssl_get_error), and they match the OpenSSL values of the same name. For detailed descriptions of the following errors, see the OpenSSL man page for `SSL_get_error` (`man SSL_get_error`). The `SSL_ERROR_*` names are aliases for the `WOLFSSL_ERROR_*` names (they are not defined when `NO_OLD_SSL_NAMES` is set). | Error Code Enum | Error Code | Error Description | | --------------- | ---------- | ----------------- | -| `SSL_ERROR_WANT_READ` | 2 | | -| `SSL_ERROR_WANT_WRITE` | 3 | | -| `SSL_ERROR_WANT_CONNECT` | 7 | | -| `SSL_ERROR_WANT_ACCEPT` | 8 | | -| `SSL_ERROR_SYSCALL` | 5 | | -| `SSL_ERROR_WANT_X509_LOOKUP` | 83 | | -| `SSL_ERROR_ZERO_RETURN` | 6 | | -| `SSL_ERROR_SSL` | 85 | | +| `WOLFSSL_ERROR_NONE` (`SSL_ERROR_NONE`) | 0 | No error | +| `WOLFSSL_ERROR_SSL` (`SSL_ERROR_SSL`) | 1 | Defined for OpenSSL compatibility; not currently returned by wolfSSL | +| `WOLFSSL_ERROR_WANT_READ` (`SSL_ERROR_WANT_READ`) | 2 | Operation did not complete; call this API again | +| `WOLFSSL_ERROR_WANT_WRITE` (`SSL_ERROR_WANT_WRITE`) | 3 | Operation did not complete; call this API again | +| `WOLFSSL_ERROR_WANT_X509_LOOKUP` (`SSL_ERROR_WANT_X509_LOOKUP`) | 4 | Operation did not complete; callback needs this API to be called again | +| `WOLFSSL_ERROR_SYSCALL` (`SSL_ERROR_SYSCALL`) | 5 | Some sort of system I/O error happened | +| `WOLFSSL_ERROR_ZERO_RETURN` (`SSL_ERROR_ZERO_RETURN`) | 6 | The connection has been closed with a closure alert | +| `WOLFSSL_ERROR_WANT_CONNECT` (`SSL_ERROR_WANT_CONNECT`) | 7 | Underlying protocol connection not started yet, call this API again | +| `WOLFSSL_ERROR_WANT_ACCEPT` (`SSL_ERROR_WANT_ACCEPT`) | 8 | Underlying protocol connection not started yet, call this API again | -Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` +`wolfSSL_get_error()` reports the internal codes `WANT_READ`, `WANT_WRITE` and `ZERO_RETURN` as `SSL_ERROR_WANT_READ`, `SSL_ERROR_WANT_WRITE` and `SSL_ERROR_ZERO_RETURN`. In `OPENSSL_EXTRA` builds it also reports `MATCH_SUITE_ERROR` and `SOCKET_PEER_CLOSED_E` as `SSL_ERROR_SYSCALL` (5), and with `WOLFSSL_ASYNC_CRYPT` it reports `MP_WOULDBLOCK` as `WC_PENDING_E`. For any other failure it returns one of the negative wolfSSL or wolfCrypt error codes listed below. [`wolfSSL_ERR_error_string()`](group__Debug.md#function-wolfssl_err_error_string) returns a text description for any wolfSSL or wolfCrypt error code. + +Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h`. The native TLS error codes use the range -301 (`WOLFSSL_FIRST_E`) to -525 (`WOLFSSL_LAST_E`). The header also defines `WOLFSSL_FATAL_ERROR` (-1) and negative counterparts (-2 to -8) of the `WOLFSSL_ERROR_*` values. | Error Code Enum | Error Code | Error Description | | --------------- | ---------- | ----------------- | +| `WOLFSSL_FATAL_ERROR` | -1 | Generic fatal error. Most APIs (for example `wolfSSL_connect()` and `wolfSSL_read()`) return this on failure; call `wolfSSL_get_error()` for the reason | +| `WOLFSSL_ERROR_WANT_READ_E` | -2 | Negative counterpart of `WOLFSSL_ERROR_WANT_READ` | +| `WOLFSSL_ERROR_WANT_WRITE_E` | -3 | Negative counterpart of `WOLFSSL_ERROR_WANT_WRITE` | +| `WOLFSSL_ERROR_WANT_X509_LOOKUP_E` | -4 | Negative counterpart of `WOLFSSL_ERROR_WANT_X509_LOOKUP` | +| `WOLFSSL_ERROR_SYSCALL_E` | -5 | Negative counterpart of `WOLFSSL_ERROR_SYSCALL` | +| `WOLFSSL_ERROR_ZERO_RETURN_E` | -6 | Negative counterpart of `WOLFSSL_ERROR_ZERO_RETURN` | +| `WOLFSSL_ERROR_WANT_CONNECT_E` | -7 | Negative counterpart of `WOLFSSL_ERROR_WANT_CONNECT` | +| `WOLFSSL_ERROR_WANT_ACCEPT_E` | -8 | Negative counterpart of `WOLFSSL_ERROR_WANT_ACCEPT` | | `INPUT_CASE_ERROR` | -301 | process input state error | | `PREFIX_ERROR` | -302 | bad index to key rounds | | `MEMORY_ERROR` | -303 | out of memory | @@ -31,7 +42,7 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `INCOMPLETE_DATA` | -310 | don't have enough data to complete task | | `UNKNOWN_RECORD_TYPE` | -311 | unknown type in record hdr | | `DECRYPT_ERROR` | -312 | error during decryption | -| `FATAL_ERROR` | -313 | revcd alert fatal error | +| `FATAL_ERROR` | -313 | recvd alert fatal error | | `ENCRYPT_ERROR` | -314 | error during encryption | | `FREAD_ERROR` | -315 | fread problem | | `NO_PEER_KEY` | -316 | need peer's key | @@ -43,6 +54,7 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `DOMAIN_NAME_MISMATCH` | -322 | peer subject name mismatch | | `WANT_READ` | -323 | want read, call again | | `NOT_READY_ERROR` | -324 | handshake layer not ready | +| `IPADDR_MISMATCH` | -325 | peer ip address mismatch | | `VERSION_ERROR` | -326 | record layer version error | | `WANT_WRITE` | -327 | want write, call again | | `BUFFER_ERROR` | -328 | malformed buffer input | @@ -51,12 +63,14 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `CLIENT_ID_ERROR` | -331 | psk client identity error | | `SERVER_HINT_ERROR` | -332 | psk server hint error | | `PSK_KEY_ERROR` | -333 | psk key error | +| `DUPE_ENTRY_E` | -334 | duplicate entry error | +| `PSK_MISSING_ERROR` | -335 | psk missing | | `GETTIME_ERROR` | -337 | gettimeofday failed ??? | | `GETITIMER_ERROR` | -338 | getitimer failed ??? | | `SIGACT_ERROR` | -339 | sigaction failed ??? | | `SETITIMER_ERROR` | -340 | setitimer failed ??? | | `LENGTH_ERROR` | -341 | record layer length error | -| `PEER_KEY_ERROR` | -342 | cant decode peer key | +| `PEER_KEY_ERROR` | -342 | can't decode peer key | | `ZERO_RETURN` | -343 | peer sent close notify | | `SIDE_ERROR` | -344 | wrong client/server type | | `NO_PEER_CERT` | -345 | peer didn't send key | @@ -66,7 +80,7 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `ECC_MAKEKEY_ERROR` | -353 | Bad Make ECC Key | | `ECC_EXPORT_ERROR` | -354 | Bad ECC Export Key | | `ECC_SHARED_ERROR` | -355 | Bad ECC Shared Secret | -| `NOT_CA_ERROR` | -357 | Not CA cert error | +| `NOT_CA_ERROR` | -357 | Not a CA cert error | | `BAD_CERT_MANAGER_ERROR` | -359 | Bad Cert Manager | | `OCSP_CERT_REVOKED` | -360 | OCSP Certificate revoked | | `CRL_CERT_REVOKED` | -361 | CRL Certificate revoked | @@ -74,20 +88,21 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `MONITOR_SETUP_E` | -363 | CRL Monitor setup error | | `THREAD_CREATE_E` | -364 | Thread Create Error | | `OCSP_NEED_URL` | -365 | OCSP need an URL for lookup | -| `OCSP_CERT_UNKNOWN` | -366 | OCSP responder doesn’t know | +| `OCSP_CERT_UNKNOWN` | -366 | OCSP responder doesn't know | | `OCSP_LOOKUP_FAIL` | -367 | OCSP lookup not successful | | `MAX_CHAIN_ERROR` | -368 | max chain depth exceeded | | `COOKIE_ERROR` | -369 | dtls cookie error | | `SEQUENCE_ERROR` | -370 | dtls sequence error | | `SUITES_ERROR` | -371 | suites pointer error | +| `MAX_CERT_EXTENSIONS_ERR` | -372 | max cert extension exceeded | | `OUT_OF_ORDER_E` | -373 | out of order message | | `BAD_KEA_TYPE_E` | -374 | bad KEA type found | | `SANITY_CIPHER_E` | -375 | sanity check on cipher error | -| `RECV_OVERFLOW_E` | -376 | RXCB returned more than rqed | +| `RECV_OVERFLOW_E` | -376 | RXCB returned more than read | | `GEN_COOKIE_E` | -377 | Generate Cookie Error | | `NO_PEER_VERIFY` | -378 | Need peer cert verify Error | | `FWRITE_ERROR` | -379 | fwrite problem | -| `CACHE_MATCH_ERROR` | -380 | cache hrd match error | +| `CACHE_MATCH_ERROR` | -380 | Cache hdr match error | | `UNKNOWN_SNI_HOST_NAME_E` | -381 | Unrecognized host name Error | | `UNKNOWN_MAX_FRAG_LEN_E` | -382 | Unrecognized max frag len Error | | `KEYUSE_SIGNATURE_E` | -383 | KeyUse digSignature error | @@ -101,10 +116,10 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `SESSION_SECRET_CB_E` | -392 | Session secret CB fcn failure | | `NO_CHANGE_CIPHER_E` | -393 | Finished before change cipher | | `SANITY_MSG_E` | -394 | Sanity check on msg order error | -| `DUPLICATE_MST_E` | -395 | Duplicate message error | +| `DUPLICATE_MSG_E` | -395 | Duplicate message error | | `SNI_UNSUPPORTED` | -396 | SSL 3.0 does not support SNI | | `SOCKET_PEER_CLOSED_E` | -397 | Underlying transport closed | -| `BAD_TICKET_KEY_CB_SZ` | -398 | Bad session ticket key cb size | +| `BAD_TICKET_KEY_CB_SZ` | -398 | Bad session ticket key cb size | | `BAD_TICKET_MSG_SZ` | -399 | Bad session ticket msg size | | `BAD_TICKET_ENCRYPT` | -400 | Bad user ticket encrypt | | `DH_KEY_SIZE_E` | -401 | DH key too small | @@ -114,18 +129,18 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `UNKNOWN_ALPN_PROTOCOL_NAME_E` | -405 | Unrecognized protocol name error | | `BAD_CERTIFICATE_STATUS_ERROR` | -406 | Bad certificate status message | | `OCSP_INVALID_STATUS` | -407 | Invalid OCSP status | -| `OCSP_WANT_READ` | -408 | OCSP callback response | +| `OCSP_WANT_READ` | -408 | OCSP I/O callback returned `WOLFSSL_CBIO_ERR_WANT_READ`, call again | | `RSA_KEY_SIZE_E` | -409 | RSA key too small | | `ECC_KEY_SIZE_E` | -410 | ECC key too small | | `DTLS_EXPORT_VER_E` | -411 | Export version error | | `INPUT_SIZE_E` | -412 | Input size too big error | | `CTX_INIT_MUTEX_E` | -413 | Initialize ctx mutex error | -| `EXT_MASTER_SECRET_NEEDED_E` | -414 | Need EMS enabled to resume | +| `EXT_MASTER_SECRET_NEEDED_E` | -414 | EMS required but not negotiated | | `DTLS_POOL_SZ_E` | -415 | Exceeded DTLS pool size | | `DECODE_E` | -416 | Decode handshake message error | | `HTTP_TIMEOUT` | -417 | HTTP timeout for OCSP or CRL req | -| `WRITE_DUP_READ_E` | -418 | Write dup write side can’t read | -| `WRITE_DUP_WRITE_E` | -419 | Write dup read side can’t write | +| `WRITE_DUP_READ_E` | -418 | Write dup write side can't read | +| `WRITE_DUP_WRITE_E` | -419 | Write dup read side can't write | | `INVALID_CERT_CTX_E` | -420 | TLS cert ctx not matching | | `BAD_KEY_SHARE_DATA` | -421 | Key share data invalid | | `MISSING_HANDSHAKE_DATA` | -422 | Handshake message missing data | @@ -141,32 +156,109 @@ Additional wolfSSL error codes can be found in `wolfssl/error-ssl.h` | `DH_PARAMS_NOT_FFDHE_E` | -432 | DH params from server not FFDHE | | `TCA_INVALID_ID_TYPE` | -433 | TLSX TCA ID type invalid | | `TCA_ABSENT_ERROR` | -434 | TLSX TCA ID no response | -| `TOO_MUCH_EARLY_DATA` | -442 | Too much early data, the AEAD key usage limit was hit before the handshake finished | -| `OCSP_NO_URL` | -522 | The certificate does not advertise an OCSP responder URL | +| `TSIP_MAC_DIGSZ_E` | -435 | Invalid MAC size for TSIP | +| `CLIENT_CERT_CB_ERROR` | -436 | Client cert callback error | +| `SSL_SHUTDOWN_ALREADY_DONE_E` | -437 | Shutdown called redundantly | +| `TLS13_SECRET_CB_E` | -438 | TLS1.3 secret Cb fcn failure | +| `DTLS_SIZE_ERROR` | -439 | Trying to send too much data | +| `NO_CERT_ERROR` | -440 | TLS1.3 - no cert set error | +| `APP_DATA_READY` | -441 | Application data ready for read | +| `TOO_MUCH_EARLY_DATA` | -442 | Too much early data: more than max_early_data_size was sent or received, or the AEAD key usage limit was reached while sending early data | +| `SOCKET_FILTERED_E` | -443 | Session stopped by network filter | +| `HTTP_RECV_ERR` | -444 | HTTP Receive error | +| `HTTP_HEADER_ERR` | -445 | HTTP Header error | +| `HTTP_PROTO_ERR` | -446 | HTTP Protocol error | +| `HTTP_STATUS_ERR` | -447 | HTTP Status error | +| `HTTP_VERSION_ERR` | -448 | HTTP Version error | +| `HTTP_APPSTR_ERR` | -449 | HTTP Application string error | +| `UNSUPPORTED_PROTO_VERSION` | -450 | bad/unsupported protocol version | +| `FALCON_KEY_SIZE_E` | -451 | Wrong key size for Falcon | +| `QUIC_TP_MISSING_E` | -452 | QUIC transport parameter missing | +| `MLDSA_KEY_SIZE_E` | -453 | Wrong key size for ML-DSA (legacy alias `DILITHIUM_KEY_SIZE_E`) | +| `DTLS_CID_ERROR` | -454 | Wrong or missing CID | +| `DTLS_TOO_MANY_FRAGMENTS_E` | -455 | Received too many fragments | +| `DTLS_PARTIAL_RECORD_READ` | -455 | Received a partial record in a datagram (shares the value -455 with `DTLS_TOO_MANY_FRAGMENTS_E`) | +| `QUIC_WRONG_ENC_LEVEL` | -456 | QUIC data received on wrong encryption level | +| `DUPLICATE_TLS_EXT_E` | -457 | Duplicate TLS extension in msg | +| `WOLFSSL_ALPN_NOT_FOUND` | -458 | TLS extension not found | +| `WOLFSSL_BAD_CERTTYPE` | -459 | Certificate type not supported | +| `WOLFSSL_BAD_STAT` | -460 | not used | +| `WOLFSSL_BAD_PATH` | -461 | No certificates found at designated path | +| `WOLFSSL_BAD_FILETYPE` | -462 | Data format not supported | +| `WOLFSSL_BAD_FILE` | -463 | Input/output error on file | +| `WOLFSSL_NOT_IMPLEMENTED` | -464 | Function not implemented | +| `WOLFSSL_UNKNOWN` | -465 | Unknown algorithm (EVP) | -Negotiation Parameter Errors +### Negotiation Parameter Errors | Error Code Enum | Error Code | Error Description | | --------------- | ---------- | ----------------- | | `UNSUPPORTED_SUITE` | -500 | Unsupported cipher suite | -| `MATCH_SUITE_ERROR` | -501 | Can’t match cipher suite | +| `MATCH_SUITE_ERROR` | -501 | Can't match cipher suite | | `COMPRESSION_ERROR` | -502 | Compression mismatch | | `KEY_SHARE_ERROR` | -503 | Key share mismatch | -| `POST_HAND_AUTH_ERROR` | -504 | Client won’t do post-hand auth | +| `POST_HAND_AUTH_ERROR` | -504 | Client won't do post-hand auth | | `HRR_COOKIE_ERROR` | -505 | HRR msg cookie mismatch | +| `UNSUPPORTED_CERTIFICATE` | -506 | unsupported certificate type | + +### PEM, EVP and Other TLS Errors + +| Error Code Enum | Error Code | Error Description | +| --------------- | ---------- | ----------------- | +| `WOLFSSL_PEM_R_NO_START_LINE_E` | -507 | No more matching objects found (PEM) | +| `WOLFSSL_PEM_R_PROBLEMS_GETTING_PASSWORD_E` | -508 | Error getting password (PEM) | +| `WOLFSSL_PEM_R_BAD_PASSWORD_READ_E` | -509 | Bad password (PEM) | +| `WOLFSSL_PEM_R_BAD_DECRYPT_E` | -510 | Decryption failed (PEM) | +| `WOLFSSL_ASN1_R_HEADER_TOO_LONG_E` | -511 | ASN header too long (compat) | +| `WOLFSSL_EVP_R_BAD_DECRYPT_E` | -512 | Decryption failed (EVP) | +| `WOLFSSL_EVP_R_BN_DECODE_ERROR` | -513 | Bignum decode error (EVP) | +| `WOLFSSL_EVP_R_DECODE_ERROR` | -514 | Decode error (EVP) | +| `WOLFSSL_EVP_R_PRIVATE_KEY_DECODE_ERROR` | -515 | Private key decode error (EVP) | +| `CRYPTO_POLICY_FORBIDDEN` | -516 | operation forbidden by system crypto-policy | +| `SESSION_TICKET_NONCE_OVERFLOW` | -517 | Session ticket nonce overflow | +| `EMPTY_RECORD_LIMIT_E` | -518 | Too many empty records received | +| `ECH_REQUIRED_E` | -519 | ECH offered but rejected by server | +| `SEQUENCE_NUMBER_E` | -520 | Record sequence number would wrap | +| `RPK_UNTRUSTED_E` | -521 | RFC 7250 Raw Public Key not trusted out of band | +| `OCSP_NO_URL` | -522 | Cert advertises no OCSP responder and no override URL is set | +| `CHAIN_VERIFY_WANT_E` | -523 | Chain verify callback has not reached a verdict yet | +| `CHAIN_VERIFY_CB_E` | -524 | Chain verify callback rejected the peer's certificates | +| `CHAIN_VERIFY_UNSUPPORTED_E` | -525 | Chain verify callback used with DTLS, RPK or OCSP stapling | + +### I/O Callback Return Codes + +The I/O callbacks (the built-in socket callbacks, or your own callbacks registered with `wolfSSL_CTX_SetIORecv()` and `wolfSSL_CTX_SetIOSend()`) return the number of bytes received or sent, or one of the following codes (`enum IOerrors` in `wolfssl/error-ssl.h`). wolfSSL converts them into the error codes above; for example, `WOLFSSL_CBIO_ERR_WANT_READ` returned by the receive callback becomes `WANT_READ`. + +| Error Code Enum | Error Code | Error Description | +| --------------- | ---------- | ----------------- | +| `WOLFSSL_CBIO_ERR_GENERAL` | -1 | general unexpected err | +| `WOLFSSL_CBIO_ERR_WANT_READ` | -2 | need to call read again | +| `WOLFSSL_CBIO_ERR_WANT_WRITE` | -2 | need to call write again | +| `WOLFSSL_CBIO_ERR_CONN_RST` | -3 | connection reset | +| `WOLFSSL_CBIO_ERR_ISR` | -4 | interrupt | +| `WOLFSSL_CBIO_ERR_CONN_CLOSE` | -5 | connection closed or epipe | +| `WOLFSSL_CBIO_ERR_TIMEOUT` | -6 | socket timeout | ## wolfCrypt Error Codes -wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. +wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error-crypt.h`. They use two ranges: -97 (`WC_SPAN1_FIRST_E`) to -300 (`WC_SPAN1_MIN_CODE_E`), and -1000 (`WC_SPAN2_FIRST_E`) to -1999 (`WC_SPAN2_MIN_CODE_E`). `MAX_CODE_E` (-96) and `MIN_CODE_E` (-1999) mark the outer limits of the wolfCrypt codes, and `WC_LAST_E` (-1042) is the last code currently allocated. `WC_FAILURE` (-1) is a generic failure code outside these ranges. [`wc_GetErrorString()`](group__Error.md#function-wc_geterrorstring) returns a text description for a wolfCrypt error code. | Error Code Enum | Error Code | Error Description | | --------------- | ---------- | ----------------- | +| `WC_FAILURE` | -1 | wolfCrypt generic failure | +| `MP_MEM` | -97 | MP dynamic memory allocation failed | +| `MP_VAL` | -98 | MP value passed is not able to be used | +| `MP_WOULDBLOCK` | -99 | MP non-blocking operation is returning after partial completion | +| `MP_NOT_INF` | -100 | MP point not at infinity | | `OPEN_RAN_E` | -101 | opening random device error | | `READ_RAN_E` | -102 | reading random device error | | `WINCRYPT_E` | -103 | windows crypt init error | | `CRYPTGEN_E` | -104 | windows crypt generation error | | `RAN_BLOCK_E` | -105 | reading random device would block | | `BAD_MUTEX_E` | -106 | Bad mutex operation | +| `WC_TIMEOUT_E` | -107 | timeout error | +| `WC_PENDING_E` | -108 | wolfCrypt operation pending (would block) | +| `WC_NO_PENDING_E` | -109 | no asynchronous operation pending | | `MP_INIT_E` | -110 | mp_init error state | | `MP_READ_E` | -111 | mp_read error state | | `MP_EXPTMOD_E` | -112 | mp_exptmod error state | @@ -179,7 +271,14 @@ wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. | `MP_INVMOD_E` | -119 | mp_invmod error state, can't inv mod | | `MP_CMP_E` | -120 | mp_cmp error state | | `MP_ZERO_E` | -121 | got a mp zero result, not expected | +| `AES_EAX_AUTH_E` | -122 | AES-EAX Authentication check failure | +| `KEY_EXHAUSTED_E` | -123 | No longer usable for operation | +| `ML_KEM_KAT_FIPS_E` | -124 | ML-KEM KAT failure | | `MEMORY_E` | -125 | out of memory error | +| `VAR_STATE_CHANGE_E` | -126 | var state modified by different thread | +| `FIPS_DEGRADED_E` | -127 | FIPS Module in degraded mode | +| `FIPS_CODE_SZ_E` | -128 | Module CODE too big | +| `FIPS_DATA_SZ_E` | -129 | Module DATA too big | | `RSA_WRONG_TYPE_E` | -130 | RSA wrong block type for RSA function | | `RSA_BUFFER_E` | -131 | RSA buffer error, output too small or input too large | | `BUFFER_E` | -132 | output buffer too small or input too large | @@ -209,7 +308,17 @@ wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. | `ASN_SIG_HASH_E` | -156 | ASN sig error, unsupported hash type | | `ASN_SIG_KEY_E` | -157 | ASN sig error, unsupported key type | | `ASN_DH_KEY_E` | -158 | ASN key init error, invalid input | +| `KDF_SRTP_KAT_FIPS_E` | -159 | SRTP-KDF Known Answer Test Failure | | `ASN_CRIT_EXT_E` | -160 | ASN unsupported critical extension | +| `ASN_ALT_NAME_E` | -161 | ASN alternate name error | +| `ASN_NO_PEM_HEADER` | -162 | ASN no PEM header found | +| `ED25519_KAT_FIPS_E` | -163 | Ed25519 Known answer test failure | +| `ED448_KAT_FIPS_E` | -164 | Ed448 Known answer test failure | +| `PBKDF2_KAT_FIPS_E` | -165 | PBKDF2 Known answer test failure | +| `WC_KEY_MISMATCH_E` | -166 | Error for private/public key mismatch | +| `ML_DSA_KAT_FIPS_E` | -167 | ML-DSA KAT failure | +| `LMS_KAT_FIPS_E` | -168 | LMS KAT failure | +| `XMSS_KAT_FIPS_E` | -169 | XMSS KAT failure | | `ECC_BAD_ARG_E` | -170 | ECC input argument of wrong type | | `ASN_ECC_KEY_E` | -171 | ASN ECC bad input | | `ECC_CURVE_OID_E` | -172 | Unsupported ECC OID curve type | @@ -218,19 +327,21 @@ wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. | `UNICODE_SIZE_E` | -175 | Unicode password too big | | `NO_PASSWORD` | -176 | no password provided by user | | `ALT_NAME_E` | -177 | alt name size problem, too big | +| `BAD_OCSP_RESPONDER` | -178 | Invalid OCSP Responder, missing specific key usage extensions | +| `CRL_CERT_DATE_ERR` | -179 | CRL date error | | `AES_GCM_AUTH_E` | -180 | AES-GCM Authentication check failure | | `AES_CCM_AUTH_E` | -181 | AES-CCM Authentication check failure | -| `CAVIUM_INIT_E` | -182 | Cavium Init type error | +| `ASYNC_INIT_E` | -182 | Async Init type error | | `COMPRESS_INIT_E` | -183 | Compress init error | | `COMPRESS_E` | -184 | Compress error | | `DECOMPRESS_INIT_E` | -185 | DeCompress init error | | `DECOMPRESS_E` | -186 | DeCompress error | | `BAD_ALIGN_E` | -187 | Bad alignment for operation, no alloc | | `ASN_NO_SIGNER_E` | -188 | ASN sig error, no CA signer to verify certificate | -| `ASN_CRL_CONFIRM_E` | -189 | ASN CRL no signer to confirm failure | +| `ASN_CRL_CONFIRM_E` | -189 | ASN CRL signature confirm failure | | `ASN_CRL_NO_SIGNER_E` | -190 | ASN CRL no signer to confirm failure | | `ASN_OCSP_CONFIRM_E` | -191 | ASN OCSP signature confirm failure | -| `BAD_ENC_STATE_E` | -192 | Bad ecc enc state operation | +| `BAD_STATE_E` | -192 | Bad state operation | | `BAD_PADDING_E` | -193 | Bad padding, msg not correct length | | `REQ_ATTRIBUTE_E` | -194 | Setting cert request attributes error | | `PKCS7_OID_E` | -195 | PKCS#7, mismatched OID error | @@ -255,11 +366,12 @@ wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. | `IS_POINT_E` | -214 | ECC is point on curve failed | | `ECC_INF_E` | -215 | ECC point infinity error | | `ECC_PRIV_KEY_E` | -216 | ECC private key not valid error | -| `SRP_CALL_ORDER_E` | -217 | SRP function called in the wrong order | -| `SRP_VERIFY_E` | -218 | SRP proof verification failed | -| `SRP_BAD_KEY_E` | -219 | SRP bad ephemeral values | -| `ASN_NO_SKID` | -220 | ASN no Subject Key Identifier found | -| `ASN_NO_AKID` | -221 | ASN no Authority Key Identifier found | +| `ECC_OUT_OF_RANGE_E` | -217 | ECC key component out of range | +| `SRP_CALL_ORDER_E` | -218 | SRP function called in the wrong order | +| `SRP_VERIFY_E` | -219 | SRP proof verification failed | +| `SRP_BAD_KEY_E` | -220 | SRP bad ephemeral values | +| `ASN_NO_SKID` | -221 | ASN no Subject Key Identifier found | +| `ASN_NO_AKID` | -222 | ASN no Authority Key Identifier found | | `ASN_NO_KEYUSAGE` | -223 | ASN no Key Usage found | | `SKID_E` | -224 | Setting Subject Key Identifier error | | `AKID_E` | -225 | Setting Authority Key Identifier error | @@ -267,9 +379,10 @@ wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. | `CERTPOLICIES_E` | -227 | Setting Certificate Policies error | | `WC_INIT_E` | -228 | wolfCrypt failed to initialize | | `SIG_VERIFY_E` | -229 | wolfCrypt signature verify error | -| `BAD_PKCS7_SIGNEEDS_CHECKCOND_E` | -230 | Bad condition variable operation | +| `BAD_COND_E` | -230 | Bad condition variable operation | | `SIG_TYPE_E` | -231 | Signature Type not enabled/available | | `HASH_TYPE_E` | -232 | Hash Type not enabled/available | +| `FIPS_INVALID_VER_E` | -233 | Invalid FIPS Version defined | | `WC_KEY_SIZE_E` | -234 | Key size error, either too small or large | | `ASN_COUNTRY_SIZE_E` | -235 | ASN Cert Gen, invalid country code size | | `MISSING_RNG_E` | -236 | RNG required but not provided | @@ -299,7 +412,7 @@ wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. | `AES_GCM_OVERFLOW_E` | -260 | AES-GCM invocation counter overflow | | `AES_CCM_OVERFLOW_E` | -261 | AES-CCM invocation counter overflow | | `RSA_KEY_PAIR_E` | -262 | RSA Key Pair-Wise consistency check fail | -| `DH_CHECK_PRIVE_E` | -263 | DH check private key error | +| `DH_CHECK_PRIV_E` | -263 | DH Check Priv Key error | | `WC_AFALG_SOCK_E` | -264 | AF_ALG socket error | | `WC_DEVCRYPTO_E` | -265 | /dev/crypto error | | `ZLIB_INIT_ERROR` | -266 | Zlib init error | @@ -309,13 +422,81 @@ wolfCrypt error codes can be found in `wolfssl/wolfcrypt/error.h`. | `WC_PKCS7_WANT_READ_E` | -270 | PKCS7 stream operation wants more input | | `CRYPTOCB_UNAVAILABLE` | -271 | Crypto callback unavailable | | `PKCS7_SIGNEEDS_CHECK` | -272 | Signature needs verified by caller | +| `PSS_SALTLEN_RECOVER_E` | -273 | PSS salt length not recoverable | +| `CHACHA_POLY_OVERFLOW` | -274 | ChaCha20Poly1305 limit overflow | | `ASN_SELF_SIGNED_E` | -275 | ASN self-signed certificate error | +| `SAKKE_VERIFY_FAIL_E` | -276 | SAKKE derivation verification error | +| `MISSING_IV` | -277 | IV was not set | | `MISSING_KEY` | -278 | Key was not set | -| `MIN_CODE_E` | -300 | errors -101 - -299 | +| `BAD_LENGTH_E` | -279 | Value of length parameter is invalid | +| `ECDSA_KAT_FIPS_E` | -280 | ECDSA KAT failure | +| `RSA_PAT_FIPS_E` | -281 | RSA Pairwise failure | +| `KDF_TLS12_KAT_FIPS_E` | -282 | TLS12 KDF KAT failure | +| `KDF_TLS13_KAT_FIPS_E` | -283 | TLS13 KDF KAT failure | +| `KDF_SSH_KAT_FIPS_E` | -284 | SSH KDF KAT failure | +| `DHE_PCT_E` | -285 | DHE Pairwise Consistency Test failure | +| `ECC_PCT_E` | -286 | ECDHE Pairwise Consistency Test failure | +| `FIPS_PRIVATE_KEY_LOCKED_E` | -287 | Cannot export private key | +| `PROTOCOLCB_UNAVAILABLE` | -288 | Protocol callback unavailable | +| `AES_SIV_AUTH_E` | -289 | AES-SIV authentication failed | +| `NO_VALID_DEVID` | -290 | no valid device ID | +| `IO_FAILED_E` | -291 | Input/output failure | +| `SYSLIB_FAILED_E` | -292 | System/library call failed | +| `USE_HW_PSK` | -293 | Callback return to indicate HW has PSK | +| `ENTROPY_RT_E` | -294 | Entropy Repetition Test failed | +| `ENTROPY_APT_E` | -295 | Entropy Adaptive Proportion Test failed | +| `ASN_DEPTH_E` | -296 | Invalid ASN.1 - depth check | +| `ASN_LEN_E` | -297 | ASN.1 length invalid | +| `SM4_GCM_AUTH_E` | -298 | SM4-GCM Authentication check failure | +| `SM4_CCM_AUTH_E` | -299 | SM4-CCM Authentication check failure | + +Error codes in the second range (-1000 to -1999): + +| Error Code Enum | Error Code | Error Description | +| --------------- | ---------- | ----------------- | +| `DEADLOCK_AVERTED_E` | -1000 | Deadlock averted -- retry the call | +| `ASCON_AUTH_E` | -1001 | ASCON Authentication check failure | +| `WC_ACCEL_INHIBIT_E` | -1002 | Crypto acceleration is currently inhibited | +| `BAD_INDEX_E` | -1003 | Bad index | +| `INTERRUPTED_E` | -1004 | Process interrupted | +| `MLKEM_PUB_HASH_E` | -1005 | Encoded public key in decapsulation key does not match stored hash | +| `BUSY_E` | -1006 | Object is busy | | `ALREADY_E` | -1007 | The operation was already done, e.g. registering the same crypto callback device ID twice | +| `SEQ_OVERFLOW_E` | -1008 | Sequence counter would overflow | +| `PUF_INIT_E` | -1009 | PUF initialization failed (reserved) | | `PUF_READ_E` | -1010 | PUF SRAM readout failed the startup health check | +| `PUF_ENROLL_E` | -1011 | PUF enrollment failed | +| `PUF_RECONSTRUCT_E` | -1012 | PUF reconstruction failed | +| `PUF_DERIVE_KEY_E` | -1013 | PUF key derivation failed | +| `PUF_IDENTITY_E` | -1014 | PUF identity retrieval failed | +| `ML_KEM_PCT_E` | -1015 | ML-KEM Pairwise Consistency Test failure | +| `ML_DSA_PCT_E` | -1016 | ML-DSA Pairwise Consistency Test failure | +| `DRBG_SHA512_KAT_FIPS_E` | -1017 | SHA-512 DRBG KAT failure | +| `SLH_DSA_KAT_FIPS_E` | -1018 | SLH-DSA CAST KAT failure | +| `TSP_VERIFY_E` | -1019 | TSP token invalid or response doesn't match request | +| `SLH_DSA_PCT_E` | -1020 | SLH-DSA Pairwise Consistency Test failure | +| `CMAC_KAT_FIPS_E` | -1021 | AES-CMAC KAT failure | +| `SHAKE_KAT_FIPS_E` | -1022 | SHAKE KAT failure | +| `DH_PCT_E` | -1023 | DH Pairwise Consistency Test failure (retired in FIPS v7+) | +| `AES_KW_KAT_FIPS_E` | -1024 | AES Key Wrap KAT failure | +| `FIPS_WRONG_API_E` | -1025 | Requested API is not allowed in FIPS mode | +| `KMAC_MIN_KEYLEN_E` | -1026 | FIPS Mode KMAC Minimum Key Length error | | `FIPS_BAD_VALUE_E` | -1027 | The value given is not allowed by FIPS policy | | `FIPS_UNAPPROVED_E` | -1028 | The operation ran, but the parameters are not FIPS approved | +| `NO_DEFAULT_FOUND_E` | -1029 | No default object registered for request type | +| `NOT_READY_E` | -1030 | Resource not yet ready (retry) | +| `OBJECT_NOT_LOCKED_E` | -1031 | Required lock on object is not held | +| `WRONG_TYPE_OBJECT_E` | -1032 | Object is wrong type for requested operation | +| `NEEDS_RECOVERY_E` | -1033 | Object needs recovery before use | +| `UNEXPECTED_STATE_E` | -1034 | Object has unexpected state | +| `STILL_REFERENCED_E` | -1035 | Object is still referenced (unsafe to deallocate) | +| `OBJECT_ORPHANED_E` | -1036 | Object orphaned (can be adopted) | +| `HWPUF_INIT_E` | -1037 | HWPUF initialization failed | +| `HWPUF_ENROLL_E` | -1038 | HWPUF enrollment failed | +| `HWPUF_START_E` | -1039 | HWPUF start failed | +| `HWPUF_GENERATE_KEY_E` | -1040 | HWPUF generate key failed | +| `HWPUF_GET_KEY_E` | -1041 | HWPUF get key failed | +| `HWPUF_ZEROIZE_E` | -1042 | HWPUF zeroize failed | ## Common Error Codes and their Solution @@ -329,8 +510,8 @@ This error occurs when using a certificate and the signing CA certificate was no ./examples/client/client -g -h www.google.com -p 443 ``` -This fails with error -188 because Google’s CA certificate wasn’t loaded with the “`-A`” command line option. +This fails with error -188 because Google's CA certificate wasn't loaded with the "`-A`" command line option. ### `WANT_READ` (-323) -The `WANT_READ` error happens often when using non-blocking sockets, and isn’t actually an error when using non-blocking sockets, but it is passed up to the caller as an error. When a call to receive data from the I/O callback would block as there isn’t data currently available to receive, the I/O callback returns `WANT_READ`. The caller should wait and try receiving again later. This is usually seen from calls to [`wolfSSL_read()`](group__IO.md#function-wolfssl_read), [`wolfSSL_negotiate()`](group__IO.md#function-wolfssl_negotiate), [`wolfSSL_accept()`](group__IO.md#function-wolfssl_accept), and [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect). The example client and server will indicate the `WANT_READ` incidents when debugging is enabled. +The `WANT_READ` error happens often when using non-blocking sockets, and isn't actually an error when using non-blocking sockets, but it is passed up to the caller as an error. When a call to receive data from the I/O callback would block as there isn't data currently available to receive, the I/O callback returns `WOLFSSL_CBIO_ERR_WANT_READ` (-2). wolfSSL records this internally as `WANT_READ` (-323), the API call returns `WOLFSSL_FATAL_ERROR` (-1), and [`wolfSSL_get_error()`](group__Debug.md#function-wolfssl_get_error) returns `SSL_ERROR_WANT_READ` (2). Applications should compare the value returned by `wolfSSL_get_error()` with `SSL_ERROR_WANT_READ` (not with -323), then wait and try receiving again later. This is usually seen from calls to [`wolfSSL_read()`](group__IO.md#function-wolfssl_read), [`wolfSSL_negotiate()`](group__IO.md#function-wolfssl_negotiate), [`wolfSSL_accept()`](group__IO.md#function-wolfssl_accept), and [`wolfSSL_connect()`](group__IO.md#function-wolfssl_connect). The example client and server will indicate the `WANT_READ` incidents when debugging is enabled. diff --git a/wolfSSL/src/appendix07.md b/wolfSSL/src/appendix07.md index a3f5d6b8..55cdeea5 100644 --- a/wolfSSL/src/appendix07.md +++ b/wolfSSL/src/appendix07.md @@ -2,7 +2,7 @@ ## A. Cipher Suites -### A-1. TLS 1.3 +### A-1 TLS 1.3 | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| @@ -16,21 +16,22 @@ | `TLS_SHA256_SHA256` | `0xC0,0xB4` | Disabled | `--enable-nullcipher` | | `TLS_SHA384_SHA384` | `0xC0,0xB5` | Disabled | `--enable-nullcipher` + `--enable-sha384` | -### A-2. TLS 1.2 ECDHE-ECDSA +### A-2 TLS 1.2 ECDHE-ECDSA | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x2B` | **Enabled** | — | -| `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x2C` | **Enabled** | — | -| `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xA9` | **Enabled** | — | -| `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA` | `0xC0,0x09` | **Enabled** | — | -| `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA` | `0xC0,0x0A` | **Enabled** | — | -| `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x23` | **Enabled** | — | +| `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x2B` | **Enabled** | - | +| `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x2C` | **Enabled** | - | +| `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xA9` | **Enabled** | - | +| `TLS_ECDHE_ECDSA_WITH_CHACHA20_OLD_POLY1305_SHA256` | `0xCC,0x14` | **Enabled** | - (see note in A-4) | +| `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA` | `0xC0,0x09` | **Enabled** | - | +| `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA` | `0xC0,0x0A` | **Enabled** | - | +| `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x23` | **Enabled** | - | | `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384` | `0xC0,0x24` | **Enabled** | `--enable-sha384` | | `TLS_ECDHE_ECDSA_WITH_AES_128_CCM` | `0xC0,0xAC` | Disabled | `--enable-aesccm` | | `TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8` | `0xC0,0xAE` | Disabled | `--enable-aesccm` | | `TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8` | `0xC0,0xAF` | Disabled | `--enable-aesccm` | -| `TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x08` | Disabled | `--enable-des3` | +| `TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x08` | Disabled | `--enable-des3` + `--enable-des3-tls-suites` | | `TLS_ECDHE_ECDSA_WITH_RC4_128_SHA` | `0xC0,0x07` | Disabled | `--enable-arc4` | | `TLS_ECDHE_ECDSA_WITH_NULL_SHA` | `0xC0,0x06` | Disabled | `--enable-nullcipher` | | `TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256` | `0xC0,0x5C` | Disabled | `--enable-aria` | @@ -39,115 +40,127 @@ | `TLS_ECDHE_ECDSA_WITH_SM4_GCM_SM3` | `0xE0,0x51` | Disabled | `--enable-sm4-gcm` + `--enable-sm3` + `--enable-sm2` | | `TLS_ECDHE_ECDSA_WITH_SM4_CCM_SM3` | `0xE0,0x52` | Disabled | `--enable-sm4-ccm` + `--enable-sm3` + `--enable-sm2` | -### A-3. TLS 1.2 ECDHE-RSA +### A-3 TLS 1.2 ECDHE-RSA | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x2F` | **Enabled** | — | -| `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x30` | **Enabled** | — | -| `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xA8` | **Enabled** | — | -| `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA` | `0xC0,0x13` | **Enabled** | — | -| `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA` | `0xC0,0x14` | **Enabled** | — | -| `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x27` | **Enabled** | — | +| `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x2F` | **Enabled** | - | +| `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x30` | **Enabled** | - | +| `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xA8` | **Enabled** | - | +| `TLS_ECDHE_RSA_WITH_CHACHA20_OLD_POLY1305_SHA256` | `0xCC,0x13` | **Enabled** | - (see note in A-4) | +| `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA` | `0xC0,0x13` | **Enabled** | - | +| `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA` | `0xC0,0x14` | **Enabled** | - | +| `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x27` | **Enabled** | - | | `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384` | `0xC0,0x28` | **Enabled** | `--enable-sha384` | -| `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x12` | Disabled | `--enable-des3` | +| `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x12` | Disabled | `--enable-des3` + `--enable-des3-tls-suites` | | `TLS_ECDHE_RSA_WITH_RC4_128_SHA` | `0xC0,0x11` | Disabled | `--enable-arc4` | -### A-4. TLS 1.2 DHE-RSA +### A-4 TLS 1.2 DHE-RSA | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `TLS_DHE_RSA_WITH_AES_128_GCM_SHA256` | `0x00,0x9E` | Disabled | `--enable-dh` | -| `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384` | `0x00,0x9F` | Disabled | `--enable-dh` | -| `TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xAA` | Disabled | `--enable-dh` + `--enable-chacha` | -| `TLS_DHE_RSA_WITH_AES_128_CBC_SHA` | `0x00,0x33` | Disabled | `--enable-dh` | -| `TLS_DHE_RSA_WITH_AES_256_CBC_SHA` | `0x00,0x39` | Disabled | `--enable-dh` | -| `TLS_DHE_RSA_WITH_AES_128_CBC_SHA256` | `0x00,0x67` | Disabled | `--enable-dh` | -| `TLS_DHE_RSA_WITH_AES_256_CBC_SHA256` | `0x00,0x6B` | Disabled | `--enable-dh` | -| `TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA` | `0x00,0x16` | Disabled | `--enable-dh` + `--enable-des3` | -| `TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA` | `0x00,0x45` | Disabled | `--enable-dh` + `--enable-camellia` | -| `TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA` | `0x00,0x88` | Disabled | `--enable-dh` + `--enable-camellia` | -| `TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256` | `0x00,0xBE` | Disabled | `--enable-dh` + `--enable-camellia` | -| `TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256` | `0x00,0xC4` | Disabled | `--enable-dh` + `--enable-camellia` | - -### A-5. TLS 1.2 RSA (Static Key Exchange) +| `TLS_DHE_RSA_WITH_AES_128_GCM_SHA256` | `0x00,0x9E` | **Enabled** | - | +| `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384` | `0x00,0x9F` | **Enabled** | - | +| `TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xAA` | **Enabled** | - | +| `TLS_DHE_RSA_WITH_CHACHA20_OLD_POLY1305_SHA256` | `0xCC,0x15` | **Enabled** | - (see note below) | +| `TLS_DHE_RSA_WITH_AES_128_CBC_SHA` | `0x00,0x33` | **Enabled** | - | +| `TLS_DHE_RSA_WITH_AES_256_CBC_SHA` | `0x00,0x39` | **Enabled** | - | +| `TLS_DHE_RSA_WITH_AES_128_CBC_SHA256` | `0x00,0x67` | **Enabled** | - | +| `TLS_DHE_RSA_WITH_AES_256_CBC_SHA256` | `0x00,0x6B` | **Enabled** | - | +| `TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA` | `0x00,0x16` | Disabled | `--enable-des3` + `--enable-des3-tls-suites` | +| `TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA` | `0x00,0x45` | Disabled | `--enable-camellia` | +| `TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA` | `0x00,0x88` | Disabled | `--enable-camellia` | +| `TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256` | `0x00,0xBE` | Disabled | `--enable-camellia` | +| `TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256` | `0x00,0xC4` | Disabled | `--enable-camellia` | + +DH is enabled by default (`--enable-dh`, except in FIPS v7 and later builds), so the DHE suites are compiled in by default. A server only negotiates them when it has DH parameters, either loaded with `wolfSSL_CTX_SetTmpDH()` (or a related function) or selected from the FFDHE groups offered by the client. + +The `_OLD_POLY1305` suites in A-2, A-3 and A-4 use an earlier draft version of the ChaCha20-Poly1305 suites (different nonce and padding) with the code points `0xCC,0x13` to `0xCC,0x15`; they are not the IANA registered RFC 7905 suites. They are compiled in and offered by default. Define `NO_OLD_POLY1305` to remove them. + +### A-5 TLS 1.2 RSA (Static Key Exchange) + +Static RSA key exchange does not provide forward secrecy and is not recommended. These suites are not compiled in by default, even with `--enable-all`. They need `WOLFSSL_STATIC_RSA`, which has no configure option (use `CPPFLAGS=-DWOLFSSL_STATIC_RSA` or `user_settings.h`); `WOLFSSL_SNIFFER` defines it automatically. | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `TLS_RSA_WITH_AES_128_GCM_SHA256` | `0x00,0x9C` | **Enabled** | — | -| `TLS_RSA_WITH_AES_256_GCM_SHA384` | `0x00,0x9D` | **Enabled** | — | -| `TLS_RSA_WITH_AES_128_CBC_SHA` | `0x00,0x2F` | **Enabled** | — | -| `TLS_RSA_WITH_AES_256_CBC_SHA` | `0x00,0x35` | **Enabled** | — | -| `TLS_RSA_WITH_AES_128_CBC_SHA256` | `0x00,0x3C` | **Enabled** | — | -| `TLS_RSA_WITH_AES_256_CBC_SHA256` | `0x00,0x3D` | **Enabled** | — | -| `TLS_RSA_WITH_AES_128_CCM_8` | `0xC0,0xA0` | Disabled | `--enable-aesccm` | -| `TLS_RSA_WITH_AES_256_CCM_8` | `0xC0,0xA1` | Disabled | `--enable-aesccm` | -| `SSL_RSA_WITH_3DES_EDE_CBC_SHA` | `0x00,0x0A` | Disabled | `--enable-des3` | -| `SSL_RSA_WITH_RC4_128_SHA` | `0x00,0x05` | Disabled | `--enable-arc4` | -| `SSL_RSA_WITH_RC4_128_MD5` | `0x00,0x04` | Disabled | `--enable-arc4` | -| `TLS_RSA_WITH_NULL_MD5` | `0x00,0x01` | Disabled | `--enable-nullcipher` | -| `TLS_RSA_WITH_NULL_SHA` | `0x00,0x02` | Disabled | `--enable-nullcipher` | -| `TLS_RSA_WITH_NULL_SHA256` | `0x00,0x3B` | Disabled | `--enable-nullcipher` | -| `TLS_RSA_WITH_CAMELLIA_128_CBC_SHA` | `0x00,0x41` | Disabled | `--enable-camellia` | -| `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA` | `0x00,0x84` | Disabled | `--enable-camellia` | -| `TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256` | `0x00,0xBA` | Disabled | `--enable-camellia` | -| `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256` | `0x00,0xC0` | Disabled | `--enable-camellia` | - -### A-6. TLS 1.2 Static ECDH +| `TLS_RSA_WITH_AES_128_GCM_SHA256` | `0x00,0x9C` | Disabled | `-DWOLFSSL_STATIC_RSA` | +| `TLS_RSA_WITH_AES_256_GCM_SHA384` | `0x00,0x9D` | Disabled | `-DWOLFSSL_STATIC_RSA` | +| `TLS_RSA_WITH_AES_128_CBC_SHA` | `0x00,0x2F` | Disabled | `-DWOLFSSL_STATIC_RSA` | +| `TLS_RSA_WITH_AES_256_CBC_SHA` | `0x00,0x35` | Disabled | `-DWOLFSSL_STATIC_RSA` | +| `TLS_RSA_WITH_AES_128_CBC_SHA256` | `0x00,0x3C` | Disabled | `-DWOLFSSL_STATIC_RSA` | +| `TLS_RSA_WITH_AES_256_CBC_SHA256` | `0x00,0x3D` | Disabled | `-DWOLFSSL_STATIC_RSA` | +| `TLS_RSA_WITH_AES_128_CCM_8` | `0xC0,0xA0` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-aesccm` | +| `TLS_RSA_WITH_AES_256_CCM_8` | `0xC0,0xA1` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-aesccm` | +| `SSL_RSA_WITH_3DES_EDE_CBC_SHA` | `0x00,0x0A` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-des3` + `--enable-des3-tls-suites` | +| `SSL_RSA_WITH_RC4_128_SHA` | `0x00,0x05` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-arc4` | +| `SSL_RSA_WITH_RC4_128_MD5` | `0x00,0x04` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-arc4` + `--enable-md5` | +| `TLS_RSA_WITH_NULL_MD5` | `0x00,0x01` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-nullcipher` + `--enable-md5` | +| `TLS_RSA_WITH_NULL_SHA` | `0x00,0x02` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-nullcipher` | +| `TLS_RSA_WITH_NULL_SHA256` | `0x00,0x3B` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-nullcipher` | +| `TLS_RSA_WITH_CAMELLIA_128_CBC_SHA` | `0x00,0x41` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-camellia` | +| `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA` | `0x00,0x84` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-camellia` | +| `TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256` | `0x00,0xBA` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-camellia` | +| `TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256` | `0x00,0xC0` | Disabled | `-DWOLFSSL_STATIC_RSA` + `--enable-camellia` | + +### A-6 TLS 1.2 Static ECDH + +Static ECDH key exchange does not provide forward secrecy and is not recommended. These suites need `WOLFSSL_STATIC_DH` (and ECC), which has no configure option (use `CPPFLAGS=-DWOLFSSL_STATIC_DH` or `user_settings.h`); `WOLFSSL_SNIFFER` defines it automatically. | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x31` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x32` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_RSA_WITH_AES_128_CBC_SHA` | `0xC0,0x0E` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_RSA_WITH_AES_256_CBC_SHA` | `0xC0,0x0F` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x29` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384` | `0xC0,0x2A` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_RSA_WITH_RC4_128_SHA` | `0xC0,0x0C` | Disabled | `--enable-staticecdh` + `--enable-arc4` | -| `TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x0D` | Disabled | `--enable-staticecdh` + `--enable-des3` | -| `TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x2D` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x2E` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA` | `0xC0,0x04` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA` | `0xC0,0x05` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x25` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384` | `0xC0,0x26` | Disabled | `--enable-staticecdh` | -| `TLS_ECDH_ECDSA_WITH_RC4_128_SHA` | `0xC0,0x02` | Disabled | `--enable-staticecdh` + `--enable-arc4` | -| `TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x03` | Disabled | `--enable-staticecdh` + `--enable-des3` | - -### A-7. TLS 1.2 PSK +| `TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x31` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x32` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_RSA_WITH_AES_128_CBC_SHA` | `0xC0,0x0E` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_RSA_WITH_AES_256_CBC_SHA` | `0xC0,0x0F` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x29` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384` | `0xC0,0x2A` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_RSA_WITH_RC4_128_SHA` | `0xC0,0x0C` | Disabled | `-DWOLFSSL_STATIC_DH` + `--enable-arc4` | +| `TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x0D` | Disabled | `-DWOLFSSL_STATIC_DH` + `--enable-des3` + `--enable-des3-tls-suites` | +| `TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256` | `0xC0,0x2D` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384` | `0xC0,0x2E` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA` | `0xC0,0x04` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA` | `0xC0,0x05` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256` | `0xC0,0x25` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384` | `0xC0,0x26` | Disabled | `-DWOLFSSL_STATIC_DH` | +| `TLS_ECDH_ECDSA_WITH_RC4_128_SHA` | `0xC0,0x02` | Disabled | `-DWOLFSSL_STATIC_DH` + `--enable-arc4` | +| `TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA` | `0xC0,0x03` | Disabled | `-DWOLFSSL_STATIC_DH` + `--enable-des3` + `--enable-des3-tls-suites` | + +### A-7 TLS 1.2 PSK + +The pure PSK suites with AES or NULL ciphers also need `WOLFSSL_STATIC_PSK`, which `--enable-psk` does not define (use `CPPFLAGS=-DWOLFSSL_STATIC_PSK` or `user_settings.h`). `TLS_PSK_WITH_CHACHA20_POLY1305_SHA256` and the DHE-PSK and ECDHE-PSK suites only need `--enable-psk`. | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `TLS_PSK_WITH_AES_128_GCM_SHA256` | `0x00,0xA8` | Disabled | `--enable-psk` | -| `TLS_PSK_WITH_AES_256_GCM_SHA384` | `0x00,0xA9` | Disabled | `--enable-psk` | -| `TLS_PSK_WITH_AES_128_CBC_SHA256` | `0x00,0xAE` | Disabled | `--enable-psk` | -| `TLS_PSK_WITH_AES_256_CBC_SHA384` | `0x00,0xAF` | Disabled | `--enable-psk` | -| `TLS_PSK_WITH_AES_128_CBC_SHA` | `0x00,0x8C` | Disabled | `--enable-psk` | -| `TLS_PSK_WITH_AES_256_CBC_SHA` | `0x00,0x8D` | Disabled | `--enable-psk` | -| `TLS_PSK_WITH_AES_128_CCM` | `0xC0,0xA4` | Disabled | `--enable-psk` + `--enable-aesccm` | -| `TLS_PSK_WITH_AES_256_CCM` | `0xC0,0xA5` | Disabled | `--enable-psk` + `--enable-aesccm` | -| `TLS_PSK_WITH_AES_128_CCM_8` | `0xC0,0xA8` | Disabled | `--enable-psk` + `--enable-aesccm` | -| `TLS_PSK_WITH_AES_256_CCM_8` | `0xC0,0xA9` | Disabled | `--enable-psk` + `--enable-aesccm` | +| `TLS_PSK_WITH_AES_128_GCM_SHA256` | `0x00,0xA8` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` | +| `TLS_PSK_WITH_AES_256_GCM_SHA384` | `0x00,0xA9` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` | +| `TLS_PSK_WITH_AES_128_CBC_SHA256` | `0x00,0xAE` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` | +| `TLS_PSK_WITH_AES_256_CBC_SHA384` | `0x00,0xAF` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` | +| `TLS_PSK_WITH_AES_128_CBC_SHA` | `0x00,0x8C` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` | +| `TLS_PSK_WITH_AES_256_CBC_SHA` | `0x00,0x8D` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` | +| `TLS_PSK_WITH_AES_128_CCM` | `0xC0,0xA4` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` + `--enable-aesccm` | +| `TLS_PSK_WITH_AES_256_CCM` | `0xC0,0xA5` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` + `--enable-aesccm` | +| `TLS_PSK_WITH_AES_128_CCM_8` | `0xC0,0xA8` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` + `--enable-aesccm` | +| `TLS_PSK_WITH_AES_256_CCM_8` | `0xC0,0xA9` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` + `--enable-aesccm` | | `TLS_PSK_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xAB` | Disabled | `--enable-psk` + `--enable-chacha` | -| `TLS_PSK_WITH_NULL_SHA256` | `0x00,0xB0` | Disabled | `--enable-psk` + `--enable-nullcipher` | -| `TLS_PSK_WITH_NULL_SHA384` | `0x00,0xB1` | Disabled | `--enable-psk` + `--enable-nullcipher` | -| `TLS_PSK_WITH_NULL_SHA` | `0x00,0x2C` | Disabled | `--enable-psk` + `--enable-nullcipher` | +| `TLS_PSK_WITH_NULL_SHA256` | `0x00,0xB0` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` + `--enable-nullcipher` | +| `TLS_PSK_WITH_NULL_SHA384` | `0x00,0xB1` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` + `--enable-nullcipher` | +| `TLS_PSK_WITH_NULL_SHA` | `0x00,0x2C` | Disabled | `--enable-psk` + `-DWOLFSSL_STATIC_PSK` + `--enable-nullcipher` | -### A-8. TLS 1.2 DHE-PSK +### A-8 TLS 1.2 DHE-PSK | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `TLS_DHE_PSK_WITH_AES_128_GCM_SHA256` | `0x00,0xAA` | Disabled | `--enable-psk` + `--enable-dh` | -| `TLS_DHE_PSK_WITH_AES_256_GCM_SHA384` | `0x00,0xAB` | Disabled | `--enable-psk` + `--enable-dh` | -| `TLS_DHE_PSK_WITH_AES_128_CBC_SHA256` | `0x00,0xB2` | Disabled | `--enable-psk` + `--enable-dh` | -| `TLS_DHE_PSK_WITH_AES_256_CBC_SHA384` | `0x00,0xB3` | Disabled | `--enable-psk` + `--enable-dh` | -| `TLS_DHE_PSK_WITH_AES_128_CCM` | `0xC0,0xA6` | Disabled | `--enable-psk` + `--enable-dh` + `--enable-aesccm` | -| `TLS_DHE_PSK_WITH_AES_256_CCM` | `0xC0,0xA7` | Disabled | `--enable-psk` + `--enable-dh` + `--enable-aesccm` | -| `TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xAD` | Disabled | `--enable-psk` + `--enable-dh` + `--enable-chacha` | -| `TLS_DHE_PSK_WITH_NULL_SHA256` | `0x00,0xB4` | Disabled | `--enable-psk` + `--enable-dh` + `--enable-nullcipher` | -| `TLS_DHE_PSK_WITH_NULL_SHA384` | `0x00,0xB5` | Disabled | `--enable-psk` + `--enable-dh` + `--enable-nullcipher` | - -### A-9. TLS 1.2 ECDHE-PSK +| `TLS_DHE_PSK_WITH_AES_128_GCM_SHA256` | `0x00,0xAA` | Disabled | `--enable-psk` | +| `TLS_DHE_PSK_WITH_AES_256_GCM_SHA384` | `0x00,0xAB` | Disabled | `--enable-psk` | +| `TLS_DHE_PSK_WITH_AES_128_CBC_SHA256` | `0x00,0xB2` | Disabled | `--enable-psk` | +| `TLS_DHE_PSK_WITH_AES_256_CBC_SHA384` | `0x00,0xB3` | Disabled | `--enable-psk` | +| `TLS_DHE_PSK_WITH_AES_128_CCM` | `0xC0,0xA6` | Disabled | `--enable-psk` + `--enable-aesccm` | +| `TLS_DHE_PSK_WITH_AES_256_CCM` | `0xC0,0xA7` | Disabled | `--enable-psk` + `--enable-aesccm` | +| `TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xAD` | Disabled | `--enable-psk` + `--enable-chacha` | +| `TLS_DHE_PSK_WITH_NULL_SHA256` | `0x00,0xB4` | Disabled | `--enable-psk` + `--enable-nullcipher` | +| `TLS_DHE_PSK_WITH_NULL_SHA384` | `0x00,0xB5` | Disabled | `--enable-psk` + `--enable-nullcipher` | + +### A-9 TLS 1.2 ECDHE-PSK | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| @@ -156,55 +169,70 @@ | `TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256` | `0xCC,0xAC` | Disabled | `--enable-psk` + `--enable-chacha` | | `TLS_ECDHE_PSK_WITH_NULL_SHA256` | `0xC0,0x3A` | Disabled | `--enable-psk` + `--enable-nullcipher` | -### A-10. TLS 1.2 DH_anon +### A-10 TLS 1.2 DH_anon | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| | `TLS_DH_anon_WITH_AES_128_CBC_SHA` | `0x00,0x34` | Disabled | `--enable-anon` | | `TLS_DH_anon_WITH_AES_256_GCM_SHA384` | `0x00,0xA7` | Disabled | `--enable-anon` | +### A-11 Signaling and Private Values + +| Name | Wire Value | Default | configure Option | +|------|-----------|:-------:|-----------------| +| `TLS_EMPTY_RENEGOTIATION_INFO_SCSV` | `0x00,0xFF` | Disabled | `--enable-renegotiation-indication` (client sends it; servers with the default `--enable-secure-renegotiation-info` recognize it) | +| `WDM_WITH_NULL_SHA256` | `0x00,0xFE` | Disabled | `--enable-mcast` (wolfSSL DTLS multicast; also enables DTLS and the NULL cipher) | + +`--enable-harden-tls` (RFC 9325) removes the DHE and RC4 suites, and with `--enable-harden-tls=128` also the 3DES suites. It cannot be combined with the NULL, static RSA, static DH or anonymous suites (the build stops with an error). + --- ## B. Key Exchange Groups -### B-1. NIST Elliptic Curves +### B-1 NIST Elliptic Curves | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| | `secp256r1` (P-256) | 23 | **Enabled** | `--enable-ecc` | | `secp384r1` (P-384) | 24 | **Enabled** | `--enable-ecc` | | `secp521r1` (P-521) | 25 | **Enabled** | `--enable-ecc` | -| `secp192r1` (P-192) | 19 | Disabled | `--enable-ecc` (TLS 1.2 only) | -| `secp224r1` (P-224) | 21 | Disabled | `--enable-ecc` (TLS 1.2 only) | +| `secp224r1` (P-224) | 21 | **Enabled** | `--enable-ecc` | +| `secp192r1` (P-192) | 19 | Disabled | `--with-eccminsz=192` | +| `secp160r1` | 16 | Disabled | `--with-eccminsz=160` | +| `secp160r2` | 17 | Disabled | `--enable-ecccustcurves=all` + `--with-eccminsz=160` | + +The minimum ECC key size (`ECC_MIN_KEY_SZ`, set with `--with-eccminsz`) is 224 bits by default (192 bits in FIPS builds), so curves smaller than P-224 need a lower minimum. Of these curves, RFC 8446 only defines `secp256r1`, `secp384r1` and `secp521r1` for TLS 1.3, but wolfSSL does not filter the other curves by protocol version. -### B-2. Koblitz Curves +### B-2 Koblitz Curves | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| -| `secp160k1` | 15 | Disabled | `--enable-ecccustcurves` | -| `secp192k1` | 18 | Disabled | `--enable-ecccustcurves` | -| `secp224k1` | 20 | Disabled | `--enable-ecccustcurves` | -| `secp256k1` | 22 | Disabled | `--enable-ecccustcurves` | +| `secp160k1` | 15 | Disabled | `--enable-ecccustcurves=all` + `--with-eccminsz=160` | +| `secp192k1` | 18 | Disabled | `--enable-ecccustcurves=all` + `--with-eccminsz=192` | +| `secp224k1` | 20 | Disabled | `--enable-ecccustcurves=all` | +| `secp256k1` | 22 | Disabled | `--enable-ecccustcurves=all` | -### B-3. Brainpool Curves +Plain `--enable-ecccustcurves` only defines `WOLFSSL_CUSTOM_CURVES`; the Koblitz curves (`HAVE_ECC_KOBLITZ`) need `--enable-ecccustcurves=all` (or `--enable-all`). + +### B-3 Brainpool Curves | Group Name | ID | TLS Ver. | Default | configure Option | |------------|:--:|:--------:|:-------:|-----------------| -| `brainpoolP256r1` | 26 | 1.2 | Disabled | `--enable-ecccustcurves` + `--enable-brainpool` | -| `brainpoolP384r1` | 27 | 1.2 | Disabled | `--enable-ecccustcurves` + `--enable-brainpool` | -| `brainpoolP512r1` | 28 | 1.2 | Disabled | `--enable-ecccustcurves` + `--enable-brainpool` | -| `brainpoolP256r1tls13` | 31 | 1.3 | Disabled | `--enable-ecccustcurves` + `--enable-brainpool` | -| `brainpoolP384r1tls13` | 32 | 1.3 | Disabled | `--enable-ecccustcurves` + `--enable-brainpool` | -| `brainpoolP512r1tls13` | 33 | 1.3 | Disabled | `--enable-ecccustcurves` + `--enable-brainpool` | +| `brainpoolP256r1` | 26 | 1.2 | Disabled | `--enable-ecccustcurves` | +| `brainpoolP384r1` | 27 | 1.2 | Disabled | `--enable-ecccustcurves` | +| `brainpoolP512r1` | 28 | 1.2 | Disabled | `--enable-ecccustcurves` | +| `brainpoolP256r1tls13` | 31 | 1.3 | Disabled | `--enable-ecccustcurves` | +| `brainpoolP384r1tls13` | 32 | 1.3 | Disabled | `--enable-ecccustcurves` | +| `brainpoolP512r1tls13` | 33 | 1.3 | Disabled | `--enable-ecccustcurves` | -### B-4. X25519 / X448 +### B-4 X25519 / X448 | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| | `x25519` | 29 | Disabled | `--enable-curve25519` | | `x448` | 30 | Disabled | `--enable-curve448` | -### B-5. FFDHE +### B-5 FFDHE | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| @@ -214,21 +242,21 @@ | `ffdhe6144` | 259 | Disabled | `-DHAVE_FFDHE_6144` | | `ffdhe8192` | 260 | Disabled | `-DHAVE_FFDHE_8192` | -### B-6. SM2 +### B-6 SM2 | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| | `sm2p256v1` | 41 | Disabled | `--enable-sm2` | -### B-7. ML-KEM Standalone +### B-7 ML-KEM Standalone | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| -| `ML-KEM-512` | 512 | Disabled | `--enable-mlkem` + `--enable-tls-mlkem-standalone` | -| `ML-KEM-768` | 513 | Disabled | `--enable-mlkem` + `--enable-tls-mlkem-standalone` | -| `ML-KEM-1024` | 514 | Disabled | `--enable-mlkem` + `--enable-tls-mlkem-standalone` | +| `ML_KEM_512` (alias `MLKEM512`) | 512 | Disabled | `--enable-mlkem` + `--enable-tls-mlkem-standalone` | +| `ML_KEM_768` (alias `MLKEM768`) | 513 | Disabled | `--enable-mlkem` + `--enable-tls-mlkem-standalone` | +| `ML_KEM_1024` (alias `MLKEM1024`) | 514 | Disabled | `--enable-mlkem` + `--enable-tls-mlkem-standalone` | -### B-8. ML-KEM Hybrid (Standard) +### B-8 ML-KEM Hybrid (Standard) | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| @@ -236,7 +264,7 @@ | `X25519MLKEM768` | 4588 | Disabled | `--enable-mlkem` + `--enable-pqc-hybrids` + `--enable-curve25519` | | `SecP384r1MLKEM1024` | 4589 | Conditionally Enabled | `--enable-mlkem` + `--enable-pqc-hybrids` | -### B-9. ML-KEM Hybrid (Experimental) +### B-9 ML-KEM Hybrid (Experimental) | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| @@ -245,51 +273,58 @@ | `SecP521r1MLKEM1024` | 12109 | Disabled | `--enable-extra-pqc-hybrids` + `--enable-experimental` | | `X25519MLKEM512` | 12214 | Disabled | Same as above + `--enable-curve25519` | | `X448MLKEM768` | 12215 | Disabled | Same as above + `--enable-curve448` | +| `P256_ML_KEM_512_OLD` | 12103 | Disabled | Same as above + `-DWOLFSSL_ML_KEM_USE_OLD_IDS` | +| `P384_ML_KEM_768_OLD` | 12104 | Disabled | Same as above + `-DWOLFSSL_ML_KEM_USE_OLD_IDS` | +| `P521_ML_KEM_1024_OLD` | 12105 | Disabled | Same as above + `-DWOLFSSL_ML_KEM_USE_OLD_IDS` | + +The `_OLD` IDs are earlier code points for the NIST curve hybrids. With `WOLFSSL_ML_KEM_USE_OLD_IDS`, each is sent together with the matching new ID (12107 to 12109). -### B-10. Kyber Round 3 Legacy +### B-10 Kyber Round 3 Legacy | Group Name | ID | Default | configure Option | |------------|:--:|:-------:|-----------------| -| `KYBER_LEVEL1` | 570 | Disabled | `--enable-mlkem=original` | -| `KYBER_LEVEL3` | 572 | Disabled | `--enable-mlkem=original` | -| `KYBER_LEVEL5` | 573 | Disabled | `--enable-mlkem=original` | -| `P256_KYBER_LEVEL1` | 12090 | Disabled | `--enable-mlkem=original` | -| `P384_KYBER_LEVEL3` | 12092 | Disabled | `--enable-mlkem=original` | -| `P521_KYBER_LEVEL5` | 12093 | Disabled | `--enable-mlkem=original` | +| `KYBER_LEVEL1` | 570 | Disabled | `--enable-mlkem=yes,original` | +| `KYBER_LEVEL3` | 572 | Disabled | `--enable-mlkem=yes,original` | +| `KYBER_LEVEL5` | 573 | Disabled | `--enable-mlkem=yes,original` | +| `P256_KYBER_LEVEL1` | 12090 | Disabled | `--enable-mlkem=yes,original` | +| `P384_KYBER_LEVEL3` | 12092 | Disabled | `--enable-mlkem=yes,original` | +| `P521_KYBER_LEVEL5` | 12093 | Disabled | `--enable-mlkem=yes,original` | | `X25519_KYBER_LEVEL1` | 12089 | Disabled | Same as above + `--enable-curve25519` | | `X25519_KYBER_LEVEL3` | 25497 | Disabled | Same as above + `--enable-curve25519` | | `X448_KYBER_LEVEL3` | 12176 | Disabled | Same as above + `--enable-curve448` | -| `P256_KYBER_LEVEL3` | 25498 | Disabled | `--enable-mlkem=original` | +| `P256_KYBER_LEVEL3` | 25498 | Disabled | `--enable-mlkem=yes,original` | + +`--enable-mlkem=original` on its own does not build any usable Kyber parameter set; use `--enable-mlkem=yes,original`. Selecting `original` disables the ML-KEM groups unless `ml-kem` is also listed (`--enable-mlkem=yes,original,ml-kem`). --- ## C. Signature Algorithms -### C-1. ECDSA (NIST Curves) +### C-1 ECDSA (NIST Curves) | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| | `ecdsa_secp256r1_sha256` | `0x04,0x03` | **Enabled** | `--enable-ecc` | | `ecdsa_secp384r1_sha384` | `0x05,0x03` | **Enabled** | `--enable-ecc` + `--enable-sha384` | | `ecdsa_secp521r1_sha512` | `0x06,0x03` | **Enabled** | `--enable-ecc` + `--enable-sha512` | -| `ecdsa_sha1` | `0x02,0x03` | Conditional | `!NO_OLD_TLS` or `WOLFSSL_ALLOW_TLS_SHA1` | +| `ecdsa_sha1` | `0x02,0x03` | Disabled | TLS 1.0/1.1 handshakes (`--enable-oldtls`); TLS 1.2 only with `-DWOLFSSL_ALLOW_TLS_SHA1` (see RFC 9155) | -### C-2. ECDSA (Brainpool, TLS 1.3 Only) +### C-2 ECDSA (Brainpool, TLS 1.3 Only) | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `ecdsa_brainpoolP256r1tls13_sha256` | `0x08,0x1A` | Disabled | `--enable-ecccustcurves` + `--enable-brainpool` | +| `ecdsa_brainpoolP256r1tls13_sha256` | `0x08,0x1A` | Disabled | `--enable-ecccustcurves` | | `ecdsa_brainpoolP384r1tls13_sha384` | `0x08,0x1B` | Disabled | Same as above + `--enable-sha384` | | `ecdsa_brainpoolP512r1tls13_sha512` | `0x08,0x1C` | Disabled | Same as above + `--enable-sha512` | -### C-3. EdDSA +### C-3 EdDSA | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| | `ed25519` | `0x08,0x07` | Disabled | `--enable-ed25519` | | `ed448` | `0x08,0x08` | Disabled | `--enable-ed448` | -### C-4. RSA-PSS RSAE +### C-4 RSA-PSS RSAE | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| @@ -297,7 +332,7 @@ | `rsa_pss_rsae_sha384` | `0x08,0x05` | **Enabled** | `--enable-rsapss` + `--enable-sha384` | | `rsa_pss_rsae_sha512` | `0x08,0x06` | **Enabled** | `--enable-rsapss` + `--enable-sha512` | -### C-5. RSA-PSS PSS (TLS 1.3 Only) +### C-5 RSA-PSS PSS (TLS 1.3 Only) | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| @@ -305,23 +340,23 @@ | `rsa_pss_pss_sha384` | `0x08,0x0A` | **Enabled** | Same as above + `--enable-sha384` | | `rsa_pss_pss_sha512` | `0x08,0x0B` | **Enabled** | Same as above + `--enable-sha512` | -### C-6. RSA PKCS#1 v1.5 +### C-6 RSA PKCS#1 v1.5 | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| -| `rsa_pkcs1_sha256` | `0x04,0x01` | **Enabled** | — | +| `rsa_pkcs1_sha256` | `0x04,0x01` | **Enabled** | - | | `rsa_pkcs1_sha384` | `0x05,0x01` | **Enabled** | `--enable-sha384` | | `rsa_pkcs1_sha512` | `0x06,0x01` | **Enabled** | `--enable-sha512` | | `rsa_pkcs1_sha224` | `0x03,0x01` | Conditional | `--enable-sha224` (Enabled by default on x86_64/aarch64) | -| `rsa_pkcs1_sha1` | `0x02,0x01` | Conditional | `!NO_OLD_TLS` or `WOLFSSL_ALLOW_TLS_SHA1` | +| `rsa_pkcs1_sha1` | `0x02,0x01` | Disabled | TLS 1.0/1.1 handshakes (`--enable-oldtls`); TLS 1.2 only with `-DWOLFSSL_ALLOW_TLS_SHA1` (see RFC 9155) | -### C-7. SM2 +### C-7 SM2 | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| | `sm2sig_sm3` | `0x07,0x08` | Disabled | `--enable-sm2` + `--enable-sm3` | -### C-8. ML-DSA / Dilithium +### C-8 ML-DSA / Dilithium | IANA Name | Wire Value | Default | configure Option | |-----------|-----------|:-------:|-----------------| @@ -329,7 +364,7 @@ | `mldsa65` (ML-DSA-65) | `0x09,0x05` | Disabled | `--enable-mldsa` | | `mldsa87` (ML-DSA-87) | `0x09,0x06` | Disabled | `--enable-mldsa` | -### C-9. SLH-DSA (FIPS 205) +### C-9 SLH-DSA (FIPS 205) The wire values come from draft-reddy-tls-slhdsa and are the same ones oqs-provider uses. SLH-DSA can sign TLS 1.3 and DTLS 1.3 handshakes, new in wolfSSL 5.9.4. @@ -348,7 +383,7 @@ The wire values come from draft-reddy-tls-slhdsa and are the same ones oqs-provi | `slhdsa_shake_256s` | `0x09,0x1B` | Disabled | `--enable-slhdsa` | | `slhdsa_shake_256f` | `0x09,0x1C` | Disabled | `--enable-slhdsa` | -### C-10. Falcon (Experimental) +### C-10 Falcon (Experimental) Falcon uses the private-use code points it shared with the old liboqs integration. The algorithm itself is now implemented natively in wolfCrypt. @@ -359,7 +394,7 @@ Falcon uses the private-use code points it shared with the old liboqs integratio --- -## D. configure Option ↔ #define Reference +## D. configure Option to #define Reference | configure Option | #define Macro | Notes | |-----------------|--------------|-------| @@ -372,29 +407,41 @@ Falcon uses the private-use code points it shared with the old liboqs integratio | `--enable-sha512` | `WOLFSSL_SHA512` | Enabled by default | | `--enable-supportedcurves` | `HAVE_SUPPORTED_CURVES` + `HAVE_TLS_EXTENSIONS` | Enabled by default | | `--enable-aesccm` | `HAVE_AESCCM` | | -| `--enable-dh` | `HAVE_DH` | | -| `--enable-psk` | `HAVE_PSK` | | +| `--enable-dh` | `HAVE_DH` | Enabled by default (except FIPS v7 and later) | +| `--enable-psk` | Removes `NO_PSK` | | | `--enable-rsapss` | `WC_RSA_PSS` | Automatic when TLS 1.3 is enabled | | `--enable-curve25519` | `HAVE_CURVE25519` | | | `--enable-curve448` | `HAVE_CURVE448` | | | `--enable-ed25519` | `HAVE_ED25519` | | | `--enable-ed448` | `HAVE_ED448` | | -| `--enable-ecccustcurves` | `WOLFSSL_CUSTOM_CURVES` | | -| `--enable-brainpool` | `HAVE_ECC_BRAINPOOL` | Requires ecccustcurves | +| `--enable-ecccustcurves` | `WOLFSSL_CUSTOM_CURVES` | `=all` also defines `HAVE_ECC_KOBLITZ`, `HAVE_ECC_SECPR2`, `HAVE_ECC_SECPR3` and `HAVE_ECC_BRAINPOOL` | +| `--enable-brainpool` | `HAVE_ECC_BRAINPOOL` | Requires ecccustcurves; enabled by default with it | | `--enable-des3` | Removes `NO_DES3` | | +| `--enable-des3-tls-suites` | Removes `NO_DES3_TLS_SUITES` | Needed for the 3DES cipher suites; requires `--enable-des3` | | `--enable-arc4` | Removes `NO_RC4` | | +| `--enable-md5` | Removes `NO_MD5` | Needed for the MD5 based suites | | `--enable-camellia` | `HAVE_CAMELLIA` | | | `--enable-aria` | `HAVE_ARIA` | | -| `--enable-nullcipher` | `HAVE_NULL_CIPHER` | Deprecated | -| `--enable-anon` | `HAVE_ANON` | Deprecated | +| `--enable-nullcipher` | `HAVE_NULL_CIPHER` | Not recommended (RFC 9325) | +| `--enable-anon` | `HAVE_ANON` | Not recommended (RFC 9325) | | `--enable-sm2` | `WOLFSSL_SM2` | | | `--enable-sm3` | `WOLFSSL_SM3` | | +| `--enable-sm4-cbc` | `WOLFSSL_SM4_CBC` | | | `--enable-sm4-gcm` | `WOLFSSL_SM4_GCM` | | -| `--enable-mlkem` | `WOLFSSL_HAVE_MLKEM` + `HAVE_PQC` | | +| `--enable-sm4-ccm` | `WOLFSSL_SM4_CCM` | | +| `--enable-mlkem` | `WOLFSSL_HAVE_MLKEM` | Enabled by default (non-FIPS or FIPS v7 and later; needs SHA-3 and SHAKE) | | `--enable-pqc-hybrids` | `WOLFSSL_PQC_HYBRIDS` | Enabled by default when mlkem is enabled | -| `--enable-mldsa` | `HAVE_DILITHIUM` | | +| `--enable-mldsa` | `WOLFSSL_HAVE_MLDSA` | `HAVE_DILITHIUM` is a legacy alias | | `--enable-slhdsa` | `WOLFSSL_HAVE_SLHDSA` | TLS 1.3 / DTLS 1.3 authentication, new in 5.9.4 | | `--enable-falcon` | `HAVE_FALCON` | Native implementation, needs --enable-experimental | | `--enable-tls13-sha512` | `WOLFSSL_TLS13_SHA512` | Keeps the SHA-512 transcript in TLS 1.3 only builds | | `--disable-tlsv12` | `WOLFSSL_NO_TLS12` | Compiles TLS 1.2 out (5.9.4 and later) | -| `--enable-staticecdh` | `WOLFSSL_STATIC_ECDH` | No PFS, deprecated | +| `--with-eccminsz=BITS` | `ECC_MIN_KEY_SZ` | Default 224 (192 with FIPS) | +| `--enable-mcast` | `WOLFSSL_MULTICAST` | Also enables DTLS and the NULL cipher | +| `--enable-renegotiation-indication` | `HAVE_RENEGOTIATION_INDICATION` | Client sends `TLS_EMPTY_RENEGOTIATION_INFO_SCSV` | +| `--enable-harden-tls` | `WOLFSSL_HARDEN_TLS` | RFC 9325 requirements; `=112` (same as `yes`) or `=128` | +| (CFLAGS) | `WOLFSSL_STATIC_RSA` | Static RSA suites, no forward secrecy | +| (CFLAGS) | `WOLFSSL_STATIC_DH` | Static ECDH suites, no forward secrecy | +| (CFLAGS) | `WOLFSSL_STATIC_PSK` | Pure PSK suites with AES or NULL ciphers | +| (CFLAGS) | `NO_OLD_POLY1305` | Removes the `_OLD_POLY1305` ChaCha20-Poly1305 suites | +| (CFLAGS) | `WOLFSSL_ALLOW_TLS_SHA1` | Offers SHA-1 signature algorithms in TLS 1.2 | diff --git a/wolfSSL/src/appendix08.md b/wolfSSL/src/appendix08.md index 23882660..6e16254c 100644 --- a/wolfSSL/src/appendix08.md +++ b/wolfSSL/src/appendix08.md @@ -2,36 +2,52 @@ ## A. Architecture-Level ISA/SIMD Optimizations +None of the assembly optimizations below are enabled by a default `./configure`. `--enable-all-asm` turns on the applicable ones for the build host: `--enable-intelasm` and SP assembly on x86-64, `--enable-armasm` and SP assembly on AArch64, and the PowerPC assembly on PowerPC hosts. It is also on by default with `--enable-all-crypto` (and therefore `--enable-all`) on most hosts. + | Architecture | Algorithms | user_settings.h Macro | configure Option | Notes | |---|---|---|---|---| | **Intel x86-64** | AES (all modes) | `WOLFSSL_AESNI` | `--enable-aesni` | AES-NI instructions | -| Intel x86-64 | SHA-256, SHA-512 | `USE_INTEL_SPEEDUP` + `HAVE_INTEL_AVX1` | Auto-detected | AVX1 assembly | -| Intel x86-64 | SHA-512, SHA-3 | `USE_INTEL_SPEEDUP` + `HAVE_INTEL_AVX2` | Auto-detected | AVX2 assembly | -| Intel x86-64 | ChaCha20, Poly1305 | `USE_INTEL_SPEEDUP` | Auto-detected | | -| Intel x86-64 | X25519 (Curve25519), Ed25519 | `USE_INTEL_SPEEDUP` | Auto-detected | fe_x25519_asm.S | -| Intel x86-64 | RSA/ECC/DH (SP) | `WOLFSSL_SP_X86_64_ASM` | Auto-detected | sp_x86_64_asm.S | -| **ARM AArch64** | AES, SHA-256/512, SHA-3, ChaCha20, Poly1305 | `WOLFSSL_ARMASM` | `--enable-armasm` | ARMv8 CE (Crypto Extension) | +| Intel x86-64 | SHA-256, SHA-512 | `USE_INTEL_SPEEDUP` | `--enable-intelasm` | `HAVE_INTEL_AVX1` / `HAVE_INTEL_AVX2` are then defined internally; the AVX1 or AVX2 code is chosen at run time | +| Intel x86-64 | SHA-3 | `USE_INTEL_SPEEDUP` | `--enable-intelasm` | sha3_asm.S | +| Intel x86-64 | ChaCha20, Poly1305 | `USE_INTEL_SPEEDUP` | `--enable-intelasm` | | +| Intel x86-64 | X25519 (Curve25519), Ed25519 | `USE_INTEL_SPEEDUP` | `--enable-intelasm` | fe_x25519_asm.S | +| Intel x86-64 | ML-KEM, ML-DSA, FrodoKEM | `USE_INTEL_SPEEDUP` | `--enable-intelasm` | wc_mlkem_asm.S, wc_mldsa_asm.S, wc_frodokem_asm.S | +| Intel x86-64 | SM3 | `USE_INTEL_SPEEDUP` | `--enable-intelasm` + `--enable-sm3` | sm3_asm.S (SM algorithms need wolfSM, see Appendix K) | +| Intel x86-64 | Falcon | - | `--enable-falcon=asm` + `--enable-experimental` | wc_falcon_fpr_x86_64_asm.S | +| Intel x86-64 | RSA/ECC/DH (SP) | `WOLFSSL_SP_X86_64_ASM` | `--enable-sp --enable-sp-asm` | sp_x86_64_asm.S | +| **Intel x86 (32-bit)** | AES, AES-XTS | `WOLFSSL_AESNI` | `--enable-aesni` | aes_asm.S, aes_xts_x86_asm.S (32-bit AES-GCM uses C GHASH over AES-NI) | +| **ARM AArch64** | AES, SHA-1, SHA-256/512, SHA-3, ChaCha20, Poly1305 | `WOLFSSL_ARMASM` | `--enable-armasm` | ARMv8 CE (Crypto Extension) | | ARM AArch64 | X25519 (Curve25519), Ed25519 | `WOLFSSL_ARMASM` | `--enable-armasm` | armv8-curve25519.S | -| ARM AArch64 | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM64_ASM` | Auto-detected | sp_arm64.c | +| ARM AArch64 | ML-KEM, ML-DSA, FrodoKEM | `WOLFSSL_ARMASM` | `--enable-armasm` | armv8-mlkem-asm.S, armv8-mldsa-asm.S, armv8-frodokem-asm.S | +| ARM AArch64 | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM64_ASM` | `--enable-sp --enable-sp-asm` | sp_arm64.c | | **ARM 32-bit (ARMv8-32)** | AES, SHA-256/512, SHA-3, ChaCha20, Poly1305 | `WOLFSSL_ARMASM` | `--enable-armasm` | | | ARM 32-bit | X25519 (Curve25519), Ed25519 | `WOLFSSL_ARMASM` | `--enable-armasm` | armv8-32-curve25519.S | -| ARM 32-bit | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM32_ASM` | Auto-detected | sp_arm32.c | -| **ARM Thumb2** | X25519 (Curve25519), Ed25519 | `WOLFSSL_ARMASM` + `WOLFSSL_ARMASM_THUMB2` | `--enable-armasm` | thumb2-curve25519.S | -| **ARM Thumb** | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM_THUMB_ASM` | Auto-detected | sp_armthumb.c | -| **ARM Cortex-M** | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM_CORTEX_M_ASM` | Auto-detected | sp_cortexm.c | -| **RISC-V 64-bit** | AES, SHA-256/512, SHA-3, ChaCha20, Poly1305 | `WOLFSSL_RISCV_ASM` | `--enable-riscv` | riscv/riscv-64-*.c | -| **PowerPC 32-bit** | SHA-256 | `WOLFSSL_PPC32_ASM` | Auto-detected | ppc32/ppc32-sha256-asm.S | +| ARM 32-bit | ML-KEM, ML-DSA, FrodoKEM | `WOLFSSL_ARMASM` | `--enable-armasm` | armv8-32-mlkem-asm.S, armv8-32-mldsa-asm.S, armv8-32-frodokem-asm.S | +| ARM 32-bit | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM32_ASM` | `--enable-sp --enable-sp-asm` | sp_arm32.c | +| **ARM Thumb2** | AES, SHA-256/512, SHA-3, ChaCha20, Poly1305, X25519 (Curve25519), Ed25519, ML-KEM, FrodoKEM | `WOLFSSL_ARMASM` + `WOLFSSL_ARMASM_THUMB2` | `--enable-armasm` | thumb2-*-asm.S, thumb2-curve25519.S | +| **ARM Thumb** | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM_THUMB_ASM` | `--enable-sp --enable-sp-asm` | sp_armthumb.c | +| **ARM Cortex-M** | RSA/ECC/DH (SP) | `WOLFSSL_SP_ARM_CORTEX_M_ASM` | `--enable-sp --enable-sp-asm` | sp_cortexm.c | +| **RISC-V 64-bit** | AES, SHA-256/512, SHA-3, ChaCha20, Poly1305 | `WOLFSSL_RISCV_ASM` | `--enable-riscv-asm` | port/riscv64/riscv-64-*-asm.S | +| RISC-V 64-bit | RSA/ECC/DH (SP) | `WOLFSSL_SP_RISCV64_ASM` | `--enable-sp --enable-sp-asm` | sp_riscv64.c | +| **PowerPC 32-bit** | AES, SHA-256, SHA-512, SHA-3 | `WOLFSSL_PPC32_ASM` | `--enable-ppc32-asm` | port/ppc32/ppc32-*-asm.S | +| **PowerPC 64-bit** | AES, SHA-256, SHA-512, SHA-3 | `WOLFSSL_PPC64_ASM` | `--enable-ppc64-asm` | port/ppc64/ppc64-*-asm.S | +| **Qualcomm Hexagon DSP** | ECC P-256 verify (SP) | `WOLFSSL_DSP` | user_settings.h | sp_dsp32.c, see IDE/HEXAGON | + +The SP assembly macros (`WOLFSSL_SP_*_ASM`) need the SP implementation (`--enable-sp`, disabled by default) together with `--enable-sp-asm`; configure then picks the macro for the host CPU. `--enable-sp-asm` is only on by default on x86-64 and AArch64 when the restricted `--enable-sp-math` is selected. The default math library is `sp_int.c` (`WOLFSSL_SP_MATH_ALL`). ## B. SP Math Library (Public Key Cryptography) | Architecture | Algorithms | user_settings.h Macro | configure Option | |---|---|---|---| -| x86-64 assembly | RSA 2048/3072/4096, ECC P-256/P-384/P-521, DH | `WOLFSSL_SP_X86_64_ASM` | Auto-detected | -| ARM AArch64 assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM64_ASM` | Auto-detected | -| ARM 32-bit assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM32_ASM` | Auto-detected | -| ARM Thumb assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM_THUMB_ASM` | Auto-detected | -| Cortex-M assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM_CORTEX_M_ASM` | Auto-detected | -| Generic C (32-bit / 64-bit) | RSA, ECC, DH | `WOLFSSL_SP_MATH` | `--enable-sp` | +| x86-64 assembly | RSA 2048/3072/4096, ECC P-256/P-384/P-521, DH | `WOLFSSL_SP_X86_64_ASM` | `--enable-sp --enable-sp-asm` | +| ARM AArch64 assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM64_ASM` | `--enable-sp --enable-sp-asm` | +| ARM 32-bit assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM32_ASM` | `--enable-sp --enable-sp-asm` | +| ARM Thumb assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM_THUMB_ASM` | `--enable-sp --enable-sp-asm` | +| Cortex-M assembly | RSA, ECC, DH | `WOLFSSL_SP_ARM_CORTEX_M_ASM` | `--enable-sp --enable-sp-asm` | +| RISC-V 64-bit assembly | RSA, ECC, DH | `WOLFSSL_SP_RISCV64_ASM` | `--enable-sp --enable-sp-asm` | +| Generic C (32-bit / 64-bit) | RSA, ECC, DH | `WOLFSSL_HAVE_SP_RSA`, `WOLFSSL_HAVE_SP_DH`, `WOLFSSL_HAVE_SP_ECC` | `--enable-sp` | + +`--enable-sp` builds the generic C implementation (sp_c32.c / sp_c64.c) and defines `WOLFSSL_HAVE_SP_RSA`, `WOLFSSL_HAVE_SP_DH` and `WOLFSSL_HAVE_SP_ECC`. `WOLFSSL_SP_MATH` (`--enable-sp-math`) is the restricted mode that only supports the key sizes and curves implemented by SP. ### sp_int.c Inline Assembly Speedups @@ -43,7 +59,10 @@ | Intel x86 (32-bit) | `WOLFSSL_SP_X86` | | ARM AArch64 | `WOLFSSL_SP_ARM64` | | ARM 32-bit | `WOLFSSL_SP_ARM32` | +| ARM Cortex-M | `WOLFSSL_SP_ARM_CORTEX_M` | | ARM Thumb | `WOLFSSL_SP_ARM_THUMB` | +| PowerPC 64-bit | `WOLFSSL_SP_PPC64` | +| PowerPC 32-bit | `WOLFSSL_SP_PPC` | | RISC-V 64-bit | `WOLFSSL_SP_RISCV64` | | RISC-V 32-bit | `WOLFSSL_SP_RISCV32` | | MIPS 64-bit | `WOLFSSL_SP_MIPS64` | @@ -52,72 +71,106 @@ ### SP Key Size Configuration +RSA-2048, RSA-3072 and ECC P-256 are included by default when SP is enabled; RSA-4096, P-384 and P-521 have to be added. Pick the one assembly macro that matches the target: + ```c -#define WOLFSSL_SP_MATH -#define WOLFSSL_SP_X86_64_ASM /* x86-64 */ -#define WOLFSSL_SP_ARM64_ASM /* AArch64 */ -#define WOLFSSL_SP_ARM_CORTEX_M_ASM /* Cortex-M */ +/* Enable SP for RSA, DH and ECC */ +#define WOLFSSL_HAVE_SP_RSA +#define WOLFSSL_HAVE_SP_DH +#define WOLFSSL_HAVE_SP_ECC + +/* Optional: restricted SP math (only the sizes and curves enabled below) */ +/* #define WOLFSSL_SP_MATH */ + +/* Optional: assembly, choose one */ +#define WOLFSSL_SP_ASM +#define WOLFSSL_SP_X86_64_ASM /* x86-64 */ +/* #define WOLFSSL_SP_ARM64_ASM */ /* AArch64 */ +/* #define WOLFSSL_SP_ARM_CORTEX_M_ASM */ /* Cortex-M */ -#define WOLFSSL_SP_2048 /* RSA-2048 */ -#define WOLFSSL_SP_3072 /* RSA-3072 */ +/* Additional key sizes and curves */ #define WOLFSSL_SP_4096 /* RSA-4096 */ -#define WOLFSSL_SP_256 /* ECC P-256 */ #define WOLFSSL_SP_384 /* ECC P-384 */ #define WOLFSSL_SP_521 /* ECC P-521 */ + +/* Remove default sizes that are not needed */ +/* #define WOLFSSL_SP_NO_2048 */ /* RSA-2048 */ +/* #define WOLFSSL_SP_NO_3072 */ /* RSA-3072 */ +/* #define WOLFSSL_SP_NO_256 */ /* ECC P-256 */ ``` ## C. Microcontroller/SoC Chip-Specific Hardware Accelerators +These ports are selected with defines in `user_settings.h` (for example `WOLFSSL_STM32F4`, which makes `settings.h` define `STM32_CRYPTO` and `STM32_HASH`); they are not detected automatically. Where a configure option exists, it is listed. + | Vendor / Chip | Algorithms | user_settings.h Macro | configure Option | Source | |---|---|---|---|---| | **STMicroelectronics** | | | | | -| STM32F2/F4/F7/H7 (CRYP) | AES-ECB/CBC/CTR/GCM | `STM32_CRYPTO` | HAL auto-detected | port/st/stm32.c | -| STM32L4/L5/WB55 | AES, SHA (partial) | `STM32_CRYPTO` | HAL auto-detected | port/st/stm32.c | -| STM32U5 (DHUK) | AES with key wrapping | `WOLFSSL_STM32U5_DHUK` | Auto-detected | port/st/stm32.c | -| STM32MP1/MP13/MP25 | AES, SHA, RSA, ECC | `WOLFSSL_STM32_CRYPT` | Auto-detected | port/st/stm32.c | -| STM32V8 (Cortex-M85) | AES, SHA, PKA, RNG | `WOLFSSL_STM32V8` | Auto-detected | port/st/stm32.c | +| STM32F2/F4/F7/H7 (CRYP) | AES-ECB/CBC/CTR/GCM | `STM32_CRYPTO` (set by the family define, e.g. `WOLFSSL_STM32F4`) | user_settings.h | port/st/stm32.c | +| STM32L4/L5/WB55 | AES, SHA (partial) | `STM32_CRYPTO` (set by the family define) | user_settings.h | port/st/stm32.c | +| STM32U5 (DHUK) | AES with key wrapping | `WOLFSSL_STM32U5_DHUK` | user_settings.h | port/st/stm32.c | +| STM32MP13 (bare metal) | AES, SHA, RNG, ECC (PKA) | `WOLFSSL_STM32MP13` (sets `STM32_CRYPTO`) | user_settings.h | port/st/stm32.c, see port/st/STM32MP13.md | +| STM32V8 (Cortex-M85) | AES, SHA, PKA, RNG | `WOLFSSL_STM32V8` | user_settings.h | port/st/stm32.c | | STM32 bare-metal (direct register access, no HAL, ~27 families) | HASH, AES, PKA, RNG, DHUK wrapped keys, CCB protected ECDSA | `WOLFSSL_STM32_BARE` | user_settings.h | port/st/stm32.c | -| STM32 CubeMX / CubeMX2 crypto callback device | AES (plaintext key), AES-GCM, ECDSA | `WOLFSSL_STM32_CUBEMX` / `WOLFSSL_MX2_CONF_INCLUDE` | Auto-detected | port/st/ | -| STSAFE-A100/A120 | ECDSA, ECDH | `WOLFSSL_STSAFEA100` / `WOLFSSL_STSAFEA120` | Auto-detected | port/st/stsafe.c | +| STM32 CubeMX / CubeMX2 crypto callback device | AES (plaintext key), AES-GCM, ECDSA | `WOLFSSL_STM32_CUBEMX` / `WOLFSSL_MX2_CONF_INCLUDE` | user_settings.h | port/st/ | +| STSAFE-A100/A120 | ECDSA, ECDH | `WOLFSSL_STSAFEA100` / `WOLFSSL_STSAFEA120` | `--enable-stsafe=a100` / `--enable-stsafe=a120` | port/st/stsafe.c | | **NXP** | | | | | -| i.MX RT (DCP) | AES-ECB/CBC/CTR/GCM, SHA | `WOLFSSL_IMXRT_DCP` | Auto-detected | port/nxp/dcp_port.c | +| i.MX RT (DCP) | AES-ECB/CBC (128-bit), SHA-1, SHA-256 | `WOLFSSL_IMXRT_DCP` | user_settings.h | port/nxp/dcp_port.c | | i.MX 6/8 (CAAM) | AES, SHA, RSA, ECC, DH, HMAC | `WOLFSSL_IMX6_CAAM` / `WOLFSSL_SECO_CAAM` | `--enable-caam` | port/caam/* | -| SE050 Secure Element | AES, SHA, RSA, ECC, X25519, ECDH | `WOLFSSL_SE050` + `WOLFSSL_SE050_CRYPT` | Auto-detected | port/nxp/se050_port.c | +| SE050 Secure Element | AES, SHA, RSA, ECC, X25519, ECDH | `WOLFSSL_SE050` + `WOLFSSL_SE050_CRYPT` | `--with-se050=PATH` | port/nxp/se050_port.c | +| EdgeLock Secure Enclave (ELE) | RNG (seed) | `WOLFSSL_NXP_ELE` | `--enable-ele` | port/nxp/ele_cryptocb.c, ele_rng.c | +| EdgeLock ELS/PKC (e.g. RW61x) | AES-ECB/CBC/CTR/GCM, CMAC, SHA-256/384/512, RNG | `WOLFSSL_ELS_PKC` | `--with-els-pkc=PATH` | port/nxp/els_pkc_port.c | +| LPC55S69 HashCrypt | AES-ECB/CBC/CTR/OFB/CFB, SHA-1, SHA-256 | `WOLFSSL_NXP_HASHCRYPT` (set by `WOLFSSL_NXP_LPC55S6X`) | user_settings.h | port/nxp/hashcrypt_port.c | +| LPC55S69 CASPER | RSA public key operations, ECC point multiply | `WOLFSSL_NXP_CASPER` (set by `WOLFSSL_NXP_LPC55S6X`) | user_settings.h | port/nxp/casper_port.c | +| LPC55S69 hardware PUF | PUF key generation and storage | `WOLFSSL_NXP_HWPUF` | user_settings.h | port/nxp/hwpuf_port.c | +| Kinetis mmCAU / LTC | AES, DES, MD5, SHA-1, SHA-256 (mmCAU); AES-GCM, RSA/ECC math (LTC) | `FREESCALE_USE_MMCAU` / `FREESCALE_USE_LTC` | user_settings.h | aes.c, des3.c, port/nxp/ksdk_port.c | +| QorIQ SEC (T1040, T2080) | AES-CBC/CTR/ECB/GCM, ECDSA, ECDH, RSA, FFDHE, RNG | `WOLFSSL_SEC_QORIQ` | `--enable-sec-qoriq` | port/nxp/sec_qoriq*.c | | **Espressif** | | | | | -| ESP32 / ESP32-S2 / ESP32-S3 | AES, SHA-1/256/384/512, RSA, ECC | `WOLFSSL_ESP32_CRYPT` | `--enable-esp32` | port/Espressif/esp32_*.c | -| ESP32-C3 / C6 / H2 | AES, SHA-256/384/512 (partial) | `WOLFSSL_ESP32_CRYPT` | `--enable-esp32` | port/Espressif/esp32_*.c | +| ESP32 / ESP32-S2 / ESP32-S3 | AES, SHA-1/256/384/512, RSA, ECC | `WOLFSSL_ESPIDF` + `WOLFSSL_ESP32` (settings.h then defines `WOLFSSL_ESP32_CRYPT`) | ESP-IDF component | port/Espressif/esp32_*.c | +| ESP32-C3 / C6 / H2 | AES, SHA-256/384/512 (partial) | `WOLFSSL_ESPIDF` + `WOLFSSL_ESP32` (settings.h then defines `WOLFSSL_ESP32_CRYPT`) | ESP-IDF component | port/Espressif/esp32_*.c | | **Renesas** | | | | | -| RX64M/RX71M/RX72M | SHA-1, SHA-256 | `WOLFSSL_RENESAS_RX64_HASH` | Auto-detected | port/Renesas/renesas_rx64_*.c | -| RX65N (SCE) | AES, SHA, RSA, ECC, RNG | `WOLFSSL_RENESAS_SCEPROTECT` | Auto-detected | port/Renesas/renesas_*.c | -| RZ/A1/A2 (TSIP) | AES, SHA, RSA, ECC, RNG | `WOLFSSL_RENESAS_TSIP` | Auto-detected | port/Renesas/renesas_tsip_*.c | -| RA4M4/RA6M4 (RSIP) | AES, SHA, RSA, ECC, RNG | `WOLFSSL_RENESAS_RSIP` | Auto-detected | port/Renesas/renesas_rsip*.c | -| RA FSP Secure Manager | AES, SHA, RSA, ECC, HMAC | `WOLFSSL_RENESAS_FSPSM` | Auto-detected | port/Renesas/renesas_fspsm_*.c | +| RX64M/RX71M/RX72M | SHA-1, SHA-256 | `WOLFSSL_RENESAS_RX64_HASH` | user_settings.h | port/Renesas/renesas_rx64_*.c | +| RX65N / RX72N (TSIP) | AES, SHA, RSA, ECC, RNG | `WOLFSSL_RENESAS_TSIP` | user_settings.h | port/Renesas/renesas_tsip_*.c | +| RA6M3 / RA6M4 (SCE Protected Mode) | AES, SHA, RSA, ECC, RNG | `WOLFSSL_RENESAS_SCEPROTECT` | user_settings.h | port/Renesas/renesas_fspsm_*.c | +| RZ/N2L (RSIP) | AES, SHA, RSA, ECC, RNG | `WOLFSSL_RENESAS_RSIP` | user_settings.h | port/Renesas/renesas_fspsm_*.c | +| RA FSP Secure Manager | AES, SHA, RSA, ECC, HMAC | `WOLFSSL_RENESAS_FSPSM` | user_settings.h | port/Renesas/renesas_fspsm_*.c | | **Cypress** | | | | | -| PSoC 6 | AES, SHA, ECC, RNG | `WOLFSSL_PSOC6_CRYPTO` | Auto-detected | port/cypress/psoc6_crypto.c | +| PSoC 6 | AES, SHA, ECC, RNG | `WOLFSSL_PSOC6_CRYPTO` | user_settings.h | port/cypress/psoc6_crypto.c | | **Silicon Labs** | | | | | -| EFR32 / EFM32 (SE) | AES, SHA, ECC, RNG | `WOLFSSL_SILABS_SE_ACCEL` | Auto-detected | port/silabs/silabs_*.c | +| EFR32 / EFM32 (SE) | AES, SHA, ECC, RNG | `WOLFSSL_SILABS_SE_ACCEL` | user_settings.h | port/silabs/silabs_*.c | +| EFR32 Secure Element crypto callback device | AES-ECB/CBC/CTR/GCM/CCM, ChaCha20, CMAC, SHA-1/224/256/384/512, HKDF, PBKDF2, ECDSA, ECDH, RNG | `WOLFSSL_SILABS_CRYPTOCB` | `--enable-silabs-cryptocb` | port/silabs/silabs_cb_*.c | | **Maxim** | | | | | -| MAX3266X | AES-ECB/CBC, RSA | `WOLFSSL_MAX3266X` | Auto-detected | port/maxim/max3266x.c | +| MAX3266X | AES-ECB/CBC, SHA-1/224/256/384/512, TRNG, MAA (RSA/ECC math) | `WOLFSSL_MAX3266X` | user_settings.h | port/maxim/max3266x.c | | MAXQ10XX | AES, SHA, RSA, ECC, RNG | `WOLFSSL_MAXQ10XX_CRYPTO` | `--with-maxq10xx=PART` | port/maxim/maxq10xx.c | | **Microchip** | | | | | -| PIC32MZ | AES, SHA, RNG | `WOLFSSL_PIC32MZ_CRYPT` | Auto-detected | port/pic32/ | -| ATECC508A / 608A | AES, SHA, ECC (ECDH/ECDSA) | `WOLFSSL_ATECC` | Auto-detected | port/atmel/atmel.c | -| **Xilinx** | | | | | -| Zynq / Zynq-7000 | AES, SHA, RSA, ECC | `WOLFSSL_XILINX_CRYPT` | `--enable-xilinx` | port/xilinx/xil-*.c | -| Versal | AES-GCM, SHA-3, RNG | `WOLFSSL_XILINX_CRYPT_VERSAL` | `--enable-xilinx` | port/xilinx/xil-versal-*.c | -| Versal Gen2 (ASU) | TRNG, hashes, HMAC, AES ciphers, CMAC, GMAC, RSA (raw, PSS, OAEP), ECC, ECDH, ECIES, EdDSA, X25519/X448 | `WOLFSSL_VERSAL_GEN2_ASU` | Vitis 2026.1 | port/xilinx/versal_gen2_asu/ | +| PIC32MZ | AES, SHA, RNG | `WOLFSSL_PIC32MZ_CRYPT` | user_settings.h | port/pic32/ | +| ATECC508A / 608A | AES, SHA, ECC (ECDH/ECDSA) | `WOLFSSL_ATECC508A` / `WOLFSSL_ATECC608A` | `--enable-microchip=508` / `--enable-microchip=608` | port/atmel/atmel.c | +| TA100 | RSA, ECC, AES-GCM | `WOLFSSL_MICROCHIP_TA100` | `--enable-microchip=100` | port/atmel/atmel.c | +| PolarFire SoC Athena F5200 (TeraFire) | AES-256-CTR, SHA-384 | `WOLFSSL_MPFS_ATHENA` | `--with-mpfs-athena=PATH` | port/microchip/mpfs_athena.c | +| **Xilinx / AMD** | | | | | +| Zynq UltraScale+ MPSoC | AES-GCM, SHA3-384, RSA | `WOLFSSL_XILINX_CRYPT` | `--enable-xilinx` | port/xilinx/xil-*.c | +| Versal | AES-GCM, SHA-3, RSA, ECDSA, RNG | `WOLFSSL_XILINX_CRYPT_VERSAL` | user_settings.h (`--enable-xilinx` only defines `WOLFSSL_XILINX_CRYPT`) | port/xilinx/xil-versal-*.c | +| Versal Gen2 (ASU) | TRNG, hashes, HMAC, AES ciphers, CMAC, GMAC, RSA (raw, PSS, OAEP), ECC, ECDH, ECIES, EdDSA, X25519/X448 (X25519/X448 need Vitis 2026.1 or later) | `WOLFSSL_VERSAL_GEN2_ASU` | user_settings.h | port/xilinx/versal_gen2_asu/ | +| **Altera** | | | | | +| Agilex 5 SDM (FPGA Crypto Services) | AES, SHA-256/384/512, HMAC, ECDSA sign, ECDH, RNG | `WOLFSSL_ALTERA_FCS` | `--enable-alterafcs` | port/altera/ | +| **Nuvoton** | | | | | +| M2354 | AES-ECB/CBC/CTR/GCM, SHA-1/224/256/384/512, RSA, ECDSA, ECDH, RNG | `WOLFSSL_NUVOTON_M2354` | user_settings.h | port/nuvoton/ | | **Texas Instruments** | | | | | +| TM4C (Tiva) | AES (CBC/CTR/GCM/CCM), 3DES, MD5, SHA-1, SHA-224, SHA-256 | `WOLFSSL_TI_CRYPT` / `WOLFSSL_TI_HASH` | user_settings.h | port/ti/ti-aes.c, ti-des3.c, ti-hash.c, ti-ccm.c | +| AM64x (SA2UL, Cortex-R5F) | TRNG, AES-ECB/CBC/GCM, SHA-256/512, HMAC, CMAC | `WOLFSSL_TI_AM64X_R5` | user_settings.h | port/ti/ti-sa2ul_r5_port.c | | C2000 C28x (AESA crypto callback device) | AES-ECB/CBC/CTR, oscillator jitter entropy | `WOLFSSL_C2000_AES` / `WOLFSSL_C2000_ENTROPY` (with `WOLFSSL_WIDE_BYTE`) | user_settings.h | port/ti/ti-c2000-*.c | | **RealTek** | | | | | -| AmebaPro2 (RTL8735B HUK crypto callback device) | AES, HMAC-SHA256, ECDSA, TRNG | `WOLFSSL_RTL8735B_HUK` / `WOLFSSL_RTL8735B_AES` | user_settings.h | port/realtek/rtl8735b.c | +| AmebaPro2 (RTL8735B HUK crypto callback device) | AES, HMAC-SHA256, ECDSA, TRNG | `WOLFSSL_RTL8735B_HUK` / `WOLFSSL_RTL8735B_AES` | user_settings.h (`--enable-rtl8735b` builds the host compile test) | port/realtek/rtl8735b.c | | **WISeKey / SealSQ** | | | | | -| VaultIC secure element | P-256 sign, verify, keygen, ECDH | `WOLFSSL_VAULTIC` | user_settings.h | port/sealsq/vaultic.c | +| VaultIC secure element | P-256 sign, verify, keygen, ECDH | `WOLFSSL_VAULTIC` | `--enable-vaultic` | port/sealsq/vaultic.c | | **Tropic Square** | | | | | -| TROPIC01 secure element | AES-CBC, AES-GCM, ECDSA, RNG | `WOLFSSL_TROPIC01` | user_settings.h | port/tropicsquare/tropic01.c | +| TROPIC01 secure element | AES-CBC, AES-GCM, ECDSA, RNG | `WOLFSSL_TROPIC01` | `--with-tropic01=PATH` | port/tropicsquare/tropic01.c | | **Vorago** | | | | | | VA416x0 | TRNG (seeds the Hash-DRBG) | `WOLFSSL_VA416X0_TRNG` | user_settings.h | wolfcrypt/src/random.c | -| **ARM CryptoCell** | | | | | -| CC-300/312/700/712/714 | AES, SHA, RSA, ECC, ChaCha, Poly1305 | `WOLFSSL_CRYPTOCELL` | `--enable-cryptocell` | port/arm/cryptocell*.c | +| **Raspberry Pi** | | | | | +| RP2040 / RP2350 (Pico) | RNG | `WOLFSSL_RPIPICO` | user_settings.h | port/rpi_pico/pico.c | +| **Nordic** | | | | | +| nRF51 | RNG | `WOLFSSL_NRF51` | user_settings.h | port/nrf51.c | | **IoT-Safe (SIM)** | ECC, SHA, RNG | `WOLFSSL_IOTSAFE` | `--enable-iotsafe` | port/iotsafe/ | ## D. External Accelerators and Coprocessors @@ -125,17 +178,27 @@ | Product | Algorithms | user_settings.h Macro | configure Option | |---|---|---|---| | Intel QuickAssist (QAT) | AES, RSA, DH, ECC, SHA | `HAVE_INTEL_QA` | `--with-intelqa=PATH` | -| Intel QAT (synchronous) | Same as above | `ENABLED_INTEL_QA_SYNC` | `--with-intelqa-sync=PATH` | +| Intel QAT (synchronous) | Same as above | `HAVE_INTEL_QA_SYNC` | `--with-intelqa-sync=PATH` | | Cavium NITROX | AES, RSA, DH, ECC, SHA | `HAVE_CAVIUM` | `--with-cavium=PATH` | -| Cavium NITROX V | Same as above | `HAVE_CAVIUM_V` | `--with-cavium=PATH` | -| Cavium Octeon (MIPS) | AES, RSA, ECC, SHA | `HAVE_CAVIUM_OCTEON` | `--with-octeon-sync=PATH` | +| Cavium NITROX V | Same as above | `HAVE_CAVIUM_V` | `--with-cavium-v=PATH` | +| Cavium Octeon (MIPS) | AES, RSA, ECC, SHA | `HAVE_CAVIUM_OCTEON_SYNC` | `--with-octeon-sync=PATH` | | NXP CAAM | AES, SHA, RSA, ECC, HMAC, DH | `WOLFSSL_CAAM` | `--enable-caam` | +| NVIDIA CUDA GPU | AES | `HAVE_CUDA` | `--enable-cuda` | +| MagicCrypto library | ARIA cipher; ECDSA, ECDH and SHA-256/384 through a crypto callback | `HAVE_ARIA` | `--enable-aria` | +| PKCS#11 token or HSM | Depends on the token | `HAVE_PKCS11` | `--enable-pkcs11` | ## E. OS Kernel Hardware Offload Interfaces | Interface | Algorithms | user_settings.h Macro | configure Option | |---|---|---|---| -| Linux `/dev/crypto` | AES, SHA-1/256/512, RSA, ECC, DH, HMAC | `WOLFSSL_DEVCRYPTO` | `--enable-devcrypto` | -| Linux Kernel Crypto API | AES, SHA, RSA, ECC, X25519, HMAC | `WOLFSSL_KCAPI` | `--enable-kcapi` | +| Linux `/dev/crypto` | AES, SHA, HMAC, RSA, ECDSA, X25519 | `WOLFSSL_DEVCRYPTO` | `--enable-devcrypto` | +| Linux Kernel Crypto API | AES, SHA, HMAC, RSA, ECC, DH | `WOLFSSL_KCAPI` | `--enable-kcapi` | | Linux AF_ALG | AES, SHA (kernel backend dependent) | `WOLFSSL_AFALG` | `--enable-afalg` | | PSA (Platform Security Architecture) | Vendor implementation dependent | `WOLFSSL_HAVE_PSA` | `--enable-psa` | +| AUTOSAR Csm / CryIf | AES-CBC, RNG, AES-CMAC | `WOLFSSL_AUTOSAR` | `--enable-autosar` | + +## F. Physically Unclonable Functions + +| Type | Function | user_settings.h Macro | configure Option | +|---|---|---|---| +| SRAM PUF | Device key derivation and identity from SRAM start-up values | `WOLFSSL_PUF` + `WOLFSSL_PUF_SRAM` | `--enable-puf` | diff --git a/wolfSSL/src/appendix09.md b/wolfSSL/src/appendix09.md index 93e57c8b..247be3e9 100644 --- a/wolfSSL/src/appendix09.md +++ b/wolfSSL/src/appendix09.md @@ -1,8 +1,8 @@ # Experimenting with Post-Quantum Cryptography -A while back, the wolfSSL team integrated experimental post-quantum cryptographic algorithms into the wolfSSL library. This was done by integrating with the Open Quantum Safe team's liboqs. wolfCrypt now has its own implementations of ML-KEM, ML-DSA, SLH-DSA, Falcon, FrodoKEM and the stateful hash based schemes (LMS/HSS, XMSS/XMSS^MT), so the liboqs integration was removed to keep the code base small and the library easier to maintain. As of wolfSSL 5.9.4 liboqs is not used for any algorithm, and the `--with-liboqs` configure option is deprecated and ignored. +A while back, the wolfSSL team integrated experimental post-quantum cryptographic algorithms into the wolfSSL library. This was done by integrating with the Open Quantum Safe team's liboqs. wolfCrypt now has its own implementations of ML-KEM, ML-DSA, SLH-DSA, Falcon, FrodoKEM and the stateful hash based schemes (LMS/HSS, XMSS/XMSS^MT), so the liboqs integration, and the older integrations with the hash-sigs (LMS/HSS) and xmss-reference (XMSS/XMSS^MT) libraries, were removed to keep the code base small and the library easier to maintain. As of wolfSSL 5.9.4 liboqs is not used for any algorithm, and the `--with-liboqs` configure option is deprecated and ignored. -This appendix is intended for anyone that wants to start learning about post-quantum cryptography in the context of (D)TLS 1.3. It explains why post-quantum algorithms are important, what we have done in response to the quantum threat and how you can start experimenting with these new algorithms. +This appendix is intended for anyone that wants to start learning about post-quantum cryptography in the context of (D)TLS 1.3. It explains why post-quantum algorithms are important, what we have done in response to the quantum threat and how you can start experimenting with these new algorithms. Notes that only apply to DTLS 1.3 are in [Post-Quantum Algorithms with DTLS](#post-quantum-algorithms-with-dtls). **Note**: Some of the post-quantum algorithms are not fully standardized yet. Some OIDs and codepoints are temporary and expected to change in the future. You should have no expectation of backwards compatibility until they are fully standardized. @@ -12,7 +12,7 @@ This appendix is intended for anyone that wants to start learning about post-qua For some time now, many resources have been devoted to the development of quantum computers. So much so that commercialization of cloud quantum computing resources has already begun. While the current state of the art is still not in the realm of being cryptographically relevant, some threat models such as "harvest now, decrypt later" mean that preparations need to happen sooner than the appearance of cryptographically relevant quantum computers. -NIST is leading the way for standardization of a new class of algorithms designed to replace the public key cryptography algorithms that will become vulnerable to quantum computers. At the time of the writing of this passage, NIST has already standardized ML-DSA, ML-KEM, and SLH-DSA. +NIST is leading the way for standardization of a new class of algorithms designed to replace the public key cryptography algorithms that will become vulnerable to quantum computers. At the time of the writing of this passage, NIST has already standardized ML-DSA, ML-KEM, and SLH-DSA. Falcon is being standardized as FN-DSA (FIPS 206), which is still a draft, so wolfSSL treats Falcon as experimental. ML-KEM (Module Lattice Key Encapsulation Mechanism) is a NIST-standardized, lattice-based post-quantum algorithm derived from Kyber. It enables two parties to establish a shared key over an insecure channel using a key encapsulation mechanism, protecting against both classical and quantum adversaries. @@ -20,7 +20,7 @@ ML-DSA (Module Lattice Digital Signature Algorithm) is a NIST-standardized, latt Both ML-KEM and ML-DSA are public-key algorithms designed to resist cryptographically relevant quantum computers. They are part of NIST's Post-Quantum Cryptography standards (FIPS 203 and FIPS 204) and can be deployed today, often in hybrid form, to prepare for the post-quantum era. -Currently, standards organizations have various draft documents describing OIDs and codepoints. NIST is working on bringing these algorithms under the ubmbrella of the CMVP regulatory framework allowing for FIPS-140-3 validations of implementations of these algorithms. +The algorithms themselves are now NIST standards: ML-KEM, ML-DSA and SLH-DSA in FIPS 203, FIPS 204 and FIPS 205, and the stateful hash-based schemes LMS and XMSS in NIST SP 800-208. wolfSSL's upcoming post-quantum FIPS submission covers ML-KEM, ML-DSA, LMS, XMSS and SLH-DSA. What is not final yet is their use in TLS: the codepoints of the ML-KEM groups come from the IETF drafts draft-ietf-tls-mlkem (pure ML-KEM) and draft-ietf-tls-ecdhe-mlkem (hybrids), and those of the SLH-DSA signature schemes from draft-reddy-tls-slhdsa. ### How do we Protect Ourselves? @@ -30,9 +30,9 @@ From a high level perspective, for every TLS 1.3 connection, authentication, int * key establishment algorithms * symmetric cipher algorithms -The threat of quantum computers to conventional cryptography takes two forms. Grover’s algorithm reduces the security of modern symmetric cipher algorithms by approximately half while Shor’s algorithm completely breaks the security of modern authentication and key establishment algorithms. As a result, we can continue to protect our communications using the AES-256 symmetric cipher which is considered sufficiently secure even in the presence of a cryptographically relevant quantum computer. We can then replace our conventional authentication and key establishment algorithms with post-quantum algorithms. Note that during TLS 1.3 handshakes, the ciphersuite specifies the symmetric cipher to be used for the duration of the connection. Both CNSA (Commercial National Security Algorithm Suite) 1.0 and 2.0 prescribe using the AES_256_GCM_SHA384 ciphersuite. For key establishment and authentication, there are post-quantum KEMs (Key Encapsulation Mechanisms) and signature schemes. +The threat of quantum computers to conventional cryptography takes two forms. Grover's algorithm reduces the security of modern symmetric cipher algorithms by approximately half while Shor's algorithm completely breaks the security of modern authentication and key establishment algorithms. As a result, we can continue to protect our communications using the AES-256 symmetric cipher which is considered sufficiently secure even in the presence of a cryptographically relevant quantum computer. We can then replace our conventional authentication and key establishment algorithms with post-quantum algorithms. Note that during TLS 1.3 handshakes, the ciphersuite specifies the symmetric cipher to be used for the duration of the connection. Both CNSA (Commercial National Security Algorithm Suite) 1.0 and 2.0 prescribe using the AES_256_GCM_SHA384 ciphersuite. For key establishment and authentication, there are post-quantum KEMs (Key Encapsulation Mechanisms) and signature schemes. -These use different kinds of math from the conventional algorithms. They are designed specifically for resistance to quantum-computers. The authentication algorithm and KEM that NIST has standardized for use with network protocols are lattice-based algorithms. +These use different kinds of math from the conventional algorithms. They are designed specifically for resistance to quantum-computers. The main signature scheme and KEM that NIST has standardized for use with network protocols are lattice-based algorithms; SLH-DSA (FIPS 205) is a hash-based alternative for signatures. * ML-DSA (Dilithium) Signature Scheme * ML-KEM (KYBER) KEM @@ -46,28 +46,28 @@ These use different kinds of math from the conventional algorithms. They are des **Note**: Dilithium Signature Scheme's AES variants were deprecated and removed as NIST is not considering them for standardization. -**Note**: Removing the liboqs integration also took the FALCON and SPHINCS+ - signature schemes with it at the time. Both are back, implemented - natively in wolfCrypt: SLH-DSA, the standardized form of SPHINCS+ - (FIPS 205), behind `--enable-slhdsa`, and Falcon at levels 1 and 5 - behind `--enable-falcon`, starting with wolfSSL 5.9.4. FrodoKEM, +**Note**: SPHINCS+, which wolfSSL used to take from liboqs, has been replaced + by the native SLH-DSA (FIPS 205) implementation, enabled with + [`--enable-slhdsa`](chapter02.md#--enable-slhdsa). Falcon used liboqs until wolfSSL 5.9.4, which + replaced it with a native implementation of levels 1 and 5, + enabled with `--enable-experimental --enable-falcon`. FrodoKEM, a key encapsulation mechanism, is available too with - `--enable-frodokem` (experimental). + `--enable-experimental --enable-frodokem`. Besides ML-KEM and ML-DSA, wolfSSL also supports these post-quantum algorithms: -* the SLH-DSA (FIPS 205) signature scheme in all twelve parameter sets. SLH-DSA can sign TLS 1.3 and DTLS 1.3 handshakes per draft-reddy-tls-slhdsa; the code points are listed in [Appendix G](appendix07.md#c-9-slh-dsa-fips-205). -* the Falcon signature scheme, native to wolfCrypt with crypto callbacks and ARM DSP / AArch64 NEON acceleration. +* the SLH-DSA (FIPS 205) signature scheme in all twelve parameter sets. `--enable-slhdsa` builds the six SHAKE parameter sets; `--enable-slhdsa=yes,sha2` adds the six SHA2 parameter sets. SLH-DSA can sign TLS 1.3 and DTLS 1.3 handshakes per draft-reddy-tls-slhdsa; the code points are listed in [Appendix G](appendix07.md#c-9-slh-dsa-fips-205). +* the Falcon signature scheme (levels 1 and 5, experimental), native to wolfCrypt with crypto callbacks and ARM DSP / AArch64 NEON acceleration. * the FrodoKEM key encapsulation mechanism (wolfCrypt only, experimental). * the stateful hash based signature schemes LMS/HSS and XMSS/XMSS^MT, covered later in this appendix. -As of wolfSSL 5.9.4 you can also build TLS 1.3 with nothing but post-quantum algorithms: ML-KEM for the key exchange, ML-DSA or SLH-DSA for authentication, and no RSA, ECC or DH. `--enable-all-quantum-crypto` turns on all of the quantum-resistant asymmetric algorithms in one go. +As of wolfSSL 5.9.4 you can also build TLS 1.3 with nothing but post-quantum algorithms: ML-KEM for the key exchange, ML-DSA or SLH-DSA for authentication, and no RSA, ECC or DH. [`--enable-all-quantum-crypto`](chapter02.md#--enable-all-quantum-crypto) turns on ML-KEM, ML-DSA, LMS, XMSS and SLH-DSA (both the SHAKE and the SHA2 parameter sets) in one go. Together with `--enable-experimental` it also turns on Falcon, FrodoKEM and the extra PQ/T hybrid groups. It does not enable the pure ML-KEM TLS groups (`--enable-tls-mlkem-standalone`). -An explanation of lattice-based cryptography would fall outside the scope of this document but more information about these algorithms can be found in their NIST submissions at . +An explanation of lattice-based cryptography would fall outside the scope of this document but more information about these algorithms can be found in their standards: FIPS 203 (), FIPS 204 () and FIPS 205 (). -Unfortunately, it might come as a shock, but we do not actually know that these algorithms will resist attacks from quantum computers. In fact, we do not even know that these algorithms are safe against a conventional computer. Its getting less and less likely, but someone could break lattice-based cryptography. However, as security experts will tell you, this is how cryptography has always worked. Algorithms are good when we start using them, but weaknesses and vulnerabilities are discovered and technology gets better. The post-quantum algorithms are somewhat problematic in that they are relatively new and could use a bit more attention from the community. +Unfortunately, it might come as a shock, but we do not actually know that these algorithms will resist attacks from quantum computers. In fact, we do not even know that these algorithms are safe against a conventional computer. It's getting less and less likely, but someone could break lattice-based cryptography. However, as security experts will tell you, this is how cryptography has always worked. Algorithms are good when we start using them, but weaknesses and vulnerabilities are discovered and technology gets better. The post-quantum algorithms are somewhat problematic in that they are relatively new and could use a bit more attention from the community. -One solution is to not put our full faith into these new algorithms. For now, we can hedge our bets by hybridizing post-quantum algorithms with the conventional algorithms that we actually trust. ECC with NIST standardized curves seem like good candidates as we have to keep using them since FIPS 140-3 compliance is a priority. For this reason, we have not only implemented post-quantum KEMs but also hybridized them with ECDH over NIST approved curves. Please see our list of hybrid groups below. +One solution is to not put our full faith into these new algorithms. For now, we can hedge our bets by hybridizing post-quantum algorithms with the conventional algorithms that we actually trust. ECC with NIST standardized curves seems like a good candidate as we have to keep using them since FIPS 140-3 compliance is a priority. For this reason, we have not only implemented post-quantum KEMs but also hybridized them with ECDH over NIST approved curves (SecP256r1MLKEM768 and SecP384r1MLKEM1024). wolfSSL also supports the X25519 hybrid X25519MLKEM768, which is the default ClientHello key share when Curve25519 is enabled because it is the hybrid that servers are most likely to accept. Please see our list of hybrid groups below. ## Getting Started with Post-Quantum algorithms in wolfSSL @@ -75,60 +75,109 @@ The following instructions will get you started from a clean Linux development e ### Build Instructions -Please see the wolfSSL repo's INSTALL file (https://github.com/wolfSSL/wolfssl/blob/master/INSTALL). Item 15 has instructions on how to configure and build wolfSSL with ML-KEM and ML-DSA enabled. None of the post-quantum algorithms need an external library; they all build from the wolfSSL sources. A typical configuration is: +None of the post-quantum algorithms need an external library; they all build from the wolfSSL sources. A typical configuration is: ```sh -./configure --enable-mlkem --enable-mldsa --enable-slhdsa +./configure --enable-mlkem --enable-mldsa --enable-slhdsa=yes,sha2 ``` For the experimental algorithms, add `--enable-experimental --enable-falcon` or `--enable-experimental --enable-frodokem`. Those two options take sub-options as well; see [`--enable-falcon`](chapter02.md#--enable-falcon) and [`--enable-frodokem`](chapter02.md#--enable-frodokem). -You will need the patched OQS OpenSSL Provider fork in order to generate X.509 certificates with post-quantum cryptographic keys and signatures. Instructions can be found at https://github.com/wolfSSL/osp/tree/master/oqs/README.md. For your convenience, pre-generated certificates can be found there as well. +Item 15 of the wolfSSL repo's INSTALL file (https://github.com/wolfSSL/wolfssl/blob/master/INSTALL) covers the same ground, but it uses the older option names `--enable-kyber` and `--enable-dilithium` (aliases for `--enable-mlkem` and [`--enable-mldsa`](chapter02.md#--enable-mldsa)) and the SecP521r1MLKEM1024 group, which needs `--enable-experimental --enable-extra-pqc-hybrids`. + +#### What Is Enabled by Default + +* ML-KEM is enabled by default, unless SHA-3 or SHAKE is disabled. `--enable-mlkem` is only needed to pass sub-options, and [`--disable-mlkem`](chapter02.md#--disable-mlkem) turns ML-KEM off. +* The standard PQ/T hybrid groups SecP256r1MLKEM768, SecP384r1MLKEM1024 and X25519MLKEM768 come with [`--enable-pqc-hybrids`](chapter02.md#--disable-pqc-hybrids), which is on by default. X25519MLKEM768 also needs [`--enable-curve25519`](chapter02.md#--enable-curve25519), which is off by default. +* The pure ML-KEM groups ML_KEM_512, ML_KEM_768 and ML_KEM_1024 need [`--enable-tls-mlkem-standalone`](chapter02.md#--enable-tls-mlkem-standalone). The configure script only turns it on by itself when the build has no ECC, Curve25519 or Curve448 to make hybrids with. +* The extra hybrid groups SecP256r1MLKEM512, SecP384r1MLKEM768, SecP521r1MLKEM1024, X25519MLKEM512 and X448MLKEM768 need `--enable-experimental --enable-extra-pqc-hybrids`. They are not available in FIPS v7 builds. +* The round 3 Kyber groups need `--enable-mlkem=yes,original` (Kyber instead of ML-KEM) or `--enable-mlkem=yes,all` (Kyber and ML-KEM). Keep `yes` in the list: without it no Kyber or ML-KEM parameter set is built. +* If the application does not configure any groups, a wolfSSL client sends an X25519MLKEM768 key share when Curve25519 is built in, and a SecP256r1MLKEM768 key share otherwise. +* ML-DSA, SLH-DSA, LMS and XMSS are off by default. Falcon and FrodoKEM also need `--enable-experimental`. + +[Appendix G](appendix07.md#b-7-ml-kem-standalone) lists all of these groups with their code points: [B-7 ML-KEM Standalone](appendix07.md#b-7-ml-kem-standalone), [B-8 ML-KEM Hybrid (Standard)](appendix07.md#b-8-ml-kem-hybrid-standard), [B-9 ML-KEM Hybrid (Experimental)](appendix07.md#b-9-ml-kem-hybrid-experimental) and [B-10 Kyber Round 3 Legacy](appendix07.md#b-10-kyber-round-3-legacy). + +#### Post-Quantum Test Certificates + +You do not need any extra tools to try out post-quantum authentication: the wolfSSL source tree has ready-made test certificates and keys. `certs/mldsa/` has ML-DSA certificates, including an ML-DSA-87 CA (`mldsa87-ca-cert.pem`) with an ML-DSA-65 leaf certificate (`mldsa65-leaf87ca-cert.pem`). `certs/slhdsa/` has SLH-DSA root certificates with ML-DSA-44 and SLH-DSA server and client certificates. They were generated with OpenSSL 3.5 or later, which can create ML-DSA and SLH-DSA keys and certificates natively. Older ML-DSA certificate chains made with the OQS provider, and the instructions for making them, are in the wolfSSL OSP repository: https://github.com/wolfSSL/osp/tree/master/oqs/README.md. ### Making a Quantum Safe TLS Connection -You can run the server and client like this in separate terminals: +You can run the server and client like this in separate terminals, from the root of the wolfSSL source tree: + +```sh +examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \ + -A certs/mldsa/mldsa87-ca-cert.pem \ + -c certs/mldsa/mldsa65-leaf87ca-cert.pem \ + -k certs/mldsa/mldsa65-leaf87ca-key.pem \ + --pqc SecP384r1MLKEM1024 +``` + +```sh +examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \ + -A certs/mldsa/mldsa87-ca-cert.pem \ + -c certs/mldsa/mldsa65-leaf87ca-cert.pem \ + -k certs/mldsa/mldsa65-leaf87ca-key.pem \ + --pqc SecP384r1MLKEM1024 +``` + +Both sides print `SSL curve name is SecP384r1MLKEM1024`, and the client prints the server's reply, `I hear you fa shizzle!`. You have just achieved a fully quantum-safe TLS 1.3 connection using AES-256 for symmetric encryption, the ML-DSA signature scheme for authentication and ECDHE hybridized with ML-KEM for key establishment. Both peers authenticate with the same ML-DSA-65 certificate, issued by the ML-DSA-87 CA. + +To authenticate with SLH-DSA instead, use the SLH-DSA certificates, which have separate server and client certificates issued by an SLH-DSA-SHAKE-128s root: ```sh examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \ - -A ../osp/oqs/mldsa87_root_cert.pem \ - -c ../osp/oqs/mldsa44_entity_cert.pem \ - -k ../osp/oqs/mldsa44_entity_key.pem \ - --pqc SecP521r1MLKEM1024 + -A certs/slhdsa/root-slhdsa-shake-128s.pem \ + -c certs/slhdsa/server-slhdsa-shake-128s.pem \ + -k certs/slhdsa/server-slhdsa-shake-128s-priv.pem \ + --pqc SecP384r1MLKEM1024 ``` ```sh examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \ - -A ../osp/oqs/mldsa44_root_cert.pem \ - -c ../osp/oqs/mldsa87_entity_cert.pem \ - -k ../osp/oqs/mldsa87_entity_key.pem \ - --pqc SecP521r1MLKEM1024 + -A certs/slhdsa/root-slhdsa-shake-128s.pem \ + -c certs/slhdsa/client-slhdsa-shake-128s.pem \ + -k certs/slhdsa/client-slhdsa-shake-128s-priv.pem \ + --pqc SecP384r1MLKEM1024 ``` -You have just achieved a fully quantum-safe TLS 1.3 connection using AES-256 for symmetric encryption, the ML-DSA signature scheme for authentication and ECDHE hybridized with ML-KEM for key establishment. +`--pqc` takes one of the group names listed in [Post Quantum Algorithm Variant Names](#post-quantum-algorithm-variant-names). The `-?` help of the examples lists every group name whatever the build, and a group that is not compiled in fails with `invalid post-quantum KEM specified`. For example, X25519MLKEM768 needs `--enable-curve25519`, and SecP521r1MLKEM1024 needs `--enable-experimental --enable-extra-pqc-hybrids`. Without `--pqc` the example client sends only classical key shares (P-256, and FFDHE 2048 when it is built in), so it does not show the library's default hybrid key share (see [Developer Notes](#developer-notes)). Further information about other post-quantum examples can be found at https://github.com/wolfSSL/wolfssl-examples/blob/master/pq/README.md. +### Post-Quantum Algorithms with DTLS + +The same groups and certificates work for DTLS 1.3. Configure wolfSSL with [`--enable-dtls13`](chapter02.md#--enable-dtls13) as well, and add `-u` to the example server and client commands above. ML-KEM key shares can make a ClientHello bigger than a single datagram, so when ML-KEM and DTLS 1.3 are both enabled, configure also turns on DTLS 1.3 ClientHello fragmentation (`--enable-dtls-frag-ch`, `WOLFSSL_DTLS_CH_FRAG`). If its first ClientHello would have to be fragmented, a wolfSSL client sends it with an empty key share. The server answers with a HelloRetryRequest, and the client sends its key share in the second ClientHello, which may be fragmented. The server has to allow fragmented ClientHellos with `wolfSSL_dtls13_allow_ch_frag()`; in builds with ML-KEM this is the default. A DTLS 1.3 server with cookies disabled can also process a fragmented first ClientHello, but only while `wolfSSL_dtls13_allow_ch_frag()` is on. + ## Post Quantum Algorithm Variant Names -Post-Quantum algorithm variant names: +Post-Quantum algorithm variant names: -NIST Security Level | PQC Variant Name --------------------- | --------------------------- -2 | `ML_DSA_44` -3 | `ML_DSA_65` -5 | `ML_DSA_87` -1 | `ML_KEM_512` -3 | `ML_KEM_768` -5 | `ML_KEM_1024` +NIST Security Level | Algorithm | wolfCrypt identifier | TLS group name +-------------------- | ----------- | -------------------- | --------------- +2 | ML-DSA-44 | `WC_ML_DSA_44` | n/a +3 | ML-DSA-65 | `WC_ML_DSA_65` | n/a +5 | ML-DSA-87 | `WC_ML_DSA_87` | n/a +1 | ML-KEM-512 | `WC_ML_KEM_512` | `ML_KEM_512` +3 | ML-KEM-768 | `WC_ML_KEM_768` | `ML_KEM_768` +5 | ML-KEM-1024 | `WC_ML_KEM_1024` | `ML_KEM_1024` -Post-Quantum hybrid KEM names: +The wolfCrypt identifiers select the parameter set, for example with `wc_MlDsaKey_SetParams()` and `wc_MlKemKey_Init()`. The TLS group names are what you pass to `--pqc` in the example client and server, and to `wolfSSL_CTX_set1_groups_list()` / `wolfSSL_set1_groups_list()`, which also accept `MLKEM512`, `MLKEM768` and `MLKEM1024`. The pure ML-KEM groups need `--enable-tls-mlkem-standalone`. -wolfSSL Variant Name | NIST ECC Curve and PQC Submission Variant Name --------------------- | ---------------------------------------------- -`SecP256r1MLKEM512` | ECDSA P-256 and KYBER512 -`SecP384r1MLKEM768` | ECDSA P-384 and KYBER768 -`SecP521r1MLKEM1024` | ECDSA P-521 and KYBER1024 +Post-Quantum hybrid KEM names. Each hybrid combines ECDH key agreement on the named curve with ML-KEM (FIPS 203): + +wolfSSL Group Name | Code Point | Combination | configure Options +-------------------- | ---------- | ------------------------- | ----------------- +`SecP256r1MLKEM768` | 4587 | ECDH P-256 + ML-KEM-768 | Default +`X25519MLKEM768` | 4588 | X25519 + ML-KEM-768 | Default, needs `--enable-curve25519` +`SecP384r1MLKEM1024` | 4589 | ECDH P-384 + ML-KEM-1024 | Default +`SecP256r1MLKEM512` | 12107 | ECDH P-256 + ML-KEM-512 | `--enable-experimental --enable-extra-pqc-hybrids` +`SecP384r1MLKEM768` | 12108 | ECDH P-384 + ML-KEM-768 | `--enable-experimental --enable-extra-pqc-hybrids` +`SecP521r1MLKEM1024` | 12109 | ECDH P-521 + ML-KEM-1024 | `--enable-experimental --enable-extra-pqc-hybrids` +`X25519MLKEM512` | 12214 | X25519 + ML-KEM-512 | As above, plus `--enable-curve25519` +`X448MLKEM768` | 12215 | X448 + ML-KEM-768 | As above, plus `--enable-curve448` + +The default hybrids use the code points of draft-ietf-tls-ecdhe-mlkem; the extra hybrids use code points from the Open Quantum Safe provider. See also [Appendix G](appendix07.md#b-8-ml-kem-hybrid-standard). ## Cryptographic Artifact Sizes @@ -136,776 +185,228 @@ All sizes are in bytes. Post-Quantum Signature Scheme Artifact Sizes: -PQC Variant Name | Public Key Size | Private Key Size | Maximum Signature Size +Parameter Set | Public Key Size | Private Key Size | Maximum Signature Size ---------------- | --------------- | ---------------- | ---------------------- -ML_DSA_44 | 1312 | 2560 | 2420 -ML_DSA_65 | 1952 | 4032 | 3309 -ML_DSA_87 | 2592 | 4896 | 4627 +ML-DSA-44 | 1312 | 2560 | 2420 +ML-DSA-65 | 1952 | 4032 | 3309 +ML-DSA-87 | 2592 | 4896 | 4627 +Falcon level 1 | 897 | 1281 | 666 +Falcon level 5 | 1793 | 2305 | 1280 + +SLH-DSA Artifact Sizes (the SHA2 and SHAKE variants of a parameter set have the same sizes): + +Parameter Set | Public Key Size | Private Key Size | Signature Size +---------------- | --------------- | ---------------- | -------------- +SLH-DSA-128s | 32 | 64 | 7856 +SLH-DSA-128f | 32 | 64 | 17088 +SLH-DSA-192s | 48 | 96 | 16224 +SLH-DSA-192f | 48 | 96 | 35664 +SLH-DSA-256s | 64 | 128 | 29792 +SLH-DSA-256f | 64 | 128 | 49856 Post-Quantum KEM Artifact Sizes: -PQC Variant Name | Public Key Size | Private Key Size | Ciphertext Size | Shared Secret Size +Parameter Set | Public Key Size | Private Key Size | Ciphertext Size | Shared Secret Size ---------------- | --------------- | ---------------- | --------------- | ------------------ -ML_KEM_512 | 800 | 1632 | 768 | 32 -ML_KEM_768 | 1184 | 2400 | 1088 | 32 -ML_KEM_1024 | 1568 | 3168 | 1568 | 32 +ML-KEM-512 | 800 | 1632 | 768 | 32 +ML-KEM-768 | 1184 | 2400 | 1088 | 32 +ML-KEM-1024 | 1568 | 3168 | 1568 | 32 + +The sizes of the LMS/HSS and XMSS/XMSS^MT keys and signatures are in [Post-Quantum Stateful Hash-Based Signatures](#post-quantum-stateful-hash-based-signatures). ## Statistics -The following statistics and benchmarks were taken on an 11th GenIntel Core i7-1185G7@3-GHz with 8 cores running Ubuntu 22.04.5 LTS +The following statistics and benchmarks were taken with wolfSSL 5.9.4 (master branch, November 2026) on an Apple M5 (4 performance and 6 efficiency cores) running macOS 27.2, built with Apple clang 21. wolfSSL: ```text -./configure --enable-kyber \ - --enable-dilithium \ +./configure --enable-mlkem \ + --enable-mldsa \ + --enable-tls-mlkem-standalone \ + --enable-experimental \ + --enable-extra-pqc-hybrids \ + --enable-curve25519 \ --disable-psk \ --disable-shared \ - --enable-intelasm \ - --enable-aesni \ + --enable-armasm \ --enable-sp-math-all \ --enable-sp-asm \ CFLAGS="-Os" ``` -**Note**: We are primarily benchmarking the post-quantum algorithms, but leave some conventional algorithms for comparison purposes. +**Note**: We are primarily benchmarking the post-quantum algorithms, but leave some conventional algorithms for comparison purposes. The pure ML-KEM groups and the extra hybrids are enabled so that they can be measured too. ### Runtime Binary Sizes -The `tls_bench` example application binary file is 2498432 bytes after being built then stripped (Approximately 2.4M). Without `--enable-kyber --enable-dilithium` it is 2290912 bytes after being built then stripped (Approximately 2.2M). This is a difference of 207520 bytes (Approximately 200K). +The `tls_bench` example application binary file is 2507328 bytes after being built then stripped (Approximately 2.4M). With `--disable-mlkem` instead of `--enable-mlkem`, and without `--enable-mldsa`, `--enable-tls-mlkem-standalone`, `--enable-experimental` and `--enable-extra-pqc-hybrids`, it is 2273088 bytes after being built then stripped (Approximately 2.2M). This is a difference of 234240 bytes (Approximately 229K). ### TLS 1.3 Data Transmission Sizes -The following results were taken by running the example server and client and recording all information being transmitted via wireshark. This includes the TLS 1.3 handshake with mutual authentication, "hello wolfssl!" and "I hear you fa shizzle!" messages. The `tcp.len` of all packets were summed: - -Ciphersuite | Authentication | Key Establishment | Total Bytes ----------------------- | -------------------- | --------------------- | ----------- -TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ECC SECP256R1 | 5455 -TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ML_KEM_512 | 6633 -TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ML_KEM_768 | 7337 -TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ML_KEM_1024 | 8201 -TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP256r1MLKEM512 | 6763 -TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP384r1MLKEM768 | 7531 -TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP521r1MLKEM1024 | 8467 -TLS_AES_256_GCM_SHA384 | ML_DSA_44 | ECC SECP256R1 | 7918 -TLS_AES_256_GCM_SHA384 | ML_DSA_65 | ECC SECP256R1 | 10233 -TLS_AES_256_GCM_SHA384 | ML_DSA_87 | ECC SECP256R1 | 13477 - -### Heap and Stack Usage - -NOTE: This is out of date. These were obtained when wolfSSL was using the liboqs - implementations of these algorithms. This is left here for historical - purposes. - -These statistics were obtained by adding the following configuration flags: `--enable-trackmemory --enable-stacksize`. - -Memory use for server sign and client verify without server authentication of the client, TLS13-AES256-GCM-SHA384 ciphersuite and ECC SECP256R1 for key exchange. - -```text -Server FALCON_LEVEL1 - -stack used = 48960 -total Allocs = 250 -heap total = 113548 -heap peak = 40990 - -Client FALCON_LEVEL1 - -stack used = 29935 -total Allocs = 768 -heap total = 179427 -heap peak = 41765 - -Server FALCON_LEVEL5 - -stack used = 89088 -total Allocs = 250 -heap total = 125232 -heap peak = 45630 - -Client FALCON_LEVEL5 - -stack used = 29935 -total Allocs = 768 -heap total = 191365 -heap peak = 47469 - -Server DILITHIUM_LEVEL2 - -stack used = 56328 -total Allocs = 243 -total Deallocs = 243 -total Bytes = 128153 -peak Bytes = 50250 - -Client DILITHIUM_LEVEL2 - -stack used = 30856 -total Allocs = 805 -total Deallocs = 805 -total Bytes = 206412 -peak Bytes = 56299 - -Server DILITHIUM_LEVEL3 - -stack used = 86216 -total Allocs = 243 -total Deallocs = 243 -total Bytes = 140128 -peak Bytes = 55161 - -Client DILITHIUM_LEVEL3 - -stack used = 33928 -total Allocs = 805 -total Deallocs = 805 -total Bytes = 220633 -peak Bytes = 61245 - -Server DILITHIUM_LEVEL5 +The following results were taken by running the example server and client and counting all the TCP payload bytes sent in both directions (the same as summing the `tcp.len` of all packets in Wireshark). This includes the TLS 1.3 handshake with mutual authentication, "hello wolfssl!" and "I hear you fa shizzle!" messages. Both peers use the same kind of certificate: the RSA rows use the examples' default certificates, and the ML-DSA rows use the self-signed `certs/mldsa/mldsa-cert.pem` and `certs/mldsa/mldsa-key.pem` on both sides. For example: -stack used = 119944 -total Allocs = 243 -total Deallocs = 243 -total Bytes = 152046 -peak Bytes = 59829 - -Client DILITHIUM_LEVEL5 - -stack used = 40328 -total Allocs = 805 -total Deallocs = 805 -total Bytes = 238167 -peak Bytes = 67049 - -Server RSA 2048 - -stack used = 52896 -total Allocs = 253 -heap total = 121784 -heap peak = 39573 - -Client RSA 2048 - -stack used = 54640 -total Allocs = 897 -heap total = 202472 -heap peak = 41760 +```sh +examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 --pqc ML_KEM_768 +examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 --pqc ML_KEM_768 ``` -Memory use for KEM groups. TLS13-AES256-GCM-SHA384 ciphersuite and RSA-2048 for client authentication of the server and without server authentication of the client. - -```text -Server KYBER_LEVEL1 - -stack used = 52896 -total Allocs = 206 -heap total = 66864 -heap peak = 28474 - -Client KYBER_LEVEL1 - -stack used = 54640 -total Allocs = 879 -heap total = 147235 -heap peak = 44538 - -Server KYBER_LEVEL3 - -stack used = 52896 -total Allocs = 206 -heap total = 67888 -heap peak = 28794 - -Client KYBER_LEVEL3 - -stack used = 54640 -total Allocs = 879 -heap total = 149411 -heap peak = 46010 - -Server KYBER_LEVEL5 - -stack used = 52896 -total Allocs = 206 -heap total = 69232 -heap peak = 29274 - -Client KYBER_LEVEL5 - -stack used = 54640 -total Allocs = 879 -heap total = 151907 -heap peak = 47642 - -Server KYBER_90S_LEVEL1 - -stack used = 52896 -total Allocs = 206 -heap total = 66864 -heap peak = 28474 - -Client KYBER_90S_LEVEL1 - -stack used = 54640 -total Allocs = 879 -heap total = 147235 -heap peak = 44538 - -Server KYBER_90S_LEVEL3 - -stack used = 52896 -total Allocs = 206 -heap total = 67888 -heap peak = 28794 - -Client KYBER_90S_LEVEL3 - -stack used = 54640 -total Allocs = 879 -heap total = 149411 -heap peak = 46010 - -Server KYBER_90S_LEVEL5 - -stack used = 52896 -total Allocs = 206 -heap total = 69232 -heap peak = 29274 - -Client KYBER_90S_LEVEL5 - -stack used = 54640 -total Allocs = 879 -heap total = 151907 -heap peak = 47642 - -Server P256_KYBER_LEVEL1 - -stack used = 52896 -total Allocs = 223 -heap total = 118940 -heap peak = 37652 - -Client P256_KYBER_LEVEL1 - -stack used = 54640 -total Allocs = 896 -heap total = 199376 -heap peak = 48932 - -Server P384_KYBER_LEVEL3 - -stack used = 52896 -total Allocs = 223 -heap total = 120108 -heap peak = 38468 - -Client P384_KYBER_LEVEL3 - -stack used = 54640 -total Allocs = 896 -heap total = 201728 -heap peak = 50468 - -Client Server P521_KYBER_LEVEL5 - -stack used = 52896 -total Allocs = 223 -heap total = 121614 -heap peak = 39458 - -Client P521_KYBER_LEVEL5 - -stack used = 54640 -total Allocs = 896 -heap total = 204422 -heap peak = 52172 - -Client Server P256_KYBER_90S_LEVEL1 - -stack used = 52896 -total Allocs = 223 -heap total = 118940 -heap peak = 37652 +For the ML-DSA rows, `-A certs/mldsa/mldsa44-cert.pem -c certs/mldsa/mldsa44-cert.pem -k certs/mldsa/mldsa44-key.pem` (or the 65 or 87 files) was added to both commands. For the rows without `--pqc`, the client was run with `-Y` so that it sends only a P-256 key share (by default it also sends an FFDHE 2048 key share). The ClientHello lists every group the build supports, so a build with fewer groups sends slightly less data. -Client P256_KYBER_90S_LEVEL1 - -stack used = 54640 -total Allocs = 896 -heap total = 199376 -heap peak = 48932 - -Server P384_KYBER_90S_LEVEL3 - -stack used = 52896 -total Allocs = 223 -heap total = 120108 -heap peak = 38468 - -Client P384_KYBER_90S_LEVEL3 - -stack used = 54640 -total Allocs = 896 -heap total = 201728 -heap peak = 50468 - -Server P521_KYBER_90S_LEVEL5 - -stack used = 52896 -total Allocs = 223 -heap total = 121614 -heap peak = 39458 - -Client P521_KYBER_90S_LEVEL5 - -stack used = 54640 -total Allocs = 896 -heap total = 204422 -heap peak = 52172 - -Server ECDSA SECP256R1 - -stack used = 52896 -total Allocs = 253 -heap total = 121784 -heap peak = 39573 +Ciphersuite | Authentication | Key Establishment | Total Bytes +---------------------- | -------------------- | --------------------- | ----------- +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ECC SECP256R1 | 5230 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ML_KEM_512 | 6668 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ML_KEM_768 | 7372 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | ML_KEM_1024 | 8236 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP256r1MLKEM768 | 7502 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | X25519MLKEM768 | 7436 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP384r1MLKEM1024 | 8430 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP256r1MLKEM512 | 6798 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP384r1MLKEM768 | 7566 +TLS_AES_256_GCM_SHA384 | RSA 2048 bit | SecP521r1MLKEM1024 | 8502 +TLS_AES_256_GCM_SHA384 | ML-DSA-44 | ECC SECP256R1 | 13918 +TLS_AES_256_GCM_SHA384 | ML-DSA-44 | SecP384r1MLKEM1024 | 17118 +TLS_AES_256_GCM_SHA384 | ML-DSA-65 | ECC SECP256R1 | 18754 +TLS_AES_256_GCM_SHA384 | ML-DSA-65 | SecP384r1MLKEM1024 | 21954 +TLS_AES_256_GCM_SHA384 | ML-DSA-87 | ECC SECP256R1 | 25306 +TLS_AES_256_GCM_SHA384 | ML-DSA-87 | SecP384r1MLKEM1024 | 28506 + +The ML_KEM_* rows need `--enable-tls-mlkem-standalone`, the SecP256r1MLKEM512, SecP384r1MLKEM768 and SecP521r1MLKEM1024 rows need `--enable-experimental --enable-extra-pqc-hybrids`, and the X25519MLKEM768 row needs `--enable-curve25519`. -Client ECDSA SECP256R1 +### Heap and Stack Usage -stack used = 54640 -total Allocs = 897 -heap total = 202472 -heap peak = 41760 -``` +These statistics were obtained by adding the following configuration flags: `--enable-trackmemory --enable-stacksize`. The example server and client then run in a thread whose stack use is measured, and print the stack used and the heap use between wolfSSL initialization and cleanup: the number of allocations, the total number of bytes allocated and the peak number of bytes in use at any one time. The figures include loading the certificates and keys, and they change with the build options. + +Memory use for server sign and client verify without server authentication of the client, TLS_AES_256_GCM_SHA384 ciphersuite and ECC SECP256R1 for key exchange. The server was run with `-d`, and the client with `-x` so that it loads no certificate of its own and with `-Y` so that it sends only a P-256 key share. The ECDSA rows use `certs/server-ecc.pem`, and the ML-DSA rows the self-signed `certs/mldsa/mldsa-cert.pem`. + +Authentication | Side | Stack Used | Allocations | Heap Total | Heap Peak +---------------- | ------ | ---------- | ----------- | ---------- | --------- +RSA 2048 | Server | 14064 | 53 | 56373 | 22214 +RSA 2048 | Client | 16056 | 66 | 59229 | 20745 +ECDSA P-256 | Server | 14064 | 47 | 29455 | 16106 +ECDSA P-256 | Client | 16056 | 50 | 31522 | 14290 +ML-DSA-44 | Server | 14064 | 52 | 170031 | 78217 +ML-DSA-44 | Client | 16056 | 52 | 114087 | 53314 +ML-DSA-65 | Server | 14064 | 52 | 247775 | 110817 +ML-DSA-65 | Client | 16056 | 52 | 160841 | 75579 +ML-DSA-87 | Server | 14064 | 52 | 367873 | 158962 +ML-DSA-87 | Client | 16056 | 52 | 236231 | 111585 + +Memory use for KEM groups. TLS_AES_256_GCM_SHA384 ciphersuite and RSA-2048 for client authentication of the server and without server authentication of the client. The server was run with `-d` and the client with `-x`. The group was selected with `--pqc ` on both sides (`-t` for X25519, and `-Y` on the client for SECP256R1). + +Key Establishment | Side | Stack Used | Allocations | Heap Total | Heap Peak +------------------ | ------ | ---------- | ----------- | ---------- | --------- +ECC SECP256R1 | Server | 14064 | 53 | 56373 | 22214 +ECC SECP256R1 | Client | 16056 | 66 | 59229 | 20745 +ECC X25519 | Server | 13320 | 54 | 48101 | 22181 +ECC X25519 | Client | 16056 | 66 | 50881 | 20712 +ML_KEM_512 | Server | 13320 | 54 | 62613 | 25854 +ML_KEM_512 | Client | 16056 | 70 | 72401 | 23112 +ML_KEM_768 | Server | 13320 | 54 | 68117 | 31038 +ML_KEM_768 | Client | 16056 | 70 | 82577 | 28765 +ML_KEM_1024 | Server | 13320 | 54 | 74965 | 37406 +ML_KEM_1024 | Client | 16056 | 70 | 95281 | 36477 +SecP256r1MLKEM768 | Server | 14832 | 61 | 78171 | 32546 +SecP256r1MLKEM768 | Client | 16056 | 80 | 93975 | 30208 +X25519MLKEM768 | Server | 13320 | 61 | 69781 | 32414 +X25519MLKEM768 | Client | 16056 | 80 | 85585 | 30109 +SecP384r1MLKEM1024 | Server | 18544 | 61 | 85691 | 39522 +SecP384r1MLKEM1024 | Client | 19376 | 80 | 107735 | 38496 +SecP256r1MLKEM512 | Server | 14832 | 61 | 72347 | 28099 +SecP256r1MLKEM512 | Client | 16056 | 80 | 83095 | 24737 +SecP384r1MLKEM768 | Server | 18544 | 61 | 78363 | 32674 +SecP384r1MLKEM768 | Client | 19376 | 80 | 94167 | 30304 +SecP521r1MLKEM1024 | Server | 24032 | 61 | 85907 | 39666 +SecP521r1MLKEM1024 | Client | 24864 | 80 | 107951 | 38604 ### Benchmarks -The following benchmarks were obtained with the following configuration flags: - -```text -./configure --enable-kyber \ - --enable-dilithium \ - --disable-shared \ - --enable-intelasm \ - --enable-aesni \ - --enable-sp \ - --enable-sp-math \ - --enable-sp-asm \ - CFLAGS="-Os -DECC_USER_CURVES -DHAVE_ECC256 -DHAVE_ECC384" -``` +The following benchmarks were obtained with the configuration flags shown at the start of [Statistics](#statistics). #### Benchmarks from wolfCrypt -**Note**: Only a single core is used. +**Note**: Only a single core is used. `-ecc` measures P-256 only; `-ecc-all`, `-p384` and `-p521` measure other curves. `-ml-kem-512`, `-ml-dsa-44` and so on select a single parameter set, and `-slhdsa`, `-falcon_level1`, `-falcon_level5`, `-lms_hss` and `-xmss_xmssmt` measure the other post-quantum algorithms when they are built in. On AArch64 the "Cycles" figures are counted with the system timer (its frequency is printed as "Clock frequency"), not in CPU core cycles. ```text -CPU: Intel x86_64 - avx1 avx2 rdrand rdseed bmi2 aesni adx movbe bmi1 sha -Math: Multi-Precision: Disabled - Single Precision: ecc 256 384 521 rsa/dh 2048 3072 4096 asm sp_x86_64.c - -ECC SECP256R1 key gen 95600 ops took 1.000 sec, avg 0.010 ms, 95587.830 ops/sec -ECDHE SECP256R1 agree 24800 ops took 1.003 sec, avg 0.040 ms, 24737.512 ops/sec -ECDSA SECP256R1 sign 61400 ops took 1.001 sec, avg 0.016 ms, 61337.775 ops/sec -ECDSA SECP256R1 verify 23000 ops took 1.001 sec, avg 0.044 ms, 22976.012 ops/sec -ML-KEM 512 key gen 284600 ops took 1.000 sec, avg 0.004 ms, 284565.467 ops/sec -ML-KEM 512 encap 270800 ops took 1.000 sec, avg 0.004 ms, 270749.585 ops/sec -ML-KEM 512 decap 172900 ops took 1.000 sec, avg 0.006 ms, 172896.249 ops/sec -ML-KEM 768 key gen 159800 ops took 1.000 sec, avg 0.006 ms, 159776.306 ops/sec -ML-KEM 768 encap 152800 ops took 1.000 sec, avg 0.007 ms, 152765.071 ops/sec -ML-KEM 768 decap 100100 ops took 1.000 sec, avg 0.010 ms, 100091.147 ops/sec -ML-KEM 1024 key gen 108300 ops took 1.000 sec, avg 0.009 ms, 108277.024 ops/sec -ML-KEM 1024 encap 104400 ops took 1.000 sec, avg 0.010 ms, 104388.900 ops/sec -ML-KEM 1024 decap 74100 ops took 1.001 sec, avg 0.014 ms, 74057.147 ops/sec -ML-DSA 44 key gen 20700 ops took 1.004 sec, avg 0.049 ms, 20617.041 ops/sec -ML-DSA 44 sign 5100 ops took 1.019 sec, avg 0.200 ms, 5003.233 ops/sec -ML-DSA 44 verify 18500 ops took 1.005 sec, avg 0.054 ms, 18403.134 ops/sec -ML-DSA 65 key gen 10200 ops took 1.007 sec, avg 0.099 ms, 10133.468 ops/sec -ML-DSA 65 sign 2900 ops took 1.004 sec, avg 0.346 ms, 2887.112 ops/sec -ML-DSA 65 verify 11600 ops took 1.005 sec, avg 0.087 ms, 11544.122 ops/sec -ML-DSA 87 key gen 7700 ops took 1.013 sec, avg 0.132 ms, 7598.278 ops/sec -ML-DSA 87 sign 2600 ops took 1.000 sec, avg 0.385 ms, 2599.634 ops/sec -ML-DSA 87 verify 7200 ops took 1.007 sec, avg 0.140 ms, 7152.274 ops/sec +./wolfcrypt/benchmark/benchmark -ecc -x25519 -ml-kem -ml-dsa +------------------------------------------------------------------------------ + wolfSSL version 5.9.4 +------------------------------------------------------------------------------ +CPU: Aarch64 - aes pmull sha256 sha512 rdm sha3 +Clock frequency: 1000000000 Hz +Math: Multi-Precision: Wolf(SP) no-dyn-stack word-size=64 bits=4096 sp_int.c + Single Precision: ecc 256 384 521 rsa/dh 2048 3072 4096 asm sp_arm64.c + Assembly Speedups: ARMASM ALIGN +wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each) +ML-KEM 512 128 key gen 416000 ops took 1.000 sec, avg 0.002 ms, 415934.748 ops/sec, 1000151922 cycles 2404.2 Cycles/op +ML-KEM 512 128 encap 364000 ops took 1.000 sec, avg 0.003 ms, 363971.971 ops/sec, 1000072762 cycles 2747.5 Cycles/op +ML-KEM 512 128 decap 244200 ops took 1.000 sec, avg 0.004 ms, 244189.521 ops/sec, 1000038535 cycles 4095.2 Cycles/op +ML-KEM 768 192 key gen 293000 ops took 1.000 sec, avg 0.003 ms, 292985.051 ops/sec, 1000045870 cycles 3413.1 Cycles/op +ML-KEM 768 192 encap 244100 ops took 1.000 sec, avg 0.004 ms, 244013.374 ops/sec, 1000350401 cycles 4098.1 Cycles/op +ML-KEM 768 192 decap 167000 ops took 1.000 sec, avg 0.006 ms, 166981.129 ops/sec, 1000109070 cycles 5988.7 Cycles/op +ML-KEM 1024 256 key gen 171900 ops took 1.000 sec, avg 0.006 ms, 171855.298 ops/sec, 1000255617 cycles 5818.8 Cycles/op +ML-KEM 1024 256 encap 152200 ops took 1.000 sec, avg 0.007 ms, 152125.140 ops/sec, 1000488156 cycles 6573.5 Cycles/op +ML-KEM 1024 256 decap 111200 ops took 1.000 sec, avg 0.009 ms, 111160.087 ops/sec, 1000354818 cycles 8996.0 Cycles/op +ECDHE [ SECP256R1] 256 agree 37200 ops took 1.001 sec, avg 0.027 ms, 37161.574 ops/sec, 1001029139 cycles 26909.4 Cycles/op +ECDSA [ SECP256R1] 256 sign 91900 ops took 1.000 sec, avg 0.011 ms, 91856.375 ops/sec, 1000471181 cycles 10886.5 Cycles/op +ECDSA [ SECP256R1] 256 verify 34900 ops took 1.001 sec, avg 0.029 ms, 34861.343 ops/sec, 1001104424 cycles 28684.9 Cycles/op +CURVE 25519 agree 66500 ops took 1.001 sec, avg 0.015 ms, 66458.866 ops/sec, 1000614019 cycles 15046.8 Cycles/op +ML-DSA 44 key gen 97300 ops took 1.000 sec, avg 0.010 ms, 97285.387 ops/sec, 1000145962 cycles 10279.0 Cycles/op +ML-DSA 44 sign 32300 ops took 1.001 sec, avg 0.031 ms, 32263.539 ops/sec, 1001125275 cycles 30994.6 Cycles/op +ML-DSA 44 verify 94500 ops took 1.001 sec, avg 0.011 ms, 94446.363 ops/sec, 1000563608 cycles 10588.0 Cycles/op +ML-DSA 65 key gen 57300 ops took 1.000 sec, avg 0.017 ms, 57272.567 ops/sec, 1000474781 cycles 17460.3 Cycles/op +ML-DSA 65 sign 22000 ops took 1.002 sec, avg 0.046 ms, 21957.444 ops/sec, 1001934023 cycles 45542.5 Cycles/op +ML-DSA 65 verify 61300 ops took 1.001 sec, avg 0.016 ms, 61249.897 ops/sec, 1000813141 cycles 16326.5 Cycles/op +ML-DSA 87 key gen 37600 ops took 1.001 sec, avg 0.027 ms, 37576.295 ops/sec, 1000626661 cycles 26612.4 Cycles/op +ML-DSA 87 sign 17600 ops took 1.005 sec, avg 0.057 ms, 17512.228 ops/sec, 1005007883 cycles 57102.7 Cycles/op +ML-DSA 87 verify 37800 ops took 1.002 sec, avg 0.027 ms, 37712.765 ops/sec, 1002308693 cycles 26516.1 Cycles/op +Benchmark complete ``` #### Benchmarks from wolfSSL -The following benchmarks were obtained with the following configuration flags: - +`tls_bench` was run with `-g`, which runs the benchmark once for every TLS 1.3 group the build supports, and `-t 2` to run each test for 2 seconds: -```text -./configure --enable-kyber \ - --enable-dilithium \ - --disable-shared \ - --enable-intelasm \ - --enable-aesni \ - --enable-sp \ - --enable-sp-math \ - --enable-sp-asm \ - CFLAGS="-Os -DECC_USER_CURVES -DHAVE_ECC256" +```sh +./examples/benchmark/tls_bench -g -l TLS13-AES256-GCM-SHA384 -t 2 ``` -**Note**: Only two cores are used for these benchmarks. - -```text -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group ECC_SECP256R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 965.511 ms - Tx Total : 7.469 ms - Rx : 2.978 MB/s - Tx : 384.903 MB/s - Connect : 48.343 ms - Connect Avg : 2.014 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group ECC_SECP256R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 967.748 ms - Tx Total : 6.789 ms - Rx : 2.971 MB/s - Tx : 423.496 MB/s - Connect : 48.574 ms - Connect Avg : 2.024 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group ECC_SECP384R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 960.296 ms - Tx Total : 7.494 ms - Rx : 2.994 MB/s - Tx : 383.617 MB/s - Connect : 56.255 ms - Connect Avg : 2.344 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group ECC_SECP384R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 962.002 ms - Tx Total : 7.367 ms - Rx : 2.989 MB/s - Tx : 390.259 MB/s - Connect : 56.220 ms - Connect Avg : 2.343 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group ECC_SECP521R1: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 938.745 ms - Tx Total : 7.889 ms - Rx : 2.929 MB/s - Tx : 348.596 MB/s - Connect : 61.261 ms - Connect Avg : 2.664 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group ECC_SECP521R1: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 940.382 ms - Tx Total : 7.540 ms - Rx : 2.924 MB/s - Tx : 364.711 MB/s - Connect : 61.433 ms - Connect Avg : 2.671 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group ML_KEM_512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 952.389 ms - Tx Total : 5.561 ms - Rx : 3.019 MB/s - Tx : 517.005 MB/s - Connect : 50.177 ms - Connect Avg : 2.091 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group ML_KEM_512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 954.202 ms - Tx Total : 4.751 ms - Rx : 3.013 MB/s - Tx : 605.110 MB/s - Connect : 48.602 ms - Connect Avg : 2.025 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group ML_KEM_768: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 955.030 ms - Tx Total : 5.882 ms - Rx : 3.010 MB/s - Tx : 488.757 MB/s - Connect : 51.283 ms - Connect Avg : 2.137 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group ML_KEM_768: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 955.658 ms - Tx Total : 6.200 ms - Rx : 3.008 MB/s - Tx : 463.686 MB/s - Connect : 49.717 ms - Connect Avg : 2.072 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group ML_KEM_1024: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 973.042 ms - Tx Total : 7.294 ms - Rx : 2.955 MB/s - Tx : 394.150 MB/s - Connect : 51.750 ms - Connect Avg : 2.156 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group ML_KEM_1024: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 973.655 ms - Tx Total : 7.996 ms - Rx : 2.953 MB/s - Tx : 359.573 MB/s - Connect : 50.328 ms - Connect Avg : 2.097 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group SecP256r1MLKEM512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 961.483 ms - Tx Total : 7.430 ms - Rx : 2.990 MB/s - Tx : 386.966 MB/s - Connect : 55.885 ms - Connect Avg : 2.329 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group SecP256r1MLKEM512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 963.042 ms - Tx Total : 7.088 ms - Rx : 2.985 MB/s - Tx : 405.605 MB/s - Connect : 53.236 ms - Connect Avg : 2.218 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group SecP384r1MLKEM768: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 927.519 ms - Tx Total : 7.338 ms - Rx : 2.965 MB/s - Tx : 374.747 MB/s - Connect : 64.464 ms - Connect Avg : 2.803 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group SecP384r1MLKEM768: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 929.281 ms - Tx Total : 6.923 ms - Rx : 2.959 MB/s - Tx : 397.229 MB/s - Connect : 60.200 ms - Connect Avg : 2.617 ms - -wolfSSL Server Benchmark on TLS13-AES128-GCM-SHA256 with group SecP521r1MLKEM1024: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 918.122 ms - Tx Total : 7.598 ms - Rx : 2.995 MB/s - Tx : 361.941 MB/s - Connect : 79.426 ms - Connect Avg : 3.453 ms -wolfSSL Client Benchmark on TLS13-AES128-GCM-SHA256 with group SecP521r1MLKEM1024: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 919.900 ms - Tx Total : 7.563 ms - Rx : 2.989 MB/s - Tx : 363.618 MB/s - Connect : 71.686 ms - Connect Avg : 3.117 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group ECC_SECP256R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 962.723 ms - Tx Total : 6.394 ms - Rx : 2.986 MB/s - Tx : 449.663 MB/s - Connect : 52.042 ms - Connect Avg : 2.168 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group ECC_SECP256R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 963.166 ms - Tx Total : 7.537 ms - Rx : 2.985 MB/s - Tx : 381.433 MB/s - Connect : 52.348 ms - Connect Avg : 2.181 ms - - - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group ECC_SECP384R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 966.071 ms - Tx Total : 8.458 ms - Rx : 2.976 MB/s - Tx : 339.929 MB/s - Connect : 56.135 ms - Connect Avg : 2.339 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group ECC_SECP384R1: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 968.053 ms - Tx Total : 7.895 ms - Rx : 2.970 MB/s - Tx : 364.155 MB/s - Connect : 56.188 ms - Connect Avg : 2.341 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group ECC_SECP521R1: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 930.195 ms - Tx Total : 7.849 ms - Rx : 2.956 MB/s - Tx : 350.364 MB/s - Connect : 62.644 ms - Connect Avg : 2.724 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group ECC_SECP521R1: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 932.128 ms - Tx Total : 7.440 ms - Rx : 2.950 MB/s - Tx : 369.619 MB/s - Connect : 62.538 ms - Connect Avg : 2.719 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group ML_KEM_512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 973.208 ms - Tx Total : 8.190 ms - Rx : 2.954 MB/s - Tx : 351.021 MB/s - Connect : 49.608 ms - Connect Avg : 2.067 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group ML_KEM_512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 975.874 ms - Tx Total : 7.051 ms - Rx : 2.946 MB/s - Tx : 407.772 MB/s - Connect : 48.708 ms - Connect Avg : 2.030 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group ML_KEM_768: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 965.259 ms - Tx Total : 8.098 ms - Rx : 2.978 MB/s - Tx : 355.041 MB/s - Connect : 51.284 ms - Connect Avg : 2.137 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group ML_KEM_768: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 967.507 ms - Tx Total : 7.774 ms - Rx : 2.972 MB/s - Tx : 369.828 MB/s - Connect : 49.899 ms - Connect Avg : 2.079 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group ML_KEM_1024: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 972.588 ms - Tx Total : 7.835 ms - Rx : 2.956 MB/s - Tx : 366.959 MB/s - Connect : 52.259 ms - Connect Avg : 2.177 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group ML_KEM_1024: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 974.238 ms - Tx Total : 7.838 ms - Rx : 2.951 MB/s - Tx : 366.813 MB/s - Connect : 50.758 ms - Connect Avg : 2.115 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group SecP256r1MLKEM512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 971.832 ms - Tx Total : 7.544 ms - Rx : 2.958 MB/s - Tx : 381.096 MB/s - Connect : 54.727 ms - Connect Avg : 2.280 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group SecP256r1MLKEM512: - Total : 6029312 bytes - Num Conns : 24 - Rx Total : 972.623 ms - Tx Total : 8.807 ms - Rx : 2.956 MB/s - Tx : 326.456 MB/s - Connect : 52.613 ms - Connect Avg : 2.192 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group SecP384r1MLKEM768: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 921.217 ms - Tx Total : 7.740 ms - Rx : 2.985 MB/s - Tx : 355.285 MB/s - Connect : 69.367 ms - Connect Avg : 3.016 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group SecP384r1MLKEM768: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 923.622 ms - Tx Total : 6.928 ms - Rx : 2.977 MB/s - Tx : 396.956 MB/s - Connect : 63.739 ms - Connect Avg : 2.771 ms - -wolfSSL Server Benchmark on TLS13-AES256-GCM-SHA384 with group SecP521r1MLKEM1024: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 920.447 ms - Tx Total : 7.735 ms - Rx : 2.988 MB/s - Tx : 355.548 MB/s - Connect : 78.446 ms - Connect Avg : 3.411 ms -wolfSSL Client Benchmark on TLS13-AES256-GCM-SHA384 with group SecP521r1MLKEM1024: - Total : 5767168 bytes - Num Conns : 23 - Rx Total : 921.889 ms - Tx Total : 7.585 ms - Rx : 2.983 MB/s - Tx : 362.578 MB/s - Connect : 71.310 ms - Connect Avg : 3.100 ms -``` +**Note**: Only two cores are used for these benchmarks: `tls_bench` runs one server thread and one client thread. The server authenticates with an RSA 2048-bit certificate, and the client is not authenticated. + +The table shows the average time to complete a handshake ("Connect Avg") reported by each side. `tls_bench` prints the first group it runs, ECC_SECP256R1 here, as "N/A". + +Group | Server Connect Avg (ms) | Client Connect Avg (ms) +------------------- | ----------------------- | ----------------------- +ECC_SECP256R1 | 0.508 | 0.489 +ECC_SECP384R1 | 0.590 | 0.571 +ECC_SECP521R1 | 0.667 | 0.651 +ECC_X25519 | 0.502 | 0.481 +FFDHE_2048 | 0.785 | 0.766 +ML_KEM_512 | 0.500 | 0.475 +ML_KEM_768 | 0.502 | 0.476 +ML_KEM_1024 | 0.513 | 0.484 +SecP256r1MLKEM768 | 0.523 | 0.495 +SecP384r1MLKEM1024 | 0.619 | 0.574 +X25519MLKEM768 | 0.530 | 0.500 +SecP256r1MLKEM512 | 0.546 | 0.513 +SecP384r1MLKEM768 | 0.655 | 0.602 +SecP521r1MLKEM1024 | 0.778 | 0.703 +X25519MLKEM512 | 0.531 | 0.501 ## Documentation -Technical documentation and other resources such as known answer tests can be found at the NIST PQC website: +The standards can be found at the NIST website: -. +- ML-KEM, FIPS 203: +- ML-DSA, FIPS 204: +- SLH-DSA, FIPS 205: +- LMS and XMSS, NIST SP 800-208: -For more algorithm-specific benchmarking information, the OQS Project has benchmarking information at their website: - - +To measure the algorithms on your own hardware, use the wolfCrypt benchmark as shown in [Benchmarks](#benchmarks). ## Post-Quantum Stateful Hash-Based Signatures -This section covers post-quantum stateful hash-based signature (HBS) schemes such as LMS/HSS, and XMSS/XMSS^MT, for which wolfSSL has recently added support. +This section covers the post-quantum stateful hash-based signature (HBS) schemes LMS/HSS and XMSS/XMSS^MT. wolfCrypt has native implementations of both. Since wolfSSL 5.9.2 they can also be used in X.509 certificates (RFC 9802): wolfSSL verifies certificates signed with HSS/LMS or XMSS/XMSS^MT, and it can generate such certificates and certificate signing requests. They are not available as TLS handshake signature algorithms. ### Motivation @@ -925,7 +426,7 @@ Instead, because of these unique strengths and characteristics, and NIST and NSA ### LMS/HSS signatures -wolfSSL is adding support for the LMS/HSS hash-based signature scheme to our wolfCrypt embedded crypto engine. This will be achieved by experimental integration with the hash-sigs LMS/HSS library (), similar to our previous libOQS integration. +wolfCrypt includes a native implementation of the LMS/HSS hash-based signature scheme (RFC 8554, NIST SP 800-208). No external library is needed. Leighton-Micali Signatures (LMS), and its multi-tree variant, the Hierarchical Signature System (HSS), is a post-quantum, stateful hash-based signature scheme. It is noted for having small public and private keys, and fast signing and verifying. Its signature sizes are larger, but are tunable via its Winternitz parameter. See these two links from RFC8554 for more details: @@ -941,23 +442,24 @@ LMS/HSS signatures are defined by 3 parameters: - height: height of an individual Merkle tree. - Winternitz: number of bits from hash used in a Winternitz chain. Used as a space-time tradeoff for the signature size. -wolfSSL supports all LMS/HSS parameters defined in RFC8554: +wolfSSL supports these LMS/HSS parameter values: -- levels = {1..8} +- levels = {1..4} - height = {5, 10, 15, 20, 25} - Winternitz = {1, 2, 4, 8} +RFC 8554 allows up to 8 levels; wolfSSL supports up to 4 (`WOLFSSL_LMS_MAX_LEVELS`, default 4). `WOLFSSL_LMS_MAX_HEIGHT` (default 25) can lower the maximum tree height to save memory. By default the parameter sets use SHA-256 with 32-byte (SHA-256/256) hashes. The SHA-256/192 and SHAKE256 (256-bit and 192-bit output) parameter sets of NIST SP 800-208 can be added at build time; see [LMS/HSS Build Instructions](#lmshss-build-instructions). + The number of available signatures is: - N = 2 ** (levels * height) -For convenience some parameter sets have been predefined in the enum `wc_LmsParm`. Its values are shown in the table below: +The parameter sets are predefined in the enum `wc_LmsParm`, and only the combinations listed there can be used, whether a key is set up with `wc_LmsKey_SetLmsParm()` or with `wc_LmsKey_SetParameters()`. Some of the SHA-256/256 parameter sets are shown in the table below; see `enum wc_LmsParm` in `wolfssl/wolfcrypt/wc_lms.h` for the full list, which also has the `WC_LMS_PARM_SHA256_192_*`, `WC_LMS_PARM_SHAKE_*` and `WC_LMS_PARM_SHAKE192_*` sets. `WC_LMS_PARM_NONE` is not a parameter set: `wc_LmsKey_SetLmsParm()` rejects it, so a parameter set must always be chosen. parameter set | description -------------------- | --------------------------- -WC_LMS_PARM_NONE | Not set, use default (WC_LMS_PARM_L1_H15_W2) WC_LMS_PARM_L1_H15_W2 | 1 level Merkle tree of 15 height, Winternitz 2 WC_LMS_PARM_L1_H15_W4 | same as above, Winternitz 4 -WC_LMS_PARM_L2_H10_W2 | 2 level Merkle tree of 10 height, Winternitz 4 +WC_LMS_PARM_L2_H10_W2 | 2 level Merkle tree of 10 height, Winternitz 2 WC_LMS_PARM_L2_H10_W4 | same as above, Winternitz 4 WC_LMS_PARM_L2_H10_W8 | same as above, Winternitz 8 WC_LMS_PARM_L3_H5_W2 | 3 level Merkle tree of 5 height, Winternitz 2 @@ -984,102 +486,204 @@ WC_LMS_PARM_L4_H5_W8 | 5340 | 1048576 As can be seen from the tables, signature sizes are primarily determined by the levels and Winternitz parameters, and height to a lesser extent: - Larger levels values increase signature size significantly. - Larger height values increase signature size modestly. -- Larger winternitz values will reduce the signature size, at the expense of longer key generation and sign/verify times. +- Larger Winternitz values will reduce the signature size, at the expense of longer key generation and sign/verify times. Key generation time is strongly determined by the height of the first level tree. A 3 level, 5 height tree is much faster than 1 level, 15 height at initial key gen, even if the number of available signatures is the same. +The public key is 60 bytes for the SHA-256/256 and SHAKE256/256 parameter sets and 52 bytes for the 192-bit ones. The private key that has to be stored is 64 bytes for the 256-bit parameter sets; `wc_LmsKey_GetPrivLen()` returns it for any parameter set. + #### LMS/HSS Build Instructions -Please see the wolfSSL repo's INSTALL file (https://github.com/wolfSSL/wolfssl/blob/master/INSTALL). Item 17 (Building with hash-sigs lib for LMS/HSS support [EXPERIMENTAL]) has instructions on how to configure and build wolfSSL and the hash-sigs LMS/HSS library. +Configure wolfSSL with [`--enable-lms`](chapter02.md#--enable-lms); no external library is needed. `--enable-all-quantum-crypto` enables LMS/HSS as well. `--enable-lms` takes a comma separated list of sub-options: -#### Benchmark Data +- `verify-only`: only signature verification is compiled in (`WOLFSSL_LMS_VERIFY_ONLY`). +- `small`: smaller code with slower signing, for when memory is limited (`WOLFSSL_WC_LMS_SMALL`). +- `sha256-192`: adds the SHA-256/192 parameter sets (`WOLFSSL_LMS_SHA256_192`). +- `shake256`: adds the SHAKE256/256 and SHAKE256/192 parameter sets (`WOLFSSL_LMS_SHAKE256`). +- `no-sha256-256`: removes the SHA-256/256 parameter sets (`WOLFSSL_NO_LMS_SHA256_256`). It must be combined with `sha256-192` or `shake256`. -The following benchmark data was taken on an 8-core Intel i7-8700 CPU @ 3.20GHz, on Fedora 38 (`6.2.9-300.fc38.x86_64`). The multi-threaded example used 4 worker threads and 4 cores, while the single-threaded example used only a single core. +For example: -As discussed in item 17 of the INSTALL file, the hash-sigs lib offers two static libraries: -- `hss_lib.a`: a single-threaded version. -- `hss_lib_thread.a`: a multi-threaded version. +```sh +./configure --enable-lms=sha256-192,shake256 +``` -The multi-threaded version will spawn worker threads to accelerate cpu intensive tasks, such as key generation. This will mainly speedup key generation and signing for all parameter values, and to a lesser extent will speedup verifying for larger levels values. +Outside the small build, `WOLFSSL_LMS_ROOT_LEVELS` and `WOLFSSL_LMS_CACHE_BITS` (both default 5, or 7 with `WOLFSSL_LMS_LARGE_CACHES`) trade the size of the `LmsKey` object for faster signing; `wolfssl/wolfcrypt/wc_lms.h` describes them. -For reference, wolfSSL was built with the following to obtain both benchmarks: +#### Using LMS/HSS Keys -```text - ./configure \ - --enable-static \ - --disable-shared \ - --enable-lms=yes \ - --with-liblms= -``` +A signing key goes through these steps: -**multi-threaded benchmark** +1. [`wc_LmsKey_Init()`](group__LMS.md#function-wc_lmskey_init), then choose the parameter set with [`wc_LmsKey_SetLmsParm()`](group__LMS.md#function-wc_lmskey_setlmsparm) or [`wc_LmsKey_SetParameters()`](group__LMS.md#function-wc_lmskey_setparameters). +2. Set the private key callbacks with [`wc_LmsKey_SetWriteCb()`](group__LMS.md#function-wc_lmskey_setwritecb), [`wc_LmsKey_SetReadCb()`](group__LMS.md#function-wc_lmskey_setreadcb) and [`wc_LmsKey_SetContext()`](group__LMS.md#function-wc_lmskey_setcontext). The context pointer is passed to the callbacks, for example a file name. +3. [`wc_LmsKey_MakeKey()`](group__LMS.md#function-wc_lmskey_makekey) generates the key pair and stores the private key with the write callback. Export the public key with [`wc_LmsKey_ExportPubRaw()`](group__LMS.md#function-wc_lmskey_exportpubraw). +4. Each [`wc_LmsKey_Sign()`](group__LMS.md#function-wc_lmskey_sign) uses up one one-time key and stores the updated private key with the write callback before it returns the signature. [`wc_LmsKey_SigsLeft()`](group__LMS.md#function-wc_lmskey_sigsleft) returns non-zero while the key can still sign. +5. To carry on signing later, for example after a restart, set up a new `LmsKey` with the same parameter set and callbacks and call [`wc_LmsKey_Reload()`](group__LMS.md#function-wc_lmskey_reload). It loads the private key with the read callback and rebuilds the cached tree state, which takes about as long as key generation. A reloaded key can sign, but it holds no public key, so keep the public key that was exported after key generation. -The following is benchmark data obtained when built against the multi-threaded `hss_lib_thread.a`, which used 4 worker threads to parallelize intensive tasks, and used 4 cores. +The callbacks have these types: -```text -./wolfcrypt/benchmark/benchmark -lms_hss ------------------------------------------------------------------------------- - wolfSSL version 5.6.3 ------------------------------------------------------------------------------- -Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c -wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each) -LMS/HSS L2_H10_W2 9300 sign 1500 ops took 1.075 sec, avg 0.717 ms, 1394.969 ops/sec -LMS/HSS L2_H10_W2 9300 verify 5200 ops took 1.002 sec, avg 0.193 ms, 5189.238 ops/sec -LMS/HSS L2_H10_W4 5076 sign 800 ops took 1.012 sec, avg 1.265 ms, 790.776 ops/sec -LMS/HSS L2_H10_W4 5076 verify 2500 ops took 1.003 sec, avg 0.401 ms, 2493.584 ops/sec -LMS/HSS L3_H5_W4 7160 sign 1500 ops took 1.051 sec, avg 0.701 ms, 1427.485 ops/sec -LMS/HSS L3_H5_W4 7160 verify 2700 ops took 1.024 sec, avg 0.379 ms, 2636.899 ops/sec -LMS/HSS L3_H5_W8 3992 sign 300 ops took 1.363 sec, avg 4.545 ms, 220.030 ops/sec -LMS/HSS L3_H5_W8 3992 verify 400 ops took 1.066 sec, avg 2.664 ms, 375.335 ops/sec -LMS/HSS L3_H10_W4 7640 sign 900 ops took 1.090 sec, avg 1.211 ms, 825.985 ops/sec -LMS/HSS L3_H10_W4 7640 verify 2400 ops took 1.037 sec, avg 0.432 ms, 2314.464 ops/sec -LMS/HSS L4_H5_W8 5340 sign 300 ops took 1.310 sec, avg 4.367 ms, 228.965 ops/sec -LMS/HSS L4_H5_W8 5340 verify 400 ops took 1.221 sec, avg 3.053 ms, 327.599 ops/sec -Benchmark complete +```c +typedef int (*wc_lms_write_private_key_cb)(const byte* priv, word32 privSz, + void* context); +typedef int (*wc_lms_read_private_key_cb)(byte* priv, word32 privSz, + void* context); ``` -**single-threaded benchmark** +The write callback must return `WC_LMS_RC_SAVED_TO_NV_MEMORY` only once the private key is in non-volatile storage, and the read callback returns `WC_LMS_RC_READ_TO_MEMORY` once it has filled `priv`. Any other return value makes the call fail with `IO_FAILED_E`. If storing the updated private key fails during signing, `wc_LmsKey_Sign()` erases the signature and the key cannot sign any more. Never sign with two copies of the same private key, and never go back to an older copy of the stored private key: both reuse one-time keys. + +To verify, import the public key into a key of its own with [`wc_LmsKey_ImportPubRaw()`](group__LMS.md#function-wc_lmskey_importpubraw), which takes the parameter set from the public key if none was set, and call [`wc_LmsKey_Verify()`](group__LMS.md#function-wc_lmskey_verify). + +The following example generates a key with the small parameter set `WC_LMS_PARM_L1_H5_W8` (32 signatures), keeps the private key in a file, signs, verifies, and reloads the key to sign again: + +```c +#include +#include +#include +#include +#include +#include +#include + +/* The private key must be stored before wc_LmsKey_MakeKey() or + * wc_LmsKey_Sign() returns. Only return WC_LMS_RC_SAVED_TO_NV_MEMORY once the + * data is durable (a real application should write a new file, sync it and + * rename it over the old one). */ +static int lms_write_key(const byte* priv, word32 privSz, void* context) +{ + FILE* f = fopen((const char*)context, "wb"); + int ok; + + if (f == NULL) + return WC_LMS_RC_WRITE_FAIL; + ok = (fwrite(priv, 1, privSz, f) == privSz); + if (fclose(f) != 0) + ok = 0; + return ok ? WC_LMS_RC_SAVED_TO_NV_MEMORY : WC_LMS_RC_WRITE_FAIL; +} + +/* Called by wc_LmsKey_Reload() to load the stored private key. */ +static int lms_read_key(byte* priv, word32 privSz, void* context) +{ + FILE* f = fopen((const char*)context, "rb"); + size_t n; + + if (f == NULL) + return WC_LMS_RC_READ_FAIL; + n = fread(priv, 1, privSz, f); + fclose(f); + return (n == privSz) ? WC_LMS_RC_READ_TO_MEMORY : WC_LMS_RC_READ_FAIL; +} + +/* Set the parameters and callbacks: needed before MakeKey and Reload. */ +static int lms_setup(LmsKey* key, const char* file) +{ + int ret = wc_LmsKey_Init(key, NULL, INVALID_DEVID); + if (ret == 0) + ret = wc_LmsKey_SetLmsParm(key, WC_LMS_PARM_L1_H5_W8); + if (ret == 0) + ret = wc_LmsKey_SetWriteCb(key, lms_write_key); + if (ret == 0) + ret = wc_LmsKey_SetReadCb(key, lms_read_key); + if (ret == 0) + ret = wc_LmsKey_SetContext(key, (void*)file); + return ret; +} + +int main(void) +{ + const char* file = "lms_priv.key"; + const byte msg[] = "firmware image"; + byte pub[HSS_MAX_PUBLIC_KEY_LEN]; + word32 pubSz = sizeof(pub); + byte* sig = NULL; + word32 sigSz = 0; + LmsKey key; + LmsKey verifyKey; + WC_RNG rng; + int ret; + + ret = wc_InitRng(&rng); + if (ret != 0) + return 1; + + /* Generate a new key pair. The private key is written with the write + * callback. */ + ret = lms_setup(&key, file); + if (ret == 0) + ret = wc_LmsKey_MakeKey(&key, &rng); + if (ret == 0) + ret = wc_LmsKey_ExportPubRaw(&key, pub, &pubSz); + if (ret == 0) + ret = wc_LmsKey_GetSigLen(&key, &sigSz); + if (ret == 0) { + sig = (byte*)malloc(sigSz); + if (sig == NULL) + ret = MEMORY_E; + } + /* Each signature uses up one one-time key. The updated private key is + * written before the signature is returned. */ + if (ret == 0) + ret = wc_LmsKey_Sign(&key, sig, &sigSz, msg, (int)sizeof(msg)); + wc_LmsKey_Free(&key); + + /* Verify with a public-key-only object. The parameter set is taken from + * the public key. */ + if (ret == 0) + ret = wc_LmsKey_Init(&verifyKey, NULL, INVALID_DEVID); + if (ret == 0) { + ret = wc_LmsKey_ImportPubRaw(&verifyKey, pub, pubSz); + if (ret == 0) + ret = wc_LmsKey_Verify(&verifyKey, sig, sigSz, msg, + (int)sizeof(msg)); + wc_LmsKey_Free(&verifyKey); + } + + /* Later, for example after a restart: reload the stored private key and + * carry on signing where it left off. */ + if (ret == 0) + ret = lms_setup(&key, file); + if (ret == 0) + ret = wc_LmsKey_Reload(&key); + if ((ret == 0) && (wc_LmsKey_SigsLeft(&key) == 0)) + ret = KEY_EXHAUSTED_E; + if (ret == 0) + ret = wc_LmsKey_Sign(&key, sig, &sigSz, msg, (int)sizeof(msg)); + wc_LmsKey_Free(&key); + + printf("LMS example %s (%d)\n", (ret == 0) ? "passed" : "failed", ret); + free(sig); + wc_FreeRng(&rng); + return (ret == 0) ? 0 : 1; +} +``` -The following is benchmark data obtained when built against the single-threaded `hss_lib.a`, -which will use only a single core. +#### Benchmark Data -```text -$ ./wolfcrypt/benchmark/benchmark -lms_hss ------------------------------------------------------------------------------- - wolfSSL version 5.6.3 ------------------------------------------------------------------------------- -Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c -wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each) -LMS/HSS L2_H10_W2 9300 sign 800 ops took 1.115 sec, avg 1.394 ms, 717.589 ops/sec -LMS/HSS L2_H10_W2 9300 verify 4500 ops took 1.001 sec, avg 0.223 ms, 4493.623 ops/sec -LMS/HSS L2_H10_W4 5076 sign 500 ops took 1.239 sec, avg 2.478 ms, 403.519 ops/sec -LMS/HSS L2_H10_W4 5076 verify 2100 ops took 1.006 sec, avg 0.479 ms, 2087.944 ops/sec -LMS/HSS L3_H5_W4 7160 sign 800 ops took 1.079 sec, avg 1.349 ms, 741.523 ops/sec -LMS/HSS L3_H5_W4 7160 verify 1600 ops took 1.012 sec, avg 0.632 ms, 1581.686 ops/sec -LMS/HSS L3_H5_W8 3992 sign 100 ops took 1.042 sec, avg 10.420 ms, 95.971 ops/sec -LMS/HSS L3_H5_W8 3992 verify 200 ops took 1.220 sec, avg 6.102 ms, 163.894 ops/sec -LMS/HSS L3_H10_W4 7640 sign 400 ops took 1.010 sec, avg 2.526 ms, 395.864 ops/sec -LMS/HSS L3_H10_W4 7640 verify 1500 ops took 1.052 sec, avg 0.701 ms, 1426.284 ops/sec -LMS/HSS L4_H5_W8 5340 sign 100 ops took 1.066 sec, avg 10.665 ms, 93.768 ops/sec -LMS/HSS L4_H5_W8 5340 verify 200 ops took 1.478 sec, avg 7.388 ms, 135.358 ops/sec -Benchmark complete +The following benchmark data was taken on the Apple M5 system described in [Statistics](#statistics), with wolfSSL 5.9.4 configured with `./configure --enable-lms --enable-xmss --enable-armasm` and with `./configure --enable-lms --enable-xmss`, by running: + +```sh +./wolfcrypt/benchmark/benchmark -lms_hss ``` -### XMSS/XMSS^MT signatures +Each time is the average in milliseconds, with `--enable-armasm` first and without it second. `--enable-armasm` uses the ARMv8 SHA-256 instructions, which speeds up all LMS/HSS operations. Reload is `wc_LmsKey_Reload()`. Only a single core is used. -wolfSSL is adding support for XMSS/XMSS^MT stateful hash-based signatures. Similar to LMS, this -will be done by experimental integration with the xmss-reference repository -(https://github.com/XMSS/xmss-reference.git), from RFC 8391 -(https://www.rfc-editor.org/rfc/rfc8391.html). +Parameter set | Signature size | Key gen (ms) | Reload (ms) | Sign (ms) | Verify (ms) +------------- | -------------- | ---------------- | ---------------- | ------------- | ------------- +L1_H5_W4 | 2352 | 1.066 / 5.535 | 1.071 / 5.381 | 0.017 / 0.089 | 0.016 / 0.085 +L1_H5_W8 | 1296 | 8.562 / 42.308 | 10.534 / 42.950 | 0.382 / 0.645 | 0.206 / 0.753 +L2_H10_W2 | 9300 | 37.449 / 188.105 | 34.651 / 188.645 | 0.052 / 0.281 | 0.016 / 0.088 +L2_H10_W4 | 5076 | 68.022 / 343.029 | 67.543 / 344.260 | 0.099 / 0.507 | 0.034 / 0.178 +L3_H5_W4 | 7160 | 3.312 / 17.186 | 3.391 / 17.427 | 0.053 / 0.268 | 0.048 / 0.268 +L3_H5_W8 | 3992 | 26.232 / 144.790 | 26.499 / 140.189 | 0.411 / 2.185 | 0.408 / 2.240 +L3_H10_W4 | 7640 | 103.184 / 548.525 | 102.161 / 563.973 | 0.099 / 0.546 | 0.050 / 0.258 +L4_H5_W8 | 5340 | 35.179 / 188.079 | 35.460 / 187.302 | 0.417 / 2.174 | 0.573 / 3.758 -The xmss-reference supports `xmss_core_fast`, and `xmss_core` implementations. The `xmss_core_fast` -implementation was designed to prioritize performance with larger private key sizes as a tradeoff. -Our integration uses `xmss_core_fast`, with a patch applied so that the wolfCrypt SHA256 implementation -may be used instead. +### XMSS/XMSS^MT signatures -The patch may be found here -```pq/stateful_hash_sig/0001-Patch-to-support-wolfSSL-xmss-reference-integration.patch``` -in the wolfssl-examples repository: https://github.com/wolfSSL/wolfssl-examples. +wolfCrypt includes a native implementation of the XMSS and XMSS^MT stateful hash-based signature schemes from RFC 8391 (https://www.rfc-editor.org/rfc/rfc8391.html) and NIST SP 800-208. Configure wolfSSL with [`--enable-xmss`](chapter02.md#--enable-xmss); no external library is needed. `--enable-all-quantum-crypto` enables XMSS/XMSS^MT as well. `--enable-xmss` takes these sub-options: + +- `verify-only`: only signature verification is compiled in (`WOLFSSL_XMSS_VERIFY_ONLY`). +- `small`: smaller code and a much smaller private key (`WOLFSSL_WC_XMSS_SMALL`). The private key then holds no tree traversal state, so signing is much slower. Overall, XMSS/XMSS^MT is similar to LMS/HSS. For a more detailed comparison see "LMS vs XMSS: Comparison of two Hash-Based Signature Standards" (https://eprint.iacr.org/2017/349.pdf). @@ -1091,7 +695,7 @@ XMSS/XMSS^MT. The public key is slightly larger in XMSS/XMSS^MT (at 68 bytes in #### Supported Parameters -wolfSSL supports the SHA256 XMSS/XMSS^MT parameter sets from Tables 10 and 11 from NIST SP 800-208 (https://csrc.nist.gov/pubs/sp/800/208/final). +wolfSSL supports the XMSS/XMSS^MT parameter sets of RFC 8391 and NIST SP 800-208 for each hash algorithm that is built in: SHA2-256 with n = 32 and n = 24, SHA2-512 (n = 64), SHAKE128 (n = 32), and SHAKE256 with n = 64, 32 and 24. FIPS builds support only the SHA2-256 and SHAKE256 sets with n = 32 and n = 24. The table below lists the SHA2-256 parameter sets with n = 32, from Tables 10 and 11 of NIST SP 800-208 (https://csrc.nist.gov/pubs/sp/800/208/final). The names of the other sets follow the same pattern, for example "XMSS-SHA2_10_192", "XMSS-SHA2_10_512", "XMSS-SHAKE_10_256", "XMSS-SHAKE256_10_256" and "XMSSMT-SHAKE256_60/12_192"; the full list is in `wolfcrypt/src/wc_xmss.c`. `WOLFSSL_XMSS_MIN_HEIGHT` and `WOLFSSL_XMSS_MAX_HEIGHT` (default 10 and 60) limit the total tree heights that are compiled in. parameter set name | Oid | n | w | h | d | h/d | Sig len ----------------------- | ----------- | --- | --- | --- | --- | --- | -- @@ -1117,132 +721,94 @@ tree levels). Similar to LMS/HSS, the number of available signatures grows as `2**h`, where h is the total height of the tree system. - -#### Benchmark Data - -In the following, benchmark data is shown for several XMSS/XMSS^MT parameter sets, -for intel x86_64 and aarch64. The SHA256 performance on these systems is also listed for reference, -as computing the large number of required hash chains will constitute the bulk of the CPU -work for XMSS/XMSS^MT. Additionally, our patch to xmss-reference substitutes wolfCrypt's SHA256 implementation, and therefore benefits from the same ASM speedups. - -As previously mentioned, our xmss integration is using the `xmss_core_fast` implementation from xmss-reference, which has faster performance at the tradeoff of larger private key sizes. - -**x86_64** - -The following x86_64 benchmark data were taken on an 8-core Intel i7-8700 CPU @ 3.20GHz, on Fedora 38 (`6.2.9-300.fc38.x86_64`). This CPU has `avx avx2` flags, which can accelerate hash operations and be utilized with `--enable-intelasm`. - -With `--enable-intelasm`: - -```text -$./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256 ------------------------------------------------------------------------------- - wolfSSL version 5.6.3 ------------------------------------------------------------------------------- -Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c -wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each) -SHA-256 500 MiB took 1.009 seconds, 495.569 MiB/s Cycles per byte = 6.14 -XMSS-SHA2_10_256 2500 sign 200 ops took 1.010 sec, avg 5.052 ms, 197.925 ops/sec -XMSS-SHA2_10_256 2500 verify 1600 ops took 1.011 sec, avg 0.632 ms, 1582.844 ops/sec -XMSSMT-SHA2_20/2_256 4963 sign 200 ops took 1.286 sec, avg 6.431 ms, 155.504 ops/sec -XMSSMT-SHA2_20/2_256 4963 verify 700 ops took 1.009 sec, avg 1.441 ms, 693.905 ops/sec -XMSSMT-SHA2_20/4_256 9251 sign 300 ops took 1.223 sec, avg 4.076 ms, 245.335 ops/sec -XMSSMT-SHA2_20/4_256 9251 verify 400 ops took 1.027 sec, avg 2.569 ms, 389.329 ops/sec -XMSSMT-SHA2_40/4_256 9893 sign 200 ops took 1.466 sec, avg 7.332 ms, 136.394 ops/sec -XMSSMT-SHA2_40/4_256 9893 verify 400 ops took 1.024 sec, avg 2.560 ms, 390.627 ops/sec -XMSSMT-SHA2_40/8_256 18469 sign 300 ops took 1.202 sec, avg 4.006 ms, 249.637 ops/sec -XMSSMT-SHA2_40/8_256 18469 verify 200 ops took 1.089 sec, avg 5.446 ms, 183.635 ops/sec -XMSSMT-SHA2_60/6_256 14824 sign 200 ops took 1.724 sec, avg 8.618 ms, 116.033 ops/sec -XMSSMT-SHA2_60/6_256 14824 verify 300 ops took 1.136 sec, avg 3.788 ms, 263.995 ops/sec -XMSSMT-SHA2_60/12_256 27688 sign 300 ops took 1.210 sec, avg 4.034 ms, 247.889 ops/sec -XMSSMT-SHA2_60/12_256 27688 verify 200 ops took 1.575 sec, avg 7.877 ms, 126.946 ops/sec -Benchmark complete -``` -Without `--enable-intelasm`: - -```text -$./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256 ------------------------------------------------------------------------------- - wolfSSL version 5.6.3 ------------------------------------------------------------------------------- -Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c -wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each) -SHA-256 275 MiB took 1.005 seconds, 273.549 MiB/s Cycles per byte = 11.13 -XMSS-SHA2_10_256 2500 sign 200 ops took 1.356 sec, avg 6.781 ms, 147.480 ops/sec -XMSS-SHA2_10_256 2500 verify 1200 ops took 1.025 sec, avg 0.854 ms, 1170.547 ops/sec -XMSSMT-SHA2_20/2_256 4963 sign 200 ops took 1.687 sec, avg 8.436 ms, 118.546 ops/sec -XMSSMT-SHA2_20/2_256 4963 verify 600 ops took 1.187 sec, avg 1.978 ms, 505.663 ops/sec -XMSSMT-SHA2_20/4_256 9251 sign 200 ops took 1.119 sec, avg 5.593 ms, 178.785 ops/sec -XMSSMT-SHA2_20/4_256 9251 verify 300 ops took 1.086 sec, avg 3.622 ms, 276.122 ops/sec -XMSSMT-SHA2_40/4_256 9893 sign 200 ops took 1.991 sec, avg 9.954 ms, 100.460 ops/sec -XMSSMT-SHA2_40/4_256 9893 verify 300 ops took 1.043 sec, avg 3.478 ms, 287.545 ops/sec -XMSSMT-SHA2_40/8_256 18469 sign 200 ops took 1.114 sec, avg 5.572 ms, 179.454 ops/sec -XMSSMT-SHA2_40/8_256 18469 verify 200 ops took 1.495 sec, avg 7.476 ms, 133.770 ops/sec -XMSSMT-SHA2_60/6_256 14824 sign 100 ops took 1.111 sec, avg 11.114 ms, 89.975 ops/sec -XMSSMT-SHA2_60/6_256 14824 verify 200 ops took 1.070 sec, avg 5.349 ms, 186.963 ops/sec -XMSSMT-SHA2_60/12_256 27688 sign 200 ops took 1.148 sec, avg 5.739 ms, 174.247 ops/sec -XMSSMT-SHA2_60/12_256 27688 verify 100 ops took 1.080 sec, avg 10.797 ms, 92.618 ops/sec -Benchmark complete +#### Using XMSS/XMSS^MT Keys + +XMSS/XMSS^MT keys are used in the same way as LMS/HSS keys, with the `wc_XmssKey_` functions, and the same rules apply to the stored private key. The differences are: + +- The parameter set is chosen by name with [`wc_XmssKey_SetParamStr()`](group__XMSS.md#function-wc_xmsskey_setparamstr), for example "XMSS-SHA2_10_256" or "XMSSMT-SHA2_20/4_256". +- The callbacks return `enum wc_XmssRc`: `WC_XMSS_RC_SAVED_TO_NV_MEMORY` from the write callback and `WC_XMSS_RC_READ_TO_MEMORY` from the read callback. +- wolfCrypt does not keep the private key in memory between signatures. [`wc_XmssKey_Sign()`](group__XMSS.md#function-wc_xmsskey_sign) reads the private key with the read callback, signs, stores the updated private key with the write callback and then erases its copy, so both callbacks must be set before signing. [`wc_XmssKey_SigsLeft()`](group__XMSS.md#function-wc_xmsskey_sigsleft) also reads the stored private key, and [`wc_XmssKey_Reload()`](group__XMSS.md#function-wc_xmsskey_reload) only checks that it can be read. +- A verify-only key needs its parameter string set with `wc_XmssKey_SetParamStr()` before [`wc_XmssKey_ImportPubRaw()`](group__XMSS.md#function-wc_xmsskey_importpubraw). +- The private key format is specific to wolfSSL, and its size depends on the parameter set and on the `small` option (for "XMSS-SHA2_10_256" it is 1343 bytes by default and 136 bytes with `small`). Do not expect XMSS/XMSS^MT private keys to work with other implementations. + +For example, the callbacks and the key generation look like this: + +```c +static enum wc_XmssRc xmss_write_key(const byte* priv, word32 privSz, + void* context) +{ + FILE* f = fopen((const char*)context, "wb"); + int ok; + + if (f == NULL) + return WC_XMSS_RC_WRITE_FAIL; + ok = (fwrite(priv, 1, privSz, f) == privSz); + if (fclose(f) != 0) + ok = 0; + return ok ? WC_XMSS_RC_SAVED_TO_NV_MEMORY : WC_XMSS_RC_WRITE_FAIL; +} + +static enum wc_XmssRc xmss_read_key(byte* priv, word32 privSz, void* context) +{ + FILE* f = fopen((const char*)context, "rb"); + size_t n; + + if (f == NULL) + return WC_XMSS_RC_READ_FAIL; + n = fread(priv, 1, privSz, f); + fclose(f); + return (n == privSz) ? WC_XMSS_RC_READ_TO_MEMORY : WC_XMSS_RC_READ_FAIL; +} + + /* In a function with XmssKey key, an initialized WC_RNG rng, + * byte pub[XMSS_SHA256_PUBLEN] and word32 pubSz = sizeof(pub): */ + ret = wc_XmssKey_Init(&key, NULL, INVALID_DEVID); + if (ret == 0) + ret = wc_XmssKey_SetParamStr(&key, "XMSS-SHA2_10_256"); + if (ret == 0) + ret = wc_XmssKey_SetWriteCb(&key, xmss_write_key); + if (ret == 0) + ret = wc_XmssKey_SetReadCb(&key, xmss_read_key); + if (ret == 0) + ret = wc_XmssKey_SetContext(&key, (void*)"xmss_priv.key"); + if (ret == 0) + ret = wc_XmssKey_MakeKey(&key, &rng); + if (ret == 0) + ret = wc_XmssKey_ExportPubRaw(&key, pub, &pubSz); ``` -**aarch64** +#### Benchmark Data -The following aarch64 data were taken on Ubuntu linux (`5.15.0-71-generic`) running on an Apple M1, with cpu flags `sha1 sha2 sha3 sha512`, which will specifically significantly accelerate SHA hash operations when built with `--enable-armasm`. +In the following, benchmark data is shown for the SHA2-256 XMSS/XMSS^MT parameter sets. The SHA256 performance is also listed for reference, as computing the large number of required hash chains will constitute the bulk of the CPU work for XMSS/XMSS^MT. The wolfCrypt XMSS/XMSS^MT implementation uses the wolfCrypt SHA-256 code, and therefore benefits from the same ASM speedups. -With `--enable-armasm`: +The data was taken on the Apple M5 system described in [Statistics](#statistics), with the same two builds as the LMS/HSS data (with and without `--enable-armasm`), by running: -```text -$ ./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256 ------------------------------------------------------------------------------- - wolfSSL version 5.6.3 ------------------------------------------------------------------------------- -Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c -wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each) -SHA-256 2305 MiB took 1.001 seconds, 2303.346 MiB/s -XMSS-SHA2_10_256 2500 sign 800 ops took 1.079 sec, avg 1.349 ms, 741.447 ops/sec -XMSS-SHA2_10_256 2500 verify 6500 ops took 1.007 sec, avg 0.155 ms, 6455.445 ops/sec -XMSSMT-SHA2_20/2_256 4963 sign 700 ops took 1.155 sec, avg 1.650 ms, 606.154 ops/sec -XMSSMT-SHA2_20/2_256 4963 verify 3100 ops took 1.021 sec, avg 0.329 ms, 3037.051 ops/sec -XMSSMT-SHA2_20/4_256 9251 sign 1100 ops took 1.006 sec, avg 0.915 ms, 1093.191 ops/sec -XMSSMT-SHA2_20/4_256 9251 verify 1700 ops took 1.013 sec, avg 0.596 ms, 1677.399 ops/sec -XMSSMT-SHA2_40/4_256 9893 sign 600 ops took 1.096 sec, avg 1.827 ms, 547.226 ops/sec -XMSSMT-SHA2_40/4_256 9893 verify 1600 ops took 1.062 sec, avg 0.664 ms, 1506.946 ops/sec -XMSSMT-SHA2_40/8_256 18469 sign 1100 ops took 1.007 sec, avg 0.916 ms, 1092.214 ops/sec -XMSSMT-SHA2_40/8_256 18469 verify 900 ops took 1.088 sec, avg 1.209 ms, 827.090 ops/sec -XMSSMT-SHA2_60/6_256 14824 sign 600 ops took 1.179 sec, avg 1.966 ms, 508.728 ops/sec -XMSSMT-SHA2_60/6_256 14824 verify 1100 ops took 1.038 sec, avg 0.944 ms, 1059.590 ops/sec -XMSSMT-SHA2_60/12_256 27688 sign 1100 ops took 1.015 sec, avg 0.923 ms, 1083.767 ops/sec -XMSSMT-SHA2_60/12_256 27688 verify 600 ops took 1.149 sec, avg 1.914 ms, 522.367 ops/sec -Benchmark complete +```sh +./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256 ``` -Without `--enable-armasm`: - -```text -$ ./wolfcrypt/benchmark/benchmark -xmss_xmssmt -sha256 ------------------------------------------------------------------------------- - wolfSSL version 5.6.3 ------------------------------------------------------------------------------- -Math: Multi-Precision: Wolf(SP) word-size=64 bits=4096 sp_int.c -wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each) -SHA-256 190 MiB took 1.020 seconds, 186.277 MiB/s -XMSS-SHA2_10_256 2500 sign 200 ops took 1.908 sec, avg 9.538 ms, 104.845 ops/sec -XMSS-SHA2_10_256 2500 verify 800 ops took 1.002 sec, avg 1.253 ms, 798.338 ops/sec -XMSSMT-SHA2_20/2_256 4963 sign 100 ops took 1.084 sec, avg 10.843 ms, 92.222 ops/sec -XMSSMT-SHA2_20/2_256 4963 verify 500 ops took 1.240 sec, avg 2.479 ms, 403.334 ops/sec -XMSSMT-SHA2_20/4_256 9251 sign 200 ops took 1.615 sec, avg 8.074 ms, 123.855 ops/sec -XMSSMT-SHA2_20/4_256 9251 verify 200 ops took 1.071 sec, avg 5.355 ms, 186.726 ops/sec -XMSSMT-SHA2_40/4_256 9893 sign 100 ops took 1.354 sec, avg 13.543 ms, 73.840 ops/sec -XMSSMT-SHA2_40/4_256 9893 verify 300 ops took 1.483 sec, avg 4.945 ms, 202.237 ops/sec -XMSSMT-SHA2_40/8_256 18469 sign 200 ops took 1.588 sec, avg 7.941 ms, 125.922 ops/sec -XMSSMT-SHA2_40/8_256 18469 verify 100 ops took 1.042 sec, avg 10.415 ms, 96.014 ops/sec -XMSSMT-SHA2_60/6_256 14824 sign 100 ops took 1.571 sec, avg 15.710 ms, 63.654 ops/sec -XMSSMT-SHA2_60/6_256 14824 verify 200 ops took 1.526 sec, avg 7.632 ms, 131.033 ops/sec -XMSSMT-SHA2_60/12_256 27688 sign 200 ops took 1.607 sec, avg 8.036 ms, 124.434 ops/sec -XMSSMT-SHA2_60/12_256 27688 verify 100 ops took 1.501 sec, avg 15.011 ms, 66.616 ops/sec -Benchmark complete -``` +`-xmss_xmssmt` runs the SHA2-256 parameter sets (n = 32 and n = 24); `-xmss_xmssmt_sha512`, `-xmss_xmssmt_shake128` and `-xmss_xmssmt_shake256` run the other hash families. SHA-256 ran at 2971.128 MiB/s with `--enable-armasm` and at 451.523 MiB/s without it. On x86_64, `--enable-intelasm` enables the assembly SHA-256 code. + +Each time is the average in milliseconds, with `--enable-armasm` first and without it second. Only a single core is used. + +Parameter set | Signature size | Key gen (ms) | Sign (ms) | Verify (ms) +---------------------- | -------------- | ------------------- | ------------- | ------------- +XMSS-SHA2_10_256 | 2500 | 147.243 / 706.314 | 0.659 / 3.129 | 0.081 / 0.364 +XMSS-SHA2_10_192 | 1492 | 152.998 / 669.786 | 0.680 / 2.939 | 0.086 / 0.386 +XMSSMT-SHA2_20/2_256 | 4963 | 298.039 / 1435.763 | 0.809 / 3.463 | 0.177 / 0.732 +XMSSMT-SHA2_20/4_256 | 9251 | 18.635 / 87.609 | 0.473 / 2.214 | 0.335 / 1.472 +XMSSMT-SHA2_40/4_256 | 9893 | 609.783 / 2879.408 | 0.862 / 3.975 | 0.339 / 1.590 +XMSSMT-SHA2_40/8_256 | 18469 | 39.661 / 189.600 | 0.481 / 2.349 | 0.647 / 3.061 +XMSSMT-SHA2_60/6_256 | 14824 | 916.980 / 4452.551 | 0.889 / 4.362 | 0.501 / 2.389 +XMSSMT-SHA2_60/12_256 | 27688 | 59.256 / 298.819 | 0.471 / 2.376 | 1.007 / 4.663 +XMSSMT-SHA2_20/2_192 | 2955 | 317.927 / 1407.238 | 0.826 / 3.531 | 0.166 / 0.818 +XMSSMT-SHA2_20/4_192 | 5403 | 20.774 / 93.409 | 0.477 / 2.312 | 0.341 / 1.535 +XMSSMT-SHA2_40/4_192 | 5885 | 641.373 / 3006.338 | 0.894 / 4.040 | 0.351 / 1.647 +XMSSMT-SHA2_40/8_192 | 10781 | 38.492 / 181.952 | 0.486 / 2.262 | 0.669 / 3.202 +XMSSMT-SHA2_60/6_192 | 8816 | 935.416 / 4241.281 | 0.862 / 4.085 | 0.508 / 2.212 +XMSSMT-SHA2_60/12_192 | 16160 | 55.882 / 263.694 | 0.446 / 2.222 | 0.959 / 4.503 ### Developer Notes -* If you are trying to thwart the “harvest now, decrypt later” threat model and you are willing to sacrifice some interoperability, then you do not want to advertise support for conventional algorithms in the Supported Groups extension. Be sure to call `wolfSSL_UseKeyShare()` and `wolfSSL_set_groups()` with your chosen algorithms. Only calling `wolfSSL_UseKeyShare()` is insufficient as that will advertise your support for quantum-vulnerable algorithms. If your peer does not support post-quantum algorithms, they will then send a HelloRetryRequest which will then result in a connection with a conventional algorithm. +* If you are trying to thwart the "harvest now, decrypt later" threat model and you are willing to sacrifice some interoperability, then you do not want to advertise support for conventional algorithms in the Supported Groups extension. By default a wolfSSL client already sends a PQ/T hybrid key share (X25519MLKEM768 when Curve25519 is built in, otherwise SecP256r1MLKEM768; define `WOLFSSL_KEY_SHARE_DEFAULT_GROUP` to choose another group) and lists the standard hybrids first in the Supported Groups extension, but the conventional groups follow them. If your peer does not support post-quantum algorithms, they will then send a HelloRetryRequest which will then result in a connection with a conventional algorithm. To prevent this, set only your chosen groups with [`wolfSSL_CTX_set_groups()`](group__Setup.md#function-wolfssl_ctx_set_groups) or [`wolfSSL_set_groups()`](group__Setup.md#function-wolfssl_set_groups), or by name with [`wolfSSL_CTX_set1_groups_list()`](group__Setup.md#function-wolfssl_ctx_set1_groups_list) or [`wolfSSL_set1_groups_list()`](group__Setup.md#function-wolfssl_set1_groups_list), which need the OpenSSL compatibility layer (for example `--enable-opensslextra`). For example, `"SecP384r1MLKEM1024:X25519MLKEM768"`; the names are case-insensitive. The key share is then made for the first group in the list that the build supports. Only calling [`wolfSSL_UseKeyShare()`](group__Setup.md#function-wolfssl_usekeyshare) is insufficient as that will advertise your support for quantum-vulnerable algorithms. diff --git a/wolfSSL/src/appendix10.md b/wolfSSL/src/appendix10.md index 9f3edc43..5154b1ea 100644 --- a/wolfSSL/src/appendix10.md +++ b/wolfSSL/src/appendix10.md @@ -2,23 +2,23 @@ ## Purpose -This guide provides a reference for developers and engineers porting the wolfSSL lightweight SSL/TLS library to new embedded platforms, operating systems, or transport mediums (TCP/IP, bluetooth, etc.). It calls out areas in the wolfSSL codebase which typically require modification when porting wolfSSL. It should be considered a “guide” and as such, it is an evolving work. If there is something you find missing, please let us know and we’ll be happy to add instructions or clarification to the document. +This guide provides a reference for developers and engineers porting the wolfSSL lightweight SSL/TLS library to new embedded platforms, operating systems, or transport mediums (TCP/IP, bluetooth, etc.). It calls out areas in the wolfSSL codebase which typically require modification when porting wolfSSL. It should be considered a "guide" and as such, it is an evolving work. If there is something you find missing, please let us know and we'll be happy to add instructions or clarification to the document. ## Audience -This guide caters to developers or engineers porting the wolfSSL and wolfCrypt to new platforms or environments that are not supported by default. +This guide caters to developers or engineers porting wolfSSL and wolfCrypt to new platforms or environments that are not supported by default. ## Introduction -Several steps need to be iterated through when getting wolfSSL to run on an embedded platform. Some of these steps are outlined in [Section 2.4](chapter02.md#building-in-a-non-standard-environment). +Several steps need to be iterated through when getting wolfSSL to run on an embedded platform. Some of these steps are outlined in [Building in a non-standard environment](chapter02.md#building-in-a-non-standard-environment) in Chapter 2. Apart from steps in Chapter 2 of the wolfSSL Manual, there are areas in the code which may need porting or modifications in order to accommodate a specific platform. wolfSSL abstracts many of these areas - attempting to make it as easy as possible to port wolfSSL to a new platform. In the `./wolfssl/wolfcrypt/settings.h` file, there are several defines specific to different operating systems, TCP/IP stacks, and chipsets (ex: MBED, FREESCALE_MQX, MICROCHIP_PIC32, MICRIUM, EBSNET, etc.). There are two main locations to put `#defines` when compiling and porting wolfSSL to a new platform: -1. New defines for a Operating System or TCP/IP stack port are typically added to the `settings.h` file when a new port of wolfSSL is completed. This provides an easy way to turn on/off features as well as customize build settings that should be “default” for that build. New custom defines can be added in this file when doing a port of wolfSSL to a new platform. We encourage users to contribute ports of wolfSSL back to the master open source code branch on [GitHub](https://www.github.com/wolfssl/wolfssl). This helps keep wolfSSL up to date and allows different ports to remain updated as the wolfSSL project improves and moves forward. +1. New defines for an Operating System or TCP/IP stack port are typically added to the `settings.h` file when a new port of wolfSSL is completed. This provides an easy way to turn on/off features as well as customize build settings that should be "default" for that build. New custom defines can be added in this file when doing a port of wolfSSL to a new platform. We encourage users to contribute ports of wolfSSL back to the master open source code branch on [GitHub](https://www.github.com/wolfssl/wolfssl). This helps keep wolfSSL up to date and allows different ports to remain updated as the wolfSSL project improves and moves forward. 2. For users not wanting to contribute back their changes to wolfSSL proper, or for users who want to customize the wolfSSL build with additional preprocessor defines, wolfSSL recommends the use of a custom `user_settings.h` header file. If `WOLFSSL_USER_SETTINGS` is defined when compiling the wolfSSL source files, wolfSSL will automatically include a custom header file called `user_settings.h`. This header should be created by the user and placed on the include path. This allows users to maintain one single file for their wolfSSL build, and makes it much easier to update to newer versions of wolfSSL. @@ -61,13 +61,13 @@ There are two additional data types used by wolfSSL and wolfCrypt, called `word3 ``` -`word32` should be mapped to the compiler’s 32-bit type, and `word16` to the compiler’s 16-bit type. If these default mappings are incorrect for your platform, you should define `WOLFSSL_TYPES` in `settings.h` or `user_settings.h` and assign your own custom typedefs for word32 and word16. +`word32` should be mapped to the compiler's 32-bit type, and `word16` to the compiler's 16-bit type. If these default mappings are incorrect for your platform, you should define `WOLFSSL_TYPES` in `settings.h` or `user_settings.h` and assign your own custom typedefs for word32 and word16. -The fastmath library in wolfSSL uses the `fp_digit` and `fp_word` types. By default these are mapped in `` depending on build configuration. +The default math library, SP math (`./wolfcrypt/src/sp_int.c`, `WOLFSSL_SP_MATH_ALL`), uses the `sp_int_digit` and `sp_int_word` types. Their size is selected with `SP_WORD_SIZE`, which is determined from the target and can be set to 32 or 64 in `user_settings.h` if needed. -`fp_word` should be twice the size of `fp_digit`. If the default cases do not hold true for your platform, you should define `WOLFSSL_BIGINT_TYPES` in `settings.h` or `user_settings.h` and assign your own custom typedefs for `fp_word` and `fp_digit`. +If you use the legacy fastmath back end (`USE_FAST_MATH`), it uses the `fp_digit` and `fp_word` types, which are mapped in ``; the legacy heap math back end (`USE_INTEGER_HEAP_MATH`) uses `mp_digit` and `mp_word` from ``. The word type should be twice the size of the digit type. If the default cases do not hold true for your platform, you should define `WOLFSSL_BIGINT_TYPES` in `settings.h` or `user_settings.h` and assign your own custom typedefs for these types. -wolfSSL does use a 64-bit type when available for some operations. The wolfSSL build tries to detect and set up the correct underlying data type for `word64` based on what `SIZEOF_LONG` and `SIZEOF_LONG_LONG` have been set to. On some platforms that don’t have a true 64-bit type, where two 32-bit types are used in conjunction, performance can be slow. To compile out the use of 64-bit types, define `NO_64BIT`. +wolfSSL does use a 64-bit type when available for some operations. The wolfSSL build tries to detect and set up the correct underlying data type for `word64` based on what `SIZEOF_LONG` and `SIZEOF_LONG_LONG` have been set to. On some platforms that don't have a true 64-bit type, where two 32-bit types are used in conjunction, performance can be slow. To compile out the use of 64-bit types, define `NO_64BIT`. ### Endianness @@ -95,7 +95,7 @@ Is your platform big endian or little endian? wolfSSL defaults to a little endi A: `` is not available. -By default, the wolfSSL API makes available `wolfSSL_writev()` to applications, which simulates `writev()` semantics. On systems that don’t have the `` header available, define `NO_WRITEV` to exclude this feature. +By default, the wolfSSL API makes available `wolfSSL_writev()` to applications, which simulates `writev()` semantics. On systems that don't have the `` header available, define `NO_WRITEV` to exclude this feature. ### Input / Output @@ -108,13 +108,13 @@ wolfSSL defaults to using a BSD-style socket interface. If your transport layer wolfSSL provides a custom I/O abstraction layer which allows users to tailor wolfSSL's I/O functionality to their system. Full details can be [found in Section 5.1.2](chapter05.md#custom-inputoutput-abstraction-layer). -Simply put, you can define `WOLFSSL_USER_IO`, then write your own I/O callback functions using wolfSSL's default `EmbedSend()` and `EmbedReceive()` as templates. These two functions are located in `./src/io.c`. +Simply put, you can define `WOLFSSL_USER_IO`, then write your own I/O callback functions using wolfSSL's default `EmbedSend()` and `EmbedReceive()` as templates. These two functions are located in `./src/wolfio.c` (header `wolfssl/wolfio.h`). Register your callbacks with `wolfSSL_CTX_SetIORecv()` and `wolfSSL_CTX_SetIOSend()`. If there is no BSD-style socket layer at all, `WOLFSSL_NO_SOCK` removes the built-in socket code. -wolfSSL uses dynamic buffers for input and output, which default to 0 bytes. If an input record is received that is greater in size than the buffer, then a dynamic buffer is temporarily used to handle the request and then freed. +wolfSSL uses small static buffers for input and output, which by default only hold a record header (`STATIC_BUFFER_LEN`, 5 bytes). If an input record is received that is greater in size than the buffer, then a dynamic buffer is temporarily used to handle the request and then freed. If you prefer using large, 16kB static buffers which will never need dynamic memory, you can enable this option by defining `LARGE_STATIC_BUFFERS`. -If dynamic buffers are used and the user requests an `wolfSSL_write()` that is bigger than the buffer size, then a dynamic block up to `MAX_RECORD_SIZE` is used to send the data. Users wishing to only send the data in chunks of the current buffer size at maximum, as defined by `RECORD_SIZE`, can do this by defining `STATIC_CHUNKS_ONLY`. When using this define, `RECORD_SIZE` defaults to 128 bytes. +If dynamic buffers are used and the user requests a `wolfSSL_write()` that is bigger than the buffer size, then a dynamic block up to `MAX_RECORD_SIZE` is used to send the data. Users wishing to only send the data in chunks of the current buffer size at maximum, as defined by `RECORD_SIZE`, can do this by defining `STATIC_CHUNKS_ONLY`. `RECORD_SIZE` defaults to 128 bytes (`MAX_MTU` in DTLS builds) and can be set to a value from 128 to 16384. ### Filesystem @@ -139,7 +139,7 @@ You can disable wolfSSL's usage of the filesystem by defining `NO_FILESYSTEM` wh Test key and certificate buffers can be found in the `./wolfssl/certs_test.h` header file. These will match up to corresponding certificates and keys found in the `./certs` directory. -The `certs_test.h` header file can be updated using the `./gencertbuf.pl` script if needed. Inside `gencertbuf.pl`, there are two arrays: `fileList_1024` and `fileList_2048`. Additional certificates or keys may be added to the respective array, depending on key size, and must be in DER format. The above mentioned arrays map a certificate/key file location with the desired buffer name. After modifying `gencertbuf.pl`, running it from the wolfSSL root directory will update the certificate and key buffers in `./wolfssl/certs_test.h`: +The `certs_test.h` header file can be updated using the `./gencertbuf.pl` script if needed. Inside `gencertbuf.pl`, there are several arrays, grouped by key type and size: `fileList_ecc`, `fileList_ed`, `fileList_x`, `fileList_1024`, `fileList_2048`, `fileList_3072`, `fileList_4096`, `fileList_sm2`, `fileList_sm2_der`, `fileList_falcon` and `fileList_cn_ip`. Additional certificates or keys may be added to the respective array, and must be in DER format (`fileList_sm2` takes PEM files). The arrays map a certificate/key file location with the desired buffer name. After modifying `gencertbuf.pl`, running it from the wolfSSL root directory will update the certificate and key buffers in `./wolfssl/certs_test.h` (and the SM buffers in `./wolfssl/certs_test_sm.h`): ```sh @@ -147,23 +147,27 @@ The `certs_test.h` header file can be updated using the `./gencertbuf.pl` script ``` -If you would like to use a filesystem other than the default, the filesystem abstraction layer is located in `./wolfssl/wolfcrypt/wc_port.h`. Here you will see filesystem ports for various platforms including EBSNET, FREESCALE_MQX, and MICRIUM. You can add a custom define for your platform if needed - allowing you to define file system functions with `XFILE`, `XFOPEN`, `XFSEEK`, etc. For example, the filesystem layer in `wc_port.h` for Micrium's µC/OS (MICRIUM) is as follows: +If you would like to use a filesystem other than the default, the filesystem abstraction layer is located in `./wolfssl/wolfcrypt/wc_port.h`. Here you will see filesystem ports for various platforms including EBSNET, FREESCALE_MQX, and MICRIUM. You can add a custom define for your platform if needed - allowing you to define file system functions with `XFILE`, `XFOPEN`, `XFSEEK`, etc. For example, the filesystem layer in `wc_port.h` for Micrium's uC/OS (MICRIUM) is as follows: ```c #elif defined(MICRIUM) -#include -#define XFILE FS_FILE* -#define XFOPEN fs_fopen -#define XFSEEK fs_fseek -#define XFTELL fs_ftell -#define XREWIND fs_rewind -#define XFREAD fs_fread -#define XFCLOSE fs_fclose -#define XSEEK_END FS_SEEK_END -#define XBADFILE NULL + #include + #define XFILE FS_FILE* + #define XFOPEN fs_fopen + #define XFSEEK fs_fseek + #define XFTELL fs_ftell + #define XFREAD fs_fread + #define XFWRITE fs_fwrite + #define XFCLOSE fs_fclose + #define XSEEK_SET FS_SEEK_SET + #define XSEEK_END FS_SEEK_END + #define XBADFILE NULL + #define XFGETS(b,s,f) -2 /* Not ported yet */ ``` +Instead of editing `wc_port.h`, you can define `WOLFSSL_USER_FILESYSTEM` and provide all of the `X*` file system macros in `user_settings.h`. + ### Threading **Q: When do I need to read this section?** @@ -172,7 +176,7 @@ A: You want to use wolfSSL in a multithreaded environment, or want to just comp If wolfSSL will only be used in a single threaded environment, the wolfSSL mutex layer can be disabled when compiling wolfSSL by defining `SINGLE_THREADED`. This will negate the need to port the wolfSSL mutex layer. -If wolfSSL needs to be used in a multithreaded environment, the wolfSSL mutex layer will need to be ported to the new environment. The mutex layer can be found in `./wolfssl/wolfcrypt/wc_port.h` and `./wolfcrypt/src/wc_port.c`. `wolfSSL_Mutex` will need to be defined for the new system in `wc_port.h` and the mutex functions (`wc_InitMutex`, `wc_FreeMutex`, `wc_LockMutex` and `wc_UnLockMutex`) in `wc_port.c`. You can search in `wc_port.h` and `wc_port.c` to see an example for some existing platform port layers (EBSNET, FREESCALE_MQX, etc.). +If wolfSSL needs to be used in a multithreaded environment, the wolfSSL mutex layer will need to be ported to the new environment. The mutex layer can be found in `./wolfssl/wolfcrypt/wc_port.h` and `./wolfcrypt/src/wc_port.c`. `wolfSSL_Mutex` will need to be defined for the new system in `wc_port.h` and the mutex functions (`wc_InitMutex`, `wc_FreeMutex`, `wc_LockMutex` and `wc_UnLockMutex`) in `wc_port.c`. You can search in `wc_port.h` and `wc_port.c` to see an example for some existing platform port layers (EBSNET, FREESCALE_MQX, etc.). Alternatively, define `WOLFSSL_USER_MUTEX`, provide the `wolfSSL_Mutex` typedef (for example in `user_settings.h`) and implement the mutex functions in your own code, without modifying `wc_port.h` or `wc_port.c`. ### Random Seed @@ -181,26 +185,28 @@ If wolfSSL needs to be used in a multithreaded environment, the wolfSSL mutex la A: Either `/dev/random` or `/dev/urandom` is not available or you want to integrate into a hardware RNG. -By default, wolfSSL uses `/dev/urandom` or `/dev/random` to generate a RNG seed. The `NO_DEV_RANDOM` define can be used when building wolfSSL to disable the default `GenerateSeed()` function. If this is defined, you need to write a custom `GenerateSeed()` function in `./wolfcrypt/src/random.c`, specific to your target platform. This allows you to seed wolfSSL’s PRNG with a hardware-based random entropy source if available. +By default, wolfSSL uses `/dev/urandom` or `/dev/random` to generate a RNG seed (on Linux, the `getrandom()` system call is used instead when `WOLFSSL_GETRANDOM` or `HAVE_GETRANDOM` is defined). The `NO_DEV_RANDOM` define can be used when building wolfSSL to disable the default `wc_GenerateSeed()` function. If this is defined, you need to provide a seed source specific to your target platform. This allows you to seed wolfSSL's PRNG with a hardware-based random entropy source if available. Instead of modifying `./wolfcrypt/src/random.c`, you can define one of the following in `user_settings.h`: + +* `CUSTOM_RAND_GENERATE_SEED` - name of your seed function, which takes `(byte* output, word32 sz)` and returns 0 on success. +* `CUSTOM_RAND_GENERATE_SEED_OS` - the same, with the `OS_Seed*` as an additional first argument. +* `CUSTOM_RAND_GENERATE_BLOCK` - name of a function with the same `(byte* output, word32 sz)` arguments that replaces the output of the wolfCrypt DRBG entirely, for example with a hardware RNG. -For examples of how `GenerateSeed()` needs to be written, reference wolfSSL’s existing `GenerateSeed()` implementations in `./wolfcrypt/src/random.c`. +For examples of how `wc_GenerateSeed()` can be written, reference wolfSSL's existing `wc_GenerateSeed()` implementations in `./wolfcrypt/src/random.c`. ### Memory **Q: When do I need to read this section?** -A: When you don’t have standard memory functions available or are interested in memory usage differences between optional math libraries. - -wolfSSL proper uses both `malloc()` and `free()` by default. When using the normal big integer math library, wolfCrypt will also use `realloc()`. +A: When you don't have standard memory functions available or are interested in memory usage differences between optional math libraries. -By default wolfSSL/wolfCrypt use the normal big integer math library, which uses quite a bit of dynamic memory. When building wolfSSL, the fastmath library can be enabled, which is both faster and uses no dynamic memory for crypto operations (all on the stack). By using fastmath, wolfSSL won't need a `realloc()` implementation at all. As the SSL layer of wolfSSL still uses some dynamic memory, `malloc()` and `free()` are still required. +wolfSSL proper uses both `malloc()` and `free()` by default. When using the legacy heap math library (`USE_INTEGER_HEAP_MATH`), wolfCrypt will also use `realloc()`. -For a comparison of resource usage (stack/heap) between the big integer math library and fastmath library, ask us to see our Resource Use document. +By default wolfSSL/wolfCrypt use the SP math library (`./wolfcrypt/src/sp_int.c`, `WOLFSSL_SP_MATH_ALL`), which is constant time and by default keeps its big integers on the stack. Define `WOLFSSL_SMALL_STACK` to move large variables from the stack to the heap on targets with little stack, and `WOLFSSL_SP_SMALL` for smaller code. `WOLFSSL_SP_MATH` restricts SP math to the key sizes and curves implemented by the SP code (see Appendix H). The legacy fastmath library (`USE_FAST_MATH`, `./wolfcrypt/src/tfm.c`, `--enable-fastmath`) and heap math library (`USE_INTEGER_HEAP_MATH`, `./wolfcrypt/src/integer.c`, `--enable-heapmath`) are still available; with fastmath, also define `TFM_TIMING_RESISTANT`. As the SSL layer of wolfSSL still uses some dynamic memory, `malloc()` and `free()` are still required. -To enable fastmath, define `USE_FAST_MATH` and build in `./wolfcrypt/src/tfm.c` instead of `./wolfcrypt/src/integer.c`. Since the stack memory can be large when using fastmath, we recommend defining `TFM_TIMING_RESISTANT` as well. +For a comparison of resource usage (stack/heap) between the math libraries, ask us to see our Resource Use document. -If the normal `malloc()`, `free()`, and possibly `realloc()` functions are not available, define `XMALLOC_USER`, then provide custom memory function hooks in `./wolfssl/wolfcrypt/types.h` specific to the target environment. +If the normal `malloc()`, `free()`, and possibly `realloc()` functions are not available, define `XMALLOC_USER`, then provide custom memory function hooks in `./wolfssl/wolfcrypt/types.h` specific to the target environment. Alternatively, define `XMALLOC_OVERRIDE` and supply your own `XMALLOC`, `XFREE` and `XREALLOC` macros, or register allocation functions at run time with `wolfSSL_SetAllocators()`. For systems without a heap, `WOLFSSL_STATIC_MEMORY` (`--enable-staticmemory`) lets wolfSSL allocate from buffers that the application provides with `wc_LoadStaticMemory()`. Please [read section 5.1.1.1](chapter05.md#memory-use) for details about using `XMALLOC_USER`. @@ -211,22 +217,22 @@ Please [read section 5.1.1.1](chapter05.md#memory-use) for details about using ` A: When standard time functions (`time()`, `gmtime()`) are not available, or you need to specify a custom clock tick function. -By default, wolfSSL uses `time()`, `gmtime()`, and `ValidateDate()`, as specified in `./wolfcrypt/src/asn.c`. These are abstracted to `XTIME`, `XGMTIME`, and `XVALIDATE_DATE`. If the standard time functions, and `time.h`, are not available, the user can define `USER_TIME`. After defining `USER_TIME`, the user can define their own `XTIME`, `XGMTIME`, and `XVALIDATE_DATE` functions. +By default, wolfSSL uses `time()`, `gmtime()`, and `wc_ValidateDate()`. These are abstracted to `XTIME`, `XGMTIME`, and `XVALIDATE_DATE` in `./wolfssl/wolfcrypt/wc_port.h`. If the standard time functions, and `time.h`, are not available, the user can define `USER_TIME`. After defining `USER_TIME`, the user can define their own `XTIME`, `XGMTIME`, and `XVALIDATE_DATE` functions. Alternatively, `TIME_OVERRIDES` keeps the standard time types but requires the user to supply both `XTIME` and `XGMTIME`. wolfSSL uses `time(0)` by default for the clock tick function. This is located in `./src/internal.c` inside of the `LowResTimer()` function. -Defining `USER_TICKS` allows the user to define their own clock tick function if `time(0)` is not wanted. The custom function needs second accuracy, but doesn’t have to be correlated to EPOCH. See `LowResTimer()` function in `./src/internal.c` for reference. +Defining `USER_TICKS` allows the user to define their own clock tick function if `time(0)` is not wanted. The custom function needs second accuracy, but doesn't have to be correlated to EPOCH. See `LowResTimer()` function in `./src/internal.c` for reference. ### C Standard Library **Q: When do I need to read this section?** -A: When you don’t have a C standard library available, or have a custom one. +A: When you don't have a C standard library available, or have a custom one. wolfSSL can be built without the C standard library to provide a higher level of portability and flexibility to developers. When doing so, the user needs to map functions they wish to use instead of the C standard ones. -Section 7, above, covered memory functions. In addition to memory function abstraction, wolfSSL also abstracts string function and math functions, where the specific functions are typically abstracted to a define in the form of `X`, where `` is the name of the function being abstracted. +The Memory section above covered memory functions. In addition to memory function abstraction, wolfSSL also abstracts string function and math functions, where the specific functions are typically abstracted to a define in the form of `X`, where `` is the name of the function being abstracted. Please read [Section 5.1](chapter05.md) for details. @@ -235,7 +241,7 @@ Please read [Section 5.1](chapter05.md) for details. **Q: When do I need to read this section?** -A: You want to enable debug messages but don’t have stderr available. +A: You want to enable debug messages but don't have stderr available. By default, wolfSSL provides debug output through stderr. In order for debug messages to be enabled, wolfSSL must be compiled with `DEBUG_WOLFSSL` defined, and `wolfSSL_Debugging_ON()` must be called from the application code. `wolfSSL_Debugging_OFF()` may be used by the application layer to turn off wolfSSL debug messages. @@ -250,16 +256,14 @@ Please read [Section 8.1](chapter08.md) for details. A: You want to use your own public key implementation with wolfSSL. -wolfSSL allows users to write their own public key callbacks which will be called when the SSL/TLS layer needs to do public key operations. The user can optionally define 6 functions: +wolfSSL allows users to write their own public key callbacks which will be called when the SSL/TLS layer needs to do public key operations. The user can optionally define several callbacks, for example: - - -1. ECC sign callback -2. ECC verify callback -3. RSA sign callback -4. RSA verify callback -5. RSA encrypt callback -6. RSA decrypt callback +1. ECC key generation, sign, verify and shared secret callbacks +2. RSA sign, verify, encrypt and decrypt callbacks, including RSA-PSS sign and verify +3. DH agree callback +4. Ed25519 and Ed448 sign and verify callbacks +5. X25519 and X448 key generation and shared secret callbacks +6. TLS key derivation callbacks (for example master secret, session keys, Finished and HKDF) For full details, please read [Section 6.4](chapter06.md#public-key-callbacks). @@ -277,6 +281,8 @@ The user will need to define 2 functions: 1. MAC/encrypt callback function 2. Decrypt/verify callback function +When Encrypt-Then-MAC is negotiated, two more callbacks are used: an encrypt/MAC callback (`wolfSSL_CTX_SetEncryptMacCb()`) and a verify/decrypt callback (`wolfSSL_CTX_SetVerifyDecryptCb()`). + For full details, please read [Section 6.3](chapter06.md#user-atomic-record-layer-processing). @@ -289,6 +295,15 @@ A: When you want to disable features. Features can be disabled when building wolfSSL by using the appropriate defines. For a list of defines available, please refer to [Chapter 2](chapter02.md). +### Crypto Callbacks + +**Q: When do I need to read this section?** + +A: You want to offload wolfCrypt operations to a hardware accelerator, secure element or other device. + +Crypto callbacks (`WOLF_CRYPTO_CB`, `--enable-cryptocb`) let you register a device with `wc_CryptoCb_RegisterDevice()` and handle cipher, hash, public key and RNG operations for that device without modifying the wolfCrypt sources. Many of the hardware ports in Appendix H use this mechanism. For full details, please read [Crypto Callbacks (cryptocb)](chapter06.md#crypto-callbacks-cryptocb). + + ## Next Steps @@ -298,14 +313,14 @@ After getting wolfSSL proper to build on the target platform, a good next step i If this step is skipped, and you instead proceed directly to establishing an SSL connection, it can be more difficult to debug problems caused by underlying crypto operations failing. -The wolfCrypt test application is located in `./wolfcrypt/test/test.c`. If an embedded application has its own `main()` function, then `NO_MAIN_DRIVER` must be defined when compiling `./wolfcrypt/test/test.c`. This will allow the application’s `main()` to call each cipher/algorithm test individually on its own. +The wolfCrypt test application is located in `./wolfcrypt/test/test.c`. If an embedded application has its own `main()` function, then `NO_MAIN_DRIVER` must be defined when compiling `./wolfcrypt/test/test.c`. This will allow the application's `main()` to call each cipher/algorithm test individually on its own. If an embedded device does not have enough resources to run the entire wolfCrypt test application, individual tests can be broken out of `test.c` and compiled individually. Please ensure that correct header files needed for the specific test case are included in the build when extracting isolated crypto tests from `test.c`. ## Support -General support questions may be sent directly to wolfSSL either through email, support forums, or wolfSSL’s Zendesk ticket tracking system. +General support questions may be sent directly to wolfSSL either through email, support forums, or wolfSSL's Zendesk ticket tracking system. Website: [https://www.wolfssl.com](https://www.wolfssl.com) diff --git a/wolfSSL/src/appendix11.md b/wolfSSL/src/appendix11.md index fc167552..0f0fea76 100644 --- a/wolfSSL/src/appendix11.md +++ b/wolfSSL/src/appendix11.md @@ -26,15 +26,15 @@ git clone https://github.com/wolfssl/wolfsm.git wolfSSL is needed to build and test the SM algorithm implementations. Checkout the wolfSSL repository from GitHub beside wolfSM: -```sh +```text # Directory structure should be: # -# ├── wolfsm -# └── wolfssl +# |-- wolfsm +# `-- wolfssl ``` ```sh -cd .. # To directory containing wolfsm +# From , the directory containing wolfsm git clone https://github.com/wolfssl/wolfssl.git ``` @@ -63,6 +63,7 @@ Choose which algorithms you require on the configure line: For example, to include SM3, SM4-GCM and SM2: ```sh +cd ../wolfssl ./autogen.sh ./configure --enable-sm3 --enable-sm4-gcm --enable-sm2 make @@ -73,8 +74,8 @@ sudo make install To use optimized implementations of SM2 you can either use C only code or C code with the faster assembly code. -For C code only: `--enable-sp` -For C and assembly code: `--enable-sp --enable-sp-asm` +* For C code only: `--enable-sp` +* For C and assembly code: `--enable-sp --enable-sp-asm` Optimized C code is available for 32 and 64 bit CPUs. @@ -84,6 +85,7 @@ Assembly code is available for the following platforms: * ARM 32-bit * ARM Thumb2 * ARM Thumb +* RISC-V 64-bit ## Testing wolfSM @@ -111,7 +113,7 @@ To benchmark specific algorithms, add to the command line the option/s matching SM ciphers are able to be used with TLSv1.2 and TLSv1.3. -Note: SM2, SM3 and at least one SM4 cipher must be built in order for SM ciphers suite to work. All algorithms must be SM. +Note: SM2, SM3 and at least one SM4 cipher must be built in order for the SM cipher suites to work. All algorithms must be SM. The cipher suites added are: - ECDHE-ECDSA-SM4-CBC-SM3 (TLSv1.2, `--enable-sm2 --enable-sm3 --enable-sm4-cbc`) diff --git a/wolfSSL/src/chapter01.md b/wolfSSL/src/chapter01.md index 5edff6a9..b51efec5 100644 --- a/wolfSSL/src/chapter01.md +++ b/wolfSSL/src/chapter01.md @@ -10,8 +10,10 @@ You can find the PDF version of this document [here](https://www.wolfssl.com/doc There are many reasons to choose wolfSSL as your embedded SSL solution. Some of the top reasons include size (typical footprint sizes range from 20-100 kB), support for -the newest standards (SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3, DTLS 1.0, DTLS 1.2, -and DTLS 1.3), current and progressive cipher support (including stream ciphers), multi- -platform, royalty free, and an OpenSSL compatibility API to ease porting into existing -applications which have previously used the OpenSSL package. For a complete feature +current standards (TLS 1.2, TLS 1.3, DTLS 1.2 and DTLS 1.3, with the legacy SSL 3.0, +TLS 1.0, TLS 1.1 and DTLS 1.0 available as build options), current and progressive +cipher support (including stream ciphers and post-quantum algorithms such as ML-KEM, +which is enabled by default), multi-platform, royalty free, and an OpenSSL compatibility +API to ease porting into existing applications which have previously used the OpenSSL +package. For a complete feature list, see [Features Overview](chapter04.md#features-overview). diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index 8be0ffc2..82febf08 100644 --- a/wolfSSL/src/chapter02.md +++ b/wolfSSL/src/chapter02.md @@ -1,8 +1,8 @@ # Building wolfSSL -wolfSSL was written with portability in mind and should generally be easy to build on most systems. If you have difficulty building wolfSSL, please don’t hesitate to seek support through our support forums () or contact us directly at [support@wolfssl.com](mailto:support@wolfssl.com). +wolfSSL was written with portability in mind and should generally be easy to build on most systems. If you have difficulty building wolfSSL, please don't hesitate to seek support through our support forums () or contact us directly at [support@wolfssl.com](mailto:support@wolfssl.com). -This chapter explains how to build wolfSSL on Unix and Windows, and provides guidance for building wolfSSL in a non-standard environment. You will find the “getting started” guide in [Chapter 3](chapter03.md#getting-started) and an SSL tutorial in [Chapter 11](chapter11.md#ssl-tutorial). +This chapter explains how to build wolfSSL on Unix and Windows, and provides guidance for building wolfSSL in a non-standard environment. You will find the "getting started" guide in [Chapter 3](chapter03.md#getting-started) and an SSL tutorial in [Chapter 11](chapter11.md#ssl-tutorial). When using the autoconf / automake system to build wolfSSL, wolfSSL uses a single Makefile to build all parts and examples of the library, which is both simpler and faster than using Makefiles recursively. @@ -15,15 +15,23 @@ The most recent version of wolfSSL can be downloaded from the wolfSSL website as After downloading the ZIP file, unzip the file using the `unzip` command. To use native line endings, enable the `-a` modifier when using unzip. From the unzip man page, the `-a` modifier functionality is described: > [...] The -a option causes files identified by zip as text files (those with -> the ‘t’ label in zipinfo listings, rather than ‘b’) to be automatically +> the 't' label in zipinfo listings, rather than 'b') to be automatically > 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 + +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. + +## Building with CMake + +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. + +CMake does not allow building in the source directory, so create a separate build directory. From the wolfSSL root directory: + +```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. -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). +Build options are set with `-D