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.
