From libolm to vodozemac

Updated 281 Days AgoPublic

Actions

This is currently a work-in-progress.

This document aims to provide you an overview of how to port your Matrix application from libolm to vodozemac.

Definitions

We will be using the following definitions in the document:

• The E2EE library means either libolm or vodozemac.
• The application means any code that uses the E2EE library, which may be another library.
• The user means anyone who interacts with the application in any way other than writing code.

Differences

vodozemac-bindings has a C++ public API, as opposed to the C API of libolm. There are a couple of differences in the API:

• Memory allocations are managed by vodozemac, not by the application.
• You can no longer pass random data into the E2EE library, as vodozemac embeds the rust's random generator in it. This renders the "test vectors" in the spec effectively useless.
• You have to have exceptions support in your compiler. This is a limitation of cxx.rs , which is used to generate the bindings. See https://github.com/dtolnay/cxx/issues/1052 for more information. This might change later.
• Pickle keys are now 32 bytes, instead of any string.

Overview of vodozemac-bindings

Everything is in the vodozemac namespace. A function may throw an exception if it returns anything other than Result<T> in rust code. In the generated C++ header, it corresponds to the noexcept specifier. If a function is declared noexcept, it does not throw an exception; otherwise, it may.

You can use the following code to check for exceptions:

template<class Func>
auto checkVodozemacError(Func &&func) -> std::optional<std::invoke_result_t<Func>>
{
    try {
        return std::forward<Func>(func)();
    } catch (const std::exception &e) {
        return std::nullopt;
    }
}

Converting from libolm

vodozemac-bindings provides function to convert data from libolm pickle format. They are called *_from_libolm_pickle and takes two arguments: the first one is the pickle data, as rust::Str, the other being the pickle key, as rust::Slice<const unsigned char>. rust::Str can be directly converted from a std::string, while rust::Slice needs some work, for example:

auto session = checkVodozemacError([&]() {
    
});

Sample code

The commits referenced in https://iron.lily-is.land/T125 provides a sample code to migrate from libolm to vodozemac.