wolfSSL Support for SSL/TLS with Alternative I/O

wolfSSL's embedded SSL/TLS library provides support for many different features, such as TLS 1.3, a FIPS 140-2 validation, and even support for SSL/TLS using less traditional I/O.  In this context, “less traditional I/O” means running SSL/TLS over something besides TCP/IP or UDP - for example Bluetooth, a serial connection, memory buffers, or a proprietary transfer protocol.  In embedded projects, we know it can be common.

The wolfSSL embedded SSL/TLS library provides a mechanism to plug in your own application-specific I/O routines. By default, the library calls a BSD socket API, with functions that call the system’s recv() and send() using a file descriptor that has been cached with wolfSSL_set_fd().

The prototypes for the I/O callback functions are:

    typedef int (*CallbackIORecv)(WOLFSSL *ssl, char *buf, int sz, void *ctx);
    typedef int (*CallbackIOSend)(WOLFSSL *ssl, char *buf, int sz, void *ctx);

In the default case, the network socket file descriptor is passed to the I/O callback through the “ctx” parameter. The “ssl” parameter is a pointer to the current wolfSSL session, giving callbacks access to session-level details if needed.

In the receive case, “buf” points to the buffer where incoming ciphertext should be copied for wolfSSL to decrypt and “sz” is the size of the buffer. Callbacks should copy “sz” bytes into “buf”, or the number of bytes available.  In the send case, “buf” points to the buffer where wolfSSL has written ciphertext to be sent and “sz” is the size of that buffer. Callbacks should send “sz” bytes from “buf” across their transport medium. In either case the number of bytes written or read should be returned, or alternatively an applicable error code.

To register your own I/O callbacks with the wolfSSL Context (WOLFSSL_CTX) for your application, use the functions wolfSSL_SetIORecv() and wolfSSL_SetIOSend().

    wolfSSL_SetIORecv(ctx, myCBIORecv);
    wolfSSL_SetIOSend(ctx, myCBIOSend);

An example use case for alternative I/O would be to have a server with a datagram socket which receives data from multiple clients or processes TLS through STDIN and STDOUT. In this case you would have four buffers:

    cipher-receive     encrypted data received from peer
    cipher-send        encrypted data to send to peer
    clear-receive      clear data received from wolfSSL
    clear-send         clear data passed to wolfSSL

Pointers to these buffers, values for their sizes, and read and write positions might be placed into a user-defined structure. A pointer to this structure could then be cached in the wolfSSL session with the functions wolfSSL_SetIOReadCtx() and wolfSSL_SetIOWriteCtx().

    wolfSSL_SetIOReadCtx(ssl, buffer_data);
    wolfSSL_SetIOWriteCtx(ssl, buffer_data);

The application would receive a block of ciphertext into the buffer “cipher-receive”. Next the application would call wolfSSL_read(ssl, buffer_data->clear_receive), causing wolfSSL to call the registered receive callback. That receive callback will be given a buffer, the size of the buffer, and the ctx, which has the “cipher-receive” buffer. The callback may be called many times internally for one call to wolfSSL_read(). If the “cipher-receive” buffer is empty, the callback should return WOLFSSL_CBIO_ERR_WANT_READ, otherwise it should return the number of bytes copied into “buf”.

When the library wants to send data, during handshaking or when wolfSSL_send() is called with plaintext, the library will call the registered send callback. The callback is given a buffer full of encrypted data, and the length of the encrypted data. In this example, the callback would copy this cipher text into “cipher-send” and return the number of bytes copied. If the “cipher-send” buffer isn’t big enough, the callback should return WOLFSSL_CBIO_ERR_WANT_WRITE.

If you are interested in looking over an example of using the wolfSSL I/O abstraction layer, we have an example client/server application at the following link that does TLS using files as the transport medium: https://github.com/wolfSSL/wolfssl-examples/tree/master/custom-io-callbacks

If you have questions about using wolfSSL’s custom I/O callback layer, please contact us at facts@wolfssl.com.

wolfSSL Embedded SSL for Bare Metal and No OS Environments

Are you looking for an SSL/TLS library which will seamlessly integrate into your bare metal or No-OS environment? If so, continue reading to learn why the wolfSSL lightweight SSL library is a perfect fit for such environments.

wolfSSL has been designed with portability and ease of use in mind, allowing developers to easily integrate it into a bare metal or operating systemless environment. As a large percentage of wolfSSL users are running the library on small, embedded devices, we have added several abstraction layers which make tying wolfSSL into these types of environments an easy task.

Available abstraction layers include:

  • Custom Input/Output
  • Standard C library / Memory
  • File system (Able to use cert/key buffers instead)
  • Threading
  • Operating System

In addition to abstraction layers, we have tried to keep wolfSSL’s memory usage as low as possible. Build sizes for a complete SSL/TLS stack range from 20-100kB depending on build options, with RAM usage between 1-36kB per connection.

To learn more about how to integrate wolfSSL into your environment or get more information about reducing wolfSSL’s memory usage, please see the wolfSSL Manual or contact us directly.

Posts navigation

1 2 3 4