diff --git a/Makefile b/Makefile index 8c839706..16fb7aad 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ DOCKER_CMD=DOCKER_BUILDKIT=1 docker build -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --target=manual --output=build -f Dockerfile . -all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfengine fips-ready +all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfengine fips-ready tuning porting build: @mkdir -p build @@ -77,6 +77,11 @@ fips-ready: PDFFILE=wolfSSL-FIPS-Ready.pdf fips-ready: build @$(DOCKER_CMD) +.PHONY: tuning +tuning: MANPATH=wolfSSL-Tuning +tuning: PDFFILE=wolfSSL-Tuning-Guide.pdf +tuning: build + @$(DOCKER_CMD) clean: rm -rf build diff --git a/wolfSSL-Tuning/Makefile b/wolfSSL-Tuning/Makefile new file mode 100644 index 00000000..b4995ce4 --- /dev/null +++ b/wolfSSL-Tuning/Makefile @@ -0,0 +1,19 @@ +-include ../common/common.am +.DEFAULT_GOAL := all +all: pdf html + + +SOURCES = section01.md \ + section02.md \ + section03.md \ + section04.md + +PDF = wolfSSL-Tuning-Guide.pdf +DOXYFILE = Doxyfile + + +.PHONY: html-prep +html-prep: + +.PHONY: pdf-prep +pdf-prep: diff --git a/wolfSSL-Tuning/header.txt b/wolfSSL-Tuning/header.txt new file mode 100644 index 00000000..aeed092f --- /dev/null +++ b/wolfSSL-Tuning/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-Tuning/mkdocs.yml b/wolfSSL-Tuning/mkdocs.yml new file mode 100644 index 00000000..d41e87a0 --- /dev/null +++ b/wolfSSL-Tuning/mkdocs.yml @@ -0,0 +1,27 @@ +site_name: wolfSSL Tuning Guide +site_url: https://wolfssl.com/ +docs_dir: build/html/ +site_dir: html/ +copyright: Copyright © 2024 wolfSSL Inc. +nav: + - "1. Introduction": index.md + - "2. Considerations": section02.md + - "3. Recipes": section03.md + - "4. Additional Information": section04.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-Tuning/src/section01.md b/wolfSSL-Tuning/src/section01.md new file mode 100644 index 00000000..5ef331ca --- /dev/null +++ b/wolfSSL-Tuning/src/section01.md @@ -0,0 +1,21 @@ +# Introduction + +This guide provides a reference for developers and engineers to tune and optimize the performance +and memory usage of the wolfSSL embedded SSL library. 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. One of our main goals +for wolfSSL is ease of use. + +## Audience + +This guide caters to developers or engineers interested in optimizing the performance and +memory usage of the wolfSSL embedded SSL library. + +## Overview + +The wolfSSL Tuning Guide is designed to help developers and engineers optimize the performance +and memory usage of the wolfSSL embedded SSL library. This evolving document aims to provide +comprehensive instructions and clarifications to ensure ease of use and adaptability for +various environments. The guide targets developers interested in refining the efficiency +of SSL/TLS operations by balancing memory footprint, performance, and security according +to specific requirements. diff --git a/wolfSSL-Tuning/src/section02.md b/wolfSSL-Tuning/src/section02.md new file mode 100644 index 00000000..e8634f36 --- /dev/null +++ b/wolfSSL-Tuning/src/section02.md @@ -0,0 +1,69 @@ +# Considerations + +## Anticipated Requirements + +The first step in tuning wolfSSL to your environment is to document your anticipated requirements. +At the highest level, design goals for SSL/TLS usually boil down to: + +- **Memory Footprint (ROM)** +- **Per-session Memory Usage (RAM)** +- **SSL Handshake Performance** +- **Data Flow Performance (bulk data transfer)** +- **Desired Security Level (see Figure 1, below)** + +## Desired Security Levels + +| Security Level | Level Name | Description | +|----------------|---------------------|---------------------------------------------------------| +| 1 | Relaxed | You just need to keep out the casual onlookers | +| 2 | Moderate | You have potential attackers out there, but they are not highly motivated | +| 3 | Corporate | Secure against professional attacks | +| 4 | Military Grade | Title speaks for itself | +| 5 | Quantum Survivable | Can survive against quantum computing based attacks | + +**Figure 1: Desired Security Levels** + +Each of these top-level goals will have trade-offs against the others as you evolve your design. + +To get started, the key variables you need to define include: + +1. Available hardware: + a. Memory available to SSL/TLS (ROM / RAM) + b. CPU type and clock speed +2. Required SSL/TLS protocol levels (i.e: TLS 1.0, TLS 1.1, TLS 1.2, etc.) +3. Required cipher suites. If the cipher suites are not defined in your requirement, you are +free to choose cipher suites that match your performance goals: + a. Public key algorithm with key length (RSA, ECC, NTRU, PSK, etc.) + b. Block / Stream ciphers (AES, DES, 3DES, RC4, HC-128, etc.) + c. Hash functions (SHA, SHA2, MD5, Blake2b, etc.) +4. What side of the connection are you on: client, server, or both? +5. Client authentication? +6. Is the other side of the SSL connection defined? + a. What SSL implementation is it using? + b. Which SSL/TLS protocol version? + c. What is the key length? + d. Is it a client or server? +7. What are the maximum number of active SSL/TLS connections/sessions needed at one time? +8. What are the SSL handshake performance requirements? +9. What are the bulk data transfer performance requirements, after SSL handshake has completed? +10. Is hardware crypto available? If yes, then what ciphers are available in hardware? +11. Editors Note: For the purpose of keeping this document usable in scope, we are excluding +operating system and TCP/IP stack tuning opportunities and reserving that for another document. + +Having noted all of the above variables, you will see that there is much to consider, so our +approach is to present three optimization recipes for reference in this guide: + +1. Optimizing for minimum footprint size (heap, stack, static data, code) +2. Optimizing for maximum speed +3. Optimizing for maximum security + +Other optimization recipes are available. Just contact us at +[facts@wolfssl.com](mailto:facts@wolfssl.com). +Additional reference recipes that we can help with include: + +1. Optimizing for large numbers of connections +2. Optimizing for particular operating systems/chipsets +3. Optimizing for particular applications +4. Optimizing for a combination of higher goals, for example maximum security with minimum footprint +5. Optimization for lower power consumption +6. Optimizing for fun and relaxation diff --git a/wolfSSL-Tuning/src/section03.md b/wolfSSL-Tuning/src/section03.md new file mode 100644 index 00000000..18125787 --- /dev/null +++ b/wolfSSL-Tuning/src/section03.md @@ -0,0 +1,81 @@ +# Recipes + +## Recipe #1 Minimum Footprint + +Many users are on deeply embedded systems, where memory resources are tight. +For those users, this section describes methods to reduce the footprint size of wolfSSL. + +1. Limit supported protocol versions to only those required, for example only allowing TLS 1.2 +connections. +2. Remove unnecessary library features at compile time - section +[2.4.1](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html) of the +wolfSSL Manual. +3. Choose a limited set of cipher suites: + a. Memory usage difference between RSA, ECC, PSK. + b. Choose smaller key sizes - section + [4.3](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL + manual. +4. Take advantage of hardware crypto if available - section +[4.4](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL manual. +5. Use compiler and toolchain optimizations. +6. Decrease maximum SSL record size if you control both ends of the connection. + +## Recipe #2 Maximum Speed + +Adding SSL/TLS to a connection will always result in an inevitable reduction of performance. +Our goal is to make that PERFORMANCE decrease as small as possible. +This section describes ways to speed up wolfSSL, both during and after the handshake. + +There are two main areas of concern regarding performance: + +1. SSL/TLS handshake speed. +2. Data flow rate (bulk data transfer, after the SSL handshake). + +When optimizing SSL handshake performance, items to consider include: + +1. Use a faster math library (big integer vs. fastmath). +2. Take advantage of hardware crypto if available - section +[4.4](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL manual. +3. Key size - [Chapter 4](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of +the wolfSSL manual. +4. Key type (RSA vs ECC for example). +5. Trade off between handshake speed and security level (such as client/server cert verification +- section [4.8](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) +- of the wolfSSL manual). +6. Consider using PSK (pre-shared keys) - +section [4.7](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL +manual. + +**Maximum data flow rate** in a streaming media environment for example, such as a video game, +VoIP application, or cloud infrastructure, cipher suite choice is critical. In this recipe, +there are many options depending on the hardware environment and number of connections. To simplify +the recipe to make it usable, we will focus on a single connection environment running on a +typical cloud-based server. + +When optimizing for maximum data flow rate, items to consider include: + +1. Choose cipher suites to prioritize faster algorithms over slower ones: Stream Ciphers, Rabbit, +HC-128. +2. Take advantage of better compiler optimization. (I am not sure if this is a +user’s practical option). +3. Take advantage of hardware crypto if available. + +## Recipe #3 Maximum Security + +The security of a SSL/TLS connection should be of high concern, since having a secure +communication channel is the primary reason for adding SSL/TLS to a project. + +As with all cryptography-based protocols, SSL/TLS security recommendations can change as new +attacks and vulnerabilities are discovered and released. Optimizing for maximum security can +have negative effects on both memory usage and performance, depending on configuration. + +1. Cipher suite choices based on the best currently available information. +2. Key size choices based on the best currently available information. +3. Other considerations… + +As you can see from the basic recipes above, optimizing SSL is a complex multivariate problem +that depends heavily on a wide range of assumptions about your initial environment. We are here +to help. The wolfSSL team has successfully guided a vast number of our customers through these +choices. We can support you in an entire spectrum of ways, from the simple question and answer +process of typical commercial support, to short term professional design consulting, up to +managing the entire implementation of your SSL project. diff --git a/wolfSSL-Tuning/src/section04.md b/wolfSSL-Tuning/src/section04.md new file mode 100644 index 00000000..7bc42374 --- /dev/null +++ b/wolfSSL-Tuning/src/section04.md @@ -0,0 +1,11 @@ +# Additional Information + +wolfSSL Porting Guide: [https://www.wolfssl.com/wolfSSL/Docs-wolfssl-porting-guide.html](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-porting-guide.html) + +Download wolfSSL: [https://wolfssl.com/wolfSSL/download/downloadForm.php](https://wolfssl.com/wolfSSL/download/downloadForm.ph) + +wolfSSL Support Forums: [http://www.wolfssl.com/forums](http://www.wolfssl.com/forums) + +Product Support Email: [support@wolfssl.com](mailto:support@wolfssl.com) + +Contact us at [info@wolfSSL.com](mailto:info@wolfSSL.com) or call us at +1 425 245-8247 for additional information. We can make our kickstart and optimization consulting available to walk you through the details.