core/crypto/aead package | Odin Programming Language

A generic interface to Authenticated Encryption with Associated Data (`AEAD`) 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)) }

Collection Info

Collection: core
Path: crypto/aead
Entries: 19

Constants 1

Jump to Constants

Types 3

Algorithm Context Implementation

Procedures 9

Jump to Procedures

algorithm init iv_size open_ctx open_oneshot reset seal_ctx seal_oneshot tag_size

Procedure Groups 2

Jump to Procedure Groups

Variables 4

Jump to Variables

ALGORITHM_NAMES IV_SIZES KEY_SIZES TAG_SIZES

Source Files

Constants

1

MAX_TAG_SIZE #

MAX_TAG_SIZE :: 32

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

Types

3

Algorithm #

Algorithm :: Algorithm

Algorithm is the algorithm identifier associated with a given Context.

Context #

Context :: Context

Context is a concrete instantiation of a specific AEAD algorithm.

Implementation #

Implementation :: 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.

Procedures

9

algorithm #

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

algorithm returns the Algorithm used by a Context instance.

init #

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

init initializes a Context with a specific AEAD Algorithm.

iv_size #

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

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

open_ctx #

@(require_results)

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 if and only if (⟺) 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 #

@(require_results)

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 if and only if (⟺) the authentication was successful. If authentication fails, the destination buffer will be zeroed. dst and ciphertext MUST alias exactly or not at all.

reset #

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

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

seal_ctx #

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 #

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 #

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

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

Procedure Groups

2

open #

open :: proc{
	open_ctx,
	open_oneshot,
}

seal #

seal :: proc{
	seal_ctx,
	seal_oneshot,
}

Variables

4

ALGORITHM_NAMES #

ALGORITHM_NAMES: [Algorithm]string = [Algorithm]string{.Invalid = "Invalid", .AES_GCM_128 = "AES-GCM-128", .AES_GCM_192 = "AES-GCM-192", .AES_GCM_256 = "AES-GCM-256", .CHACHA20POLY1305 = "chacha20poly1305", .XCHACHA20POLY1305 = "xchacha20poly1305", .AEGIS_128L = "AEGIS-128L", .AEGIS_128L_256 = "AEGIS-128L-256", .AEGIS_256 = "AEGIS-256", .AEGIS_256_256 = "AEGIS-256-256", .DEOXYS_II_256 = "Deoxys-II-256"}

ALGORITM_NAMES is the Algorithm to algorithm name string.

IV_SIZES #

IV_SIZES: [Algorithm]int = [Algorithm]int{.Invalid = 0, .AES_GCM_128 = aes.GCM_IV_SIZE, .AES_GCM_192 = aes.GCM_IV_SIZE, .AES_GCM_256 = aes.GCM_IV_SIZE, .CHACHA20POLY1305 = chacha20poly1305.IV_SIZE, .XCHACHA20POLY1305 = chacha20poly1305.XIV_SIZE, .AEGIS_128L = aegis.IV_SIZE_128L, .AEGIS_128L_256 = aegis.IV_SIZE_128L, .AEGIS_256 = aegis.IV_SIZE_256, .AEGIS_256_256 = aegis.IV_SIZE_256, .DEOXYS_II_256 = deoxysii.IV_SIZE}

IV_SIZES is the Algorithm to initialization vector size in bytes. Note: Some algorithms (such as AES-GCM) support variable IV sizes.

KEY_SIZES #

KEY_SIZES: [Algorithm]int = [Algorithm]int{.Invalid = 0, .AES_GCM_128 = aes.KEY_SIZE_128, .AES_GCM_192 = aes.KEY_SIZE_192, .AES_GCM_256 = aes.KEY_SIZE_256, .CHACHA20POLY1305 = chacha20poly1305.KEY_SIZE, .XCHACHA20POLY1305 = chacha20poly1305.KEY_SIZE, .AEGIS_128L = aegis.KEY_SIZE_128L, .AEGIS_128L_256 = aegis.KEY_SIZE_128L, .AEGIS_256 = aegis.KEY_SIZE_256, .AEGIS_256_256 = aegis.KEY_SIZE_256, .DEOXYS_II_256 = deoxysii.KEY_SIZE}

KEY_SIZES is the Algorithm to key size in bytes.

TAG_SIZES #

TAG_SIZES: [Algorithm]int = [Algorithm]int{.Invalid = 0, .AES_GCM_128 = aes.GCM_TAG_SIZE, .AES_GCM_192 = aes.GCM_TAG_SIZE, .AES_GCM_256 = aes.GCM_TAG_SIZE, .CHACHA20POLY1305 = chacha20poly1305.TAG_SIZE, .XCHACHA20POLY1305 = chacha20poly1305.TAG_SIZE, .AEGIS_128L = aegis.TAG_SIZE_128, .AEGIS_128L_256 = aegis.TAG_SIZE_256, .AEGIS_256 = aegis.TAG_SIZE_128, .AEGIS_256_256 = aegis.TAG_SIZE_256, .DEOXYS_II_256 = deoxysii.TAG_SIZE}

TAG_SIZES is the Algorithm to tag size in bytes.