OpenSIPS 3.2 and the supported SSL/TLS libraries

OpenSIPS has had a troubled history using the openSSL library for it’s SSL/TLS support. While most of the issues have been solved, it has become more and more difficult to maintain the existing TLS implementation using openSSL. As such, starting with OpenSIPS 3.2, a new TLS implementation, based on the wolfSSL library is now available. You can read more about the process of finding a suitable TLS library and the arguments behind wolfSSL in this article.

Instead of taking a radical approach, of completely dropping the openSSL implementation, we have decided to support both the openSSL and wolfSSL libraries. Before definitively replacing openSSL, we have to make sure that the wolfSSL implementation is stable and there are no other reasons to still keep openSSL.

Configuration

In terms of OpenSIPS configuration, when you want to use TLS transport for SIP, WebSocket or BIN traffic, you now have to also explicitly load one of the new tls_openssl or tls_wolfssl modules. That is because the TLS operations have been restructured into these dedicated, library-specific modules, while the tls_mgm module acts as a transparent interface between the actual implementations and the TLS-based transport protocol modules (proto_tls, proto_wss and proto_bins).

The TLS-related settings available through the tls_mgm module remain the same regardless of the TLS library used (with small exceptions, like the tls_method parameter which does not accept a range of methods when using wolfSSL) and no other configuration steps are necessary.

However, the tls_mgm module may also be used strictly for managing TLS certificates and parameters, by modules other than transport protocol ones, like db_mysql, cachedb_redis, rabbitmq etc. For such modules, there is no actual TLS implementation in OpenSIPS (but rather, the respective external libraries use openSSL directly) so there is no need for the tls_openssl or tls_wolfssl modules. In that case, you will have to set the new tls_library module parameter from tls_mgm to “none“. Otherwise, the module will throw an error at startup, as it tries to auto-detect which TLS library to use based on the loaded modules.

Also, note that OpenSIPS uses wolfSSL as a statically-linked library which comes bundled with the new tls_wolfssl module so no external dependency is required.

Example

Here is a basic example of the sequence of modules that need to be loaded for using proto_tls and the openSSL library:

loadmodule "tls_openssl.so"

loadmodule "tls_mgm.so"
modparam("tls_mgm", "server_domain", "mydom")
...

loadmodule "proto_tls.so"

And alternatively, if you want to use wolfSSL:

loadmodule "tls_wolfssl.so"

loadmodule "tls_mgm.so"
modparam("tls_mgm", "server_domain", "mydom")
...

loadmodule "proto_tls.so"

Conclusion

Starting with OpenSIPS 3.2, we can finally transition away from the openSSL library in favor of the more OpenSIPS-friendly wolfSSL. All while still having the flexibility of switching between TLS implementations by simply loading a different OpenSIPS module.