A FFI crate, C++ and Golang wrappers to expose functionality from challenge-bypass-ristretto
The challenge-bypass-ristretto crate implements a form of blinded tokens using a VOPRF protocol in rust. This
crate exposes C FFI functions and is configured to produce a static library so that the functionality
can be used in other languages.
Currently there are bindings for C++ and Golang.
The FFI crate handles all allocation of blinded token structures, returning
a pointer to the underlying memory using Box::into_raw(Box::new(...)).
Correspondingly, there are destructor functions to free the memory for each
structure. The higher level bindings take care to ensure that these destructors
are automatically called, any new bindings added should take care to do the
same.
No direct introspection / modification of the Rust allocated objects from external bindings is allowed. The C header exposes only an opaque pointer to the Rust allocated objects.
Other than the destructor no FFI functions exposed mutate or take ownership of the passed structures.
Error handling at the C FFI layer is done via a thread local variable
LAST_ERROR which is set when an error
occurs. For most functions, a NULL return is indicative of an error. For
verification functions that would normally return a bool, an int is returned
instead. In these cases -1 indicates an error.
Convenience functions are included to handle encoding / decoding structures to / from base64.
UTF-8 strings are expected in all places strings are passed. These bindings do not attempt to address cross-platform string differences such as UTF-16 on windows.
Cbindgen was used to generate the C header file.
This crate instantiates challenge-bypass-ristretto with Sha512 as the hash and
rand::OsRng as the cryptographically secure random number generator.
The C++ bindings can optionally be built with exceptions turned off. This is
intended for interoperability with Chromium which by default does not use
exceptions. If exceptions are turned off, instead of being thrown exceptions
are assigned to a thread local variable. The exception_occured() function
must be called after every function call and if an error occurred the
get_last_exception() function can be called to retrieve and clear the exception.
Working on this repository requires having Rust, Go 1.11, g++, musl and valgrind to be installed. Alternatively - Rust, g++ / valgrind and Docker can be used as there is a Dockerfile for building and testing the Golang bindings.
There are end to end test binaries for the C++ and Golang bindings, when run under valgrind we can ensure memory is being properly freed.
make examples/cpp.out
valgrind --leak-check=yes --error-exitcode=1 ./examples/cpp.out
make examples/golang.dyn.out
valgrind --suppressions=.valgrind.supp --run-libc-freeres=no --leak-check=yes --undef-value-errors=no --error-exitcode=1 examples/golang.dyn.out
make go-docker-test
cbindgen -o src/lib.h