Skip to content

Commit a2e32f8

Browse files
author
Jack Tjaden
committed
Added the wolfSSL-tuning guide
1 parent a1e3f27 commit a2e32f8

File tree

8 files changed

+254
-0
lines changed

8 files changed

+254
-0
lines changed

‎Makefile

+5
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,11 @@ fips-ready: PDFFILE=wolfSSL-FIPS-Ready.pdf
7777
fips-ready: build
7878
@$(DOCKER_CMD)
7979

80+
.PHONY: tuning
81+
tuning: MANPATH=wolfSSL-Tuning
82+
tuning: PDFFILE=wolfSSL-Tuning-Guide.pdf
83+
tuning: build
84+
@$(DOCKER_CMD)
8085

8186
clean:
8287
rm -rf build

‎wolfSSL-Tuning/Makefile

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
-include ../common/common.am
2+
.DEFAULT_GOAL := all
3+
all: pdf html
4+
5+
6+
SOURCES = section01.md \
7+
section02.md \
8+
section03.md \
9+
section04.md
10+
11+
PDF = wolfSSL-Tuning-Guide.pdf
12+
DOXYFILE = Doxyfile
13+
14+
15+
.PHONY: html-prep
16+
html-prep:
17+
18+
.PHONY: pdf-prep
19+
pdf-prep:

‎wolfSSL-Tuning/header.txt

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
% wolfSSL Tuning Guide ![](logo.png)
2+
3+
---
4+
header-includes:
5+
# Blank pages on new sections
6+
- \usepackage{titlesec}
7+
- \newcommand{\sectionbreak}{\clearpage}
8+
# Fancy page headers
9+
- \usepackage{fancyhdr}
10+
- \pagestyle{fancy}
11+
- \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.}
12+
# Wrap long syntax highlighting code blocks
13+
- \usepackage{fvextra}
14+
- \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}
15+
# Wrap long non-sytax highlighted code blocks
16+
- \usepackage{listings}
17+
- \let\verbatim\undefined
18+
- \let\verbatimend\undefined
19+
- \lstnewenvironment{verbatim}{\lstset{breaklines,basicstyle=\ttfamily}}{}
20+
subparagraph: yes
21+
---

‎wolfSSL-Tuning/mkdocs.yml

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
site_name: wolfSSL Tuning Guide
2+
site_url: https://wolfssl.com/
3+
docs_dir: build/html/
4+
site_dir: html/
5+
copyright: Copyright © 2024 wolfSSL Inc.
6+
nav:
7+
- "1. Introduction": index.md
8+
- "2. Considerations": section02.md
9+
- "3. Recipes": section03.md
10+
- "4. Additional Information": section04.md
11+
theme:
12+
name: null
13+
custom_dir: ../mkdocs-material/material
14+
language: en
15+
palette:
16+
primary: indigo
17+
accent: indigo
18+
font:
19+
text: roboto
20+
code: roboto mono
21+
icon: "logo.png"
22+
logo: logo.png
23+
favicon: logo.png
24+
feature:
25+
tabs: true
26+
extra_css: [skin.css]
27+
use_directory_urls: false

‎wolfSSL-Tuning/src/section01.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Introduction
2+
3+
This guide provides a reference for developers and engineers to tune and optimize the performance
4+
and memory usage of the wolfSSL embedded SSL library. It should be considered a “guide” and
5+
as such, it is an evolving work. If there is something you find missing, please let us know
6+
and we’ll be happy to add instructions or clarification to the document. One of our main goals
7+
for wolfSSL is ease of use.
8+
9+
## Audience
10+
11+
This guide caters to developers or engineers interested in optimizing the performance and
12+
memory usage of the wolfSSL embedded SSL library.
13+
14+
## Overview
15+
16+
The wolfSSL Tuning Guide is designed to help developers and engineers optimize the performance
17+
and memory usage of the wolfSSL embedded SSL library. This evolving document aims to provide
18+
comprehensive instructions and clarifications to ensure ease of use and adaptability for
19+
various environments. The guide targets developers interested in refining the efficiency
20+
of SSL/TLS operations by balancing memory footprint, performance, and security according
21+
to specific requirements.

‎wolfSSL-Tuning/src/section02.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Considerations
2+
3+
## Anticipated Requirements
4+
5+
The first step in tuning wolfSSL to your environment is to document your anticipated requirements.
6+
At the highest level, design goals for SSL/TLS usually boil down to:
7+
8+
- **Memory Footprint (ROM)**
9+
- **Per-session Memory Usage (RAM)**
10+
- **SSL Handshake Performance**
11+
- **Data Flow Performance (bulk data transfer)**
12+
- **Desired Security Level (see Figure 1, below)**
13+
14+
## Desired Security Levels
15+
16+
| Security Level | Level Name | Description |
17+
|----------------|---------------------|---------------------------------------------------------|
18+
| 1 | Relaxed | You just need to keep out the casual onlookers |
19+
| 2 | Moderate | You have potential attackers out there, but they are not highly motivated |
20+
| 3 | Corporate | Secure against professional attacks |
21+
| 4 | Military Grade | Title speaks for itself |
22+
| 5 | Quantum Survivable | Can survive against quantum computing based attacks |
23+
24+
**Figure 1: Desired Security Levels**
25+
26+
Each of these top-level goals will have trade-offs against the others as you evolve your design.
27+
28+
To get started, the key variables you need to define include:
29+
30+
1. Available hardware:
31+
a. Memory available to SSL/TLS (ROM / RAM)
32+
b. CPU type and clock speed
33+
2. Required SSL/TLS protocol levels (i.e: TLS 1.0, TLS 1.1, TLS 1.2, etc.)
34+
3. Required cipher suites. If the cipher suites are not defined in your requirement, you are
35+
free to choose cipher suites that match your performance goals:
36+
a. Public key algorithm with key length (RSA, ECC, NTRU, PSK, etc.)
37+
b. Block / Stream ciphers (AES, DES, 3DES, RC4, HC-128, etc.)
38+
c. Hash functions (SHA, SHA2, MD5, Blake2b, etc.)
39+
4. What side of the connection are you on: client, server, or both?
40+
5. Client authentication?
41+
6. Is the other side of the SSL connection defined?
42+
a. What SSL implementation is it using?
43+
b. Which SSL/TLS protocol version?
44+
c. What is the key length?
45+
d. Is it a client or server?
46+
7. What are the maximum number of active SSL/TLS connections/sessions needed at one time?
47+
8. What are the SSL handshake performance requirements?
48+
9. What are the bulk data transfer performance requirements, after SSL handshake has completed?
49+
10. Is hardware crypto available? If yes, then what ciphers are available in hardware?
50+
11. Editors Note: For the purpose of keeping this document usable in scope, we are excluding
51+
operating system and TCP/IP stack tuning opportunities and reserving that for another document.
52+
53+
Having noted all of the above variables, you will see that there is much to consider, so our
54+
approach is to present three optimization recipes for reference in this guide:
55+
56+
1. Optimizing for minimum footprint size (heap, stack, static data, code)
57+
2. Optimizing for maximum speed
58+
3. Optimizing for maximum security
59+
60+
Other optimization recipes are available. Just contact us at
61+
[[email protected]](mailto:[email protected]).
62+
Additional reference recipes that we can help with include:
63+
64+
1. Optimizing for large numbers of connections
65+
2. Optimizing for particular operating systems/chipsets
66+
3. Optimizing for particular applications
67+
4. Optimizing for a combination of higher goals, for example maximum security with minimum footprint
68+
5. Optimization for lower power consumption
69+
6. Optimizing for fun and relaxation

‎wolfSSL-Tuning/src/section03.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Recipes
2+
3+
## Recipe #1 Minimum Footprint
4+
5+
Many users are on deeply embedded systems, where memory resources are tight.
6+
For those users, this section describes methods to reduce the footprint size of wolfSSL.
7+
8+
1. Limit supported protocol versions to only those required, for example only allowing TLS 1.2
9+
connections.
10+
2. Remove unnecessary library features at compile time - section
11+
[2.4.1](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html) of the
12+
wolfSSL Manual.
13+
3. Choose a limited set of cipher suites:
14+
a. Memory usage difference between RSA, ECC, PSK.
15+
b. Choose smaller key sizes - section
16+
[4.3](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL
17+
manual.
18+
4. Take advantage of hardware crypto if available - section
19+
[4.4](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL manual.
20+
5. Use compiler and toolchain optimizations.
21+
6. Decrease maximum SSL record size if you control both ends of the connection.
22+
23+
## Recipe #2 Maximum Speed
24+
25+
Adding SSL/TLS to a connection will always result in an inevitable reduction of performance.
26+
Our goal is to make that PERFORMANCE decrease as small as possible.
27+
This section describes ways to speed up wolfSSL, both during and after the handshake.
28+
29+
There are two main areas of concern regarding performance:
30+
31+
1. SSL/TLS handshake speed.
32+
2. Data flow rate (bulk data transfer, after the SSL handshake).
33+
34+
When optimizing SSL handshake performance, items to consider include:
35+
36+
1. Use a faster math library (big integer vs. fastmath).
37+
2. Take advantage of hardware crypto if available - section
38+
[4.4](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL manual.
39+
3. Key size - [Chapter 4](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of
40+
the wolfSSL manual.
41+
4. Key type (RSA vs ECC for example).
42+
5. Trade off between handshake speed and security level (such as client/server cert verification
43+
- section [4.8](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html)
44+
- of the wolfSSL manual).
45+
6. Consider using PSK (pre-shared keys) -
46+
section [4.7](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-4-features.html) of the wolfSSL
47+
manual.
48+
49+
**Maximum data flow rate** in a streaming media environment for example, such as a video game,
50+
VoIP application, or cloud infrastructure, cipher suite choice is critical. In this recipe,
51+
there are many options depending on the hardware environment and number of connections. To simplify
52+
the recipe to make it usable, we will focus on a single connection environment running on a
53+
typical cloud-based server.
54+
55+
When optimizing for maximum data flow rate, items to consider include:
56+
57+
1. Choose cipher suites to prioritize faster algorithms over slower ones: Stream Ciphers, Rabbit,
58+
HC-128.
59+
2. Take advantage of better compiler optimization. (I am not sure if this is a
60+
user’s practical option).
61+
3. Take advantage of hardware crypto if available.
62+
63+
## Recipe #3 Maximum Security
64+
65+
The security of a SSL/TLS connection should be of high concern, since having a secure
66+
communication channel is the primary reason for adding SSL/TLS to a project.
67+
68+
As with all cryptography-based protocols, SSL/TLS security recommendations can change as new
69+
attacks and vulnerabilities are discovered and released. Optimizing for maximum security can
70+
have negative effects on both memory usage and performance, depending on configuration.
71+
72+
1. Cipher suite choices based on the best currently available information.
73+
2. Key size choices based on the best currently available information.
74+
3. Other considerations…
75+
76+
As you can see from the basic recipes above, optimizing SSL is a complex multivariate problem
77+
that depends heavily on a wide range of assumptions about your initial environment. We are here
78+
to help. The wolfSSL team has successfully guided a vast number of our customers through these
79+
choices. We can support you in an entire spectrum of ways, from the simple question and answer
80+
process of typical commercial support, to short term professional design consulting, up to
81+
managing the entire implementation of your SSL project.

‎wolfSSL-Tuning/src/section04.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Additional Information
2+
3+
wolfSSL Porting Guide: [https://www.wolfssl.com/wolfSSL/Docs-wolfssl-porting-guide.html](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-porting-guide.html)
4+
5+
Download wolfSSL: [https://wolfssl.com/wolfSSL/download/downloadForm.php](https://wolfssl.com/wolfSSL/download/downloadForm.ph)
6+
7+
wolfSSL Support Forums: [http://www.wolfssl.com/forums](http://www.wolfssl.com/forums)
8+
9+
Product Support Email: [[email protected]](mailto:[email protected])
10+
11+
Contact us at [[email protected]](mailto:[email protected]) 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.

0 commit comments

Comments
 (0)