wolfSSL Manual

Chapter 5: Portability

5.1 Abstraction Layers

5.1.1 C Standard Library Abstraction Layer

wolfSSL (formerly CyaSSL) can be built without the C standard library to provide a higher level of portability and flexibility to developers. The user will have to map the functions they wish to use instead of the C standard ones. Memory Use

Most C programs use malloc() and free() for dynamic memory allocation. wolfSSL uses XMALLOC() and XFREE() instead. By default, these point to the C runtime versions. By defining XMALLOC_USER, the user can provide their own hooks. Each memory function takes two additional arguments over the standard ones, a heap hint, and an allocation type. The user is free to ignore these or use them in any way they like.  You can find the wolfSSL memory functions in wolfssl/wolfcrypt/types.h.

wolfSSL also provides the ability to register memory override functions at runtime instead of compile time. wolfssl/wolfcrypt/memory.h is the header for this functionality and the user can call the following function to setup the memory functions:

int wolfSSL_SetAllocators(wolfSSL_Malloc_cb  malloc_function,

                        wolfSSL_Free_cb    free_function,

                        wolfSSL_Realloc_cb realloc_function);

See the header wolfssl/wolfcrypt/memory.h for the callback prototypes and memory.c for the implementation. string.h

wolfSSL uses several functions that behave like string.h’s memcpy(), memset(), and memcmp() amongst others. They are abstracted to XMEMCPY(), XMEMSET(), and XMEMCMP() respectively.  And by default, they point to the C standard library versions.  Defining XSTRING_USER allows the user to provide their own hooks in types.h. For example, by default XMEMCPY() is:

#define XMEMCPY(d,s,l)    memcpy((d),(s),(l))

After defining XSTRING_USER you could do:

#define XMEMCPY(d,s,l)    my_memcpy((d),(s),(l))

Or if you prefer to avoid macros:

external void* my_memcpy(void* d, const void* s, size_t n);

to set wolfSSL’s abstraction layer to point to your version my_memcpy(). math.h

wolfSSL uses two functions that behave like math.h’s pow() and log(). They are only required by Diffie-Hellman, so if you exclude DH from the build, then you don’t have to provide your own. They are abstracted to XPOW() and XLOG() and found in wolfcrypt/src/dh.c. File System Use

By default, wolfSSL uses the system’s file system for the purpose of loading keys and certificates. This can be turned off by defining NO_FILESYSTEM, see item V. If instead, you’d like to use a file system but not the system one, you can use the XFILE() layer in ssl.c to point the file system calls to the ones you’d like to use.  See the example provided by the MICRIUM define.

5.1.2 Custom Input/Output Abstraction Layer

wolfSSL provides a custom I/O abstraction layer for those who wish to have higher control over I/O of their SSL connection or run SSL on top of a different transport medium other than TCP/IP.

The user will need to define 2 functions:

  1. 1.The network Send function

  2. 2.The network Receive function

These two functions are prototyped by CallbackIOSend and CallbackIORecv in ssl.h:

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

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

The user needs to register these functions per WOLFSSL_CTX with wolfSSL_SetIOSend() and wolfSSL_SetIORecv().  For example, in the default case, CBIORecv() and CBIOSend() are registered at the bottom of io.c:

void wolfSSL_SetIORecv(WOLFSSL_CTX *ctx, CallbackIORecv CBIORecv)


    ctx->CBIORecv = CBIORecv;



void wolfSSL_SetIOSend(WOLFSSL_CTX *ctx, CallbackIOSend CBIOSend)


   ctx->CBIOSend = CBIOSend;


The user can set a context per WOLFSSL object (session) with wolfSSL_SetIOWriteCtx() and wolfSSL_SetIOReadCtx(), as demonstrated at the bottom of io.c.  For example, if the user is using memory buffers, the context may be a pointer to a structure describing where and how to access the memory buffers.  The default case, with no user overrides, registers the socket as the context.

The CBIORecv and CBIOSend function pointers can be pointed to your custom I/O functions. The default Send() and Receive() functions, EmbedSend() and EmbedReceive(), located in io.c, can be used as templates and guides.

WOLFSSL_USER_IO can be defined to remove the automatic setting of the default I/O functions EmbedSend() and EmbedReceive().

5.1.3 Operating System Abstraction Layer

The wolfSSL OS abstraction layer helps facilitate easier porting of wolfSSL to a user’s operating system.  The wolfssl/wolfcrypt/settings.h file contains settings which end up triggering the OS layer.

OS-specific defines are located in wolfssl/wolfcrypt/types.h for wolfCrypt and wolfssl/internal.h for wolfSSL.

5.2 Supported Operating Systems

One factor which defines wolfSSL is its ability to be easily ported to new platforms.  As such, wolfSSL has support for a long list of operating systems out-of-the-box.  Currently-supported operating systems include:

Win32/64, Linux, Mac OS X, Solaris, ThreadX, VxWorks, FreeBSD, NetBSD, OpenBSD, embedded Linux, WinCE, Haiku, OpenWRT, iPhone (iOS), Android, Nintendo Wii and Gamecube through DevKitPro, QNX, MontaVista, NonStop, TRON/ITRON/µITRON, Micrium's µC/OS, FreeRTOS, SafeRTOS, Freescale MQX, Nucleus, TinyOS, HP/UX, TIRTOS

5.3 Supported Chipmakers

wolfSSL has support for chipsets from chipmakers, including: ARM, Intel, ST (STM32F2/F4), Motorola, mbed, Freescale, Microchip (PIC32), Texas Instruments, and more.

Docs -> wolfSSL Manual

Questions? +1 (425) 245-8247