Themis by Cossack Labs v0.12.1 Release Notes

Release Date: 2019-09-26 // about 2 months ago

Previous changes from v0.12.0

  • TL;DR:

    • βž• Added WasmThemis to support WebAssembly (works with Electron and Node.js);
    • βž• added experimental support for Windows (using MSYS2 compiler and NSIS installer);
    • βž• added support of Go Modules;
    • βž• added package for ThemisPP;
    • βž• added support for Node.js v12 LTS (in addition to v10 and v8) in jsThemis;
    • βž• added extra safety checks and fixes for tricky bugs.

    πŸ’₯ Breaking changes:

    • 🐧 Linux: when building from sources, the default installation path of Themis Core library has been changed from /usr to /usr/local. If you’re affected, read the instructions on how to make a clean upgrade below.
    • Go: some of GoThemis APIs have been renamed to comply with Go naming convention (old API are marked as deprecated and will be removed in the next release). If you’re using Go – please switch to new functions.
    • πŸ’Ž Ruby: deprecated rubythemis gem has been completely removed in favour of rbthemis.


    • Core

      • Soter (low-level security core used by Themis)

      Improved security and code quality, implemented better handling of secrets and memory management. These changes decrease the chance of potential memory leaks.

      • Introduced new internal function: soter_wipe(). It can be used to securely wipe sensitive data from memory after it's no longer needed. All Themis cryptosystems now use this new API (#488).
      • Improved usage and error handling of OpenSSL/BoringSSL PRNGs. Thank you, @veorq for bringing up this issue (#485).
      • Improved memory safety and fixed potential corner-case issues in OpenSSL/BoringSSL usage. Thanks, @outspace for identifying these issues (#501, #524, #525, #535).
      • Key generation
      • Improved key validity checks across all Themis cryptosystems. Now it’s harder to use wrong keys or misuse them (#486).
      • Improved error handling for EC key generator that could produce an invalid public key without returning an error. Thanks, @vixentael for finding this issue (#500).
      • Secure Cell
      • Improved handling of edge cases with large data buffers (#496, #497).
      • Improved performance of Secure Cell's encryption/decryption (#496).
      • Library ABI
      • Themis shared libraries now have a formal ABI version. This ensures that no compatibility issues arise if we ever need to introduce breaking changes in the ABI (#454).
      • Removed private symbols from public export lists. Themis has been accidentally exporting various private utility functions. Private functions not intended for public use are now hidden (#458, #472).
      • Installation & packaging
      • Themis now installs to /usr/local by default when building from source on Linux (#448).

      This may be a breaking change if your system has non-standard precedence rules. If you install Themis from source code directly, please do a clean upgrade the following way:

        make uninstall PREFIX=/usr
        make install   PREFIX=/usr/local

      Please consider using binary repositories to install Themis. If your system or package manager is not supported yet, please let us know via

      • Themis packages now support multiarch installations (#512).

      Multiarch enables parallel installation of 32-bit and 64-bit versions of the library. This is particularly important on CentOS where some tools like pkg-config would fail to locate Themis due to non-standard installation path.

      • Updated Makefile to support a number of standard GNU variables like libdir (#453, #455).
      • Improved accuracy of package dependencies to make sure you don't have to install anything manually after installing Themis from package repositories (#446).
      • NSIS installer is now available for Windows. To build NSIS installer, use make nsis_installer command in MSYS2 environment. You can read more about MSYS2 target here (#474).
      • Dependency updates
      • Embedded BoringSSL submodule has been updated to the latest upstream version (#528).
      • Only the necessary parts of embedded BoringSSL are now built, leading to 2x build speedup (#447).
      • Other changes
      • Miscellaneous improvements and cleanups in the Makefile (#450, #451, #452, #459, #523, #527).
      • Core libraries are now linked dynamically to test binaries (#460).
    • Android

      • Embedded BoringSSL submodule has been updated to the latest upstream version (#528).
      • Only the necessary parts of embedded BoringSSL are now built, leading to 2x build speedup (#447).
    • C++


      • libthemispp-dev for Debian and Ubuntu,
      • libthemispp-devel for CentOS.
    • Go

      • Breaking changes
      • Some APIs have been renamed to conform with the Go naming conventions (#424).

      The old names are now deprecated and scheduled for removal in the next release. Please migrate to using the new names when you upgrade.

      | Old API | New API | | -------------------------------------- | -------------------------- | | cell.CELL_MODE_SEAL | cell.ModeSeal | | compare.COMPARE_MATCH | compare.Match | | keys.KEYTYPE_EC | keys.TypeEC | | session.STATE_ESTABLISHED | session.StateEstablished | | (*session.SecureSession) GetRemoteId | GetRemoteID |

      • GoThemis is now compatible with Go 1.11 modules starting with this release. For example, you are now able to pin a specific version of GoThemis in your projects (#505).
    • 🍎 iOS, macOS

      • Example code and projects for Objective-C and Swift are now up-to-date, cleaned up, and modernised (#463, #467)
      • OpenSSL version is pinned to for Carthage package and to to CocoaPods package as a workaround for a compilation issue with the latest versions (#539, #484).
    • Java

      • JNI wrapper for desktop Java does not require a separate installation of Themis Core from now on (#450).
    • Node.js

      • JsThemis now supports latest Node.js v12 LTS (in addition to v10 and v8) (#499, #502).
      • JsThemis can now be used on Windows provided that Themis Core is installed to C:\Program Files\Themis (#475).
      • Improved error reporting when keys are misused with Secure Message objects (#465).
    • PHP

      • Updated PHP installer to use the latest Composer version (#519).
    • πŸ’Ž Ruby

      • Breaking changes
      • rubythemis gem has been completely removed after being deprecated in Themis 0.11. Please use require 'rbthemis' in your projects (#508).
    • Rust

      • Minor internal code style modernizations (#466).
    • WebAssembly

      WasmThemis supports the full functionality of other Themis wrappers: Secure Cell, Secure Message, Secure Session, and Secure Comparator. WasmThemis package is available via npm as wasm-themis, sample code can be found in docs/examples/js, and the How-To guide is available on the documentation server (#457, #461, #462, #473, #482, #489, #490, #491, #492,#494, #495, #498, #507, #513).

      • WasmThemis is tested with current Node.js LTS versions, popular Web browsers, and Electron framework. It is also tested for compatibility with other Themis wrappers (#509, #510, #511).
    • 🏁 Windows

      • It is now possible to compile Themis Core for Windows using MSYS2 environment. See the instructions here (#469).
      • NSIS installer is now provided for the distribution of Themis on Windows. It's compatible with the new MSYS2 builds (#474).
      • It is now possible to compile JsThemis on Windows, given that Themis Core is installed (#475).
      • Miscellaneous compatibility fixes should make it possible to compile Themis Core with Microsoft Visual Studio. This platform does not have full official support yet, though (#470, #471).

    πŸ“„ Docs:

    • πŸ—„ Themis GitHub Wiki is being deprecated. Please find the latest documentation for Themis on Cossack Labs Documentation Server. If you're used to using the Themis Wiki or have bookmarked a few pages for further use, don't worry - its pages and table of contents stay where they were, but each will now link to its corresponding Cossack Labs Documentation Server counterpart.

    • Code of Conduct has been introduced to make sure that Themis project has a welcoming environment (#518).

    • πŸ‘Œ Improved and updated installation guides for numerous languages and platforms.


    • πŸ†• New Makefile targets and use cases:

      • emmake make all builds WasmThemis in Emscripten environment (#475);
      • make all can be run in MSYS2 environment on Windows now (#469);
      • make nsis_installer builds NSIS installer for Windows binaries (#474);
      • make deb and make rpm now build ThemisPP packages, too (#506);
      • NO_NIST_STS environment variable can be used to disable the long-running NIST statistical test suite when doing make test (#456).
    • βœ‚ Removed Makefile targets:

      • Deprecated rubythemis targets have been completely removed. Use make rbthemis_install to install RubyThemis instead (#508).
    • ⚑️ Multiple updates in the way Themis is installed and packaged. The most significant are switch to /usr/local for installation from source code and added support for multiarch installation packages (Read more).

    • βœ… JsThemis and WasmThemis are now tested on all current LTS versions of Node.js (#502, #510).

    • βœ… Integration tests are getting stronger with WebAssembly platform being added to the suite (#511).

    • βœ… CI servers are now using the latest RVM for testing RubyThemis (#503, #504).