From f9720e15bfb8eb4c4dbf5d9efdf12f8603365cc1 Mon Sep 17 00:00:00 2001 From: Jack Tjaden Date: Thu, 6 Jun 2024 13:48:39 -0600 Subject: [PATCH 1/3] Added wolfSSL-FAQ directory --- Makefile | 8 +- wolfSSL-FAQ/Makefile | 17 +++ wolfSSL-FAQ/header.txt | 21 +++ wolfSSL-FAQ/mkdocs.yml | 25 ++++ wolfSSL-FAQ/src/section01.md | 24 ++++ wolfSSL-FAQ/src/section02.md | 257 +++++++++++++++++++++++++++++++++++ 6 files changed, 351 insertions(+), 1 deletion(-) create mode 100644 wolfSSL-FAQ/Makefile create mode 100644 wolfSSL-FAQ/header.txt create mode 100644 wolfSSL-FAQ/mkdocs.yml create mode 100644 wolfSSL-FAQ/src/section01.md create mode 100644 wolfSSL-FAQ/src/section02.md diff --git a/Makefile b/Makefile index d3bcec0b..9b1d9455 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ endif DOCKER_CMD=DOCKER_BUILDKIT=1 docker build -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --build-arg V=$(V) --target=manual --output=build -f Dockerfile . -all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfhsm wolfengine fips-ready tuning porting +all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfhsm wolfengine fips-ready tuning porting faq build: $(Q)mkdir -p build @@ -94,5 +94,11 @@ tuning: PDFFILE=wolfSSL-Tuning-Guide.pdf tuning: build @$(DOCKER_CMD) +.PHONY: faq +faq: MANPATH=wolfSSL-FAQ +faq: PDFFILE=wolfSSL-FAQ.pdf +faq: build + @$(DOCKER_CMD) + clean: $(Q)rm -rf build diff --git a/wolfSSL-FAQ/Makefile b/wolfSSL-FAQ/Makefile new file mode 100644 index 00000000..c1da31ca --- /dev/null +++ b/wolfSSL-FAQ/Makefile @@ -0,0 +1,17 @@ +-include ../common/common.am +.DEFAULT_GOAL := all +all: pdf html + + +SOURCES = section01.md \ + section02.md + +PDF = wolfSSL-FAQ.pdf +DOXYFILE = Doxyfile + + +.PHONY: html-prep +html-prep: + +.PHONY: pdf-prep +pdf-prep: diff --git a/wolfSSL-FAQ/header.txt b/wolfSSL-FAQ/header.txt new file mode 100644 index 00000000..aeed092f --- /dev/null +++ b/wolfSSL-FAQ/header.txt @@ -0,0 +1,21 @@ +% wolfSSL Tuning Guide ![](logo.png) + +--- +header-includes: + # Blank pages on new sections + - \usepackage{titlesec} + - \newcommand{\sectionbreak}{\clearpage} + # Fancy page headers + - \usepackage{fancyhdr} + - \pagestyle{fancy} + - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.} + # Wrap long syntax highlighting code blocks + - \usepackage{fvextra} + - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}} + # Wrap long non-sytax highlighted code blocks + - \usepackage{listings} + - \let\verbatim\undefined + - \let\verbatimend\undefined + - \lstnewenvironment{verbatim}{\lstset{breaklines,basicstyle=\ttfamily}}{} +subparagraph: yes +--- diff --git a/wolfSSL-FAQ/mkdocs.yml b/wolfSSL-FAQ/mkdocs.yml new file mode 100644 index 00000000..018bb5da --- /dev/null +++ b/wolfSSL-FAQ/mkdocs.yml @@ -0,0 +1,25 @@ +site_name: wolfSSL FAQ +site_url: https://wolfssl.com/ +docs_dir: build/html/ +site_dir: html/ +copyright: Copyright © 2024 wolfSSL Inc. +nav: + - "1. Introduction": index.md + - "2. FAQ": section02.md +theme: + name: null + custom_dir: ../mkdocs-material/material + language: en + palette: + primary: indigo + accent: indigo + font: + text: roboto + code: roboto mono + icon: "logo.png" + logo: logo.png + favicon: logo.png + feature: + tabs: true +extra_css: [skin.css] +use_directory_urls: false diff --git a/wolfSSL-FAQ/src/section01.md b/wolfSSL-FAQ/src/section01.md new file mode 100644 index 00000000..117a4595 --- /dev/null +++ b/wolfSSL-FAQ/src/section01.md @@ -0,0 +1,24 @@ +# Introduction + +This page lists some of the most common issues and questions that are received by our wolfSSL +security experts, along with their responses. This FAQ is useful for solving general +questions that pertain to building/implementing wolfSSL. +If this page does not provide an answer to your question, please feel free to check +the wolfSSL Manual, or contact us at support@wolfssl.com. + +## Questions + +1. How do I manage the build configuration for wolfSSL? +2. How do I find the correct CA certificate to load into a client for authenticating a SSL/TLS server? +3. How do I put my certificate into a buffer? +4. How much Flash/RAM does wolfSSL use? +5. Is it possible to use no dynamic memory with wolfSSL and/or wolfCrypt? +6. How do I build wolfSSL on... (*NIX, Windows, Embedded device)? +7. How do I pull wolfSSL into my IDE project? What files and headers do I need? +8. Do you have benchmarks for my specific platform? +9. Why are there no common cipher suites found between my client/server when connecting? +10. Can I use a smaller maximum I/O record size than 16kB? +11. How do I extract a public key from a X.509 certificate? +12. Do you have examples of using SSL/TLS or cryptography? +13. Why won’t my application connect to a server, I have enabled required ciphers and protocol version...? +14. How do I sign a certificate? diff --git a/wolfSSL-FAQ/src/section02.md b/wolfSSL-FAQ/src/section02.md new file mode 100644 index 00000000..f661cdd9 --- /dev/null +++ b/wolfSSL-FAQ/src/section02.md @@ -0,0 +1,257 @@ +# Frequently Asked Questions + +## How do I manage the build configuration for wolfSSL? + +The MOST common issue we see is a mis-configuration between APP and Library. If you compile the +wolfSSL library independent of your application you MUST include the same configure options in +the application as were used in the library. + +If building with “./configure” the build system will generate the file +`/wolfssl/options.h` with all the settings needed for your application. +Simply add the lines: + +``` +#include +#include +#include +/* other wolf headers below */ +``` + +If building the wolfSSL sources directly the options.h will not contain any generated +configuration. In that case our recommended option is to define the preprocessor macro +“WOLFSSL_USER_SETTINGS” in your project and create your own “user_settings.h” file. Make +sure the file is somewhere in your include path. You can use the same include pattern above, +but exclude the options.h. + +Here are some example “user_settings.h” you can use for reference: + +* Windows: /IDE/WIN/user_settings.h +* GCC ARM: /IDE/GCC-ARM/Header/user_settings.h +* NXP ARM: /IDE/ROWLEY-CROSSWORKS-ARM/user_settings.h +* Xcode: /IDE/XCODE/user_settings.h + +## How do I find the correct CA certificate to load into a client for authenticating a SSL/TLS server? + +How to find and load the correct CA (root) certificate into a client application or device can be +tricky at first. First, users need to understand how wolfSSL verifies certificate chains. +[Section 7.3](https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-7-keys-and-certificates.html) of +the [wolfSSL Manual](https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-toc.html) explains +wolfSSL’s certificate validation process: + +wolfSSL requires that only the top or **“root”** certificate in a chain to be loaded as a trusted +certificate in order to verify a certificate chain SO LONG as the server sends the complete chain. +This means that if you have a certificate chain ( **A** -> **B** -> **C** ), where C is signed +by B, and B is signed by A, wolfSSL only requires that **certificate A** be loaded as a trusted +certificate in order to verify the entire chain (A->B->C) assuming that the server sends both +(B -> C) in the handshake. + +Let’s look at a simple example. If a server certificate chain looks like this: + +``` +A +| ---- > B + | ---- > C +``` + +The wolfSSL client should already have at least root **cert “A”** loaded as a trusted root (wolfSSL_CTX_load_verify_[ locations | buffer]). When the client receives the server +cert chain (B -> C), it uses the verify certificate (A) to verify B, and if B has not been +previously loaded into wolfSSL as a trusted root, B gets stored in wolfSSL's internal cert chain. +If B is verified successfully, then it can be used to verify C. + +Following this model, as long as root cert "A" has been loaded as a trusted root into the +wolfSSL client, the server certificate chain will still be able to be verified if the server +sends (A->B->C), or (B->C). If the server ONLY sends (C), and not the intermediate certificate, +the chain will not be able to be verified unless the wolfSSL client has already loaded both A and +B as a trusted roots. You may call wolfSSL_CTX_load_verify_[ locations | buffer] as many times as +is necessary to load all of your trusted roots, wolfSSL will keep appending them into the trust +store. + +Examples: + +``` +// Load a PEM formatted file: +wolfSSL_CTX_load_verify_locations(ctx, fileName, NULL); + +// Load a DER formatted file: +wolfSSL_CTX_der_load_verify_locations(ctx, fileName, WOLFSSL_FILETYPE_ASN1); + +// Load a DER formatted buffer: +wolfSSL_CTX_load_verify_buffer(ctx, buf, bufLength, WOLFSSL_FILETYPE_ASN1) + +// Load ALL PEM files in a directory +wolfSSL_CTX_load_verify_locations(ctx, NULL, directoryName); +``` + +## How do I put my certificate into a buffer? + +To generate a certificate buffer you will find a perl script `/gencertbuf.pl` +(short for generate certificate buffers) + +1. You would want to acquire your own certificate and place it in a location that suits your +needs. (We keep our test ones in `/certs/` directory, feel free to also place your +valid ones there also). +2. Modify the above mentioned perl script and add your new certificate(s) to the appropriate +`@fileList` (1024 for 1024 bit RSA certs, 256 for ECC 256-bit certs... etc) +3. Re-run that script to re-generate the header file `/wolfssl/certs_test.h` + +You have to run this file manually IE: `perl gencertbuf.pl` OR `./gencertbuf.pl` + +## How much Flash/RAM does wolfSSL use? + +wolfSSL memory usage depends on how the library is configured when it is compiled and what features +you plan on using. Many options exist to control the amount of memory the library uses. Please +[contact us](mailto:facts@wolfssl.com) for the wolfSSL Resource Use document. + +The primary factors in peak resource usage are key size and the math library used. Fast math and +a larger key size increases resource utilization. + +## Is it possible to use no dynamic memory with wolfSSL and/or wolfCrypt? + +wolfSSL provides two mutually exclusive options to control the usage of dynamic memory. You can +configure wolfSSL with `--enable-staticmemory` or by defining the WOLFSSL_STATIC_MEMORY macro. +However, this feature is limited to basic TLS connections and currently is not supported +in wolfCrypt. You can also define the macro `XMALLOC_USER` to have wolfSSL use your own +malloc function. + +## How do I build wolfSSL on... (*NIX, Windows, Embedded device)? + +Please see section 2 of the wolfSSL Manual located +[HERE](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html) +which covers building wolfSSL. + +## How do I pull wolfSSL into my IDE project? What files and headers do I need? + +wolfSSL provides the necessary project files for many popular IDEs. You can find instructions for +these IDEs in the /IDE/ directory of the wolfSSL source. + +src/*.c +wolfcrypt/src/*.c +wolfssl/*.h +wolfssl/wolfcrypt/*.h +Include path wolfssl root. + +Further documentation on building wolfSSL on various platforms can be found in [Section 2.4 wolfSSL Manual](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html). + +## Do you have benchmarks for my specific platform? + +wolfSSL provides a benchmark application that can be compiled for any platform wolfSSL supports. +The benchmark application will run benchmarks on enabled algorithms. The application source is +located in wolfcrypt/benchmark/benchmark.c. For *nix platforms, the benchmark can be ran using +./wolfcrypt/benchmark/benchmark. The benchmark is compiled by default. + +If benchmarking on an embedded platform, define `BENCH_EMBEDDED` + +For more details regarding benchmarking wolfSSL, please reference the [wolfSSL and wolfCrypt Benchmarks webpage](https://www.wolfssl.com/docs/benchmarks/). + +## Why are there no common cipher suites found between my client/server when connecting? + +Ensure that wolfSSL was configured and built with common cipher suites on both the client +and server. You can add additional cipher suites with configure options. You can view configure +options on *nix systems with ./`configure --help` + +To view default cipher suite on *nix system use this command from `` directory: + +`./examples/client/client -e` + +To view default cipher suites on windows system use this command from the directory where +client.exe is located: + +`./client.exe -e` + +``` +nmap --script ssl-enum-ciphers -p 443 www.google.com +``` + +## Can I use a smaller maximum I/O record size than 16kB? + +TLS specifies a fixed maximum record length of 2^14 bytes (~16kB). wolfSSL provides two +options to use a smaller maximum record size. The first option is to configure wolfSSL with +`--enable-maxfragment`. This requires the client to make an additional call when connecting to a +server. The client needs to use either `wolfSSL_CTX_UseMaxFragment` or `wolfSSL_UseMaxFragment`. +The client should use the CTX method if they plan on making multiple connections to the same +server. + +The other option is to define `MAX_RECORD_SIZE`. In order to use this, however, both the client +and server needs to have the option set. If the client is connecting to servers outside of your +control, this is not an option to use. + +## How do I extract a public key from a X.509 certificate? + +wolfSSL provides this functionality in its public API. You can call `wolfssl_x509_get_pubkey()` +to return a WOLFSSL_EVP_PKEY pointer. WOLFSSL_EVP_PKEY is a struct with several data members +related to the key. You can access the key directly from this pointer. The declaration of the +struct can be found in ``. + +## Do you have examples of using SSL/TLS or cryptography? + +wolfSSL maintains several examples for using the library on the official wolfSSL GitHub +repository. You can download the examples by cloning the repository at +[https://github.com/wolfSSL/wolfssl-examples](https://github.com/wolfSSL/wolfssl-examples). + +Some of the more heavily trafficked directories are: + +- [https://github.com/wolfSSL/wolfssl-examples/tree/master/tls](https://github.com/wolfSSL/wolfssl-examples/tree/master/tls) +- [https://github.com/wolfSSL/wolfssl-examples/tree/master/dtls](https://github.com/wolfSSL/wolfssl-examples/tree/master/dtls) +- [https://github.com/wolfSSL/wolfssl-examples/tree/master/certgen](https://github.com/wolfSSL/wolfssl-examples/tree/master/certgen) + +There are currently examples of using algorithms (3DES, AES, and Camellia), examples of using TLS client and server, wolfSSL CertManager, and signatures and verification. + +For users looking for a command line utility for wolfSSL, see the wolfCLU repository +([https://github.com/wolfSSL/wolfCLU](https://github.com/wolfSSL/wolfCLU)). + +## Why won’t my application connect to a server, I have enabled required ciphers and protocol version...? + +Some servers require specific TLS extensions and specific ECC curves to be enabled or they +will ignore any connection attempt outright regardless of supported ciphers and protocol version. +If you are building wolfSSL without the configure script (Makefile project, IDE project, etc), +please make sure you have defined `HAVE_TLS_EXTENSIONS` and `HAVE_SUPPORTED_CURVES`. + +## How do I sign a certificate? + +Signing certificates is a key feature of many secure protocols. wolfSSL provides API that are +capable of performing this action and make the process simple and painless. The key API that +implement this functionality are listed below: + +* [wc_MakeCerReq](https://www.wolfssl.com/documentation/manuals/wolfssl/group__ASN.html#function-wc_makecertreq) +* [wc_SignCert](https://www.wolfssl.com/documentation/manuals/wolfssl/group__ASN.html#function-wc_signcert) + +wolfSSL also maintains an example repository that shows these API in action, and provides the +context in which to use them. This is shown in the CSR example application, which is located +within `wolfssl-examples/certgen/`. To build and run the example, it requires wolfSSL to be built +and installed as well (with certain options). wolfSSL can be downloaded from the +[download page](https://www.wolfssl.com/download/), or from a git-clone command, while the examples +can be downloaded from a git-clone of the examples repository [https://github.com/wolfSSL/wolfssl-examples](https://github.com/wolfSSL/wolfssl-examples). + +An example of cloning and then building wolfSSL with the examples is shown below: + +``` +# Download, build, and install wolfSSL +git clone https://github.com/wolfSSL/wolfssl #(if not downloaded from the download page) +cd wolfssl +./autogen.sh +./configure --enable-certgen --enable-certreq +make +sudo make install +cd .. + +# Download and build the CSR example +git clone https://github.com/wolfSSL/wolfssl-examples +cd wolfssl-examples/certgen/ +make + +./csr_example +-----BEGIN EC PRIVATE KEY----- +MHcCAQEEIOkUjkguP0GTizna+13jooJu55sbQBsAqqkMZqjQeO55oAoGCCqGSM49 +AwEHoUQDQgAEWYTvqyt3e3nLkIWqBhjmZcxLu8XcLN+mUW+g4dO5qdGxnKEYxaz1 +3/K3dXlU75e3MlCIjC5gTiEuPbs3N+eIzw== +-----END EC PRIVATE KEY----- +-----BEGIN CERTIFICATE REQUEST----- +MIIBTDCB8wIBAjCBkDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAk9SMREwDwYDVQQH +DAhQb3J0bGFuZDEQMA4GA1UECgwHd29sZlNTTDEUMBIGA1UECwwLRGV2ZWxvcG1l +bnQxGDAWBgNVBAMMD3d3dy53b2xmc3NsLmNvbTEfMB0GCSqGSIb3DQEJARYQaW5m +b0B3b2xmc3NsLmNvbTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABFmE76srd3t5 +y5CFqgYY5mXMS7vF3CzfplFvoOHTuanRsZyhGMWs9d/yt3V5VO+XtzJQiIwuYE4h +Lj27NzfniM+gADAKBggqhkjOPQQDAgNIADBFAiEAy8GSm89MAU69hKfp6rwaR3Eg +IjaBzRZ4VxRl22LQ+IcCIEiP9OLVIemAfZz2D26g/3oIF2ETjjwAhh8UpZSiJmdh +-----END CERTIFICATE REQUEST----- +``` From 9083dfa63e446d893a72f92236ea70f97c6a701c Mon Sep 17 00:00:00 2001 From: Jack Tjaden Date: Fri, 7 Jun 2024 09:45:21 -0600 Subject: [PATCH 2/3] Added links from ToC to headers --- wolfSSL-FAQ/src/section01.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/wolfSSL-FAQ/src/section01.md b/wolfSSL-FAQ/src/section01.md index 117a4595..8af7cb13 100644 --- a/wolfSSL-FAQ/src/section01.md +++ b/wolfSSL-FAQ/src/section01.md @@ -8,17 +8,17 @@ the wolfSSL Manual, or contact us at support@wolfssl.com. ## Questions -1. How do I manage the build configuration for wolfSSL? -2. How do I find the correct CA certificate to load into a client for authenticating a SSL/TLS server? -3. How do I put my certificate into a buffer? -4. How much Flash/RAM does wolfSSL use? -5. Is it possible to use no dynamic memory with wolfSSL and/or wolfCrypt? -6. How do I build wolfSSL on... (*NIX, Windows, Embedded device)? -7. How do I pull wolfSSL into my IDE project? What files and headers do I need? -8. Do you have benchmarks for my specific platform? -9. Why are there no common cipher suites found between my client/server when connecting? -10. Can I use a smaller maximum I/O record size than 16kB? -11. How do I extract a public key from a X.509 certificate? -12. Do you have examples of using SSL/TLS or cryptography? -13. Why won’t my application connect to a server, I have enabled required ciphers and protocol version...? -14. How do I sign a certificate? +1. [How do I manage the build configuration for wolfSSL?](./section02.md#how-do-i-manage-the-build-configuration-for-wolfssl) +2. [How do I find the correct CA certificate to load into a client for authenticating a SSL/TLS server?](./section02.md#how-do-i-find-the-correct-ca-certificate-to-load-into-a-client-for-authenticating-a-ssl-tls-server) +3. [How do I put my certificate into a buffer?](./section02.md#how-do-i-put-my-certificate-into-a-buffer) +4. [How much Flash/RAM does wolfSSL use?](./section02.md#how-much-flash-ram-does-wolfssl-use) +5. [Is it possible to use no dynamic memory with wolfSSL and/or wolfCrypt?](./section02.md#is-it-possible-to-use-no-dynamic-memory-with-wolfssl-and-or-wolfcrypt) +6. [How do I build wolfSSL on... (*NIX, Windows, Embedded device)?](./section02.md#how-do-i-build-wolfssl-on-nix-windows-embedded-device) +7. [How do I pull wolfSSL into my IDE project? What files and headers do I need?](./section02.md#how-do-i-pull-wolfssl-into-my-ide-project-what-files-and-headers-do-i-need) +8. [Do you have benchmarks for my specific platform?](./section02.md#do-you-have-benchmarks-for-my-specific-platform) +9. [Why are there no common cipher suites found between my client/server when connecting?](./section02.md#why-are-there-no-common-cipher-suites-found-between-my-client-server-when-connecting) +10. [Can I use a smaller maximum I/O record size than 16kB?](./section02.md#can-i-use-a-smaller-maximum-io-record-size-than-16kb) +11. [How do I extract a public key from a X.509 certificate?](./section02.md#how-do-i-extract-a-public-key-from-a-x509-certificate) +12. [Do you have examples of using SSL/TLS or cryptography?](./section02.md#do-you-have-examples-of-using-ssl-tls-or-cryptography) +13. [Why won’t my application connect to a server, I have enabled required ciphers and protocol version...](./section02.md#why-wont-my-application-connect-to-a-server-i-have-enabled-required-ciphers-and-protocol-version) +14. [How do I sign a certificate?](./section02.md#how-do-i-sign-a-certificate) From afe2c1034dc1c9e4df36debbf1705d99d51f3a0c Mon Sep 17 00:00:00 2001 From: Jack Tjaden Date: Fri, 7 Jun 2024 10:07:23 -0600 Subject: [PATCH 3/3] Fixed header to FAQ --- wolfSSL-FAQ/header.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wolfSSL-FAQ/header.txt b/wolfSSL-FAQ/header.txt index aeed092f..bdf7bc0f 100644 --- a/wolfSSL-FAQ/header.txt +++ b/wolfSSL-FAQ/header.txt @@ -1,4 +1,4 @@ -% wolfSSL Tuning Guide ![](logo.png) +% wolfSSL FAQ ![](logo.png) --- header-includes: