Features
wolfSSL (formerly CyaSSL) supports the C programming language as a primary interface, but also supports several other host languages, including Java, PHP, Perl, and Python (through a SWIG interface). If you have interest in hosting wolfSSL in another programming language that is not currently supported, please contact us.
This chapter covers some of the features of wolfSSL in more depth, including Stream Ciphers, AES-NI, IPv6 support, SSL Inspection (Sniffer) support, and more.
For an overview of wolfSSL features, please reference the wolfSSL product webpage:
https://wolfssl.com/wolfSSL/Products-wolfssl.html
wolfSSL supports SSL 3.0, TLS (1.0, 1.1, 1.2, 1.3 (client side)), and DTLS (1.0 and 1.2). You can easily select a protocol to use by using one of the following functions (as shown for either the client or server). wolfSSL does not support SSL 2.0, as it has been insecure for several years. The client and server functions below change slightly when using the OpenSSL compatibility layer. For the OpenSSL-compatible functions, please see Chapter 13.
wolfDTLSv1_server_method(void); /*DTLS 1.0*/
wolfDTLSv1_2_server_method(void); /*DTLS 1.2*/
wolfSSLv3_server_method(void); /*SSL 3.0*/
wolfTLSv1_server_method(void); /*TLS 1.0*/
wolfTLSv1_1_server_method(void); /*TLS 1.1*/
wolfTLSv1_2_server_method(void); /*TLS 1.2*/
wolfSSLv23_server_method(void); /*Use highest possible version
from SSLv3 - TLS 1.2*/wolfSSL supports robust server downgrade with the wolfSSLv23_server_method() function. See section 4.2.3 for a details.
wolfDTLSv1_client_method(void); /* DTLS 1.0*/
wolfDTLSv1_2_client_method(void); /* DTLS 1.2*/
wolfSSLv3_client_method(void); /* SSL 3.0*/
wolfTLSv1_client_method(void); /* TLS 1.0*/
wolfTLSv1_1_client_method(void); /* TLS 1.1*/
wolfTLSv1_2_client_method(void); /* TLS 1.2*/
wolfSSLv23_client_method(void); /* Use highest possible version
from SSLv3 - TLS 1.2*/wolfSSL supports robust client downgrade with the wolfSSLv23_client_method() function. See section 4.2.3 for a details.
For details on how to use these functions, please see Chapter 3, “Getting Started.” For a comparison between SSL 3.0, TLS 1.0, 1.1, 1.2, and DTLS, please see Appendix A.
Both wolfSSL clients and servers have robust version downgrade capability. If a specific protocol version method is used on either side, then only that version will be negotiated or an error will be returned. For example, a client that uses TLS 1.0 and tries to connect to an SSL 3.0 only server, the connection will fail, likewise connecting to a TLS 1.1 will fail as well.
To resolve this issue, a client that uses the wolfSSLv23_client_method() function will use the highest protocol version supported by the server and downgrade to TLS 1.0 if needed. In this case, the client will be able to connect to a server running TLS 1.0 - TLS 1.2. The only versions it can't connect to is SSL 2.0 which has been insecure for years, and SSL 3.0 which has been disabled by default.
Similarly, a server using the wolfSSLv23_server_method() function can handle clients supporting protocol versions from TLS 1.0 - TLS 1.2. A wolfSSL server can't accept a connection from SSLv2 because no security is provided.
If you are an adopter of IPv6 and want to use an embedded SSL implementation then you may have been wondering if wolfSSL supports IPv6. The answer is yes, we do support wolfSSL running on top of IPv6.
wolfSSL was designed as IP neutral, and will work with both IPv4 and IPv6, but the current test applications default to IPv4 (so as to apply to a broader range of systems). To change the test applications to IPv6, use the --enable-ipv6 option while building wolfSSL.
Further information on IPv6 can be found here: http://en.wikipedia.org/wiki/IPv6.
wolfSSL has support for DTLS (“Datagram” TLS) for both client and server. The current supported version is DTLS 1.0.
The TLS protocol was designed to provide a secure transport channel across a reliable medium (such as TCP). As application layer protocols began to be developed using UDP transport (such as SIP and various electronic gaming protocols), a need arose for a way to provide communications security for applications which are delay sensitive. This need lead to the creation of the DTLS protocol.
Many people believe the difference between TLS and DTLS is the same as TLS vs. UDP. This is incorrect. UDP has the benefit of having no handshake, no tear-down, and no delay in the middle if something gets lost (compared with TCP). DTLS on the other hand, has an extended SSL handshake and tear-down and must implement TCP-like behavior for the handshake. In essence, DTLS reverses the benefits that are offered by UDP in exchange for a secure connection.
DTLS can be enabled when building wolfSSL by using the --enable-dtls build option.
wolfSSL supports the lightweight internet protocol implementation out of the box. To use this protocol all you need to do is define WOLFSSL_LWIP or navigate to the settings.h file and uncomment the line:
/*#define WOLFSSL_LWIP*/The focus of lwIP is to reduce RAM usage while still providing a full TCP stack. That focus makes lwIP great for use in embedded systems, an area where wolfSSL is an ideal match for SSL/TLS needs.
To see what ciphers are currently being used you can call the method:
wolfSSL_get_ciphers()This function will return the currently enabled cipher suites.
Cipher suites come in a variety of strengths. Because they are made up of several different types of algorithms (authentication, encryption, and message authentication code (MAC)), the strength of each varies with the chosen key sizes.
There can be many methods of grading the strength of a cipher suite - the specific method used seems to vary between different projects and companies and can include things such as symmetric and public key algorithm key sizes, type of algorithm, performance, and known weaknesses.
NIST (National Institute of Standards and Technology) makes recommendations on choosing an acceptable cipher suite by providing comparable algorithm strengths for varying key sizes of each. The strength of a cryptographic algorithm depends on the algorithm and the key size used. The NIST Special Publication, SP800-57, states that two algorithms are considered to be of comparable strength as follows:
… two algorithms are considered to be of comparable strength for the given key sizes (X and Y) if the amount of work needed to “break the algorithms” or determine the keys (with the given key sizes) is approximately the same using a given resource. The security strength of an algorithm for a given key size is traditionally described in terms of the amount of work it takes to try all keys for a symmetric algorithm with a key size of “X” that has no shortcut attacks (i.e., the most efficient attack is to try all possible keys).
The following two tables are based off of both Table 2 (pg. 64) and Table 4 (pg. 66) from NIST SP800-57, and shows comparable security strength between algorithms as well as a strength measurement (based off of NIST’s suggested algorithm security lifetimes using bits of security).
Note: In the following table “L” is the size of the public key for finite field cryptography (FFC), “N” is the size of the private key for FFC, “k” is considered the key size for integer factorization cryptography (IFC), and “f” is considered the key size for elliptic curve cryptography.
| Bits of Security | Symmetric Key Algorithms | FFC Key Size (DSA, DH, etc.) | IFC Key Size (RSA, etc.) | ECC Key Size (ECDSA, etc.) |
|---|---|---|---|---|
| 80 | 2TDEA, etc. | L = 1024 N = 160 |
k = 1024 | f = 160 - 223 |
| 128 | AES-128, etc. | L = 3072 N = 256 |
k = 3072 | f = 256 - 383 |
| 192 | AES-192, etc. | L = 7680 N = 384 |
k = 7680 | f = 384 - 511 |
| 256 | AES-256, etc. | L = 15360 N = 512 |
k = 15360 | f = 512 + |
(Table 2: Relative Bit and Key Strengths)
| Bits of Security | Description |
|---|---|
| 80 | Security good through 2010 |
| 128 | Security good through 2030 |
| 192 | Long term protection |
| 256 | Secure for the foreseeable future |
(Table 3: Bit Strength Descriptions)
Using this table as a guide, to begin to classify a cipher suite, we categorize it based on the strength of the symmetric encryption algorithm. In doing this, a rough grade classification can be devised to classify each cipher suite based on bits of security (only taking into account symmetric key size):
-
LOW = bits of security smaller than 128 bits
-
MEDIUM = bits of security equal to 128 bits
-
HIGH = bits of security larger than 128 bits
Outside of the symmetric encryption algorithm strength, the strength of a cipher suite will depend greatly on the key sizes of the key exchange and authentication algorithm keys. The strength is only as good as the cipher suite’s weakest link.
Following the above grading methodology (and only basing it on symmetric encryption algorithm strength), wolfSSL 2.0.0 currently supports a total of 0 LOW strength cipher suites, 12 MEDIUM strength cipher suites, and 8 HIGH strength cipher suites – as listed below. The following strength classification could change depending on the chosen key sizes of the other algorithms involved. For a reference on hash function security strength, see Table 3 (pg. 64) of NIST SP800-57.
In some cases, you will see ciphers referenced as “EXPORT” ciphers. These ciphers originated from the time period in US history (as late as 1992) when it was illegal to export software with strong encryption from the United States. Strong encryption was classified as “Munitions” by the US Government (under the same category as Nuclear Weapons, Tanks, and Ballistic Missiles). Because of this restriction, software being exported included “weakened” ciphers (mostly in smaller key sizes). In the current day, this restriction has been lifted, and as such, EXPORT ciphers are no longer a mandated necessity.
The following cipher suites are supported by wolfSSL. A cipher suite is a combination of authentication, encryption, and message authentication code (MAC) algorithms which are used during the TLS or SSL handshake to negotiate security settings for a connection.
Each cipher suite defines a key exchange algorithm, a bulk encryption algorithm, and a message authentication code algorithm (MAC). The key exchange algorithm (RSA, DSS, DH, EDH) determines how the client and server will authenticate during the handshake process. The bulk encryption algorithm (DES, 3DES, AES, ARC4, RABBIT, HC-128), including block ciphers and stream ciphers, is used to encrypt the message stream. The message authentication code (MAC) algorithm (MD2, MD5, SHA-1, SHA-256, SHA-512, RIPEMD) is a hash function used to create the message digest.
The table below matches up to the cipher suites (and categories) found in <wolfssl_root>/wolfssl/internal.h (starting at about line 706). If you are looking for a cipher suite which is not in the following list, please contact us to discuss getting it added to wolfSSL.
| wolfSSL Cipher Suites (version 3.10.0) | |
|---|---|
| TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA TLS_DH_anon_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_NULL_SHA TLS_PSK_WITH_AES_256_CBC_SHA TLS_PSK_WITH_AES_128_CBC_SHA256 TLS_PSK_WITH_AES_256_CBC_SHA384 TLS_PSK_WITH_AES_128_CBC_SHA TLS_PSK_WITH_NULL_SHA256 TLS_PSK_WITH_NULL_SHA384 TLS_PSK_WITH_NULL_SHA SSL_RSA_WITH_RC4_128_SHA SSL_RSA_WITH_RC4_128_MD5 SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_RSA_WITH_IDEA_CBC_SHA |
|
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_RC4_128_SHA TLS_ECDHE_ECDSA_WITH_RC4_128_SHA TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_PSK_WITH_NULL_SHA256 TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_NULL_SHA |
ECC cipher suites |
| TLS_ECDH_RSA_WITH_AES_256_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDH_RSA_WITH_RC4_128_SHA TLS_ECDH_ECDSA_WITH_RC4_128_SHA TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 |
Static ECDH cipher suites |
| TLS_RSA_WITH_HC_128_MD5 TLS_RSA_WITH_HC_128_SHA TLS_RSA_WITH_RABBIT_SHA |
wolfSSL extension - eSTREAM cipher suites |
| TLS_RSA_WITH_AES_128_CBC_B2B256 TLS_RSA_WITH_AES_256_CBC_B2B256 TLS_RSA_WITH_HC_128_B2B256 |
Blake2b cipher suites |
| TLS_QSH | wolfSSL extension - Quantum-Safe Handshake |
| TLS_NTRU_RSA_WITH_RC4_128_SHA TLS_NTRU_RSA_WITH_3DES_EDE_CBC_SHA TLS_NTRU_RSA_WITH_AES_128_CBC_SHA TLS_NTRU_RSA_WITH_AES_256_CBC_SHA |
wolfSSL extension - NTRU cipher suites |
| TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_NULL_SHA256 TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 TLS_DHE_PSK_WITH_NULL_SHA256 |
SHA-256 cipher suites |
| TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 TLS_DHE_PSK_WITH_NULL_SHA384 |
SHA-384 cipher suites |
| TLS_RSA_WITH_AES_128_GCM_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 TLS_PSK_WITH_AES_128_GCM_SHA256 TLS_PSK_WITH_AES_256_GCM_SHA384 TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 |
AES-GCM cipher suites |
| TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 |
ECC AES-GCM cipher suites |
| TLS_RSA_WITH_AES_128_CCM_8 TLS_RSA_WITH_AES_256_CCM_8 TLS_ECDHE_ECDSA_WITH_AES_128_CCM TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8 TLS_PSK_WITH_AES_128_CCM TLS_PSK_WITH_AES_256_CCM TLS_PSK_WITH_AES_128_CCM_8 TLS_PSK_WITH_AES_256_CCM_8 TLS_DHE_PSK_WITH_AES_128_CCM TLS_DHE_PSK_WITH_AES_256_CCM |
AES-CCM cipher suites |
| TLS_RSA_WITH_CAMELLIA_128_CBC_SHA TLS_RSA_WITH_CAMELLIA_256_CBC_SHA TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 |
Camellia cipher suites |
| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 TLS_ECDHE_RSA_WITH_CHACHA20_OLD_POLY1305_SHA256 TLS_ECDHE_ECDSA_WITH_CHACHA20_OLD_POLY1305_SHA256 TLS_DHE_RSA_WITH_CHACHA20_OLD_POLY1305_SHA256 |
ChaCha cipher suites |
| TLS_EMPTY_RENEGOTIATION_INFO_SCSV | Renegotiation Indication Extension Special Suite |
wolfSSL supports AEAD suites, including AES-GCM, AES-CCM, and CHACHA-POLY1305. The big difference between these AEAD suites and others is that they authenticate the encrypted data. This helps with mitigating man in the middle attacks that result in having data tampered with. AEAD suites use a combination of a block cipher (or more recently also a stream cipher) algorithm combined with a tag produced by a keyed hash algorithm. Combining these two algorithms is handled by the wolfSSL encrypt and decrypt process which makes it easier for users. All that is needed for using a specific AEAD suite is simply enabling the algorithms that are used in a supported suite.
wolfSSL supports the AES, DES, 3DES, and Camellia block ciphers and the RC4, RABBIT, HC-128 and CHACHA20 stream ciphers. AES, DES, 3DES, RC4 and RABBIT are enabled by default. Camellia, HC-128, and ChaCha20 can be enabled when building wolfSSL (with the --enable-hc128, --enable-camellia, and --enable-chacha build options, respectively). The default mode of AES is CBC mode. To enable GCM or CCM mode with AES, use the --enable-aesgcm and --enable-aesccm build options. Please see the examples for usage and the wolfCrypt Usage Reference (Chapter 10) for specific usage information.
SSL uses RC4 as the default stream cipher. It's a good one, though it's getting a little old. wolfSSL has added two ciphers from the eStream project into the code base, RABBIT and HC-128. RABBIT is nearly twice as fast as RC4 and HC-128 is about 5 times as fast! So if you've ever decided not to use SSL because of speed concerns, using wolfSSL's stream ciphers should lessen or eliminate that performance doubt. Recently wolfSSL also added ChaCha20. While RC4 performs about .11 times faster than ChaCha, RC4 is generally considered less secure than ChaCha. ChaCha can put up very nice times of it’s own with added security as a tradeoff.
To see a comparison of cipher performance, visit the wolfSSL Benchmark web page, located here: http://wolfssl.com/yaSSL/benchmarks-wolfssl.html.
A block cipher has to be encrypted in chunks that are the block size for the cipher. For example, AES has block size of 16 bytes. So if you're encrypting a bunch of small, 2 or 3 byte chunks back and forth, over 80% of the data is useless padding, decreasing the speed of the encryption/decryption process and needlessly wasting network bandwidth to boot. Basically block ciphers are designed for large chunks of data, have block sizes requiring padding, and use a fixed, unvarying transformation.
Stream ciphers work well for large or small chunks of data. They are suitable for smaller data sizes because no block size is required. If speed is a concern, stream ciphers are your answer, because they use a simpler transformation that typically involves an xor'd keystream. So if you need to stream media, encrypt various data sizes including small ones, or have a need for a fast cipher then stream ciphers are your best bet.
wolfSSL supports several different hashing functions, including MD2, MD4, MD5, SHA-1, SHA-2 (SHA-224, SHA-256, SHA-384, SHA-512), SHA-3 (BLAKE2), and RIPEMD-160. Detailed usage of these functions can be found in the wolfCrypt Usage Reference, Section 10.1.
wolfSSL supports the RSA, ECC, DSA/DSS, DH, and NTRU public key options, with support for EDH (Ephemeral Diffie-Hellman) on the wolfSSL server. Detailed usage of these functions can be found in the wolfCrypt Usage Reference, section 10.5.
wolfSSL has support for four cipher suites utilizing NTRU public key:
-
TLS_NTRU_RSA_WITH_3DES_EDE_CBC_SHA
-
TLS_NTRU_RSA_WITH_RC4_128_SHA
-
TLS_NTRU_RSA_WITH_AES_128_CBC_SHA
-
TLS_NTRU_RSA_WITH_AES_256_CBC_SHA
The strongest one, AES-256, is the default. If wolfSSL is enabled with NTRU and the NTRU library is available, these cipher suites are built into the wolfSSL library. A wolfSSL client will have these cipher suites available without any interaction needed by the user. On the other hand, a wolfSSL server application will need to load an NTRU private key and NTRU x509 certificate in order for those cipher suites to be available for use.
The example servers, echoserver and server, both use the define HAVE_NTRU (which is turned on by enabling NTRU) to specify whether or not to load NTRU keys and certificates. The wolfSSL package comes with test keys and certificates in the /certs directory. ntru-cert.pem is the certificate and ntru-key.raw is the private key blob.
The wolfSSL NTRU cipher suites are given the highest preference order when the protocol picks a suite. Their exact preference order is the reverse of the above listed suites, i.e., AES-256 will be picked first and 3DES last before moving onto the “standard” cipher suites. Basically, if a user builds NTRU into wolfSSL and both sides of the connection support NTRU then an NTRU cipher suite will be picked unless a user on one side has explicitly excluded them by stating to only use different cipher suites. Using NTRU over RSA can provide a 20 - 200X speed improvement. The improvement increases as the size of keys increases, meaning a much larger speed benefit when using large keys (8192-bit) versus smaller keys (1024-bit).
wolfSSL has support for Elliptic Curve Cryptography (ECC) including but not limited to: ECDH-ECDSA, ECDHE-ECDSA, ECDH-RSA, ECDHE-PSK and ECDHE-RSA.
wolfSSL’s ECC implementation can be found in the <wolfssl_root>/wolfssl/wolfcrypt/ecc.h header file and the <wolfssl_root>/wolfcrypt/src/ecc.c source file.
Supported cipher suites are shown in the table above. ECC is disabled by default on non x86_64 builds, but can be turned on when building wolfSSL with the HAVE_ECC define or by using the autoconf system:
$ ./configure --enable-ecc
$ make
$ make checkWhen “make check” runs, note the numerous cipher suites that wolfSSL checks (if make check doesn’t produce a list of cipher suites run ./testsuite/testsuite.test on its own). Any of these cipher suites can be tested individually, e.g., to try ECDH-ECDSA with AES256-SHA, the example wolfSSL server can be started like this:
$ ./examples/server/server -d -l ECDHE-ECDSA-AES256-SHA -c ./certs/server-ecc.pem -k ./certs/ecc-key.pem(-d) disables client cert check while (-l) specifies the cipher suite list. (-c) is the certificate to use and (-k) is the corresponding private key to use. To have the client connect try:
$ ./examples/client/client -A ./certs/server-ecc.pemwhere (-A) is the CA certificate to use to verify the server.
PKCS (Public Key Cryptography Standards) refers to a group of standards created and published by RSA Security, Inc. wolfSSL has support for PKCS #5, PKCS #8, and PBKD from PKCS #12.
PKCS #5 is a password based key derivation method which combines a password, a salt, and an iteration count to generate a password-based key. wolfSSL supports both PBKDF1 and PBKDF2 key derivation functions. A key derivation function produces a derived key from a base key and other parameters (such as the salt and iteration count as explained above). PBKDF1 applies a hash function (MD5, SHA1, etc) to derive keys, where the derived key length is bounded by the length of the hash function output. With PBKDF2, a pseudorandom function is applied (such as HMAC-SHA-1) to derive the keys. In the case of PBKDF2, the derived key length is unbounded.
wolfSSL also supports the PBKDF function from PKCS #12 in addition to PBKDF1 and PBKDF2. The function prototypes look like this:
int PBKDF2(byte* output, const byte* passwd, int pLen,
const byte* salt,int sLen, int iterations,
int kLen, int hashType);
int PKCS12_PBKDF(byte* output, const byte* passwd, int pLen,
const byte* salt, int sLen, int iterations,
int kLen, int hashType, int purpose);output contains the derived key, passwd holds the user password of length pLen, salt holds the salt input of length sLen, iterations is the number of iterations to perform, kLen is the desired derived key length, and hashType is the hash to use (which can be MD5, SHA1, or SHA2).
If you are using ./configure to build wolfssl, the way to enable this functionality is to use the option --enable-pwdbased
A full example can be found in /wolfcrypt/test.c. More information can be found on PKCS #5, PBKDF1, and PBKDF2 from the following specifications:
PKCS#5, PBKDF1, PBKDF2: http://tools.ietf.org/html/rfc2898
PKCS #8 is designed as the Private-Key Information Syntax Standard, which is used to store private key information - including a private key for some public-key algorithm and set of attributes.
The PKCS #8 standard has two versions which describe the syntax to store both encrypted private keys and non-encrypted keys. wolfSSL supports both unencrypted and encrypted PKCS #8. Supported formats include PKCS #5 version 1 - version 2, and PKCS#12. Types of encryption available include DES, 3DES, RC4, and AES.
PKCS#8: http://tools.ietf.org/html/rfc5208
By default, wolfSSL will pick the “best” (highest security) cipher suite that both sides of the connection can support. To force a specific cipher, such as 128 bit AES, add something similar to:
wolfSSL_CTX_set_cipher_list(ctx, “AES128-SHA”);after the call to wolfSSL_CTX_new(); so that you have:
ctx = wolfSSL_CTX_new(method);
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
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.
The wolfSSL quantum safe handshake ciphersuite is given the highest preference order when the protocol picks a suite. Basically, if a user builds NTRU into wolfSSL and both sides of the connection support NTRU then an NTRU cipher suite will be picked unless a user on one side has explicitly excluded them by stating to only use different cipher suites.
Users can adjust what crypto algorithms and if the client sends across public keys by using the function examples
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.
wolfSSL_isQSH(ssl);
