design/cryptography-principles.md

# Cryptography Principles

Author: Filippo Valsorda\
Last updated: June 2019\
Discussion: [golang.org/issue/32466](https://golang.org/issue/32466)

https://golang.org/design/cryptography-principles

The Go cryptography libraries goal is to *help developers build
secure applications*. Thus, they aim to be **secure**, **safe**,
**practical** and **modern**, in roughly that order.

**Secure**. We aim to provide a secure implementation free of
security vulnerabilities.

> This is achieved through reduced complexity, testing, code
> review, and a focus on readability.  We will only accept
> changes when there are enough maintainer resources to ensure
> their (ongoing) security.

**Safe**. The goal is to make the libraries easy—not just
possible—to use securely, as library misuse is just as dangerous
to applications as vulnerabilities.

> The default behavior should be safe in as many scenarios as
> possible, and unsafe functionality, if at all available,
> should require explicit acknowledgement in the API.
> Documentation should provide guidance on how to choose and use
> the libraries.

**Practical**. The libraries should provide most developers with
a way to securely and easily do what they are trying to do,
focusing on common use cases to stay minimal.

> The target is applications, not diagnostic or testing tools.
> It’s expected that niche and uncommon needs will be addressed
> by third-party projects. Widely supported functionality is
> preferred to enable interoperability with non-Go applications.
>
> Note that performance, flexibility and compatibility are only
> goals to the extent that they make the libraries useful, not as
> absolute values in themselves.

**Modern**. The libraries should provide the best available
tools for the job, and they should keep up to date with progress
in cryptography engineering.

> If functionality becomes legacy and superseded, it should be
> marked as deprecated and a modern replacement should be
> provided and documented.
>
> Modern doesn’t mean experimental. As the community grows, it’s
> expected that most functionality will be implemented by
> third-party projects first, and that’s ok.

Note that this is an ordered list, from highest to lowest
priority. For example, an insecure implementation or unsafe API
will not be considered, even if it enables more use cases or is
more performant.

---

The Go cryptography libraries are the `crypto/...` and
`golang.org/x/crypto/...` packages in the Go standard library
and subrepos.

The specific criteria for what is considered a common use case,
widely supported or superseded are complex and out of scope for
this document.