liboqs-go offers a Go wrapper for the master branch of Open Quantum Safe liboqs C library, which is a C library for quantum-resistant cryptographic algorithms.
The wrapper is written in Go, hence in the following it is assumed that you have access to a Go compliant environment. liboqs-go has been extensively tested on Linux and macOS systems. Continuous integration is provided via Travis CI.
liboqs-go depends on the liboqs C library; liboqs master branch must first be compiled as a UNIX/Linux/macOS library, see the building instructions below.
In addition, we assume you have access to:
- a POSIX compliant system (UNIX/Linux/macOS). For now,
cgois not fully supported under Windows due to various ABI issues; we will add Windows support when it becomes available. - Go version 1.7 or later (version 1.11 or later for Go modules support)
- a standard C compliant compiler (
gcc/clangetc.) pkg-config(usesudo apt-get install pkg-configto install on Ubuntu/Debian-based Linux platforms)
liboqs-go is a Go package. The project contains the following files and directories:
oqs/oqs.go: main package file for the wrapper.config/liboqs.pc:pkg-configconfiguration file needed bycgoexamples/kem/kem.go: key encapsulation exampleexamples/rand/rand.go: RNG exampleexamples/sig/sig.go: signature exampleoqstests: unit tests
The examples in the examples directory are self-explanatory and provide more details about the wrapper's API.
First, you must build the master branch of liboqs according to the liboqs building instructions, followed (optionally) by a sudo make install to ensure that the compiled library is system-wide visible (by default it installs under /usr/local/include and /usr/local/lib on Linux/macOS).
If running/building on Linux, you may need to set the LD_LIBRARY_PATH environment variable to point to the path
to liboqs' library directory, e.g.
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
assuming liboqs.so.* were installed in /usr/local/lib (true if you ran sudo make install after building liboqs).
Download/clone the liboqs-go wrapper repository in the directory of your choice, e.g. $HOME, by typing in a terminal/console
cd $HOME && git clone https://github.com/open-quantum-safe/liboqs-go
Next, you must modify the following lines in $HOME/liboqs-go/.config/liboqs.pc
LIBOQS_INCLUDE_DIR=/usr/local/include
LIBOQS_LIB_DIR=/usr/local/lib
so they correspond to your C liboqs include/lib installation directories.
Finally, you must add/append the $HOME/liboqs-go/.config directory to the PKG_CONFIG_PATH environment variable, i.e.
export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$HOME/liboqs-go/.config
Once you have configured your system as directed above, simply import "github.com/open-quantum-safe/liboqs-go/oqs" in the Go application of your choice, initialize the application module with go mod init <module_name>, and finally run it with go run <module_name> or build it with go build <module_name>.
To run the examples from the terminal/console, type e.g.
go run $HOME/liboqs-go/examples/kem/kem.go
Replace go run with go build if you intend to build the corresponding executable; in this case it will be built in the directory from which you ran the go build command.
To run the unit tests from the terminal/console, type
go test -v $HOME/liboqs-go/oqstests/*
To build the unit test executable from the terminal/console, type
go test -c $HOME/liboqs-go/oqstests/*
This will build the oqstests.test executable in the directory you ran the above command from.
Install the latest version of the liboqs-go wrapper by typing
go get github.com/open-quantum-safe/liboqs-go/oqs
in a terminal/console. This will install the wrapper in the first directory set by your $GOPATH environment variable. In my case $GOPATH is set to $HOME/go, and the Go package manager installs the wrapper in $HOME/go/src/github.com/open-quantum-safe/liboqs-go. To update a previously installed Go wrapper, type
go get -u github.com/open-quantum-safe/liboqs-go/oqs
in a terminal/console.
To simplify the instructions to follow, export the path to the wrapper in the LIBOQSGO_INSTALL_PATH environment variable by typing in a terminal/console
export LIBOQSGO_INSTALL_PATH=/your/path/to/liboqs-go
In my case LIBOQSGO_INSTALL_PATH is set to $HOME/go/src/github.com/open-quantum-safe/liboqs-go.
Next, you must modify the following lines in $LIBOQSGO_INSTALL_PATH/.config/liboqs.pc
LIBOQS_INCLUDE_DIR=/usr/local/include
LIBOQS_LIB_DIR=/usr/local/lib
so they correspond to your C liboqs include/lib installation directories.
Finally, you must add/append the $LIBOQSGO_INSTALL_PATH/.config directory to the PKG_CONFIG_PATH environment variable, i.e.
export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$LIBOQSGO_INSTALL_PATH/.config
Once you have configured your system as directed above, simply import "github.com/open-quantum-safe/liboqs-go/oqs" in the Go application of your choice and run it with go run <application_name.go> or build it with go build <applicaiton_name.go>.
To run the examples from the terminal/console, type e.g.
go run $LIBOQSGO_INSTALL_PATH/examples/kem/kem.go
Replace go run with go build if you intend to build the corresponding executable; in this case it will be built in the directory from which you ran the go build command.
To run the unit tests from the terminal/console, type
go test -v github.com/open-quantum-safe/liboqs-go/oqstests
To build the unit test executable from the terminal/console, type (from the directory in which you want to build the executable)
go test -c $LIBOQSGO_INSTALL_PATH/oqstests/*
This will build the oqstests.test executable in the directory of your choice above.
The liboqs-go wrapper is fully documented using the Go standard documentation conventions. For example, to read the full documentation about the oqs.Signature.Verify method, type in a terminal/console
go doc $HOME/liboqs-go/oqs.Signature.Verify
if using Go modules, or
go doc github.com/open-quantum-safe/liboqs-go/oqs.Signature.Verify
if not using Go modules.
For the RNG-related function, type e.g.
go doc $HOME/liboqs-go/oqs/rand.RandomBytes
if using Go modules, or
go doc github.com/open-quantum-safe/liboqs-go/oqs/rand.RandomBytes
if not using Go modules.
For GoDoc automatically-generated documentation in HTML format, click here.
For the RNG-related documentation, click here.
liboqs is designed for prototyping and evaluating quantum-resistant cryptography. Security of proposed quantum-resistant algorithms may rapidly change as research advances, and may ultimately be completely insecure against either classical or quantum computers.
We believe that the NIST Post-Quantum Cryptography standardization project is currently the best avenue to identifying potentially quantum-resistant algorithms. liboqs does not intend to "pick winners", and we strongly recommend that applications and protocols rely on the outcomes of the NIST standardization project when deploying post-quantum cryptography.
We acknowledge that some parties may want to begin deploying post-quantum cryptography prior to the conclusion of the NIST standardization project. We strongly recommend that any attempts to do make use of so-called hybrid cryptography, in which post-quantum public-key algorithms are used alongside traditional public key algorithms (like RSA or elliptic curves) so that the solution is at least no less secure than existing traditional cryptography.
Just like liboqs, liboqs-go is provided "as is", without warranty of any kind. See LICENSE for the full disclaimer.
liboqs-go is licensed under the MIT License; see LICENSE for details.
The Open Quantum Safe project is led by Douglas Stebila and Michele Mosca at the University of Waterloo.
liboqs-go was developed by Vlad Gheorghiu at evolutionQ and University of Waterloo.
Financial support for the development of Open Quantum Safe has been provided by Amazon Web Services and the Tutte Institute for Mathematics and Computing.
We'd like to make a special acknowledgement to the companies who have dedicated programmer time to contribute source code to OQS, including Amazon Web Services, evolutionQ, and Microsoft Research.
Research projects which developed specific components of OQS have been supported by various research grants, including funding from the Natural Sciences and Engineering Research Council of Canada (NSERC); see the source papers for funding acknowledgments.