ccm

README

go-encryptions/ccm

Pure-Go AES-CCM (Counter with CBC-MAC) AEAD, per RFC 3610 and NIST SP 800-38C. CCM is not in the Go standard library — crypto/cipher only exposes GCM — so this package fills the gap without pulling in golang.org/x/crypto.

It wraps any 128-bit cipher.Block (typically crypto/aes) and implements the standard cipher.AEAD interface, so it drops into anything that already speaks Seal/Open. Built for the go-encryptions family; the primary consumer is go-encryptions/zfscrypt (OpenZFS native encryption).

Install

go get github.com/go-encryptions/ccm

Usage

block, _ := aes.NewCipher(key)          // 16/24/32-byte AES key
aead, err := ccm.NewCCM(block, 16, 12)  // tagSize=16, nonceSize=12 (the OpenZFS default)
if err != nil { /* ... */ }

ct := aead.Seal(nil, nonce, plaintext, additionalData)
pt, err := aead.Open(nil, nonce, ct, additionalData) // err != nil ⇒ authentication failed

Parameter ranges

parameter	symbol	allowed	notes
nonce size	N	[7, 13] bytes	encoded as L = 15 − N
tag size	M	{4, 6, 8, 10, 12, 14, 16}	even, 4…16
plaintext	P	len(P) ≤ 2^(8L) − 1	with N=12 ⇒ up to 2^24 bytes (one ZFS block)

NewCCM validates all three and returns an error on out-of-range values; Seal panics on a wrong-length nonce or oversized plaintext, matching the cipher.AEAD contract.

Security notes

• Tag verification is constant-time (crypto/subtle); Open commits to dst only after the tag checks out and wipes its scratch buffer on failure.
• Correct CBC-MAC + CTR construction with proper AAD length encoding (RFC 3610 §2.2).
• No weak primitives, no unsafe, no cgo. Pure Go.

License

BSD-3-Clause © the go-encryptions/ccm authors.

Documentation

Overview

Package ccm implements the CCM (Counter with CBC-MAC) AEAD mode specified by RFC 3610 and NIST SP 800-38C, suitable for use with AES (or any 128-bit block cipher).

CCM is not provided by the Go standard library — stdlib's crypto/cipher only exposes GCM. This package fills that gap so callers (in particular OpenZFS native-encryption parsers) don't have to depend on golang.org/x/crypto for AES-CCM.

The implementation is pure Go, uses only crypto/aes + the caller-supplied cipher.Block, and exposes the standard cipher.AEAD interface so it composes with any code that already understands GCM-style sealed/open.

Parameter ranges:

nonce size  N  ∈ [7, 13]   (RFC 3610 §3 — encoded as L = 15 - N)
tag size    M  ∈ {4, 6, 8, 10, 12, 14, 16}
plaintext   P  with len(P) ≤ 2^(8L) - 1

Typical OpenZFS usage: N=12, M=16 (L=3, so the encoded-length field is 3 bytes — sufficient for any ZFS block since a block is at most 2^24 bytes).

Index

• func NewCCM(b cipher.Block, tagSize, nonceSize int) (cipher.AEAD, error)
• type CCM
  • func (c *CCM) NonceSize() int
  • func (c *CCM) Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)
  • func (c *CCM) Overhead() int
  • func (c *CCM) Seal(dst, nonce, plaintext, additionalData []byte) []byte

Functions

func NewCCM

func NewCCM(b cipher.Block, tagSize, nonceSize int) (cipher.AEAD, error)

NewCCM returns a cipher.AEAD that uses b in CCM mode with the given tag and nonce sizes (in bytes). b must have a 16-byte block size; tagSize must be one of {4,6,8,10,12,14,16}; nonceSize must be in [7, 13].

Types

type CCM

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

CCM is the cipher.AEAD wrapper around a 128-bit block cipher configured for CCM mode. Construct one with NewCCM.

func (*CCM) NonceSize

func (c *CCM) NonceSize() int

NonceSize returns the configured nonce length.

func (*CCM) Open

func (c *CCM) Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)

Open verifies and decrypts ciphertext, authenticates additionalData, and if successful appends the resulting plaintext to dst, returning the updated slice. The nonce must be NonceSize() bytes long. If the authentication tag does not verify Open returns an error and dst is unchanged.

func (*CCM) Overhead

func (c *CCM) Overhead() int

Overhead returns the number of bytes Seal appends after the ciphertext (the authentication tag).

func (*CCM) Seal

func (c *CCM) Seal(dst, nonce, plaintext, additionalData []byte) []byte

Seal encrypts and authenticates plaintext, authenticates additionalData and appends the result to dst, returning the updated slice. The nonce must be NonceSize() bytes long and must be unique for any particular key.