crypt

README

crypt

AES-CBC + PKCS#7 encryption with hex-encoded ciphertext output. Designed for storing short secrets (API keys, tokens) at rest.

Zero third-party dependencies — uses crypto/aes, crypto/cipher, crypto/rand from the standard library.

Install

go get github.com/ubgo/crypt

Quick start

package main

import (
    "fmt"

    "github.com/ubgo/crypt"
)

func main() {
    c, err := crypt.New("12345678901234567890123456789012") // 32-byte AES-256 key
    if err != nil { panic(err) }

    encrypted, _ := c.Encrypt("api-secret-123")
    fmt.Println(encrypted) // hex-encoded ciphertext

    decrypted, _ := c.Decrypt(encrypted)
    fmt.Println(decrypted) // "api-secret-123"
}

Key sizes

The key length selects the AES variant:

Key length	Variant
16 bytes	AES-128
24 bytes	AES-192
32 bytes	AES-256 (recommended)

Any other length returns an error from New.

Cipher vs. one-shot

// Reuse a Cipher across calls (constructs fresh AES blocks per Encrypt/Decrypt — safe to share).
c, _ := crypt.New(key)
out1, _ := c.Encrypt("a")
out2, _ := c.Encrypt("b")

// Or use the package-level helpers if you don't want to keep a Cipher around.
out, _ := crypt.EncryptWithKey(key, "secret")

Notes

• Each Encrypt call uses a fresh random IV from crypto/rand. The IV is prepended to the ciphertext, so two encryptions of the same plaintext produce different outputs (semantically secure).
• Output is hex-encoded for easy storage in TEXT columns. If you want base64, swap the encoder — it's the only line involved.
• AES-CBC alone provides confidentiality but not authenticity. For threat models where ciphertext tampering matters, prefer AES-GCM (authenticated encryption) — crypt will grow a GCM mode in a future release.
• The package validates PKCS#7 padding strictly on decryption: a tampered ciphertext that produces invalid padding returns ErrInvalidPadding rather than garbage plaintext.

API

Symbol	Purpose
New(key string) (*Cipher, error)	Construct a Cipher from a 16/24/32-byte key.
(*Cipher).Encrypt(plaintext string) (string, error)	Encrypt; returns hex(IV ‖ ciphertext).
(*Cipher).Decrypt(ciphertext string) (string, error)	Decrypt and unpad.
EncryptWithKey(key, plaintext string) (string, error)	One-shot Encrypt.
DecryptWithKey(key, ciphertext string) (string, error)	One-shot Decrypt.
ErrCiphertextTooShort, ErrCiphertextNotBlockAligned, ErrInvalidPadding	Sentinel errors for use with errors.Is.

License

Apache License 2.0. See LICENSE.

Documentation

Overview

Package crypt provides AES-CBC + PKCS#7 encryption with hex-encoded ciphertext output. Designed for storing short secrets (API keys, tokens) at rest in a database column.

Keys must be 16, 24, or 32 bytes long, selecting AES-128, AES-192, or AES-256 respectively. AES-256 is strongly recommended for new code.

The package has zero third-party dependencies and uses crypto/rand for IV generation. The output is hex-encoded for easy storage in TEXT-style columns; switch to base64 if you prefer.

Example:

c, err := crypt.New("32-byte-aes-256-key-go-here-padded")
if err != nil { return err }
enc, _ := c.Encrypt("my-secret")
dec, _ := c.Decrypt(enc) // "my-secret"

Index

• Variables
• func DecryptWithKey(key, ciphertext string) (string, error)
• func EncryptWithKey(key, plaintext string) (string, error)
• type Cipher
  • func New(key string) (*Cipher, error)
  • func (c *Cipher) Decrypt(ciphertext string) (string, error)
  • func (c *Cipher) Encrypt(plaintext string) (string, error)

Variables

var ErrCiphertextNotBlockAligned = errors.New("crypt: ciphertext is not a multiple of the block size")

ErrCiphertextNotBlockAligned is returned when ciphertext (excluding IV) is not a multiple of the AES block size.

var ErrCiphertextTooShort = errors.New("crypt: ciphertext too short")

ErrCiphertextTooShort is returned when ciphertext is smaller than the AES block size — which means it cannot contain the IV.

var ErrInvalidPadding = errors.New("crypt: invalid PKCS#7 padding")

ErrInvalidPadding is returned when PKCS#7 padding cannot be removed because the padding length byte is out of range or inconsistent.

Functions

func DecryptWithKey

func DecryptWithKey(key, ciphertext string) (string, error)

DecryptWithKey is the package-level form of Cipher.Decrypt.

func EncryptWithKey

func EncryptWithKey(key, plaintext string) (string, error)

EncryptWithKey is the package-level form of Cipher.Encrypt. Useful for one-shot calls when you don't want to construct a Cipher.

Types

type Cipher

type Cipher struct {
	// contains filtered or unexported fields
}

Cipher is a reusable AES-CBC + PKCS#7 cipher pre-keyed at construction.

Cipher is safe for concurrent use — every Encrypt / Decrypt call constructs a fresh cipher.Block from the stored key.

func New

func New(key string) (*Cipher, error)

New constructs a Cipher from a 16, 24, or 32-byte key string.

func (*Cipher) Decrypt

func (c *Cipher) Decrypt(ciphertext string) (string, error)

Decrypt reverses Encrypt: hex-decodes the input, takes the IV from the first AES block, AES-CBC decrypts the rest, and removes PKCS#7 padding.

func (*Cipher) Encrypt

func (c *Cipher) Encrypt(plaintext string) (string, error)

Encrypt PKCS#7-pads the plaintext, AES-CBC encrypts it with a fresh random IV, and returns hex(IV || ciphertext).