{"id":28462261,"url":"https://github.com/open-quantum-safe/liboqs-go","last_synced_at":"2025-07-03T16:31:10.684Z","repository":{"id":48799701,"uuid":"215630242","full_name":"open-quantum-safe/liboqs-go","owner":"open-quantum-safe","description":"Go bindings for liboqs","archived":false,"fork":false,"pushed_at":"2025-02-04T20:15:49.000Z","size":207,"stargazers_count":97,"open_issues_count":0,"forks_count":30,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-06-07T04:08:45.805Z","etag":null,"topics":["cryptography","go","golang","post-quantum-cryptography","quantum-computing"],"latest_commit_sha":null,"homepage":"https://openquantumsafe.org/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-quantum-safe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-16T19:41:08.000Z","updated_at":"2025-05-09T07:35:37.000Z","dependencies_parsed_at":"2023-02-09T12:46:29.279Z","dependency_job_id":"8ad21357-03eb-40f9-965e-47cb77849a42","html_url":"https://github.com/open-quantum-safe/liboqs-go","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/open-quantum-safe/liboqs-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-quantum-safe%2Fliboqs-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-quantum-safe%2Fliboqs-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-quantum-safe%2Fliboqs-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-quantum-safe%2Fliboqs-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-quantum-safe","download_url":"https://codeload.github.com/open-quantum-safe/liboqs-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-quantum-safe%2Fliboqs-go/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263360758,"owners_count":23454780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","go","golang","post-quantum-cryptography","quantum-computing"],"created_at":"2025-06-07T04:08:46.836Z","updated_at":"2025-07-03T16:31:10.672Z","avatar_url":"https://github.com/open-quantum-safe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# liboqs-go: Go bindings for liboqs\n\n[![GitHub actions](https://github.com/open-quantum-safe/liboqs-go/actions/workflows/go.yml/badge.svg)](https://github.com/open-quantum-safe/liboqs-go/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/open-quantum-safe/liboqs-go)](https://goreportcard.com/report/github.com/open-quantum-safe/liboqs-go)\n[![Documentation](https://godoc.org/github.com/open-quantum-safe/liboqs-go/oqs?status.svg)](https://pkg.go.dev/github.com/open-quantum-safe/liboqs-go/oqs)\n\n---\n\n## About\n\nThe **Open Quantum Safe (OQS) project** has the goal of developing and\nprototyping quantum-resistant cryptography.\n\n**liboqs-go** offers a Go wrapper for the\n[Open Quantum Safe](https://openquantumsafe.org/)\n[liboqs](https://github.com/open-quantum-safe/liboqs/) C library, which is a C\nlibrary for quantum-resistant cryptographic algorithms.\n\nliboqs-go is a Go package, hence in the following it is assumed that you have\naccess to a Go compliant environment. liboqs-go has been extensively tested on\nLinux, macOS and Windows platforms. Continuous integration is provided via\nGitHub actions.\n\nThe project contains the following files and directories:\n\n- **`oqs/oqs.go`: main package file for the wrapper**\n- `.config/liboqs-go.pc`: `pkg-config` configuration file needed by `cgo`\n- `.config-static/liboqs-go.pc`: `pkg-config` configuration file needed by\n  `cgo` when linking statically against liboqs\n- `examples`: usage examples, including a client/server KEM over TCP/IP\n- `oqstests`: unit tests\n\n---\n\n## Pre-requisites\n\n- [liboqs](https://github.com/open-quantum-safe/liboqs)\n- [git](https://git-scm.com/)\n- [CMake](https://cmake.org/)\n- C compiler, e.g., [gcc](https://gcc.gnu.org/)\n  , [clang](https://clang.llvm.org)\n  , [MSYS2](https://www.msys2.org/) etc.\n- [Go 1.21 or later](https://go.dev/)\n- `pkg-config` (use `sudo apt-get install pkg-config` to install on\n  Ubuntu/Debian-based Linux platforms or install it\n  via a third-party compiler such as [MSYS2](https://www.msys2.org/) on\n  Windows)\n- If using Windows, you need a C compiler supported by `cgo` added to your\n  `PATH` environment variable; currently, the best supported ones are provided\n  by [MSYS2](https://www.msys2.org/)\n  and [`tdm-gcc`](https://jmeubank.github.io/tdm-gcc/);\n  [Cygwin](https://www.cygwin.com/) is **not yet supported**\n  by `cgo`; we recommend using MSYS2 since it also contains `pkg-config` as a\n  package; to install `gcc` and `pkg-config` under MSYS2, please execute in a\n  MSYS2 terminal window\n  `pacman -S mingw64/mingw-w64-x86_64-gcc mingw64/mingw-w64-x86_64-pkg-config`,\n  then add the corresponding installation location (e.g,\n  `C:\\msys64\\mingw64\\bin`) to your `PATH` environment variable by executing\n  `set PATH=%PATH%;C:\\msys64\\mingw64\\bin`.\n\n  **Very important:** make sure that\n  the `PATH` entry to the `gcc` and `pkg-config` provided by `MSYS2`comes\n  **before** any other (if any) `gcc` and `pkg-config` executables you may have\n  installed (e.g. such as the ones provided\n  by [Cygwin](https://www.cygwin.com)). To verify, type into a Command Prompt\n  `gcc --version`, and you should get an output such as\n\n  \u003e gcc (Rev3, Built by MSYS2 project) 9.1.0\n\n---\n\n## Functional restrictions\n\nNo known issues as of liboqs-0.12.0\n\n---\n\n## Installation\n\nIn the rest of this document, we assume you execute commands from inside the\n`$HOME` directory on UNIX-like systems, or from inside the `%USERPROFILE%` on\nWindows.\n\n### Configure, build and install liboqs\n\nExecute in a Terminal/Console/Administrator Command Prompt\n\n```shell\ngit clone --depth=1 https://github.com/open-quantum-safe/liboqs\ncmake -S liboqs -B liboqs/build -DBUILD_SHARED_LIBS=ON\ncmake --build liboqs/build --parallel 8\ncmake --build liboqs/build --target install\n```\n\nThe last line may require prefixing it by `sudo` on UNIX-like systems.\nChange `--parallel 8` to match the number of available cores on your system.\n\nOn UNIX-like platforms, you may need to set\nthe `LD_LIBRARY_PATH` (`DYLD_LIBRARY_PATH` on macOS) environment variable to\npoint to the path to liboqs' library directory, e.g.,\n\n```shell\nexport LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib\n```\n\nOn Windows platforms, **you must ensure** that the liboqs shared\nlibrary `oqs.dll` is visible system-wide, and that the following environment\nvariable are being set. Use the \"Edit the system environment variables\" Control\nPanel tool or execute in a Command Prompt, e.g.,\n\n```shell\nset PATH=%PATH%;C:\\Program Files (x86)\\liboqs\\bin\n```\n\nYou can change liboqs' installation directory by configuring the build to use\nan alternative path, e.g., `C:\\liboqs`, by replacing the first CMake line above\nby\n\n```shell\ncmake -S liboqs -B liboqs/build -DCMAKE_INSTALL_PREFIX=\"C:\\liboqs\" -DBUILD_SHARED_LIBS=ON\n```\n\n### Configure and install the wrapper\n\nExecute in a Terminal/Console/Administrator Command Prompt\n\n```shell\ngit clone --depth=1 https://github.com/open-quantum-safe/liboqs-go\n```\n\nNext, you must modify the following lines in\n[`$HOME/liboqs-go/.config/liboqs-go.pc`](https://github.com/open-quantum-safe/liboqs-go/tree/main/.config/liboqs-go.pc)\n\n    LIBOQS_INCLUDE_DIR=/usr/local/include\n    LIBOQS_LIB_DIR=/usr/local/lib\n\nso they correspond to your liboqs include/lib installation directories. On\nWindows, **using forward slashes `/` and not\nback-slashes**, e.g.,\n\n    LIBOQS_INCLUDE_DIR=C:/Program Files (x86)/liboqs/bin\n    LIBOQS_LIB_DIR=C:/Program Files (x86)/liboqs/lib\n\nFinally, you must add/append the `$HOME/liboqs-go/.config` directory to the\n`PKG_CONFIG_PATH` environment variable, i.e., on UNIX-like systems execute in a\nterminal\n\n```shell\nexport PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$HOME/liboqs-go/.config\n```\n\nor, on Windows platforms, use the \"Edit the system environment variables\"\nControl Panel tool or execute in a Command Prompt\n\n```shell\nset PKG_CONFIG_PATH=%PKG_CONFIG_PATH%;$HOME/liboqs-go/.config\n```\n\n### Linking statically against liboqs - excluding macOS/OS X platforms\n\nReplace `.config` with `.config-static` when setting the `PKG_CONFIG_PATH`\nenvironment variable above. This assumes that you previously compiled and\ninstalled the static version of liboqs, i.e., you did not pass\n`-DBUILD_SHARED_LIBS=ON` to CMake when configuring liboqs above.\n\nNote that `.config-static/liboqs-go.pc` links statically against OpenSSL as\nwell. In case you don't have OpenSSL installed, remove the `-lcrypto` from the\nlast line of `.config-static/liboqs-go.pc`, and make sure you compiled liboqs\nwithout OpenSSL, i.e., pass the `-DOQS_USE_OPENSSL=OFF` CMake flag when\nconfiguring liboqs, otherwise you will get linker errors.\n\n**Important:** Ensure that you run `go clean -cache` before building or\nrunning, so `pkg-config` refreshes its cache.\n\n### Linking statically against liboqs - macOS/OS X platforms\n\nThe macOS/OS X linker does not allow choosing static vs dynamic linking when\nboth static and dynamic versions of a library are installed. In this case, the\ndynamic version will always be chosen by the linker. Hence, to link statically\nagains liboqs on macOS/OS X, make sure you have not installed the dynamic\nversion of liboqs anywhere on your system, and use the `.config` (not\n`.config-static`) when setting the `PKG_CONFIG_PATH` environment variable.\n\n**Important:** Ensure that you run `go clean -cache` before building or\nrunning.\n\n### Run the examples\n\nFrom inside the `liboqs-go` directory, execute\n\n```shell\ngo run examples/kem/kem.go\ngo run examples/sig/sig.go\ngo run examples/rand/rand.go\n```\n\n### Build executables\n\nReplace `go run` by `go build`, e.g., `go build examples/kem/kem.go`.\n\n**Note** go binaries produced on macOS arm64 are not code-signed properly. See\n[https://github.com/golang/go/issues/63997](https://github.com/golang/go/issues/63997).\n\nTo fix, run\n\n```shell\ncodesign -f -s - path/to/executable\n```\n\n### Run the unit tests\n\nFrom inside the `liboqs-go` directory, execute\n\n```shell\ncd liboqs-go\ngo test -v ./oqstests\n```\n\nOn Windows, you may need to replace forward-slashes `/` by back-slashes `\\`.\n\n---\n\n## Usage in standalone applications\n\nliboqs-go can be imported into Go programs with\n\n```go\nimport (\n    \"github.com/open-quantum-safe/liboqs-go/oqs\"\n)\n```\n\nThe examples in the\n[`examples`](https://github.com/open-quantum-safe/liboqs-go/tree/main/examples)\ndirectory are self-explanatory and provide more details about the wrapper's\nAPI.\n\n---\n\n## Documentation\n\nThe `liboqs-go` wrapper is fully documented using the Go standard documentation\nconventions. For example, to read the full documentation about the\n`oqs.Signature.Verify` method, execute from inside the `liboqs-go` directory\n\n```shell\ngo doc liboqs-go/oqs.Signature.Verify\n```\n\nFor the RNG-related function, execute e.g.\n\n```shell\ngo doc liboqs-go/oqs/rand.RandomBytes\n```\n\nFor automatically-generated documentation in HTML format,\nclick [here](https://pkg.go.dev/github.com/open-quantum-safe/liboqs-go/oqs).\n\nFor the RNG-related documentation, click\n[here](https://pkg.go.dev/github.com/open-quantum-safe/liboqs-go/oqs/rand).\n\n---\n\n## Docker\n\nA self-explanatory minimalistic Docker file is provided in\n[`Dockerfile`](https://github.com/open-quantum-safe/liboqs-go/tree/main/Dockerfile).\n\nBuild the image by executing\n\n```shell\ndocker build -t oqs-go .\n```\n\nRun, e.g., the key encapsulation example by executing\n\n```shell\ndocker run -it oqs-go sh -c \"cd liboqs-go \u0026\u0026 go run examples/kem/kem.go\"\n```\n\nOr, run the unit tests with\n\n```shell\ndocker run -it oqs-go sh -c \"cd liboqs-go \u0026\u0026 go test -v ./oqstests\"\n```\n\nIn case you want to use the Docker container as a development environment,\nmount your current project in the Docker container with\n\n```shell\ndocker run --rm -it --workdir=/app -v ${PWD}:/app oqs-go /bin/bash\n```\n\n---\n\n## Limitations and security\n\nliboqs is designed for prototyping and evaluating quantum-resistant\ncryptography. Security of proposed quantum-resistant algorithms may rapidly\nchange as research advances, and may ultimately be completely insecure against\neither classical or quantum computers.\n\nWe believe that the NIST Post-Quantum Cryptography standardization project is\ncurrently the best avenue to identifying potentially quantum-resistant\nalgorithms. liboqs does not intend to \"pick winners\", and we strongly recommend\nthat applications and protocols rely on the outcomes of the NIST\nstandardization project when deploying post-quantum cryptography.\n\nWe acknowledge that some parties may want to begin deploying post-quantum\ncryptography prior to the conclusion of the NIST standardization project. We\nstrongly recommend that any attempts to do make use of so-called\n**hybrid cryptography**, in which post-quantum public-key algorithms are used\nalongside traditional public key algorithms (like RSA or elliptic curves) so\nthat the solution is at least no less secure than existing traditional\ncryptography.\n\nJust like liboqs, liboqs-go is provided \"as is\", without warranty of any kind.\nSee [LICENSE](https://github.com/open-quantum-safe/liboqs-go/blob/main/LICENSE)\nfor the full disclaimer.\n\n---\n\n## License\n\nliboqs-go is licensed under the MIT License;\nsee [LICENSE](https://github.com/open-quantum-safe/liboqs-go/blob/main/LICENSE)\nfor details.\n\n---\n\n## Team\n\nThe Open Quantum Safe project is led by\n[Douglas Stebila](https://www.douglas.stebila.ca/research/) and\n[Michele Mosca](http://faculty.iqc.uwaterloo.ca/mmosca/) at the University of\nWaterloo.\n\nliboqs-go was developed by [Vlad Gheorghiu](https://vsoftco.github.io) at\n[softwareQ Inc.](https://www.softwareq.ca) and at the University of Waterloo.\n\n---\n\n## Support\n\nFinancial support for the development of Open Quantum Safe has been provided by\nAmazon Web Services and the Canadian Centre for Cyber Security.\n\nWe'd like to make a special acknowledgement to the companies who have dedicated\nprogrammer time to contribute source code to OQS, including Amazon Web\nServices, evolutionQ, softwareQ, and Microsoft Research.\n\nResearch projects which developed specific components of OQS have been\nsupported by various research grants, including funding from the Natural\nSciences and Engineering Research Council of Canada (NSERC); see the source\npapers for funding acknowledgments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-quantum-safe%2Fliboqs-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-quantum-safe%2Fliboqs-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-quantum-safe%2Fliboqs-go/lists"}