design/cryptography-principles.md

# Cryptography Principles

Author: Filippo Valsorda

Last updated: June 2019

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.

---

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.