encryption

Documentation

Overview

Package encryption provides AES-256-GCM encryption utilities for private posts.

Overview

This package implements symmetric encryption using AES-256-GCM (Galois/Counter Mode), which provides both confidentiality and authenticity. The encryption workflow is:

1. Derive a 256-bit key from a password using PBKDF2 with SHA-256 2. Generate a random 12-byte nonce for each encryption 3. Encrypt plaintext using AES-256-GCM 4. Output: base64(salt + nonce + ciphertext + tag)

Client-Side Decryption

The encrypted content can be decrypted in the browser using the Web Crypto API. The salt, nonce, and ciphertext are concatenated and base64-encoded for easy transmission. The same PBKDF2 parameters must be used for key derivation.

Security Notes

- Use a unique password/key for each sensitivity level - The encryption protects content, not metadata (title, description remain public) - Keys should be stored in environment variables, never committed to source control

Index

• Constants
• Variables
• func Decrypt(ciphertext64, password string) ([]byte, error)
• func DecryptWithKey(ciphertext64 string, key []byte) ([]byte, error)
• func DeriveKey(password string, salt []byte) ([]byte, error)
• func Encrypt(plaintext []byte, password string) (string, error)
• func EncryptWithKey(plaintext, key, salt []byte) (string, error)
• func GenerateSalt() ([]byte, error)

Constants

const (
	// SaltSize is the size of the salt in bytes.
	SaltSize = 16

	// NonceSize is the size of the GCM nonce in bytes.
	// GCM recommends a 12-byte nonce for optimal performance and security.
	NonceSize = 12

	// KeySize is the size of the AES-256 key in bytes.
	KeySize = 32

	// PBKDF2Iterations is the number of PBKDF2 iterations for key derivation.
	// 100,000 iterations provides a good balance between security and performance.
	// This must match the client-side JavaScript implementation.
	PBKDF2Iterations = 100000
)

Constants for encryption parameters.

Variables

var (
	ErrEmptyPassword    = errors.New("encryption: password cannot be empty")
	ErrEmptySalt        = errors.New("encryption: salt cannot be empty")
	ErrInvalidSaltSize  = errors.New("encryption: salt must be 16 bytes")
	ErrEmptyPlaintext   = errors.New("encryption: plaintext cannot be empty")
	ErrEmptyCiphertext  = errors.New("encryption: ciphertext cannot be empty")
	ErrInvalidKey       = errors.New("encryption: key must be 32 bytes")
	ErrMalformedData    = errors.New("encryption: ciphertext too short to contain salt, nonce, and tag")
	ErrDecryptionFailed = errors.New("encryption: decryption failed (wrong password or corrupted data)")
)

Common errors for encryption operations.

Functions

func Decrypt

func Decrypt(ciphertext64, password string) ([]byte, error)

Decrypt decrypts base64-encoded ciphertext using AES-256-GCM. The input format must be: base64(salt || nonce || ciphertext || tag)

The password is used with PBKDF2 to derive the decryption key.

func DecryptWithKey

func DecryptWithKey(ciphertext64 string, key []byte) ([]byte, error)

DecryptWithKey decrypts base64-encoded ciphertext using a pre-derived key. The input format must be: base64(salt || nonce || ciphertext || tag)

The key must be a 32-byte AES-256 key.

func DeriveKey

func DeriveKey(password string, salt []byte) ([]byte, error)

DeriveKey derives a 256-bit encryption key from a password and salt using PBKDF2. The salt should be a random 16-byte value. For encryption, generate a new salt. For decryption, extract the salt from the ciphertext header.

func Encrypt

func Encrypt(plaintext []byte, password string) (string, error)

Encrypt encrypts plaintext using AES-256-GCM and returns a base64-encoded string. The output format is: base64(salt || nonce || ciphertext || tag) where || denotes concatenation.

The key must be a 32-byte AES-256 key (use DeriveKey to create from password). A new random salt and nonce are generated for each call.

func EncryptWithKey

func EncryptWithKey(plaintext, key, salt []byte) (string, error)

EncryptWithKey encrypts plaintext using a pre-derived key. The output format is: base64(salt || nonce || ciphertext || tag) where the salt is provided for storage with the ciphertext.

The key must be a 32-byte AES-256 key.

func GenerateSalt

func GenerateSalt() ([]byte, error)

GenerateSalt generates a cryptographically secure random salt.