wolfSSL/wolfssl
1
0
Fork 1
mirror of https://github.com/wolfSSL/wolfssl.git synced 2025-09-25 14:41:05 +02:00
Code Issues Packages Projects Releases Wiki Activity

Additions

Alex Abrahamson
2017-11-09 14:40:38 -07:00
parent 84c8e60c3b
commit 838fc496ef
1 changed files with 265 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
Features.md

@@ -294,7 +294,7 @@ wolfSSL_CTX_set_cipher_list(ctx, “AES128-SHA”);
wolfSSL has support for the cipher suite utilizing post quantum handshake cipher suite such as with NTRU:
> **TLS_QSH**
**TLS_QSH**
If wolfSSL is enabled with NTRU and the NTRU package is available, the TLS_QSH cipher suite is built into the wolfSSL library. A wolfSSL client and server will have this cipher suite available without any interaction needed by the user.
@@ -302,12 +302,274 @@ The wolfSSL quantum safe handshake ciphersuite is given the highest preference o
Users can adjust what crypto algorithms and if the client sends across public keys by using the function examples
wolfSSL_UseClientQSHKeys(ssl, 1);
```c
wolfSSL_UseClientQSHKeys(ssl, 1);
wolfSSL_UseSupportedQSH(ssl, WOLFSSL_NTRU_EESS439);
```
To test if a QSH connection was established after a client has connected the following function example can be used.
```c
wolfSSL_isQSH(ssl);
```
# 4.4 Hardware Accelerated Crypto
wolfSSL is able to take advantage of several hardware accelerated (or “assisted”) crypto functionalities in various processors and chips. The following sections explain which technologies wolfSSL supports out-of-the-box.
### 4.4.1 Intel AES-NI
AES is a key encryption standard used by governments worldwide, which wolfSSL has always supported. Intel has released a new set of instructions that is a faster way to implement AES. wolfSSL is the first SSL library to fully support the new instruction set for production environments.
Essentially, Intel has added AES instructions at the chip level that perform the computationally-intensive parts of the AES algorithm, boosting performance. For a list of Intel’s chips that currently have support for AES-NI, you can look here:
http://ark.intel.com/search/advanced/?s=t&AESTech=true
We have added the functionality to wolfSSL to allow it to call the instructions directly from the chip, instead of running the algorithm in software. This means that when you’re running wolfSSL on a chipset that supports AES-NI, you can run your AES crypto 5-10 times faster!
If you are running on an AES-NI supported chipset, enable AES-NI with the **--enable-aesni** build option. To build wolfSSL with AES-NI, GCC 4.4.3 or later is required to make use of the assembly code.
References and further reading on AES-NI, ordered from general to specific, are listed below. For information about performance gains with AES-NI, please see the third link to the Intel Software Network page.
|AES (Wikipedia)|http://en.wikipedia.org/wiki/Advanced_Encryption_Standard|
|AES-NI (Wikipedia)|http://en.wikipedia.org/wiki/AES_instruction_set|
|AES-NI (Intel Software Network page)|http://software.intel.com/en-us/articles/intel-advanced-encryption-standard-instructions-aes-ni/|
### 4.4.2 STM32F2
wolfSSL is able to use the STM32F2 hardware-based cryptography and random number generator through the STM32F2 Standard Peripheral Library.
For necessary defines, see the **WOLFSSL_STM32F2** define in settings.h. The WOLFSSL_STM32F2 define enables STM32F2 hardware crypto and RNG support by default. The defines for enabling these individually are **STM32F2_CRYPTO** (for hardware crypto support) and **STM32F2_RNG** (for hardware RNG support).
Documentation for the STM32F2 Standard Peripheral Library can be found in the following document:
http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/USER_MANUAL/DM00023896.pdf
### 4.4.3 Cavium NITROX
wolfSSL has support for Cavium NITROX (http://www.cavium.com/processor_security.html). To enable Cavium NITROX support when building wolfSSL use the following configure option:
```sh
$ ./configure --with-cavium=/home/user/cavium/software
```
Where the “**--with-cavium=**” option is pointing to your licensed cavium/software directory. Since Cavium doesn't build a library wolfSSL pulls in the cavium_common.o file which gives a libtool warning about the portability of this. Also, if you're using the github source tree you'll need to remove the -Wredundant-decls warning from the generated Makefile because the cavium headers don't conform to this warning.
Currently wolfSSL supports Cavium RNG, AES, 3DES, RC4, HMAC, and RSA directly at the crypto layer. Support at the SSL level is partial and currently just does AES, 3DES, and RC4. RSA and HMAC are slower until the Cavium calls can be utilized in non-blocking mode. The example client turns on cavium support as does the crypto test and benchmark. Please see the **HAVE_CAVIUM** define.
# 4.5 SSL Inspection (Sniffer)
Beginning with the wolfSSL 1.5.0 release, wolfSSL has included a build option allowing it to be built with SSL Sniffer (SSL Inspection) functionality. This means that you can collect SSL traffic packets and with the correct key file, are able to decrypt them as well. The ability to “inspect” SSL traffic can be useful for several reasons, some of which include:
* Analyzing Network Problems
* Detecting network misuse by internal and external users
* Monitoring network usage and data in motion
* Debugging client/server communications
To enable sniffer support, build wolfSSL with the **--enable-sniffer** option on *nix or use the **vcproj** files on Windows. You will need to have **pcap** installed on *nix or **WinPcap** on Windows. The main sniffer functions which can be found in sniffer.h are listed below with a short description of each:
**ssl_SetPrivateKey** - Sets the private key for a specific server and port. <br>
**ssl_SetNamedPrivateKey** - Sets the private key for a specific server, port and domain name. <br>
**ssl_DecodePacket** - Passes in a TCP/IP packet for decoding. <br>
**ssl_Trace** - Enables / Disables debug tracing to the traceFile. <br>
**ssl_InitSniffer** - Initialize the overall sniffer. <br>
**ssl_FreeSniffer** - Free the overall sniffer. <br>
**ssl_EnableRecovery** - Enables option to attempt to pick up decoding of SSL traffic in the case of lost packets. <br>
**ssl_GetSessionStats** - Obtains memory usage for the sniffer sessions. <br>
To look at wolfSSL's sniffer support and see a complete example, please see the "**snifftest**" app in the "sslSniffer/sslSnifferTest" folder from the wolfSSL download.
Keep in mind that because the encryption keys are setup in the SSL Handshake, the handshake needs to be decoded by the sniffer in order for future application data to be decoded. For example, if you are using "snifftest" with the wolfSSL example echoserver and echoclient, the snifftest application must be started before the handshake begins between the server and client.
The sniffer can only decode streams encrypted with the following algorithms: AES-CBC, DES3-CBC, ARC4, HC-128, RABBIT, Camellia-CBC, and IDEA. If ECDHE or DHE key agreement is used the stream cannot be sniffed; only RSA key-exchange is supported.
# 4.6 Compression
wolfSSL supports data compression with the **zlib** library. The ./configure build system detects the presence of this library, but if you're building in some other way define the constant **HAVE_LIBZ** and include the path to zlib.h for your includes.
Compression is off by default for a given cipher. To turn it on, use the function wolfSSL_set_compression() before SSL connecting or accepting. Both the client and server must have compression turned on in order for compression to be used.
Keep in mind that while compressing data before sending decreases the actual size of the messages being sent and received, the amount of data saved by compression usually takes longer in time to analyze than it does to send it raw on all but the slowest of networks.
# 4.7 Pre-Shared Keys
wolfSSL has support for these ciphers with static pre-shared keys:
**TLS_PSK_WITH_AES_256_CBC_SHA** <br>
**TLS_PSK_WITH_AES_128_CBC_SHA256** <br>
**TLS_PSK_WITH_AES_256_CBC_SHA384** <br>
**TLS_PSK_WITH_AES_128_CBC_SHA** <br>
**TLS_PSK_WITH_NULL_SHA256** <br>
**TLS_PSK_WITH_NULL_SHA384** <br>
**TLS_PSK_WITH_NULL_SHA** <br>
**TLS_PSK_WITH_AES_128_GCM_SHA256** <br>
**TLS_PSK_WITH_AES_256_GCM_SHA384** <br>
**TLS_PSK_WITH_AES_128_CCM** <br>
**TLS_PSK_WITH_AES_256_CCM** <br>
**TLS_PSK_WITH_AES_128_CCM_8** <br>
**TLS_PSK_WITH_AES_256_CCM_8** <br>
**TLS_PSK_WITH_CHACHA20_POLY1305** <br>
These suites are built into wolfSSL with **WOLFSSL_STATIC_PSK** on, all PSK suites can be turned off at build time with the constant **NO_PSK**. To only use these ciphers at runtime use the function **wolfSSL_CTX_set_cipher_list()** with the desired ciphersuite.
wolfSSL has support for ephemeral key PSK suites:
**ECDHE-PSK-AES128-CBC-SHA256** <br>
**ECDHE-PSK-NULL-SHA256** <br>
**ECDHE-PSK-CHACHA20-POLY1305** <br>
**DHE-PSK-CHACHA20-POLY1305** <br>
**DHE-PSK-AES256-GCM-SHA384** <br>
**DHE-PSK-AES128-GCM-SHA256** <br>
**DHE-PSK-AES256-CBC-SHA384** <br>
**DHE-PSK-AES128-CBC-SHA256** <br>
**DHE-PSK-AES128-CBC-SHA256** <br>
On the client, use the function **wolfSSL_CTX_set_psk_client_callback**() to setup the callback. The client example in <wolfSSL_Home>/examples/client/client.c gives example usage for setting up the client identity and key, though the actual callback is implemented in wolfssl/test.h.
On the server side two additional calls are required:
**_wolfSSL_CTX_set_psk_server_callback()_** <br>
**_wolfSSL_CTX_use_psk_identity_hint()_**
The server stores its identity hint to help the client with the 2nd call, in our server example that's "wolfssl server". An example server psk callback can also be found in my_psk_server_cb() in wolfssl/test.h.
wolfSSL supports identities and hints up to 128 octets and pre-shared keys up to 64 octets.
# 4.8 Client Authentication
Client authentication is a feature which enables the server to authenticate clients by requesting that the clients send a certificate to the server for authentication when they connect. Client authentication requires an X.509 client certificate from a CA (or self-signed if generated by you or someone other than a CA).
By default, wolfSSL validates all certificates that it receives - this includes both client and server. To set up client authentication, the server must load the list of trusted CA certificates to be used to verify the client certificate against:
```c
wolfSSL_CTX_load_verify_locations(ctx, caCert, 0);
```
To turn on client verification and control its behavior, the wolfSSL_CTX_set_verify() function is used. In the following example, **SSL_VERIFY_PEER** turns on a certificate request from the server to the client. **SSL_VERIFY_FAIL_IF_NO_PEER_CERT** instructs the server to fail if the client does not present a certificate to validate on the server side. Other options to wolfSSL_CTX_set_verify() include SSL_VERIFY_NONE and SSL_VERIFY_CLIENT_ONCE.
```c
wolfSSL_CTX_set_verify(ctx,SSL_VERIFY_PEER | ((usePskPlus)?
SSL_VERIFY_FAIL_EXCEPT_PSK :
SSL_VERIFY_FAIL_IF_NO_PEER_CERT),0);
```
An example of client authentication can be found in the example server (server.c) included in the wolfSSL download (/examples/server/server.c).
# 4.9 Server Name Indication
SNI is useful when a server hosts multiple ‘virtual’ servers at a single underlying network address. It may be desirable for clients to provide the name of the server which it is contacting. To enable SNI with wolfSSL you can simply do:
```sh
$ ./configure --enable-sni
```
Using SNI on the client side requires an additional function call, which should be one of the following functions:
```c
wolfSSL_CTX_UseSNI()
wolfSSL_UseSNI()
```
wolfSSL_CTX_UseSNI() is most recommended when the client contacts the same server multiple times. Setting the SNI extension at the context level will enable the SNI usage in all SSL objects created from that same context from the moment of the call forward.
wolfSSL_UseSNI() will enable SNI usage for one SSL object only, so it is recommended to use this function when the server name changes between sessions.
On the server side one of the same function calls is required. Since the wolfSSL server doesn't host multiple 'virtual' servers, the SNI usage is useful when the termination of the connection is desired in the case of SNI mismatch. In this scenario, wolfSSL_CTX_UseSNI() will be more efficient, as the server will set it only once per context creating all subsequent SSL objects with SNI from that same context.
# 4.10 Handshake Modifications
### 4.10.1 Grouping Handshake Messages
wolfSSL has the ability to group handshake messages if the user desires. This can be done at the context level with:
```c
wolfSSL_CTX_set_group_messages(ctx);
```
or at the SSL object level with:
```c
wolfSSL_set_group_messages(ssl);
```
# 4.11 Truncated HMAC
Currently defined TLS cipher suites use the HMAC to authenticate record-layer communications. In TLS, the entire output of the hash function is used as the MAC tag. However, it may be desirable in constrained environments to save bandwidth by truncating the output of the hash function to 80 bits when forming MAC tags. To enable the usage of Truncated HMAC at wolfSSL you can simply do:
```sh
$ ./configure --enable-truncatedhmac
```
Using Truncated HMAC on the client side requires an additional function call, which should be one of the following functions:
```c
wolfSSL_CTX_UseTruncatedHMAC();
wolfSSL_UseTruncatedHMAC();
```
**wolfSSL_CTX_UseTruncatedHMAC()** is most recommended when the client would like to enable Truncated HMAC for all sessions. Setting the Truncated HMAC extension at context level will enable it in all SSL objects created from that same context from the moment of the call forward.
**wolfSSL_UseTruncatedHMAC()** will enable it for one SSL object only, so it's recommended to use this function when there is no need for Truncated HMAC on all sessions.
On the server side no call is required. The server will automatically attend to the client's request for Truncated HMAC.
All TLS extensions can also be enabled with:
```sh
$ ./configure --enable-tlsx
```
# 4.12 User Crypto Module
User Crypto Module allows for a user to plug in custom crypto that they want used during supported operations (Currently RSA operations are supported). An example of a module is located in the directory root_wolfssl/wolfcrypt/user-crypto/ using IPP libraries. Examples of the configure option when building wolfSSL to use a crypto module is as follows :
```sh
$ ./configure --with-user-crypto
```
or
```sh
$ ./configure --with-user-crypto=/dir/to
```
When creating a user crypto module that performs RSA operations, it is mandatory that there is a header file for RSA called user_rsa.h. For all user crypto operations it is mandatory that the users library be called libusercrypto. These are the names that wolfSSL autoconf tools will be looking for when linking and using a user crypto module. In the example provided with wolfSSL, the header file user_rsa.h can be found in the directory wolfcrypt/user-crypto/include/ and the library once created is located in the directory wolfcrypt/user-crypto/lib/ . For a list of required API look at the header file provided.
To build the example, after having installed IPP libraries, the following commands from the root wolfSSL directory should be ran.
```sh
$ cd wolfcrypt/user-crypto/
$ ./autogen.sh
$ ./configure
$ make
$ sudo make install
```
The included example in wolfSSL requires the use of IPP, which will need to be installed before the project can be built. Though even if not having IPP libraries to build the example it is intended to provide users with an example of file name choice and API interface. Once having made and installed both the library libusercrypto and header files, making wolfSSL use the crypto module does not require any extra steps. Simply using the configure flag --with-user-crypto will map all function calls from the typical wolfSSL crypto to the user crypto module.
Memory allocations, if using wolfSSL’s XMALLOC, should be tagged with DYNAMIC_TYPE_USER_CRYPTO. Allowing for analyzing memory allocations used by the module.
User crypto modules **cannot** be used in conjunction with the wolfSSL configure options fast-rsa and/or fips. Fips requires that specific, certified code be used and fast-rsa makes use of the example user crypto module to perform RSA operations.
# 4.13 Timing-Resistance in wolfSSL
wolfSSL provides the function “ConstantCompare” which guarantees constant time when doing comparison operations that could potentially leak timing information. This API is used at both the TLS and crypto level in wolfSSL to deter against timing based, side-channel attacks.
The wolfSSL ECC implementation has the define ECC_TIMING_RESISTANT to enable timing-resistance in the ECC algorithm. Similarly the define TFM_TIMING_RESISTANT is provided in the fast math libraries for RSA algorithm timing-resistance. The function exptmod uses the timing resistant Montgomery ladder.
[See also: --enable-harden](https://github.com/wolfSSL/wolfssl/wiki/Building-wolfSSL#25-build-options-configure-options)