crypto / org.apache.tuweni.crypto.sodium / AES256GCM

AES256GCM

class AES256GCM : AutoCloseable (source)

Authenticated Encryption with Additional Data using AES-GCM.

WARNING: Despite being the most popular AEAD construction due to its use in TLS, safely using AES-GCM in a different context is tricky.

No more than ~350 GB of input data should be encrypted with a given key. This is for ~16 KB messages -- Actual figures vary according to message sizes.

In addition, nonces are short and repeated nonces would totally destroy the security of this scheme. Nonces should thus come from atomic counters, which can be difficult to set up in a distributed environment.

Unless you absolutely need AES-GCM, use XChaCha20Poly1305 instead. It doesn't have any of these limitations. Or, if you don't need to authenticate additional data, just stick to Sodium#crypto_box(byte[], byte[], long, byte[], byte[], byte[]).

This class depends upon the JNR-FFI library being available on the classpath, along with its dependencies. See https://github.com/jnr/jnr-ffi. JNR-FFI can be included using the gradle dependency 'com.github.jnr:jnr-ffi'.

Types

Key

class Key : Destroyable

An AES256-GSM key.

Nonce

class Nonce

An AES256-GSM nonce.

Functions

close

fun close(): Unit

decrypt

fun decrypt(cipherText: Bytes, nonce: Nonce): Bytes?
fun decrypt(cipherText: ByteArray, nonce: Nonce): ByteArray?
fun decrypt(cipherText: Bytes, data: Bytes, nonce: Nonce): Bytes?
fun decrypt(cipherText: ByteArray, data: ByteArray, nonce: Nonce): ByteArray?

Decrypt a message.

static fun decrypt(cipherText: Bytes, key: Key, nonce: Nonce): Bytes?
static fun decrypt(cipherText: ByteArray, key: Key, nonce: Nonce): ByteArray?
static fun decrypt(cipherText: Bytes, data: Bytes, key: Key, nonce: Nonce): Bytes?
static fun decrypt(cipherText: ByteArray, data: ByteArray, key: Key, nonce: Nonce): ByteArray?

Decrypt a message using a given key.

decryptDetached

fun decryptDetached(cipherText: Bytes, mac: Bytes, nonce: Nonce): Bytes?
fun decryptDetached(cipherText: ByteArray, mac: ByteArray, nonce: Nonce): ByteArray?
fun decryptDetached(cipherText: Bytes, mac: Bytes, data: Bytes, nonce: Nonce): Bytes?
fun decryptDetached(cipherText: ByteArray, mac: ByteArray, data: ByteArray, nonce: Nonce): ByteArray?

Decrypt a message using a detached message authentication code.

static fun decryptDetached(cipherText: Bytes, mac: Bytes, key: Key, nonce: Nonce): Bytes?
static fun decryptDetached(cipherText: ByteArray, mac: ByteArray, key: Key, nonce: Nonce): ByteArray?
static fun decryptDetached(cipherText: Bytes, mac: Bytes, data: Bytes, key: Key, nonce: Nonce): Bytes?
static fun decryptDetached(cipherText: ByteArray, mac: ByteArray, data: ByteArray, key: Key, nonce: Nonce): ByteArray?

Decrypt a message using a given key and a detached message authentication code.

encrypt

fun encrypt(message: Bytes, nonce: Nonce): Bytes
fun encrypt(message: ByteArray, nonce: Nonce): ByteArray
fun encrypt(message: Bytes, data: Bytes, nonce: Nonce): Bytes
fun encrypt(message: ByteArray, data: ByteArray, nonce: Nonce): ByteArray

Encrypt a message.

static fun encrypt(message: Bytes, key: Key, nonce: Nonce): Bytes
static fun encrypt(message: ByteArray, key: Key, nonce: Nonce): ByteArray
static fun encrypt(message: Bytes, data: Bytes, key: Key, nonce: Nonce): Bytes
static fun encrypt(message: ByteArray, data: ByteArray, key: Key, nonce: Nonce): ByteArray

Encrypt a message for a given key.

encryptDetached

fun encryptDetached(message: Bytes, nonce: Nonce): DetachedEncryptionResult
fun encryptDetached(message: ByteArray, nonce: Nonce): DetachedEncryptionResult
fun encryptDetached(message: Bytes, data: Bytes, nonce: Nonce): DetachedEncryptionResult
fun encryptDetached(message: ByteArray, data: ByteArray, nonce: Nonce): DetachedEncryptionResult

Encrypt a message, generating a detached message authentication code.

static fun encryptDetached(message: Bytes, key: Key, nonce: Nonce): DetachedEncryptionResult
static fun encryptDetached(message: ByteArray, key: Key, nonce: Nonce): DetachedEncryptionResult
static fun encryptDetached(message: Bytes, data: Bytes, key: Key, nonce: Nonce): DetachedEncryptionResult
static fun encryptDetached(message: ByteArray, data: ByteArray, key: Key, nonce: Nonce): DetachedEncryptionResult

Encrypt a message for a given key, generating a detached message authentication code.

forKey

static fun forKey(key: Key): AES256GCM

Pre-compute the expansion for the key.

Note that the returned instance of AES256GCM should be closed using #close() (or try-with-resources) to ensure timely release of the expanded key, which is held in native memory.

isAvailable

static fun isAvailable(): Boolean

Check if Sodium and the AES256-GCM algorithm is available.