Skip to content

Commit e6f584c

Browse files
haydenroche5haydenroche5
authored
Merge pull request #52 from lealem47/wolfEngine
2 parents 8bbb695 + 3eca8bf commit e6f584c

17 files changed

+718
-1
lines changed

‎Makefile‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
DOCKER_CMD=DOCKER_BUILDKIT=1 docker build -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --target=manual --output=build -f Dockerfile .
22

3-
all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm
3+
all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfengine
44

55
build:
66
@mkdir -p build
@@ -59,5 +59,11 @@ wolftpm: PDFFILE=wolfTPM-Manual.pdf
5959
wolftpm: build
6060
@$(DOCKER_CMD)
6161

62+
.PHONY: wolfengine
63+
wolfengine: MANPATH=wolfEngine
64+
wolfengine: PDFFILE=wolfEngine-Manual.pdf
65+
wolfengine: build
66+
@$(DOCKER_CMD)
67+
6268
clean:
6369
rm -rf build

‎wolfEngine/Makefile‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
-include ../common/common.am
2+
.DEFAULT_GOAL := all
3+
all: pdf html
4+
5+
6+
SOURCES = chapter01.md \
7+
chapter02.md \
8+
chapter03.md \
9+
chapter04.md \
10+
chapter05.md \
11+
chapter06.md \
12+
chapter07.md \
13+
chapter08.md \
14+
chapter09.md \
15+
chapter10.md \
16+
chapter11.md
17+
18+
PDF = wolfEngine-Manual.pdf
19+
20+
.PHONY: html-prep
21+
html-prep:
22+
23+
.PHONY: pdf-prep
24+
pdf-prep:

‎wolfEngine/header.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
% wolfEngine Documentation ![](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 2022 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+
---

‎wolfEngine/mkdocs.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
site_name: wolfEngine Manual
2+
site_url: https://wolfssl.com/
3+
docs_dir: build/html/
4+
site_dir: html/
5+
copyright: Copyright © 2022 wolfSSL Inc.
6+
nav:
7+
- "1. Introduction": index.md
8+
- "2. OpenSSL Version Compatability": chapter02.md
9+
- "3. Building wolfEngine": chapter03.md
10+
- "4. FIPS 140-2 Support": chapter04.md
11+
- "5. Engine Control Commands": chapter05.md
12+
- "6. Logging": chapter06.md
13+
- "7. Portability": chapter07.md
14+
- "8. Loading wolfEngine": chapter08.md
15+
- "9. wolfEngine Design": chapter09.md
16+
- "10. Notes on Open Source Integration": chapter10.md
17+
- "11. Support and OpenSSL Version Adding": chapter11.md
18+
theme:
19+
name: null
20+
custom_dir: ../mkdocs-material/material
21+
language: en
22+
palette:
23+
primary: indigo
24+
accent: indigo
25+
font:
26+
text: roboto
27+
code: roboto mono
28+
icon: "logo.png"
29+
logo: logo.png
30+
favicon: logo.png
31+
feature:
32+
tabs: true
33+
extra_css: [skin.css]
34+
use_directory_urls: false

‎wolfEngine/src/chapter01.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Introduction
2+
3+
The wolfCrypt Engine (wolfEngine) is an OpenSSL engine for the wolfCrypt and wolfCrypt FIPS cryptography libraries. wolfEngine provides an OpenSSL engine implementation, as a shared or static library, to allow applications currently using OpenSSL to leverage wolfCrypt cryptography for FIPS and non-FIPS use cases.
4+
5+
wolfEngine is structured as a separate standalone library which links against wolfSSL (libwolfssl) and OpenSSL. wolfEngine implements and exposes an **OpenSSL engine implementation** which wraps the wolfCrypt native APIinternally. A high-level diagram of wolfEngine and how it relates to applications and OpenSSL is displayed below in Figure 1.
6+
7+
For more details on the design and architecture of wolfEngine see the [wolfEngine Design](chapter09.md) chapter.
8+
9+
10+
![wolfEngine Overview](png/wolfengine_overview.png)
11+
12+
wolfEngine is compiled by default as a shared library called **libwolfengine** which can be dynamically registered at runtime by an application or OpenSSL through a config file. wolfEngine also provides an entry point for applications to load the engine when compiled in a static build.

‎wolfEngine/src/chapter02.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# OpenSSL Version Compatability
2+
3+
wolfEngine has been tested against the following versions of OpenSSL. wolfEngine may work with other versions, but may require some modification or adjustment:
4+
5+
- OpenSSL 1.0.2h
6+
- OpenSSL 1.1.1b
7+
8+
If you are interested in having wolfSSL add support to wolfEngine for other OpenSSL versions, please contact wolfSSL at [[email protected]](mailto:[email protected]).

‎wolfEngine/src/chapter03.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Building wolfEngine
2+
3+
## Getting wolfEngine Source Code
4+
5+
The most recent version of wolfEngine can be obtained directly from wolfSSL Inc. Contact [[email protected]](mailto:[email protected]) for more information.
6+
7+
## wolfEngine Package Structure
8+
9+
The general wolfEngine package is structured as follows:
10+
11+
```
12+
certs/ (Test certificates and keys, used with unit tests)
13+
engine.conf (Example OpenSSL config file using wolfEngine)
14+
include/
15+
wolfengine/ (wolfEngine header files)
16+
openssl_patches/
17+
1.0.2h/tests/ (patches for OpenSSL 1.0.2h test apps)
18+
1.1.1b/tests/ (patches for OpenSSL 1.1.1b test apps)
19+
scripts/ (wolfEngine test scripts)
20+
src/ (wolfEngine source files)
21+
test/ (wolfEngine test files)
22+
user_settings.h (EXAMPLE user_settings.h)
23+
```
24+
## OpenSSL Version Caveats
25+
26+
Depending on the version of OpenSSL being used with wolfEngine, there are several algorithms support caveats, including:
27+
28+
- SHA-3 support is only available with OpenSSL versions 1.1.1+
29+
- EC_KEY_METHOD is only available with OpenSSL versions 1.1.1+
30+
31+
## Building on *nix
32+
33+
### Building OpenSSL
34+
35+
A pre-installed version of OpenSSL may be used with wolfEngine (barring algorithm caveats above), or OpenSSL can be recompiled for use with wolfEngine. General instructions for compiling OpenSSL on *nix-like platforms will be similar to the following. For complete and comprehensive OpenSSL build instructions, reference the OpenSSL INSTALL file and documentation.
36+
```
37+
git clone https://github.com/openssl/openssl.git
38+
cd openssl
39+
./config no-fips -shared
40+
make
41+
sudo make install
42+
```
43+
44+
### Building wolfSSL
45+
46+
If using a FIPS-validated version of wolfSSL with wolfEngine, follow the build instructions provided with your specific FIPS validated source bundle and Security Policy. In addition to the correct “--enable-fips” configure option, wolfEngine will need wolfSSL to be compiled with “ **WOLFSSL_PUBLIC_MP** ” defined. For example, building the “wolfCrypt Linux FIPSv2” bundle on Linux:
47+
```
48+
cd wolfssl-X.X.X-commercial-fips-linuxv
49+
./configure **--enable-fips=v2 CFLAGS=”-DWOLFSSL_PUBLIC_MP”**
50+
make
51+
./wolfcrypt/test/testwolfcrypt
52+
< modify fips_test.c using verifyCore hash output from testwolfcrypt
53+
>
54+
make
55+
./wolfcrypt/test/testwolfcrypt
56+
< all algorithms should PASS >
57+
sudo make install
58+
```
59+
60+
To build non-FIPS wolfSSL for use with wolfEngine:
61+
```
62+
cd wolfssl-X.X.X
63+
64+
./configure --enable-cmac --enable-keygen --enable-sha --enable-des
65+
--enable-aesctr --enable-aesccm --enable-x963kdf
66+
CPPFLAGS="-DHAVE_AES_ECB -DWOLFSSL_AES_DIRECT -DWC_RSA_NO_PADDING
67+
-DWOLFSSL_PUBLIC_MP -DECC_MIN_KEY_SZ=192 -DWOLFSSL_PSS_LONG_SALT
68+
-DWOLFSSL_PSS_SALT_LEN_DISCOVER"
69+
70+
make
71+
sudo make install
72+
```
73+
74+
If cloning wolfSSL from GitHub, you will need to run the `autogen.sh` script before running `./configure`. This will generate the configure script:
75+
```
76+
./autogen.sh
77+
```
78+
79+
### Building wolfEngine
80+
When building wolfEngine on Linux or other *nix-like systems, use the autoconf system. To configure and compile wolfEngine run the following two commands from the wolfEngine root directory:
81+
```
82+
./configure
83+
make
84+
```
85+
86+
If building wolfEngine from GitHub, run autogen.sh before running configure:
87+
```
88+
./autogen.sh
89+
```
90+
91+
Any number of build options can be appended to ./configure. For a list of available build options, please reference the “Build Options” section below or run the following command to see a list of available build options to pass to the ./configure script:
92+
```
93+
./configure --help
94+
```
95+
96+
wolfEngine will use the system default OpenSSL library installation unless changed with the “--with-openssl” configure option:
97+
```
98+
./configure --with-openssl=/usr/local/ssl
99+
```
100+
101+
The custom OpenSSL installation location may also need to be added to your library search path. On Linux, `LD_LIBRARY_PATH` is used:
102+
```
103+
export LD_LIBRARY_PATH=/usr/local/ssl:$LD_LIBRARY_PATH
104+
```
105+
106+
To build then install wolfEngine, run:
107+
```
108+
make
109+
make install
110+
```
111+
112+
You may need superuser privileges to install, in which case precede the command with sudo:
113+
```
114+
sudo make install
115+
```
116+
117+
To test the build, run the built-in tests from the root wolfEngine directory:
118+
```
119+
./test/unit.test
120+
```
121+
122+
Or use autoconf to run the tests:
123+
```
124+
make check
125+
```
126+
127+
If you get an error like `error while loading shared libraries: libssl.so.3` then the library cannot be found. Use the `LD_LIBRARY_PATH` environment variable as described in the section above.
128+
129+
## Building on WinCE
130+
131+
For full wolfEngine compatibility, ensure you have the following flags in your `user_settings.h` file for wolfCrypt:
132+
```
133+
#define WOLFSSL_CMAC
134+
#define WOLFSSL_KEY_GEN
135+
#undef NO_SHA
136+
#undef NO_DES
137+
#define WOLFSSL_AES_COUNTER
138+
#define HAVE_AESCCM
139+
#define HAVE_AES_ECB
140+
#define WOLFSSL_AES_DIRECT
141+
#define WC_RSA_NO_PADDING
142+
#define WOLFSSL_PUBLIC_MP
143+
#define ECC_MIN_KEY_SZ=192
144+
```
145+
146+
Add wolfEngine flags to your `user_settings.h` file depending on which algorithms and features you want to use. You can find a list of wolfEngine user settings flags in the `user_settings.h` file in wolfEngine’s directory.
147+
148+
Build wcecompat, wolfCrypt and OpenSSL for Windows CE, and keep track of their paths.
149+
150+
In the wolfEngine directory, open the sources file and change the OpenSSL, wolfCrypt, and `user_settings.h` paths to the directories you are using. You will need to update the paths in the INCLUDES and TARGETLIBS sections.
151+
152+
Load the wolfEngine project in Visual Studio. Include either `bench.c`, or `unit.h` and `unit.c` depending on if you want to run the benchmark or unit tests.
153+
154+
Build the project, and you will end up with a wolfEngine.exe executable. You can run this executable with ` --help` to see a full list of options. You may need to run it with the `--static` flag to use wolfEngine as a static engine.
155+
156+
## Build Options (./configure Options)
157+
158+
The following are options which may be appended to the `./configure` script to customize how the wolfEngine library is built.
159+
160+
By default, wolfEngine only builds a shared library, with building of a static library disabled. This speeds up build times by a factor of two. Either mode can be explicitly disabled or enabled if desired.
161+
162+
| Option | Default Value | Description |
163+
| :--------- | :---------------: | :-------------- |
164+
| --enable-static | **Disabled** | Build static libraries |
165+
| --enable-shared | Enabled | Build shared libraries |
166+
| --enable-debug | **Disabled** | Enable wolfEngine debugging support |
167+
| --enable-coverage | **Disabled** | Build to generate code coverage stats |
168+
| --enable-usersettings | **Disabled** | Use your own user_settings.h and do not add Makefile CFLAGS |
169+
| --enable-dynamic-engine | Enabled | Enable loading wolfEngine as a dynamic engine |
170+
| --enable-singlethreaded | **Disabled** | Enable wolfEngine single threaded |
171+
| --enable-digest | Enabled | Enable use of wc_Hash API for digesting data |
172+
| --enable-sha | Enabled | Enable SHA-1 |
173+
| --enable-sha224 | Enabled | Enable SHA2-224 |
174+
| --enable-sha256 | Enabled | Enable SHA2-256 |
175+
| --enable-sha384 | Enabled | Enable SHA2-384 |
176+
| --enable-sha512 | Enabled | Enable SHA2-512 |
177+
| --enable-sha3 | Enabled | Enable SHA3 |
178+
| --enable-sha3-224 | Enabled | Enable SHA3-224 |
179+
| --enable-sha3-256 | Enabled | Enable SHA3-256 |
180+
| --enable-sha3-384 | Enabled | Enable SHA3-384 |
181+
| --enable-sha3-512 | Enabled | Enable SHA3-512 |
182+
| --enable-cmac | Enabled | Enable CMAC |
183+
| --enable-hmac | Enabled | Enable HMAC |
184+
| --enable-des3cbc| Enabled | Enable 3DES-CBC |
185+
| --enable-aesecb | Enabled | Enable AES-ECB |
186+
| --enable-aescbc | Enabled | Enable AES-CBC |
187+
| --enable-aesctr | Enabled | Enable AES-CTR |
188+
| --enable-aesgcm | **Disabled** | Enable AES-GCM |
189+
| --enable-aesccm | **Disabled** | Enable AES-CCM |
190+
| --enable-rand | Enabled | Enable RAND |
191+
| --enable-rsa | Enabled | Enable RSA |
192+
| --enable-dh | Enabled | Enable DH |
193+
| --enable-evp-pkey | Enabled | Enable EVP_PKEY APIs |
194+
| --enable-ecc | Enabled | Enable ECC |
195+
| --enable-ec-key | Enabled | Enable ECC using EC_KEY |
196+
| --enable-ecdsa | Enabled | Enable ECDSA |
197+
| --enable-ecdh | Enabled | Enable ECDH |
198+
| --enable-eckg | Enabled | Enable EC Key Generation |
199+
| --enable-p192 | Enabled | Enable EC Curve P-192 |
200+
| --enable-p224 | Enabled | Enable EC Curve P-224 |
201+
| --enable-p256 | Enabled | Enable EC Curve P-256 |
202+
| --enable-p384 | Enabled | Enable EC Curve P-384 |
203+
| --enable-p521 | Enabled | Enable EC Curve P-521 |
204+
| --with-openssl=DIR | | OpenSSL installation location to link against. If not set, use the system default library and include paths. |
205+
206+
## Build Defines
207+
208+
wolfEngine exposes several preprocessor defines that allow users to configure how wolfEngine is built. These are described in the table below.
209+
210+
| Define | Description |
211+
| :---------------------------------------------- | :-------------- |
212+
| WOLFENGINE_DEBUG | Build wolfEngine with debug symbols, optimization level, and debug logging. |
213+
| WE_NO_DYNAMIC_ENGINE | Do not build wolfEngine with dynamic engine support. Dynamic engines are ones that can be loaded into OpenSSL at runtime. |
214+
| WE_SINGLE_THREADED | Build wolfEngine in single-threaded mode. This removes the need for locking around global resources used internally. |
215+
| WE_USE_HASH | Enable digest algorithms using the wc_Hash API. |
216+
| WE_HAVE_SHA1 | Enable SHA-1 digest algorithm. |
217+
| WE_HAVE_SHA224 | Enable SHA-2 digest algorithm with digest size 224. |
218+
| WE_HAVE_SHA256 | Enable SHA-2 digest algorithm with digest size 256. |
219+
| WE_HAVE_SHA384 | Enable SHA-2 digest algorithm with digest size 384. |
220+
| WE_HAVE_SHA512| Enable SHA-2 digest algorithm with digest size 512. |
221+
| WE_SHA1_DIRECT | Enable the SHA-1 digest algorithm using the wc_Sha API. Incompatible with WE_USE_HASH. |
222+
| WE_SHA224_DIRECT | Enable the SHA-2 224 digest algorithm using the wc_Sha224 API. Incompatible with WE_USE_HASH. |
223+
| WE_SHA256_DIRECT | Enable the SHA-2 256 digest algorithm using the wc_Sha256 API. Incompatible with WE_USE_HASH. |
224+
| WE_HAVE_SHA3_224 | Enable SHA-3 digest algorithm with digest size 224. Not available in OpenSSL 1.0.2. |
225+
| WE_HAVE_SHA3_256 | Enable SHA-3 digest algorithm with digest size 256. Not available in OpenSSL 1.0.2. |
226+
| WE_HAVE_SHA3_384 | Enable SHA-3 digest algorithm with digest size 384. Not available in OpenSSL 1.0.2. |
227+
| WE_HAVE_SHA3_512 | Enable SHA-3 digest algorithm with digest size 512. Not available in OpenSSL 1.0.2. |
228+
| WE_HAVE_EVP_PKEY | Enable functionality that uses the EVP_PKEY API. This includes things like RSA, DH, etc. |
229+
| WE_HAVE_CMAC | Enable CMAC algorithm. |
230+
| WE_HAVE_HMAC | Enable HMAC algorithm. |
231+
| WE_HAVE_DES3CBC | Enable DES3-CBC algorithm. |
232+
|WE_HAVE_AESECB | Enable AES algorithm with ECB mode. |
233+
| WE_HAVE_AESCBC | Enable AES algorithm with CBC mode. |
234+
| WE_HAVE_AESCTR | Enable AES algorithm with countee mode. |
235+
| WE_HAVE_AESGCM | Enable AES algorithm with GCM mode. |
236+
| WE_HAVE_AESCCM |Enable AES algorithm with CCM mode. |
237+
| WE_HAVE_RANDOM | Enable wolfCrypt random implementation. |
238+
| WE_HAVE_RSA | Enable RSA operations (e.g. sign, verify, key generation, etc.). |
239+
| WE_HAVE_DH | Enable Diffie-Hellman operations (e.g. key generation, shared secret computation, etc.). |
240+
| WE_HAVE_ECC | Enable support for elliptic curve cryptography. |
241+
| WE_HAVE_EC_KEY | Enable support for EC_KEY_METHOD. Not available in OpenSSL 1.0.2. |
242+
| WE_HAVE_ECDSA | Enable ECDSA algorithm. |
243+
| WE_HAVE_ECDH | Enable EC Diffie-Hellman operations. |
244+
| WE_HAVE_ECKEYGEN | Enable EC key generation. |
245+
| WE_HAVE_EC_P192 | Enable EC curve P192. |
246+
| WE_HAVE_EC_P224 | Enable EC curve P224. |
247+
| WE_HAVE_EC_P256 | Enable EC curve P256. |
248+
| WE_HAVE_EC_P384 | Enable EC curve P384. |
249+
| WE_HAVE_EC_P512 | Enable EC curve P512. |
250+
| WE_HAVE_DIGEST | Compile code in benchmark program and unit tests for use with digest algorithms. |
251+
| WOLFENGINE_USER_SETTINGS | Read user-specified defines from user_settings.h. |
252+

‎wolfEngine/src/chapter04.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# FIPS 140-2 Support
2+
3+
wolfEngine has been designed to work with FIPS 140-2 validated versions of wolfCrypt when compiled against a FIPS-validated version of wolfCrypt. This usage scenario requires a properly licensed and validated version of wolfCrypt, as obtained from wolfSSL Inc.
4+
5+
Note that wolfCrypt FIPS libraries cannot be “switched” into non-FIPS mode. wolfCrypt FIPS and regular wolfCrypt are two separate source code packages.
6+
7+
When wolfEngine is compiled to use wolfCrypt FIPS, it will only include support and register engine callbacks for FIPS-validated algorithms, modes, and key sizes. If OpenSSL based applications call non-FIPS validated algorithms, execution may not enter wolfEngine and could be handled by the default OpenSSL engine or other registered engine providers, based on the OpenSSL configuration.
8+
9+
**NOTE** : If targeting FIPS compliance,and non-wolfCrypt FIPS algorithms are called from a different engine, those algorithms are outside the scope of
10+
wolfEngine and wolfCrypt FIPS and may not be FIPS validated.
11+
12+
For more information on using wolfCrypt FIPS (140-2 / 140-3), contact wolfSSL at [email protected].

0 commit comments

Comments
 (0)