libsodium_crypto_aead_aes256gcm (libsodium v3.0.1)

AES256-GCM authenticated encryption with additional data.

This construction is only available on CPUs with hardware AES support; check is_available/0 before use and prefer libsodium_crypto_aead_xchacha20poly1305 for portable code. Nonces are npubbytes/0 bytes and must never be reused with the same key.

The precomputation functions (beforenm/1 and the _afternm variants) expand the key once into an opaque state/0.

case libsodium_crypto_aead_aes256gcm:is_available() of
    1 ->
        Key = libsodium_crypto_aead_aes256gcm:keygen(),
        Nonce = libsodium_randombytes:buf(libsodium_crypto_aead_aes256gcm:npubbytes()),
        Ciphertext = libsodium_crypto_aead_aes256gcm:encrypt(<<"message">>, <<"header">>, Nonce, Key),
        <<"message">> = libsodium_crypto_aead_aes256gcm:decrypt(Ciphertext, <<"header">>, Nonce, Key);
    0 ->
        ok
end.

Summary

Types

k()

A crypto_aead_aes256gcm_KEYBYTES (32-byte) binary.

mac()

A crypto_aead_aes256gcm_ABYTES (16-byte) binary.

npub()

A crypto_aead_aes256gcm_NPUBBYTES (12-byte) binary.

state()

An opaque native crypto_aead_aes256gcm_state.

Functions

abytes()

Return crypto_aead_aes256gcm_abytes(), in bytes.

beforenm(K)

Expand the key K into a precomputed state for the _afternm functions.

decrypt(C, NPub, K)

Verify and decrypt the ciphertext C with the additional data AD, nonce NPub, and key K.

decrypt(C, AD, NPub, K)

Verify and decrypt the ciphertext C with the additional data AD, nonce NPub, and key K.

decrypt_afternm(C, NPub, Ctx)

Like decrypt/4, using a state precomputed by beforenm/1.

decrypt_afternm(C, AD, NPub, Ctx)

Like decrypt/4, using a state precomputed by beforenm/1.

decrypt_detached(C, MAC, NPub, K)

Verify the detached tag MAC and decrypt C with the additional data AD. Returns the plaintext, or -1 when verification fails.

decrypt_detached(C, MAC, AD, NPub, K)

Verify the detached tag MAC and decrypt C with the additional data AD. Returns the plaintext, or -1 when verification fails.

decrypt_detached_afternm(C, MAC, NPub, Ctx)

Like decrypt_detached/5, using a state precomputed by beforenm/1.

decrypt_detached_afternm(C, MAC, AD, NPub, Ctx)

Like decrypt_detached/5, using a state precomputed by beforenm/1.

encrypt(M, NPub, K)

Encrypt and authenticate M together with the additional data AD using the nonce NPub and key K.

encrypt(M, AD, NPub, K)

Encrypt and authenticate M together with the additional data AD using the nonce NPub and key K.

encrypt_afternm(M, NPub, Ctx)

Like encrypt/4, using a state precomputed by beforenm/1.

encrypt_afternm(M, AD, NPub, Ctx)

Like encrypt/4, using a state precomputed by beforenm/1.

encrypt_detached(M, NPub, K)

Encrypt and authenticate M with the additional data AD, returning the ciphertext and the authentication tag separately as {C, MAC}.

encrypt_detached(M, AD, NPub, K)

Encrypt and authenticate M with the additional data AD, returning the ciphertext and the authentication tag separately as {C, MAC}.

encrypt_detached_afternm(M, NPub, Ctx)

Like encrypt_detached/4, using a state precomputed by beforenm/1.

encrypt_detached_afternm(M, AD, NPub, Ctx)

Like encrypt_detached/4, using a state precomputed by beforenm/1.

is_available()

Return 1 when the CPU supports hardware-accelerated AES256-GCM, otherwise 0.

keybytes()

Return crypto_aead_aes256gcm_keybytes(), in bytes.

keygen()

Generate a random keybytes/0 byte key.

messagebytes_max()

Return crypto_aead_aes256gcm_messagebytes_max(), in bytes.

npubbytes()

Return crypto_aead_aes256gcm_npubbytes(), in bytes.

nsecbytes()

Return crypto_aead_aes256gcm_nsecbytes(), in bytes.

statebytes()

Return crypto_aead_aes256gcm_statebytes(), in bytes.

Types

k()

-type k() :: <<_:256>>.

A crypto_aead_aes256gcm_KEYBYTES (32-byte) binary.

mac()

-type mac() :: <<_:128>>.

A crypto_aead_aes256gcm_ABYTES (16-byte) binary.

npub()

-type npub() :: <<_:96>>.

A crypto_aead_aes256gcm_NPUBBYTES (12-byte) binary.

state()

-type state() :: libsodium_nif:crypto_aead_aes256gcm_state().

An opaque native crypto_aead_aes256gcm_state.

Operations never modify a state: each returns a new one, so earlier states remain valid and can be reused or shared between processes. States cannot be serialized; they exist only within the running VM.

Functions

abytes()

-spec abytes() -> Result when Result :: 16.

Return crypto_aead_aes256gcm_abytes(), in bytes.

beforenm(K)

-spec beforenm(K) -> Result when K :: k(), Result :: state() | -1.

Expand the key K into a precomputed state for the _afternm functions.

decrypt(C, NPub, K)

-spec decrypt(C, NPub, K) -> Result
                 when C :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Verify and decrypt the ciphertext C with the additional data AD, nonce NPub, and key K.

Returns the plaintext, or -1 when verification fails.

decrypt(C, AD, NPub, K)

-spec decrypt(C, AD, NPub, K) -> Result
                 when C :: binary(), AD :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Verify and decrypt the ciphertext C with the additional data AD, nonce NPub, and key K.

Returns the plaintext, or -1 when verification fails.

decrypt_afternm(C, NPub, Ctx)

-spec decrypt_afternm(C, NPub, Ctx) -> Result
                         when C :: binary(), NPub :: npub(), Ctx :: state(), Result :: binary() | -1.

Like decrypt/4, using a state precomputed by beforenm/1.

decrypt_afternm(C, AD, NPub, Ctx)

-spec decrypt_afternm(C, AD, NPub, Ctx) -> Result
                         when
                             C :: binary(),
                             AD :: binary(),
                             NPub :: npub(),
                             Ctx :: state(),
                             Result :: binary() | -1.

Like decrypt/4, using a state precomputed by beforenm/1.

decrypt_detached(C, MAC, NPub, K)

-spec decrypt_detached(C, MAC, NPub, K) -> Result
                          when
                              C :: binary(),
                              MAC :: mac(),
                              NPub :: npub(),
                              K :: k(),
                              Result :: binary() | -1.

Verify the detached tag MAC and decrypt C with the additional data AD. Returns the plaintext, or -1 when verification fails.

decrypt_detached(C, MAC, AD, NPub, K)

-spec decrypt_detached(C, MAC, AD, NPub, K) -> Result
                          when
                              C :: binary(),
                              MAC :: mac(),
                              AD :: binary(),
                              NPub :: npub(),
                              K :: k(),
                              Result :: binary() | -1.

Verify the detached tag MAC and decrypt C with the additional data AD. Returns the plaintext, or -1 when verification fails.

decrypt_detached_afternm(C, MAC, NPub, Ctx)

-spec decrypt_detached_afternm(C, MAC, NPub, Ctx) -> Result
                                  when
                                      C :: binary(),
                                      MAC :: mac(),
                                      NPub :: npub(),
                                      Ctx :: state(),
                                      Result :: binary() | -1.

Like decrypt_detached/5, using a state precomputed by beforenm/1.

decrypt_detached_afternm(C, MAC, AD, NPub, Ctx)

-spec decrypt_detached_afternm(C, MAC, AD, NPub, Ctx) -> Result
                                  when
                                      C :: binary(),
                                      MAC :: mac(),
                                      AD :: binary(),
                                      NPub :: npub(),
                                      Ctx :: state(),
                                      Result :: binary() | -1.

Like decrypt_detached/5, using a state precomputed by beforenm/1.

encrypt(M, NPub, K)

-spec encrypt(M, NPub, K) -> Result
                 when M :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Encrypt and authenticate M together with the additional data AD using the nonce NPub and key K.

Returns the ciphertext followed by an abytes/0 byte authentication tag.

encrypt(M, AD, NPub, K)

-spec encrypt(M, AD, NPub, K) -> Result
                 when M :: binary(), AD :: binary(), NPub :: npub(), K :: k(), Result :: binary() | -1.

Encrypt and authenticate M together with the additional data AD using the nonce NPub and key K.

Returns the ciphertext followed by an abytes/0 byte authentication tag.

encrypt_afternm(M, NPub, Ctx)

-spec encrypt_afternm(M, NPub, Ctx) -> Result
                         when M :: binary(), NPub :: npub(), Ctx :: state(), Result :: binary() | -1.

Like encrypt/4, using a state precomputed by beforenm/1.

encrypt_afternm(M, AD, NPub, Ctx)

-spec encrypt_afternm(M, AD, NPub, Ctx) -> Result
                         when
                             M :: binary(),
                             AD :: binary(),
                             NPub :: npub(),
                             Ctx :: state(),
                             Result :: binary() | -1.

Like encrypt/4, using a state precomputed by beforenm/1.

encrypt_detached(M, NPub, K)

-spec encrypt_detached(M, NPub, K) -> Result
                          when M :: binary(), NPub :: npub(), K :: k(), Result :: {binary(), mac()} | -1.

Encrypt and authenticate M with the additional data AD, returning the ciphertext and the authentication tag separately as {C, MAC}.

encrypt_detached(M, AD, NPub, K)

-spec encrypt_detached(M, AD, NPub, K) -> Result
                          when
                              M :: binary(),
                              AD :: binary(),
                              NPub :: npub(),
                              K :: k(),
                              Result :: {binary(), mac()} | -1.

Encrypt and authenticate M with the additional data AD, returning the ciphertext and the authentication tag separately as {C, MAC}.

encrypt_detached_afternm(M, NPub, Ctx)

-spec encrypt_detached_afternm(M, NPub, Ctx) -> Result
                                  when
                                      M :: binary(),
                                      NPub :: npub(),
                                      Ctx :: state(),
                                      Result :: {binary(), mac()} | -1.

Like encrypt_detached/4, using a state precomputed by beforenm/1.

encrypt_detached_afternm(M, AD, NPub, Ctx)

-spec encrypt_detached_afternm(M, AD, NPub, Ctx) -> Result
                                  when
                                      M :: binary(),
                                      AD :: binary(),
                                      NPub :: npub(),
                                      Ctx :: state(),
                                      Result :: {binary(), mac()} | -1.

Like encrypt_detached/4, using a state precomputed by beforenm/1.

is_available()

-spec is_available() -> Result when Result :: integer().

Return 1 when the CPU supports hardware-accelerated AES256-GCM, otherwise 0.

keybytes()

-spec keybytes() -> Result when Result :: 32.

Return crypto_aead_aes256gcm_keybytes(), in bytes.

keygen()

-spec keygen() -> Result when Result :: k().

Generate a random keybytes/0 byte key.

messagebytes_max()

-spec messagebytes_max() -> Result when Result :: non_neg_integer().

Return crypto_aead_aes256gcm_messagebytes_max(), in bytes.

npubbytes()

-spec npubbytes() -> Result when Result :: 12.

Return crypto_aead_aes256gcm_npubbytes(), in bytes.

nsecbytes()

-spec nsecbytes() -> Result when Result :: 0.

Return crypto_aead_aes256gcm_nsecbytes(), in bytes.

statebytes()

-spec statebytes() -> Result when Result :: 512.

Return crypto_aead_aes256gcm_statebytes(), in bytes.