diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index 1d268323..6214e61a 100644 --- a/wolfSSL/src/chapter02.md +++ b/wolfSSL/src/chapter02.md @@ -2443,6 +2443,8 @@ Enabling this option will turn on User Atomic Record Layer Processing callbacks. Enable Public Key Callbacks +Eabling this option will turn on Public Key callbacks, allowing the application to register its own ECC sign/verify and RSA sign/verify and encrypt/decrypt callbacks. + ### `--enable-sniffer` Enable wolfSSL sniffer support. @@ -2465,14 +2467,12 @@ Stream ciphers: Enable AES-GCM support. -Eabling this option will turn on Public Key callbacks, allowing the application to register its own ECC sign/verify and RSA sign/verify and encrypt/decrypt callbacks. +Enabling AES-GCM will add these cipher suites to wolfSSL. wolfSSL offers four different implementations of AES-GCM balancing speed versus memory consumption. If available, wolfSSL will use 64-bit or 32-bit math. For embedded applications, there is a speedy 8-bit version that uses RAM-based lookup tables (8KB per session) which is speed comparable to the 64-bit version and a slower 8-bit version that doesn't take up any additional RAM. The --enable-aesgcm configure option may be modified with the options `=word32`, `=table`, or `=small`, i.e. `--enable-aesgcm=table`. ### `--enable-aesccm` Enable AES-CCM support -Enabling AES-GCM will add these cipher suites to wolfSSL. wolfSSL offers four different implementations of AES-GCM balancing speed versus memory consumption. If available, wolfSSL will use 64-bit or 32-bit math. For embedded applications, there is a speedy 8-bit version that uses RAM-based lookup tables (8KB per session) which is speed comparable to the 64-bit version and a slower 8-bit version that doesn't take up any additional RAM. The --enable-aesgcm configure option may be modified with the options `=word32`, `=table`, or `=small`, i.e. `--enable-aesgcm=table`. - ### `--disable-aescbc` Used to with [`--disable-aescbc`](#--disable-aescbc) to compile out AES-CBC diff --git a/wolfSSL/src/chapter03.md b/wolfSSL/src/chapter03.md index f95ddd36..7bba302c 100644 --- a/wolfSSL/src/chapter03.md +++ b/wolfSSL/src/chapter03.md @@ -496,7 +496,7 @@ This section will explain the basic steps needed to add wolfSSL to a client appl ```c /*after connecting to socket fd*/ - WOLF SSL* ssl; + WOLFSSL* ssl; if ((ssl = wolfSSL_new(ctx)) == NULL) { fprintf(stderr, "wolfSSL_new error.\n"); exit(EXIT_FAILURE); @@ -558,7 +558,7 @@ calling: This section will explain the basic steps needed to add wolfSSL to a server application using the wolfSSL native API. For a client explanation, please see [Changing a Client Application to Use wolfSSL](#changing-a-client-application-to-use-wolfssl). A more complete walk-through, with example code, is located in the [SSL Tutorial](chapter11.md#ssl-tutorial) chapter. -1. Follow the instructions above for a client, except change the client method call in step 5 to a server one, so: +1. Follow the instructions above for a client, except change the client method call in step 2 to a server one, so: ```c wolfSSL_CTX_new(wolfTLSv1_client_method()); diff --git a/wolfSSL/src/chapter04.md b/wolfSSL/src/chapter04.md index 1ddf7e72..743e6c33 100644 --- a/wolfSSL/src/chapter04.md +++ b/wolfSSL/src/chapter04.md @@ -62,7 +62,7 @@ Further information on IPv6 can be found here: wolfSSL has support for DTLS (“Datagram” TLS) for both client and server. The current supported versions are DTLS 1.0, 1.2, and 1.3. -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. +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 led to the creation of the DTLS protocol. Many people believe the difference between TLS and DTLS is the same as TCP 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. @@ -147,7 +147,7 @@ The following cipher suites are supported by wolfSSL. A cipher suite is a combin 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), 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/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. +The table below matches up to the cipher suites (and categories) found in `/wolfssl/internal.h` (starting at about line 1097). 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. ECC cipher suites: @@ -290,7 +290,7 @@ wolfSSL supports AEAD suites, including AES-GCM, AES-CCM, and CHACHA-POLY1305. T wolfSSL supports the **AES**, **DES**, **3DES**, and **Camellia** block ciphers and the **RC4**, and **CHACHA20 **stream ciphers. AES, DES, 3DES, RC4, and ChaCha20 are enabled by default. Camellia can be enabled when building wolfSSL with the [`--enable-camellia`](chapter02.md#--enable-camellia) build option. The default mode of AES is CBC mode. To enable GCM or CCM mode with AES, use the [`--enable-aesgcm`](chapter02.md#--enable-aesgcm) and [`--enable-aesccm`](chapter02.md#--enable-aesccm) build options. Please see the examples for usage and the [wolfCrypt Usage Reference](chapter10.md#wolfcrypt-usage-reference) for specific usage information. -While SSL uses RC4 as the default stream cipher, it has been obsoleted due to compromise. Recently wolfSSL added ChaCha20. While RC4 is about 11% more performant 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. +While SSL uses RC4 as the default stream cipher, it has been obsoleted due to compromise. Recently wolfSSL added ChaCha20. While RC4 is about 11% more performant than ChaCha, RC4 is generally considered less secure than ChaCha. ChaCha can put up very nice times of its own with added security as a tradeoff. To see a comparison of cipher performance, visit the wolfSSL Benchmark web page, located here: . @@ -350,7 +350,7 @@ wolfSSL also supports the PBKDF function from PKCS #12 in addition to PBKDF1 and ```c int PBKDF2(byte* output, const byte* passwd, int pLen, - const byte* salt,int sLen, int iterations, + const byte* salt, int sLen, int iterations, int kLen, int hashType); int PKCS12_PBKDF(byte* output, const byte* passwd, int pLen, @@ -376,7 +376,7 @@ PKCS#8: [https://tools.ietf.org/html/rfc5208](https://tools.ietf.org/html/rfc52 #### PKCS #7 -PKCS #7 is designed to transfer bundles of data whether is an enveloped certificate or unencrypted but signed string of data. The functionality is turned on by using the enable option ([`--enable-pkcs7`](chapter02.md#--enable-pkcs7)) or by using the macro `HAVE_PKCS7`. Note that degenerate cases are allowed by default as per the RFC having an empty set of signers. To toggle allowing degenerate cases on and off the function `wc_PKCS7_AllowDegenerate()` can be called. +PKCS #7 is designed to transfer bundles of data whether as an enveloped certificate or unencrypted but signed string of data. The functionality is turned on by using the enable option ([`--enable-pkcs7`](chapter02.md#--enable-pkcs7)) or by using the macro `HAVE_PKCS7`. Note that degenerate cases are allowed by default as per the RFC having an empty set of signers. To toggle allowing degenerate cases on and off the function `wc_PKCS7_AllowDegenerate()` can be called. Supported features include: @@ -424,7 +424,7 @@ wolfSSL_CTX_set_cipher_list(ctx, "AES128-SHA"); ### OpenQuantumSafe's liboqs Integration -Please see the appendix "Experimenting with Quantum-Safe Cryptography" in this document for more details. +Please see the appendix "Experimenting with Post-Quantum Cryptography" in this document for more details. ## Hardware Accelerated Crypto @@ -481,9 +481,9 @@ For necessary defines, see the `WOLFSSL_ESPWROOM32` define in `settings.h`. The Unlike the ESP32, there's no hardware-based cryptography available for the ESP8266. See the `WOLFSSL_ESP8266` define in `user_settings.h` or use `./configure CFLAGS="-DWOLFSSL_ESP8266"` to compile for the embedded ESP8266 target. -### ERF32 +### EFR32 -wolfSSL is able to use the ERF32 family of devices for hardware-based cryptography. +wolfSSL is able to use the EFR32 family of devices for hardware-based cryptography. To enable support define `WOLFSSL_SILABS_SE_ACCEL` in user_settings.h. wolfSSL currently supports the hardware acceleration of RNG, AES-CBC, AES-GCM, AES-CCM, SHA-1, SHA-2, ECDHE, and ECDSA on the EFR32 platform. @@ -495,7 +495,7 @@ wolfSSL supports using the Trust Protection Unit (TPU), Modular Arithmetic Accel To enable support define `WOLFSSL_MAX3266X` and `WOLFSSL_SP_MATH_ALL`. wolfSSL currently supports the hardware acceleration of RNG, AES-CBC, AES-GCM, AES-ECB, SHA-1, SHA-2, RSA 2048, and ECDSA. -This HW also supports the use of wolfSSL's crypto callback feature to allow the usage of both HW and SW implentations. +This HW also supports the use of wolfSSL's crypto callback feature to allow the usage of both HW and SW implementations. More details of the support can be found in the README.md at wolfcrypt/src/port/maxim of the wolfSSL repository tree. @@ -531,7 +531,7 @@ Watch callbacks with wolfSSL sniffer can be turned on with `WOLFSSL_SNIFFER_WATC * `ssl_SetWatchKey_buffer`: Loads a new DER format key into server session. * `ssl_SetWatchKey_file`: File version of `ssl_SetWatchKey_buffer`. -Statistics collecting with the sniffer can be compiled in with defining the macro `WOLFSSL_SNIFFER_STATS`. The statistics are kept in a SSLStats structure and are copied to an applications SSLStats structure by a call to `ssl_ReadStatistics`. Additional API to use with sniffer statistics is `ssl_ResetStatistics` (resets the collection of statistics) and `ssl_ReadResetStatistics` (reads the current statistic values and then resets the internal state). The following is the current statistics kept when turned on: +Statistics collecting with the sniffer can be compiled in by defining the macro `WOLFSSL_SNIFFER_STATS`. The statistics are kept in a SSLStats structure and are copied to an application's SSLStats structure by a call to `ssl_ReadStatistics`. Additional API to use with sniffer statistics is `ssl_ResetStatistics` (resets the collection of statistics) and `ssl_ReadResetStatistics` (reads the current statistic values and then resets the internal state). The following is the current statistics kept when turned on: * `sslStandardConns` * `sslClientAuthConns` @@ -583,7 +583,7 @@ Or if you are using a user_settings.h header, add the following macro definition ``` user_settings.h -　　#define WOLFSSL_STATIC_MEMORY + #define WOLFSSL_STATIC_MEMORY ``` The static-buffer-allocation option is implemented by default to fall back to the standard malloc() function when a NULL heap hint is passed in. If a heap hint is passed in and the memory associated with it is exhausted, an error will occur. If the environment does not provide dynamic memory management functionality, a link error will occur. Therefore, also define the **WOLFSSL_NO_MALLOC** macro to disable this feature if needed: @@ -591,11 +591,11 @@ The static-buffer-allocation option is implemented by default to fall back to th ``` user_settings.h -　　#define WOLFSSL_STATIC_MEMORY + #define WOLFSSL_STATIC_MEMORY #define WOLFSSL_NO_MALLOC ``` -In addition there are two build configurations. `--enable-staticmemory=small` which is a +In addition there are two build configurations. One is `--enable-staticmemory=small` which is a smaller version that has smaller struct sizes and less supporting API's available. The other build configuration is `--enable-staticmemory=debug` that enables the ability to set a callback function. This is useful in cases where printf() is not available for determining what is being allocated and what @@ -667,7 +667,7 @@ int ret; #define MAX_CONCURRENT_IO 0 unsigned char GEN_MEM[GEN_MEM_SIZE]; -unsigned char IO_MEM[IO_MEM_SIZE];　 +unsigned char IO_MEM[IO_MEM_SIZE]; /* set up a general-purpose buffer and generate WOLFSSL_CTX from it on the first call. */ ret = wolfSSL_CTX_load_static_memory( @@ -719,8 +719,8 @@ The memory block size and number of blocks for each area to be used are defined /wolfssl/wolfcrypt/memory.h #define WOLFSSL_STATIC_ALIGN 16 /* alignment 16 bytes by default*/ - #define WOLFMEM_MAX_BUCKETS 9　　/* number of buckets */ - 　#define WOLFMEM_IO_SZ 16992 /* buffer size for I/O */ + #define WOLFMEM_MAX_BUCKETS 9 /* number of buckets */ + #define WOLFMEM_IO_SZ 16992 /* buffer size for I/O */ #define LARGEST_MEM_BUCKET 16128 /* the max block size */ #define WOLFMEM_BUCKETS 64,128,256,512,1024,2432,3456, 4544,LARGEST_MEM_BUCKET @@ -728,7 +728,7 @@ The memory block size and number of blocks for each area to be used are defined ``` -* **WOLFSSL_STATIC_ALIGN** specifies the buffer alignment size. 16 bytes by default. You need to change it according to the alignment size of your MCU. +* **WOLFSSL_STATIC_ALIGN** specifies the buffer alignment size. It is 16 bytes by default. You need to change it according to the alignment size of your MCU. * **WOLFMEM_MAX_BUCKETS** shows the number of buckets. This means using 9 different bucket sizes. * **WOLFMEM_BUCKETS** specifies the number of bytes in blocks in each bucket, separated by commas, from smallest to largest. This definition applies to general purpose buffers. @@ -738,27 +738,28 @@ In the example above, a bucket with a block size of 64 bytes is the minimum size #### Macros for I/O Use Buffers -For TLS client +For TLS client: - `wolfTLSv1_3_client_method_ex` - `wolfTLSv1_2_client_method_ex` - `wolfTLSv1_1_client_method_ex` - `wolfSSLv23_client_method_ex` -For TLS server +For TLS server: + - `wolfTLSv1_3_server_method_ex` - `wolfTLSv1_2_server_method_ex` - `wolfTLSv1_1_server_method_ex` - `wolfSSLv23_server_method_ex` -For DTLS client +For DTLS client: - `wolfDTLSv1_3_client_method_ex` - `wolfTLSv1_2_client_method_ex` - `wolfTLSv1_1_client_method_ex` - `wolfSSLv23_client_method_ex` -For DTLS server +For DTLS server: - `wolfDTLSv1_3_server_method_ex` - `wolfTLSv1_2_server_method_ex` @@ -847,9 +848,9 @@ wolfSSL_CTX_load_verify_locations(ctx, caCert, 0); To turn on client verification and control its behavior, the [`wolfSSL_CTX_set_verify()`](group__Setup.md#function-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()`](group__Setup.md#function-wolfssl_ctx_set_verify) include `SSL_VERIFY_NONE` and `SSL_VERIFY_CLIENT_ONCE`. ```c -wolfSSL_CTX_set_verify(ctx,SSL_VERIFY_PEER | ((usePskPlus)? +wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | (usePskPlus ? SSL_VERIFY_FAIL_EXCEPT_PSK : - SSL_VERIFY_FAIL_IF_NO_PEER_CERT),0); + 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`). @@ -904,38 +905,6 @@ All TLS extensions can also be enabled with: ./configure --enable-tlsx ``` -## 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`](chapter02.md#--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. - ## 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. diff --git a/wolfSSL/src/chapter06.md b/wolfSSL/src/chapter06.md index a06ab3bd..f2cd745e 100644 --- a/wolfSSL/src/chapter06.md +++ b/wolfSSL/src/chapter06.md @@ -120,6 +120,7 @@ Additionally, each callback type requires its specific feature to be enabled (e. wolfSSL provides DH (Diffie-Hellman) callbacks for users who wish to have more control over DH key generation and key agreement operations during the SSL/TLS connection. The user can optionally define 2 functions: + 1. DH key generation callback 2. DH key agreement callback @@ -138,6 +139,7 @@ typedef int (*CallbackDhAgree)(WOLFSSL* ssl, struct DhKey* key, ``` The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with: + * `wolfSSL_CTX_SetDhGenerateKeyPair()` * `wolfSSL_CTX_SetDhAgreeCb()` @@ -152,6 +154,7 @@ To use DH callbacks, wolfSSL needs to be compiled with `HAVE_DH` defined. wolfSSL provides Ed25519 callbacks for users who wish to have more control over Ed25519 sign/verify operations during the SSL/TLS connection. The user can optionally define 2 functions: + 1. Ed25519 sign callback 2. Ed25519 verify callback @@ -172,10 +175,12 @@ typedef int (*CallbackEd25519Verify)(WOLFSSL* ssl, ``` The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with: + * `wolfSSL_CTX_SetEd25519SignCb()` * `wolfSSL_CTX_SetEd25519VerifyCb()` The user can set a context per WOLFSSL object (session) with: + * `wolfSSL_SetEd25519SignCtx()` * `wolfSSL_SetEd25519VerifyCtx()` @@ -188,6 +193,7 @@ To use Ed25519 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` wolfSSL provides X25519 callbacks for users who wish to have more control over X25519 key generation and shared secret computation during the SSL/TLS connection. The user can optionally define 2 functions: + 1. X25519 key generation callback 2. X25519 shared secret callback @@ -205,10 +211,12 @@ typedef int (*CallbackX25519SharedSecret)(WOLFSSL* ssl, ``` The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with: + * `wolfSSL_CTX_SetX25519KeyGenCb()` * `wolfSSL_CTX_SetX25519SharedSecretCb()` The user can set a context per WOLFSSL object (session) with: + * `wolfSSL_SetX25519KeyGenCtx()` * `wolfSSL_SetX25519SharedSecretCtx()` @@ -221,6 +229,7 @@ To use X25519 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` a wolfSSL provides Ed448 callbacks for users who wish to have more control over Ed448 sign/verify operations during the SSL/TLS connection. The user can optionally define 2 functions: + 1. Ed448 sign callback 2. Ed448 verify callback @@ -241,10 +250,12 @@ typedef int (*CallbackEd448Verify)(WOLFSSL* ssl, ``` The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with: + * `wolfSSL_CTX_SetEd448SignCb()` * `wolfSSL_CTX_SetEd448VerifyCb()` The user can set a context per WOLFSSL object (session) with: + * `wolfSSL_SetEd448SignCtx()` * `wolfSSL_SetEd448VerifyCtx()` @@ -257,6 +268,7 @@ To use Ed448 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` an wolfSSL provides X448 callbacks for users who wish to have more control over X448 key generation and shared secret operations during the SSL/TLS connection. The user can optionally define 2 functions: + 1. X448 key generation callback 2. X448 shared secret callback @@ -274,10 +286,12 @@ typedef int (*CallbackX448SharedSecret)(WOLFSSL* ssl, ``` The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with: + * `wolfSSL_CTX_SetX448KeyGenCb()` * `wolfSSL_CTX_SetX448SharedSecretCb()` The user can set a context per WOLFSSL object (session) with: + * `wolfSSL_SetX448KeyGenCtx()` * `wolfSSL_SetX448SharedSecretCtx()` @@ -290,6 +304,7 @@ To use X448 callbacks, wolfSSL needs to be compiled with `HAVE_PK_CALLBACKS` and wolfSSL provides RSA PSS callbacks for users who wish to have more control over RSA PSS sign/verify operations during the SSL/TLS connection. The user can optionally define 4 functions: + 1. RSA PSS sign callback 2. RSA PSS verify callback 3. RSA PSS sign check callback @@ -320,12 +335,14 @@ typedef int (*CallbackRsaPssSignCheck)(WOLFSSL* ssl, ``` The user needs to write and register these functions per wolfSSL context (`WOLFSSL_CTX`) with: + * `wolfSSL_CTX_SetRsaPssSignCb()` * `wolfSSL_CTX_SetRsaPssVerifyCb()` * `wolfSSL_CTX_SetRsaSignCheckCb()` * `wolfSSL_CTX_SetRsaPssSignCheckCb()` The user can set a context per WOLFSSL object (session) with: + * `wolfSSL_SetRsaPssSignCtx()` * `wolfSSL_SetRsaPssVerifyCtx()` * `wolfSSL_SetRsaSignCheckCtx()` @@ -432,7 +449,7 @@ The high level steps use crypto callbacks are: #### 1. Compile wolfSSL with crypto callback support -Support for crypto callbacks is enabled in wolfSSL via the `–enable-cryptocb` configure option, or `#define WOLF_CRYPTO_CB`. +Support for crypto callbacks is enabled in wolfSSL via the `–-enable-cryptocb` configure option, or `#define WOLF_CRYPTO_CB`. #### 2. Register your callback and unique devID with wolfCrypt @@ -467,6 +484,7 @@ wc_InitCmac_ex This will cause wolfCrypt to invoke the crypto callback in place of the default implementation. This is not an exhaustive API list. Please refer to the wolfCrypt API documentation to see if a particular algorithm supports crypto callbacks. #### 4. (TLS only): associate the devId with a wolfSSL context + To enable use of a crypto callback when using TLS, you must supply the `devId` arguments on initialization of a `WOLFSSL_CTX` or `WOLFSSL` struct. ```c wolfSSL_CTX_SetDevId(ctx, devId); diff --git a/wolfSSL/src/chapter07.md b/wolfSSL/src/chapter07.md index a6c5f352..b13bcf77 100644 --- a/wolfSSL/src/chapter07.md +++ b/wolfSSL/src/chapter07.md @@ -174,7 +174,7 @@ int wolfSSL_CTX_trust_peer_cert(WOLFSSL_CTX *ctx, ## Certificate Chain Verification -wolfSSL requires that only the top or “root” certificate in a chain to be loaded as a trusted certificate in order to verify a certificate chain. This means that if you have a certificate chain (A -\> B -\> C), where C is signed by B, and B is signed by A, wolfSSL only requires that certificate A be loaded as a trusted certificate in order to verify the entire chain (A-\>B-\>C). +wolfSSL requires only the top or “root” certificate in a chain to be loaded as a trusted certificate in order to verify a certificate chain. This means that if you have a certificate chain (A -\> B -\> C), where C is signed by B, and B is signed by A, wolfSSL only requires that certificate A be loaded as a trusted certificate in order to verify the entire chain (A-\>B-\>C). For example, if a server certificate chain looks like: @@ -192,7 +192,7 @@ Checking the domain name of the certificate is an important step that verifies t ## No File System and using Certificates -Normally a file system is used to load private keys, certificates, and CAs. Since wolfSSL is sometimes used in environments without a full file system an extension to use memory buffers instead is provided. To use the extension define the constant `NO_FILESYSTEM` and the following functions will be made available: +Normally a file system is used to load private keys, certificates, and CAs. Since wolfSSL is sometimes used in environments without a full file system, an extension to use memory buffers instead is provided. To use the extension define the constant `NO_FILESYSTEM` and the following functions will be made available: * [`int wolfSSL_CTX_load_verify_buffer(WOLFSSL_CTX* ctx, const unsigned char* in,long sz, int format);`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_buffer) * [`int wolfSSL_CTX_use_certificate_buffer(WOLFSSL_CTX* ctx, const unsigned char* in, long sz, int format);`](group__CertsKeys.md#function-wolfssl_ctx_use_certificate_buffer) @@ -204,7 +204,7 @@ Use these functions exactly like their counterparts that are named `*_file` inst ### Test Certificate and Key Buffers -wolfSSL has come bundled with test certificate and key files in the past. Now it also comes bundled with test certificate and key buffers for use in environments with no filesystem available. These buffers are available in `certs_test.h` when defining one or more of `USE_CERT_BUFFERS_1024`, `USE_CERT_BUFFERS_2048`, or `USE_CERT_BUFFERS_256`. +wolfSSL comes bundled with test certificate and key files. Additionally, it also comes bundled with test certificate and key buffers for use in environments with no filesystem available. These buffers are available in `certs_test.h` when defining one or more of `USE_CERT_BUFFERS_1024`, `USE_CERT_BUFFERS_2048`, or `USE_CERT_BUFFERS_256`. ## Serial Number Retrieval @@ -225,7 +225,7 @@ wolfSSL supports RSA key generation of varying lengths up to 4096 bits. Key gene int MakeRsaKey(RsaKey* key, int size, long e, RNG* rng); ``` -Where `size` is the length in bits and `e` is the public exponent, using 65537 is usually a good choice for `e`. The following from `wolfcrypt/test/test.c` gives an example creating an RSA key of 1024 bits: +Where `size` is the length in bits and `e` is the public exponent (using 65537 is usually a good choice for `e`). The following from `wolfcrypt/test/test.c` gives an example creating an RSA key of 1024 bits: ```c RsaKey genKey; diff --git a/wolfSSL/src/chapter09.md b/wolfSSL/src/chapter09.md index e618e86d..547714b4 100644 --- a/wolfSSL/src/chapter09.md +++ b/wolfSSL/src/chapter09.md @@ -52,7 +52,7 @@ wolfSSL (formerly CyaSSL) is thread safe by design. Multiple threads can enter t ## Input and Output Buffers -wolfSSL now uses dynamic buffers for input and output. They default to 0 bytes and are controlled by the `RECORD_SIZE` define in `wolfssl/internal.h`. If an input record is received that is greater in size than the static buffer, then a dynamic buffer is temporarily used to handle the request and then freed. You can set the static buffer size up to the `MAX_RECORD_SIZE` which is 2^16 or 16,384. +wolfSSL now uses dynamic buffers for input and output. They default to 0 bytes and are controlled by the `RECORD_SIZE` define in `wolfssl/internal.h`. If an input record is received that is greater in size than the static buffer, then a dynamic buffer is temporarily used to handle the request and then freed. You can set the static buffer size up to the `MAX_RECORD_SIZE` which is 2^14 or 16,384. If you prefer the previous way that wolfSSL operated, with 16Kb static buffers that will never need dynamic memory, you can still get that option by defining `LARGE_STATIC_BUFFERS`. diff --git a/wolfSSL/src/chapter10.md b/wolfSSL/src/chapter10.md index 2732d47f..206a0420 100644 --- a/wolfSSL/src/chapter10.md +++ b/wolfSSL/src/chapter10.md @@ -263,7 +263,7 @@ For usage examples please see the camellia_test() function in `/wo **NOTE**: ARC4 is outdated and considered insecure. Please consider using a different stream cipher. -The most common stream cipher used on the Internet is ARC4. wolfCrypt supports it through the header `wolfssl/wolfcrypt/arc4.h`. Usage is simpler than block ciphers because there is no block size and the key length can be any length. The following is a typical usage of ARC4. +wolfCrypt supports ARC4 through the header `wolfssl/wolfcrypt/arc4.h`. Usage is simpler than block ciphers because there is no block size and the key length can be any length. The following is a typical usage of ARC4. ```c Arc4 enc; diff --git a/wolfSSL/src/chapter11.md b/wolfSSL/src/chapter11.md index 358e20d5..97e3bb61 100644 --- a/wolfSSL/src/chapter11.md +++ b/wolfSSL/src/chapter11.md @@ -256,7 +256,7 @@ EchoServer: * [`wolfDTLSv1_2_server_method();`](ssl_8h.md#function-wolfdtlsv1_2_server_method) - DTLS 1.2 * [`wolfDTLSv1_3_server_method();`](ssl_8h.md#function-wolfdtlsv1_3_server_method) - DTLS 1.3 -We need to load our CA (Certificate Authority) certificate into the `WOLFSSL_CTX` so that the when the echoclient connects to the echoserver, it is able to verify the server’s identity. To load the CA certificates into the `WOLFSSL_CTX`, use [`wolfSSL_CTX_load_verify_locations()`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations). This function requires three arguments: a `WOLFSSL_CTX` pointer, a certificate file, and a path value. The path value points to a directory which should contain CA certificates in PEM format. When looking up certificates, wolfSSL will look at the certificate file value before looking in the path location. In this case, we don’t need to specify a certificate path because we will specify one CA file - as such we use the value 0 for the path argument. The [`wolfSSL_CTX_load_verify_locations`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations) function returns either `SSL_SUCCESS` or `SSL_FAILURE`: +We need to load our CA (Certificate Authority) certificate into the `WOLFSSL_CTX` so that the when the echoclient connects to the echoserver, it is able to verify the server’s identity. To load the CA certificates into the `WOLFSSL_CTX`, use [`wolfSSL_CTX_load_verify_locations()`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations). This function requires three arguments: a `WOLFSSL_CTX` pointer, a certificate file, and a path value. The path value points to a directory which should contain CA certificates in PEM format. When looking up certificates, wolfSSL will look at the certificate file value before looking in the path location. In this case, we don’t need to specify a certificate path because we will specify one CA file - as such we use NULL for the path argument. The [`wolfSSL_CTX_load_verify_locations`](group__CertsKeys.md#function-wolfssl_ctx_load_verify_locations) function returns either `SSL_SUCCESS` or `SSL_FAILURE`: ```c wolfSSL_CTX_load_verify_locations(WOLFSSL_CTX* ctx, const char* file, const char* path) @@ -278,10 +278,10 @@ EchoClient: } /* Load CA certificates into WOLFSSL_CTX */ - if (wolfSSL_CTX_load_verify_locations(ctx,"../certs/ca-cert.pem",0) != + if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", NULL) != SSL_SUCCESS) { - fprintf(stderr, "Error loading ../certs/ca-cert.pem, please check" - "the file.\n"); + fprintf(stderr, "Error loading ../certs/ca-cert.pem, " + "please check the file.\n"); exit(EXIT_FAILURE); } ``` @@ -304,7 +304,7 @@ if ( (ctx = wolfSSL_CTX_new(wolfTLSv1_2_server_method())) == NULL) { } /* Load CA certificates into WOLFSSL_CTX */ -if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", 0) != +if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", NULL) != SSL_SUCCESS) { fprintf(stderr, "Error loading ../certs/ca-cert.pem, " "please check the file.\n"); @@ -312,7 +312,7 @@ if (wolfSSL_CTX_load_verify_locations(ctx, "../certs/ca-cert.pem", 0) != } /* Load server certificates into WOLFSSL_CTX */ -if (wolfSSL_CTX_use_certificate_file(ctx,"../certs/server-cert.pem", +if (wolfSSL_CTX_use_certificate_file(ctx, "../certs/server-cert.pem", SSL_FILETYPE_PEM) != SSL_SUCCESS) { fprintf(stderr, "Error loading ../certs/server-cert.pem, please" "check the file.\n"); @@ -320,7 +320,7 @@ if (wolfSSL_CTX_use_certificate_file(ctx,"../certs/server-cert.pem", } /* Load keys */ -if (wolfSSL_CTX_use_PrivateKey_file(ctx,"../certs/server-key.pem", +if (wolfSSL_CTX_use_PrivateKey_file(ctx, "../certs/server-key.pem", SSL_FILETYPE_PEM) != SSL_SUCCESS) { fprintf(stderr, "Error loading ../certs/server-key.pem, please check" "the file.\n"); @@ -341,11 +341,11 @@ wolfSSL_Cleanup(); ### EchoClient -A WOLFSSL object needs to be created after each TCP Connect and the socket file descriptor needs to be associated with the session. In the echoclient example, we will do this after the call to `Connect()`, shown below: +A WOLFSSL object needs to be created after each TCP connect and the socket file descriptor needs to be associated with the session. In the echoclient example, we will do this after the call to `connect()`, shown below: ```c /* Connect to socket file descriptor */ -Connect(sockfd, (SA *) &servaddr, sizeof(servaddr)); +connect(sockfd, (SA *) &servaddr, sizeof(servaddr)); ``` Directly after connecting, create a new `WOLFSSL` object using the [`wolfSSL_new()`](group__Setup.md#function-wolfssl_new) function. This function returns a pointer to the `WOLFSSL` object if successful or `NULL` in the case of failure. We can then associate the socket file descriptor (`sockfd`) with the new `WOLFSSL` object (`ssl`): @@ -497,7 +497,7 @@ while(cleanup != 1) } ``` -For the echoserver we need to disable the operating system from restarting calls which were being executed before the signal was handled after our handler has finished. By disabling these, the operating system will not restart calls to `accept()` after the signal has been handled. If we didn’t do this, we would have to wait for another client to connect and disconnect before the echoserver would clean up resources and exit. To define the signal handler and turn off `SA_RESTART`, first define act and oact structures in the echoserver’s `main()` function: +For the echoserver we need to disable the operating system from restarting calls which were being executed before the signal was handled after our handler has finished. By disabling these, the operating system will not restart calls to `accept()` after the signal has been handled. If we didn’t do this, we would have to wait for another client to connect and disconnect before the echoserver would clean up resources and exit. To define the signal handler and turn off `SA_RESTART`, first define `act` and `oact` structures in the echoserver’s `main()` function: ```c struct sigaction act, oact;