In this past (here and here) we have written about wolfSSL’s I/O abstraction layer and support for alternative I/O mediums. We wanted to refresh our reader’s memory about this helpful feature. 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 looking for a lightweight TLS solution, we know this can be common.
wolfSSL I/O Abstraction Layer
wolfSSL 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’s file descriptor is passed to the I/O callback in 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_CTX, use the functions wolfSSL_SetIORecv() and wolfSSL_SetIOSend().
wolfSSL_SetIORecv(ctx, myCBIORecv); wolfSSL_SetIOSend(ctx, myCBIOSend);
A Simple Example using Memory Buffers
Oftentimes walking through a simple example helps make this more understandable. One example use case for alternative I/O is a server that receives data from multiple clients or processes TLS through STDIN and STDOUT. In this application there could be four buffers:
- cipher-receive encrypted data received from peer
- cipher-send encrypted data to be sent 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 can be placed into a user-defined structure. A pointer to this structure would 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”, and call wolfSSL_read(ssl, buffer_data->clear_receive), causing wolfSSL to call the registered receive callback. The receive callback will be given a buffer, the size of the buffer, and the context (ctx), which contains the “cipher-receive” buffer. The callback might be called many times internally for a single call to wolfSSL_read(). If the “cipher-receive” buffer is empty, the callback will return -2 (WOLFSSL_CBIO_ERR_WANT_READ), otherwise it will return the number of bytes copied into “buf”. WOLFSSL_CBIO_ERR_WANT_READ is an error condition that indicates that there was no data available for reading at the time that the callback requested data. In this case, the application should loop back around and make the high-level API call (wolfSSL_read(), wolfSSL_connect(), etc) again when data is ready to be read.
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 -2 (WOLFSSL_CBIO_ERR_WANT_WRITE).
Additional Resources
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. Please feel free to contact us at facts@wolfssl.com with any further questions about using the wolfSSL lightweight TLS library.
https://github.com/wolfSSL/wolfssl-examples/tree/master/custom-io-callbacks
