symcrypt

README

🔏 symcrypt

A short description

Documentation

• The Github README, https://github.com/peterldowns/symcrypt
• The go.dev docs, pkg.go.dev/github.com/peterldowns/symcrypt

The Github README is the primary source for documentation. The code itself is supposed to be well-organized, and each function has a meaningful docstring, so you should be able to explore it quite easily using an LSP plugin, reading the code, or clicking through the go.dev docs.

Changelog

See /CHANGELOG.

How it works

basic architecture and ideas

Install

go get github.com/peterldowns/symcrypt@latest

Quickstart

API

FAQ

How can I contribute?

symcrypt is a standard golang project, you'll need a working golang environment. If you're of the nix persuasion, this repo comes with a flakes-compatible development shell that you can enter with nix develop (flakes) or nix-shell (standard).

If you use VSCode, the repo comes with suggested extensions and settings.

Testing and linting scripts are defined with Just, see the Justfile to see how to run those commands manually. There are also Github Actions that will lint and test your PRs.

Contributions are more than welcome!

Documentation

Overview

symcrypt ("symmetric cryptography") provides a safe interface for symmetrically encrypting and decrypting values.

Based on the examples at: - https://pkg.go.dev/golang.org/x/crypto/chacha20poly1305#example-NewX - https://cs.opensource.google/go/x/crypto/+/refs/tags/v0.24.0:chacha20poly1305/chacha20poly1305_test.go

Providing `ownerID` is required for the "Authenticated" part of AEAD to actually function correctly. The idea is that if you encrypt a secret for one user, you want to prevent against a case where you accidentally decrypt it for a different user. To do this, you send in the user's ID when you encrypt and decrypt messages.

For more information, read https://en.wikipedia.org/wiki/Authenticated_encryption

Index

• type Ciphertext
• type Client
  • func NewClient(hexKey HexKey) (Client, error)
• type HexKey
  • func GenerateRandomKey() (HexKey, error)
• type Owner
• type Plaintext

Types

type Ciphertext

type Ciphertext string

These types provide "Safety Through Incompatibility" — the goal is to make it harder to accidentally treat plaintext like ciphertext, or mix-and-match owners incorrectly.

For more information on the general concept, you may enjoy reading: https://lukasschwab.me/blog/gen/safe-incompatibility.html

type Client

type Client interface {
	// Encrypt a Plaintext secret for a given Owner.
	Encrypt(plaintext Plaintext, ownerID Owner) (Ciphertext, error)
	// Decrypt a Ciphertext secret for a specific Owner.
	//
	// If the secret was not encrypted for this same Owner, the implementation
	// must return an error.
	Decrypt(ciphertext Ciphertext, ownerID Owner) (Plaintext, error)
}

Client allows for encrypting and decrypting secrets that are "owned" by something or someone that has a unique identifier. If you Encrypt() a plaintext value for a given owner, you will ownly be able to Decrypt() the ciphertext back into plaintext for that same owner. The goal of this interface is to make it harder for application programmers to accidentally decrypt secrets for someone other than the owner.

For example usages, see the tests.

func NewClient

func NewClient(hexKey HexKey) (Client, error)

type HexKey

type HexKey string

A 32-byte (chacha20poly1305.KeySize) secret key, hex-encoded as a string.

func GenerateRandomKey

func GenerateRandomKey() (HexKey, error)

GenerateRandomKey generates a random key that can be used by a Client to encrypt/decrypt messages. It uses a cryptographically-secure source of random bytes.

type Owner

type Owner string

These types provide "Safety Through Incompatibility" — the goal is to make it harder to accidentally treat plaintext like ciphertext, or mix-and-match owners incorrectly.

For more information on the general concept, you may enjoy reading: https://lukasschwab.me/blog/gen/safe-incompatibility.html

type Plaintext

type Plaintext string

These types provide "Safety Through Incompatibility" — the goal is to make it harder to accidentally treat plaintext like ciphertext, or mix-and-match owners incorrectly.

For more information on the general concept, you may enjoy reading: https://lukasschwab.me/blog/gen/safe-incompatibility.html