Libsodium documentation
  • Introduction
  • Installation
  • Quickstart and FAQ
  • Projects using libsodium
  • Commercial support
  • Bindings for other languages
  • Usage
  • Helpers
  • Padding
  • Secure memory
  • Generating random data
  • Secret-key cryptography
    • Authenticated encryption
    • Encrypted streams and file encryption
    • Encrypting a set of related messages
    • Authentication
    • AEAD constructions
      • ChaCha20-Poly1305
        • Original ChaCha20-Poly1305 construction
        • IETF ChaCha20-Poly1305 construction
        • XChaCha20-Poly1305 construction
      • AEGIS-256
      • AEGIS-128L
      • AES256-GCM
        • AES256-GCM with precomputation
  • Public-key cryptography
    • Authenticated encryption
    • Public-key signatures
    • Sealed boxes
  • Hashing
    • Generic hashing
    • Short-input hashing
  • Password hashing
    • The pwhash* API
  • Key derivation
    • HKDF
  • Key exchange
  • Advanced
    • SHA-2
    • HMAC-SHA-2
    • The Scrypt function
    • Point*scalar multiplication
    • One-time authentication
    • Stream ciphers
      • ChaCha20
      • XChaCha20
      • Salsa20
      • XSalsa20
    • Ed25519 to Curve25519
    • Finite field arithmetic
      • Ristretto
    • Custom RNG
  • Internals
  • Roadmap
Powered by GitBook
On this page
  • Combined mode with precalculation
  • Detached mode with precalculation
  • Constants
  • Data types
  • Notes
  1. Secret-key cryptography
  2. AEAD constructions
  3. AES256-GCM

AES256-GCM with precomputation

Applications that encrypt several messages using the same key can gain a little speed by expanding the AES key only once, via the precalculation interface.

int crypto_aead_aes256gcm_beforenm(crypto_aead_aes256gcm_state *ctx_,
                                   const unsigned char *k);

The crypto_aead_aes256gcm_beforenm() function initializes a context ctx by expanding the key k and always returns 0.

A 16 bytes alignment is required for the address of ctx. The size of this value can be obtained using sizeof(crypto_aead_aes256gcm_state), or crypto_aead_aes256gcm_statebytes().

Combined mode with precalculation

int crypto_aead_aes256gcm_encrypt_afternm(unsigned char *c,
                                          unsigned long long *clen_p,
                                          const unsigned char *m,
                                          unsigned long long mlen,
                                          const unsigned char *ad,
                                          unsigned long long adlen,
                                          const unsigned char *nsec,
                                          const unsigned char *npub,
                                          const crypto_aead_aes256gcm_state *ctx_);
int crypto_aead_aes256gcm_decrypt_afternm(unsigned char *m,
                                          unsigned long long *mlen_p,
                                          unsigned char *nsec,
                                          const unsigned char *c,
                                          unsigned long long clen,
                                          const unsigned char *ad,
                                          unsigned long long adlen,
                                          const unsigned char *npub,
                                          const crypto_aead_aes256gcm_state *ctx_);

The crypto_aead_aes256gcm_encrypt_afternm() and crypto_aead_aes256gcm_decrypt_afternm() functions are identical to crypto_aead_aes256gcm_encrypt() and crypto_aead_aes256gcm_decrypt(), but accept a previously initialized context ctx instead of a key.

Detached mode with precalculation

int crypto_aead_aes256gcm_encrypt_detached_afternm(unsigned char *c,
                                                   unsigned char *mac,
                                                   unsigned long long *maclen_p,
                                                   const unsigned char *m,
                                                   unsigned long long mlen,
                                                   const unsigned char *ad,
                                                   unsigned long long adlen,
                                                   const unsigned char *nsec,
                                                   const unsigned char *npub,
                                                   const crypto_aead_aes256gcm_state *ctx_);
int crypto_aead_aes256gcm_decrypt_detached_afternm(unsigned char *m,
                                                   unsigned char *nsec,
                                                   const unsigned char *c,
                                                   unsigned long long clen,
                                                   const unsigned char *mac,
                                                   const unsigned char *ad,
                                                   unsigned long long adlen,
                                                   const unsigned char *npub,
                                                   const crypto_aead_aes256gcm_state *ctx_)

The crypto_aead_aes256gcm_encrypt_detached_afternm() and crypto_aead_aes256gcm_decrypt_detached_afternm() functions are identical to crypto_aead_aes256gcm_encrypt_detached() and crypto_aead_aes256gcm_decrypt_detached(), but accept a previously initialized context ctx instead of a key.

Constants

  • crypto_aead_aes256gcm_KEYBYTES

  • crypto_aead_aes256gcm_NPUBBYTES

  • crypto_aead_aes256gcm_ABYTES

Data types

  • crypto_aead_aes256gcm_state

Notes

The nonce is 96 bits long. In order to prevent nonce reuse, if a key is being reused, it is recommended to increment the previous nonce instead of generating a random nonce for each message. To prevent nonce reuse in a client-server protocol, either use different keys for each direction, or make sure that a bit is masked in one direction, and set in the other.

When using AES-GCM, it is also recommended to switch to a new key before reaching ~350 GB encrypted with the same key. If frequent rekeying is not an option, use (X)ChaCha20-Poly1305 instead.

PreviousAES256-GCMNextPublic-key cryptography

Last updated 1 year ago