GDSodium

GDSodium is a set of libsodium bindings for GDScript. GDSodium is provided as a GDExtension or module targeting Godot 4.2 and above.

Usage guide

GDSodium is currently not stable. You shouldn't use it for anything important yet.

However, once GDSodium is stable head over to releases and grab the newest gdsodium.zip. Unzip into your project and you should be good to go. This adds the GDSodium extension to your project, which will be automatically loaded and included in exports.

If you plan on exporting to web or otherwise want to use GDSodium as a module instead, you can add GDSodium to your custom Godot's modules directory. It's recommended that you add GDSodium as a submodule pegged to a specific release. Once added, GDSodium will automatically compile when you compile the engine.

When exporting using a template which has the module built in (like for web) from a Godot project which has the extension as well Godot will (and should) give an error that it cannot find a suitable library file for the platform. The error shouldn't prevent the export from working. If no error is returned then the extension has been included with the export. In the case of web this will usually result in some platforms failing to run the export.

By using GDSodium you must agree to some licenses. GDSodium itself is public domain, but libsodium and GDExtension both have credit requirements. You must include the licenses for godot-cpp and libsodium in your final project. If your project is graphical-only, you should have some menu option which shows a list of licenses, including the licenses for godot-cpp and libsodium.

GDSodium is mainly a collection of static methods which closely follow libsodium's API. The exceptions are the piecewise utilities (generic hash, sign, stream, box, etc.) which are objects that are instantiated.

All instantiable objects have the following methods:

• new() allocates the object, returning a new one
• start(args, ...) initializes the object with the given args
• create(args, ...) allocates and initializes the object

Once created, an object can be start()ed many times, each time resetting the internal state.

Some objects have more complex APIs, like HKDF. Additionally, most utilities which use keys will have generate_*() methods, which will often accept an optional seed.

Supported architectures

• Windows: x86_32, x86_64
• Linux: x86_32, x86_64, arm64, ppc32, ppc64
• Android: arm32 (armv7), arm64 (armv8/aarch64), x86_32, x86_64
• Web (use as a module is preferred)

Other architectures and platforms should be supported, but they either haven't or can't be added to the Docker buildsystem so they are not included in releases.

On Linux, arm32 and riscv64 compilation fails with Godot, so those platforms will not be supported until that issue is fixed. It's a threading-related issue.

Further, only x86_64 and arm64 Linux, x86_64 Windows, x86_64 and arm64 Android, and web are tested.

Testing

GDSodium uses [GUT] for unit testing. Almost all tests are parameterized, running on 10 static cases and 10 runtime cases. Before running the tests you need to run SCons. See the compiling section for more info. To generate the static test cases use ./run_tests.sh generate. To run the tests use ./run_tests.sh.

There is also support for coverage testing. To use it compile with scons coverage=yes then run tests. gcovr and similar can be used, or the convenience script coverage.sh can be used to generate summaries with per-file coverage information.

Compiling

Docker

If you have Docker:

$ git clone --recurse-submodules https://github.com/stkptr/gdsodium
$ cd gdsodium/docker-build
$ ./build.sh

This compiles for all supported architectures, except macOS and iOS. The Docker buildsystem is structured with an x86_64host in mind. Expect a build time of about 2 to 3 hours on an 8 core machine.

The buildsystem has the basis for macOS and iOS development in place, but will not produce binaries at this point. Further, the system in place so far needs insecure mode enabled. See here for more info.

SCons

Debian

• apt install git python3 pipx build-essential
• pipx install scons

Windows (MinGW)

MSVC is currently not supported.

• choco see https://chocolatey.org/install
• choco install git python3 zig mingw
• pip install scons

MacOS

Refer to the Godot documentation.

Compilation procedure

$ git clone --recurse-submodules https://github.com/stkptr/gdsodium
$ cd gdsodium
$ scons

If you're using Windows, or would like to build libsodium with Zig for any other reason, use scons sodium_use_zig=yes instead of just scons.