wolfSSL Custom I/O Setup

wolfSSL provides a mechanism to plug in your own application specific I/O routines. By default, the library uses functions that call the system’s recv() and send() functions with a file descriptor cached with the function wolfSSL_set_fd().

The prototypes for the I/O routines are:

int CBIORecv(CYASSL* ssl, char* buf, int sz, void* ctx);
int CBIOSend(CYASSL* ssl, char* buf, int sz, void* ctx);

In the default case, the network socket’s file descriptor is passed to the I/O routine in the ctx parameter. The ssl parameter is a pointer to the current session. In the receive case, buf points to the buffer where incoming cipher text should be copied for wolfSSL to decrypt and sz is the size of the buffer. In the send case, buf points to the buffer where wolfSSL has written cipher text to be sent and sz is the size of that buffer.

First you need to register your I/O callbacks with the CYASSL_CTX for your application using the functions wolfSSL_SetIORecv() and wolfSSL_SetIOSend().

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

As an example, for your application you want to control the socket for your own purposes. An example 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 should be placed into a structure. This structure should be saved to the wolfSSL session with the functions wolfSSL_SetIOReadCtx() and wolfSSL_SetIOWriteCtx().

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

The application receives a block of cipher text into the buffer cipher-receive. Next the application would call wolfSSL_read(ssl, buffer_data->clear_receive), causing wolfSSL to call myCBIORecv(). myCBIORecv() 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 for one call to wolfSSL_read(). If the cipher-receive buffer is empty, the callback should return -2, otherwise it should return the number of bytes copied into buf.

When the library wants to send data, like during handshaking or when wolfSSL_send() is called with some clear text, the library will call myCBIOSend(). 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.