package core:crypto/aead
Source

⌘K
Ctrl+K
or
/

    Overview

    package aead provides a generic interface to the supported Authenticated Encryption with Associated Data algorithms.

    Both a one-shot and context based interface are provided, with similar usage. If multiple messages are to be sealed/opened via the same key, the context based interface may be more efficient, depending on the algorithm.

    WARNING: Reusing the same key + iv to seal (encrypt) multiple messages results in catastrophic loss of security for most algorithms.

    Example: 
    package aead_example

import "core:bytes"
import "core:crypto"
import "core:crypto/aead"

main :: proc() {
	algo := aead.Algorithm.XCHACHA20POLY1305

	// The example added associated data, and plaintext.
	aad_str := "Get your ass in gear boys."
	pt_str := "They're immanetizing the Eschaton."

	aad := transmute([]byte)aad_str
	plaintext := transmute([]byte)pt_str
	pt_len := len(plaintext)

	// Generate a random key for the purposes of illustration.
	key := make([]byte, aead.KEY_SIZES[algo])
	defer delete(key)
	crypto.rand_bytes(key)

	// `ciphertext || tag`, is a common way data is transmitted, so
	// demonstrate that.
	buf := make([]byte, pt_len + aead.TAG_SIZES[algo])
	defer delete(buf)
	ciphertext, tag := buf[:pt_len], buf[pt_len:]

	// Seal the AAD + Plaintext.
	iv := make([]byte, aead.IV_SIZES[algo])
	defer delete(iv)
	crypto.rand_bytes(iv) // Random IVs are safe with XChaCha20-Poly1305.
	aead.seal(algo, ciphertext, tag, key, iv, aad, plaintext)

	// Open the AAD + Ciphertext.
	opened_pt := buf[:pt_len]
	if ok := aead.open(algo, opened_pt, key, iv, aad, ciphertext, tag); !ok {
		panic("aead example: failed to open")
	}

	assert(bytes.equal(opened_pt, plaintext))
}

    Types

    Algorithm ¶
    Source

    Algorithm :: enum int {
	Invalid, 
	AES_GCM_128, 
	AES_GCM_192, 
	AES_GCM_256, 
	CHACHA20POLY1305, 
	XCHACHA20POLY1305, 
}
     

    Algorithm is the algorithm identifier associated with a given Context.

    Related Procedures With Parameters
    Related Procedures With Returns

    Context ¶
    Source

    Context :: struct {
	_algo: Algorithm,
	_impl: union {
		aes.Context_GCM, 
		chacha20poly1305.Context, 
	},
}
     

    Context is a concrete instantiation of a specific AEAD algorithm.

    Related Procedures With Parameters

    Implementation ¶
    Source

    Implementation :: union {
	aes.Implementation, 
	chacha20.Implementation, 
}
     

    Implementation is an AEAD implementation. Most callers will not need to use this as the package will automatically select the most performant implementation available.

    Related Procedures With Parameters

    Constants

    MAX_TAG_SIZE ¶
    Source

    MAX_TAG_SIZE :: 16
     

    MAX_TAG_SIZE is the maximum size tag that can be returned by any of the Algorithms supported via this package.

    Variables

    ALGORITHM_NAMES ¶
    Source

    ALGORITHM_NAMES: [Algorithm]string = …
     

    ALGORITM_NAMES is the Agorithm to algorithm name string.

    IV_SIZES ¶
    Source

    IV_SIZES: [Algorithm]int = …
     

    IV_SIZES is the Algorithm to initialization vector size in bytes.

    Note: Some algorithms (such as AES-GCM) support variable IV sizes.

    KEY_SIZES ¶
    Source

    KEY_SIZES: [Algorithm]int = …
     

    KEY_SIZES is the Algorithm to key size in bytes.

    TAG_SIZES ¶
    Source

    TAG_SIZES: [Algorithm]int = …
     

    TAG_SIZES is the Algorithm to tag size in bytes.

    Procedures

    algorithm ¶
    Source

    algorithm :: proc(ctx: ^Context) -> Algorithm {…}
     

    algorithm returns the Algorithm used by a Context instance.

    init ¶
    Source

    init :: proc(ctx: ^Context, algorithm: Algorithm, key: []u8, impl: Implementation = nil) {…}
     

    init initializes a Context with a specific AEAD Algorithm.

    iv_size ¶
    Source

    iv_size :: proc(ctx: ^Context) -> int {…}
     

    iv_size returns the IV size of a Context instance in bytes.

    open_ctx ¶
    Source

    open_ctx :: proc(
	ctx:                      ^Context, 
	dst, iv, aad, ciphertext, 
	tag:                      []u8, 
) -> bool {…}
     

    open_ctx authenticates the aad and ciphertext, and decrypts the ciphertext, with the provided Context, iv, and tag, and stores the output in dst, returning true iff the authentication was successful. If authentication fails, the destination buffer will be zeroed.

    dst and plaintext MUST alias exactly or not at all.

    open_oneshot ¶
    Source

    open_oneshot :: proc(
	algo:                               Algorithm, 
	dst, key, iv, aad, ciphertext, tag: []u8, 
	impl:                               Implementation = nil, 
) -> bool {…}
     

    open authenticates the aad and ciphertext, and decrypts the ciphertext, with the provided algorithm, key, iv, and tag, and stores the output in dst, returning true iff the authentication was successful. If authentication fails, the destination buffer will be zeroed.

    dst and plaintext MUST alias exactly or not at all.

    reset ¶
    Source

    reset :: proc(ctx: ^Context) {…}
     

    reset sanitizes the Context. The Context must be re-initialized to be used again.

    seal_ctx ¶
    Source

    seal_ctx :: proc(
	ctx:               ^Context, 
	dst, tag, iv, aad, 
	plaintext:         []u8, 
) {…}
     

    seal_ctx encrypts the plaintext and authenticates the aad and ciphertext, with the provided Context and iv, stores the output in dst and tag.

    dst and plaintext MUST alias exactly or not at all.

    seal_oneshot ¶
    Source

    seal_oneshot :: proc(
	algo:                              Algorithm, 
	dst, tag, key, iv, aad, plaintext: []u8, 
	impl:                              Implementation = nil, 
) {…}
     

    seal_oneshot encrypts the plaintext and authenticates the aad and ciphertext, with the provided algorithm, key, and iv, stores the output in dst and tag.

    dst and plaintext MUST alias exactly or not at all.

    tag_size ¶
    Source

    tag_size :: proc(ctx: ^Context) -> int {…}
     

    tag_size returns the tag size of a Context instance in bytes.

    Procedure Groups

    open ¶
    Source

    open :: proc{
	open_ctx,
	open_oneshot,
}

    seal ¶
    Source

    seal :: proc{
	seal_ctx,
	seal_oneshot,
}

    Source Files

    Generation Information

    Generated with odin version dev-2024-09 (vendor "odin") Windows_amd64 @ 2024-09-15 21:11:16.882742500 +0000 UTC