Skip to content

Commit f4b5a8a

Browse files
cconloncconlon
authored
Merge pull request #163 from haydenroche5/readme
Improve README.md.
2 parents dcc8071 + 7debc7d commit f4b5a8a

File tree

1 file changed

+85
-40
lines changed

1 file changed

+85
-40
lines changed

‎README.md‎

Lines changed: 85 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1-
2-
## Description
1+
# wolfEngine
32

4-
wolfEngine is a library that can be used as an Engine in OpenSSL.
3+
wolfEngine is an [OpenSSL engine](https://www.openssl.org/docs/man1.0.2/man3/engine.html)
4+
backed by wolfSSL's wolfCrypt cryptography library. wolfCrypt is
5+
[FIPS-validated](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/Certificate/3389),
6+
so wolfEngine can be used to achieve FIPS compliance with OpenSSL, all without
7+
having to touch the OpenSSL code itself.
58

69
## Features
710

@@ -34,20 +37,31 @@ wolfEngine is a library that can be used as an Engine in OpenSSL.
3437
* Curve P-256
3538
* Curve P-384
3639
* Curve P-521
37-
38-
### OpenSSL Version Caveats
39-
40+
* HMAC
41+
* CMAC
42+
* HKDF
43+
* PBKDF2
44+
* TLS PRF
45+
46+
### OpenSSL Version Support
47+
wolfEngine can be used with any OpenSSL version that supports the engine
48+
framework. Engines are deprecated in OpenSSL 3.0.0. They're replaced with a
49+
similar concept called [providers](https://www.openssl.org/docs/manmaster/man7/provider.html).
50+
wolfSSL also offers a provider backed by wolfCrypt. Please reach out to
51+
[email protected] if you're interested in evaluating the wolfSSL provider.
52+
53+
#### Caveats
4054
* SHA-3 support is only available with OpenSSL versions 1.1.1+.
4155
* EC_KEY_METHOD is only available with OpenSSL versions 1.1.1+.
4256

43-
## Building on *nix Systems
57+
## Building on \*nix
4458

4559
### OpenSSL
4660

61+
Assuming you've downloaded OpenSSL source code into a directory called openssl:
4762
```
48-
git clone https://github.com/openssl/openssl.git
4963
cd openssl
50-
./config no-fips
64+
./config shared
5165
make
5266
sudo make install
5367
```
@@ -58,50 +72,71 @@ sudo make install
5872
git clone https://github.com/wolfssl/wolfssl.git
5973
cd wolfssl
6074
./autogen.sh
61-
./configure --enable-opensslcoexist --enable-cmac --enable-keygen --enable-sha --enable-des3 --enable-aesctr --enable-aesccm --enable-x963kdf CPPFLAGS="-DHAVE_AES_ECB -DWOLFSSL_AES_DIRECT -DWC_RSA_NO_PADDING -DWOLFSSL_PUBLIC_MP -DECC_MIN_KEY_SZ=192 -DWOLFSSL_PSS_LONG_SALT -DWOLFSSL_PSS_SALT_LEN_DISCOVER"
75+
./configure --enable-opensslcoexist --enable-cmac --enable-keygen --enable-sha
76+
--enable-des3 --enable-aesctr --enable-aesccm --enable-x963kdf
77+
CPPFLAGS="-DHAVE_AES_ECB -DWOLFSSL_AES_DIRECT -DWC_RSA_NO_PADDING
78+
-DWOLFSSL_PUBLIC_MP -DECC_MIN_KEY_SZ=192 -DWOLFSSL_PSS_LONG_SALT
79+
-DWOLFSSL_PSS_SALT_LEN_DISCOVER"
6280
make
6381
sudo make install
6482
```
6583

66-
Add `--enable-pwdbased` to the configure command above if PKCS#12 is used in OpenSSL.
84+
Add `--enable-pwdbased` to the configure command above if using PKCS#12.
6785

68-
Remove `-DWOLFSSL_PSS_LONG_SALT -DWOLFSSL_PSS_SALT_LEN_DISCOVER` and add `--enable-fips=v2` to the configure command above if building from a FIPS v2 bundle and not the git repository. Change `--enable-fips=v2` to `--enable-fips=ready` if using a FIPS Ready bundle.
86+
Remove `-DWOLFSSL_PSS_LONG_SALT -DWOLFSSL_PSS_SALT_LEN_DISCOVER` and add
87+
`--enable-fips=v2` to the configure command above if building from a FIPS v2
88+
bundle and not the git repository. Change `--enable-fips=v2` to
89+
`--enable-fips=ready` if using a FIPS Ready bundle.
6990

7091
### wolfEngine
7192

7293
```
94+
git clone https://github.com/wolfSSL/wolfEngine.git
95+
cd wolfEngine
7396
./autogen.sh
74-
./configure
97+
./configure --with-openssl=/path/to/openssl/installation --with-wolfssl=/path/to
98+
/wolfssl/installation
7599
make
100+
make check
76101
```
77102

78-
To build using a different OpenSSL installation directory (e.g. one at /usr/local/ssl) use:
103+
`make check` may fail if the OpenSSL or wolfSSL libraries aren't found. In this
104+
case, try `export LD_LIBRARY_PATH=/path/to/openssl/installation/lib:/path/to/
105+
wolfssl/installation/lib:$LD_LIBRARY_PATH` and re-run `make check`.
79106

80-
```
81-
./configure --with-openssl=/usr/local/ssl
82-
make
83-
export LD_LIBRARY_PATH=/usr/local/ssl/lib
84-
make check
85-
```
107+
#### Customizing
86108

87-
* To build wolfEngine in single-threaded mode, add `--enable-singlethreaded` to the configure command.
88-
* To build wolfEngine with PBES support (used with PKCS #12), add `--enable-pbe`. Note: wolfSSL must have been configured with `--enable-pwdbased`.
89-
* To disable support for loading wolfEngine dynamically, add `--disable-dynamic-engine`.
109+
* To build wolfEngine in single-threaded mode, add `--enable-singlethreaded` to
110+
the configure command.
111+
* To build wolfEngine with PBES support (used with PKCS #12), add
112+
`--enable-pbe`. Note: wolfSSL must have been configured with
113+
`--enable-pwdbased`.
114+
* To disable support for loading wolfEngine dynamically, add
115+
`--disable-dynamic-engine`.
90116
* To build a static version of wolfEngine, add `--enable-static`.
91-
* To use a custom user_settings.h file to override the defines produced by `./configure`, add `--enable-usersettings` and place a user_settings.h file with the defines you want in the include directory. See the root of the project for an example user_settings.h.
92-
* To build wolfEngine with debug support, add `--enable-debug`. Then, to activate the debug logging at runtime, your application should send this control command to wolfEngine (denoted "e" here): `ENGINE_ctrl_cmd(e, "enable_debug", 1, NULL, NULL, 0)`.
93-
94-
## Testing on *nix Systems
117+
* To use a custom user_settings.h file to override the defines produced by
118+
`./configure`, add `--enable-usersettings` and place a user_settings.h file with
119+
the defines you want in the include directory. See the root of the project for
120+
an example user_settings.h.
121+
* To build wolfEngine with debug support, add `--enable-debug`. Then, to
122+
activate the debug logging at runtime, your application should send this control
123+
command to wolfEngine (denoted "e" here): `ENGINE_ctrl_cmd(e, "enable_debug", 1,
124+
NULL, NULL, 0)`.
125+
* To build wolfEngine for use with OpenSSH, add `--enable-openssh`.
126+
127+
## Testing on \*nix
95128

96129
### Unit Tests
97-
To run automated unit tests:
98130

99-
* `make test`
131+
Run the unit tests with `make check`.
100132

101-
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.
133+
If you get an error like `error while loading shared libraries: libssl.so.3`
134+
then the library cannot be found. Use the `LD_LIBRARY_PATH` environment variable
135+
as described earlier.
102136

103137
### Integration Tests
104-
There are no automated integration tests, yet.
138+
See the scripts directory for integration tests with other applications (e.g.
139+
OpenSSH, stunnel, etc.).
105140

106141
## Building on Windows
107142

@@ -115,25 +150,27 @@ expects the following directory structure:
115150
└── wolfssl
116151
```
117152

118-
### Building OpenSSL
153+
### OpenSSL
119154

120-
Follow the instructions in the OpenSSL `INSTALL` file. The list of commands to run are:
155+
Follow the instructions in the OpenSSL `INSTALL` file. The list of commands to
156+
run are:
121157
```
122158
$ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
123-
$ nmake clean # This command needs to be run if OpenSSL has previously been built in this directory with a different configuration.
159+
$ nmake clean # This command needs to be run if OpenSSL has previously been
160+
built in this directory with a different configuration.
124161
$ nmake
125162
```
126163

127-
### Building wolfSSL
164+
### wolfSSL
128165

129166
Compile wolfSSL using one of the solution projects available in the
130167
project (`wolfssl.sln` or `wolfssl64.sln`). The following is a list of defines
131168
that are generated when using the configure script. You do not need to turn all
132169
of them on but this list will provide full functionality. For ease of use, it is
133170
recommended to add the desired defines to the `user_settings.h` file used in
134-
the chosen wolfSSL Visual Studio solution. Please make sure to update the defines
135-
in the wolfEngine `user_settings.h` file to match the defines used to compile
136-
wolfSSL.
171+
the chosen wolfSSL Visual Studio solution. Please make sure to update the
172+
defines in the wolfEngine `user_settings.h` file to match the defines used to
173+
compile wolfSSL.
137174

138175
```
139176
/* Settings generated by the configure script when compiling for wolfEngine */
@@ -195,7 +232,7 @@ wolfSSL.
195232
#define NO_OLD_MD5_NAME
196233
```
197234

198-
### Building wolfEngine
235+
### wolfEngine
199236

200237
It is enough to compile the wolfEngine solution to generate the DLL file.
201238
Please make sure that you have updated the `user_settings.h` header to match
@@ -206,5 +243,13 @@ files into the output directory. If you want to skip this step and use system
206243
supplied versions of OpenSSL, delete the command under:
207244

208245
```
209-
test Properties -> Configuration Properties -> Build Events -> Post-Build Event -> Command Line
246+
test Properties -> Configuration Properties -> Build Events -> Post-Build Event
247+
-> Command Line
210248
```
249+
250+
## Need Help?
251+
252+
Please reach out to [email protected] for technical support. If you're
253+
interested in commercial licensing, FIPS operating environment additions,
254+
consulting services, or other business engagements, please reach out to
255+
[email protected].

0 commit comments

Comments
 (0)