Kyber is a Go crypto toolbox for protocols more interesting than plain signing

One abstraction over groups, hashes, encodings and XOFs

Kyber is described as a toolbox of advanced cryptographic primitives for Go, targeting applications like Cothority that need more than straightforward signing and encryption. The package layout shows what that means in practice. The top level holds group.go, hash.go, random.go, xof.go and encoding.go, with subpackages for group, suites, encrypt, sign, share, shuffle, proof, pairing, xof, util, internal and compatible, plus a benchmark directory and a docs directory. The group package is the core idea, since it defines an interface for working with a group of a given order without caring whether the group is an elliptic curve, a finite field or a set of integers, and the suites package supplies concrete implementations of that interface. That is what lets the same protocol code run over Ed25519 or over a pairing-friendly curve. The compatible directory signals the other half of the design, code that keeps older or alternative implementations able to interoperate.

Suites bundle the algorithms so callers pick one name

The getting started example shows the level of abstraction a caller actually works at. Everything starts with a suite, and the example finds one by name:

package main

import (
    "fmt"
    "go.dedis.ch/kyber/v4/suites"
)

func main() {
    s := suites.MustFind("Ed25519")
    x := s.Scalar().Zero()
    fmt.Println(x)
}

A suite is a bundle of a group, a hash function, an XOF and the signature and encryption schemes that work with them, and the suite name string selects the bundle. From the suite you get a scalar, a point, and the operations on them. MustFind is the panicking variant, so a typo in the suite name crashes at startup rather than returning an error nobody checks. The go.mod file shows the breadth of implementations behind that single call: github.com/cloudflare/circl, github.com/consensys/gnark-crypto and github.com/kilic/bls12-381 are all direct dependencies, alongside golang.org/x/crypto and the project's own go.dedis.ch/fixbuf. The module requires Go 1.25.0.

Variable time by default, constant time behind a build tag

Kyber includes a mix of variable time and constant time implementations, and this is the single most important operational detail in the library. If an application is sensitive to timing based attacks and needs to constrain Kyber to offering only constant time implementations, the documentation says to call suites.RequireConstantTime() in the init() function of the main package. The build machinery backs this up, because the constant time path is a separate compilation mode rather than a runtime flag. The Makefile runs the linter twice, once plain and once with the constantTime build tag, and the test suite has a test-constantTime target that runs the tests with the same tag, plus a build target that compiles the package both ways. That structure is deliberate. A developer who never runs the tagged build may not notice a variable time implementation slipping into a sensitive path.

The v4 module path hides a real wire compatibility break

Kyber moved to Go modules at v3.0.0 and respects semantic versioning from that point, with the import path go.dedis.ch/kyber/v4 for the current major version. The versioning history is spelled out: crypto.v0 was the first semi-stable version, kyber.v1 never existed in order to keep the kyber, onet and cothority versions linked, and gopkg.in/dedis/kyber.v2 was the last stable version. The migration warning is specific. In v4.0.1 modifications to certain structures were introduced making compatibility between v3 and v4 nodes not straight forward, and the project recommends carefully reviewing the new structures to adapt marshaling methods in systems where nodes of different versions interact, with the example that a field type might have changed from int to int32 in v4. For a deployment where mixed version nodes must talk to each other, that is a marshaling audit, not a version bump.

ECDH shared secrets can use the full point instead of the x coordinate

There is one protocol detail the documentation calls out on its own. Traditionally ECDH derives the shared secret from the x point only, but in this framework you can either manually retrieve the value or use the MarshalBinary method to take the combined (x, y) value as the shared secret. The project recommends the MarshalBinary route for new software and protocols using the framework, because it is cleaner and generalizes across different types of groups, for example both integer and elliptic curve groups. The cost is stated just as plainly: it will likely be incompatible with other implementations of ECDH. That is a real interoperability decision rather than a detail, since a peer running a different ECDH stack will derive a different secret if one side changes convention. The library also ships an xof package for extendable output functions and a random package for randomness, which is where the underlying primitives meet the protocol level code.

Shares, shuffles and proofs are the reason the library exists

Most of the top level directories correspond to protocol primitives that ordinary crypto libraries do not provide: a share package, a shuffle package, a proof package, a pairing package, a sign package and an encrypt package. The examples directory confirms the intent, with example files named dh_test.go for Diffie-Hellman, enc_test.go and bn256_enc_test.go for encryption, sig_test.go for signatures, and neff_shuffle_test.go for a Neff shuffle. The shuffles and proofs are the layers a general purpose library will not have, because they exist to support collective decision making and threshold schemes rather than to encrypt a file. The README compares the toolkit's purpose to making it possible, and preferably easy, to do slightly more interesting things that most current crypto libraries do not support effectively, and names the Charm rapid prototyping library for Python as the closest existing comparable.

The licence is not labelled, and the security guarantee is explicitly absent

Two disclaimers in the documentation deserve to be read before anything else. The library is offered as-is, and without a guarantee, and it will need an independent security review before it should be considered ready for use in security-critical applications. If you integrate Kyber into your application it is your responsibility to arrange for that audit. That is a stronger warning than most library documentation carries, and it is written by the authors rather than by a lawyer. Security problems are reported to [email protected]. The licence is a separate matter: the hosting service reports a custom licence that it could not classify, and the README does not name a licence, so the LICENSE file in the repository is the one to read before you vendor the code or ship a product that depends on it. The project is not archived, the last push was on 2026-06-22, and the tags are v4.0.2 on 2026-04-14, v4.0.1 on 2026-03-09 and v3.1.0 back in November 2022.

Where Kyber is the wrong tool

The documentation itself rules out the most common use case, and it is worth repeating that the authors aimed it at developers who are at least moderately knowledgeable about cryptography. If you want a library that makes it easy to implement basic crypto functionality correctly, meaning plain public key encryption and signing, then NaCl secretbox may be a better choice, and Google's Tink is offered as the other option. The concrete costs of choosing Kyber anyway are visible. The API is group oriented, so a developer who thinks in terms of encrypt and decrypt has to learn the suite, scalar and point model first. The mixed time implementations mean a deployment can be timing sensitive without the developer having chosen that, unless the constantTime build is used and enforced in CI. The v3 to v4 marshaling change makes cross version deployments an audit item. And for a library that carries no guarantee and demands an independent review, the total engineering cost of a project starts well before the first protocol is written. A useful test is whether your problem needs threshold shares, a non interactive proof or a shuffle. If it does not, a simpler library will be faster to adopt and easier to reason about.

Editorial conclusion

Adopt Kyber when you are implementing a protocol that needs group operations, threshold shares, shuffles or non interactive proofs and you want one abstraction across suites, and pick NaCl secretbox or Tink instead when you only need plain public key encryption and signing. Verify first which build tag and suite combination you deploy, since the constantTime tag is a separate compilation mode rather than a runtime switch, and read the LICENSE file, since the hosting service reports a custom licence the project does not label in the README.

Frequently asked questions

Official sources

1. dedis/kyber on GitHub
2. Issues
3. README
4. Releases