Installing WasmThemis #

WasmThemis is available on npm and can be installed with the usual npm install. Usually you want to install the stable package to benefit from automatic dependency management and security updates. However, you can also build and install the latest WasmThemis from the source code.

Installing stable version with npm #

Just run the following line to install WasmThemis for your project:

npm install wasm-themis

Once WasmThemis is installed, you can try out code examples.

Installing WasmThemis to ReactJS application #

To use WasmThemis with ReactJS application read the tutorial.

Deploying apps with WasmThemis #

WasmThemis is distributed as Node.js package which is compatible with many JavaScript module bundlers like Browserify, webpack, and Electron framework packager.

However, in addition to JavaScript code, WasmThemis also includes the compiled WebAssembly bytecode. The bytecode is located in node_modules/wasm-themis/src/libthemis.wasm file, which will be loaded by the browser separately.

Copy libthemis.wasm #

Make sure that libthemis.wasm is placed next to the produced JavaScript bundle by copying it from node_modules/wasm-themis/src/libthemis.wasm directory when building your application.

Bundler specifics #

If you are using Webpack, you may also need to add the following declaration to your webpack.config.js:

// WasmThemis code is generated by Emscripten to be universal.
// It includes some references to Node.js modules for Node.js support,
// but they are not accessible (and not used) in web browsers.
resolve: {
    fallback: {
        crypto: false,
        fs:     false,
        http:   false,
        https:  false,
        net:    false,
        path:   false,
        stream: false,
        tls:    false,
        util:   false,
        url:    false,
        zlib:   false,
    }
},

Or if you are using webpack 4:

node: {
    crypto: 'empty',
    fs:     'empty',
    http:   'empty',
    https:  'empty',
    net:    'empty',
    path:   'empty',
    stream: 'empty',
    tls:    'empty',
    util:   'empty',
    url:    'empty',
    zlib:   'empty',
}

Web server MIME types #

Web servers should use MIME type application/wasm for serving WebAssembly files. This enables more efficient streaming compilation process with shorter startup times. The servers are usually pre-configured to use proper MIME types, but if you see the following warning message:

wasm streaming compile failed: TypeError: Failed to execute 'compile' on
'WebAssembly': Incorrect response MIME type. Expected 'application/wasm'.

then you might need to check the web server configuration.

Nginx MIME types are configured via the /etc/nginx/mime.types configuration file. Apache and other servers typically use the /etc/mime.types configuration file. Reload configuration or restart the server for the change to take effect.

Building latest version from source #

If the stable package version does not suit your needs, you can manually build and install the latest version of Themis from source code.

Note: WasmThemis is compiled with Emscripten toolchain. Unfortunately, Emscripten does not support 32-bit architectures and some older systems such as CentOS 7.

You will not be able to develop and build WasmThemis on those older systems. However, the resulting WebAssembly binaries are portable and can be installed and used anywhere.

WasmThemis uses BoringSSL as its cryptographic backend. BoringSSL is included as a submodule in the Themis repository, but you will need to install its build dependencies as well.

Checkout Themis repository.

git clone https://github.com/cossacklabs/themis.git

Install Emscripten toolchain as described in the documentation here.

If you haven’t used Emscripten before, take a look at this tutorial before proceeding.
Activate a suitable toolchain version.

Emscripten installs the latest “upstream” flavor by default so you need to explicitly install and activate a suitable version (run this from Emscripten SDK directory):
```
./emsdk install  3.0.0
./emsdk activate 3.0.0
source ./emsdk_env.sh
```
The current version is available in WasmThemis repository.

Read the Emscripten documentation to learn more about managing toolchain versions.
Make sure that BoringSSL submodule is checked out:
```
git submodule update --init
```
Make sure that BoringSSL build dependencies are installed.

You will typically need to install Go, CMake, GNU Make.
Build and package WasmThemis by running the following in the root of Themis repository:
```
emmake make wasmthemis
```
Be aware that build may fail if non-WASM Themis was previously build in this same directory. In that case, run make clean before building WasmThemis.

The resulting package will be placed into build/wasm-themis.tgz in Themis source tree.

To run the test suite for WasmThemis wrapper (and a more extensive one for the Themis Core library), run the following commands:

emmake make test_wasm
emmake make test