tuweni / org.apache.tuweni.crypto.sodium / Box


class Box : AutoCloseable (source)

Public-key authenticated encryption.

Using public-key authenticated encryption, Bob can encrypt a confidential message specifically for Alice, using Alice's public key.

Using Bob's public key, Alice can compute a shared secret key. Using Alice's public key and his secret key, Bob can compute the exact same shared secret key. That shared secret key can be used to verify that the encrypted message was not tampered with, before eventually decrypting it.

Alice only needs Bob's public key, the nonce and the ciphertext. Bob should never ever share his secret key, even with Alice.

And in order to send messages to Alice, Bob only needs Alice's public key. Alice should never ever share her secret key either, even with Bob.

Alice can reply to Bob using the same system, without having to generate a distinct key pair.

The nonce doesn't have to be confidential, but it should be used with just one encryption for a particular pair of public and secret keys.

One easy way to generate a nonce is to use Nonce#random(), considering the size of the nonces the risk of any random collisions is negligible. For some applications, if you wish to use nonces to detect missing messages or to ignore replayed messages, it is also acceptable to use an incrementing counter as a nonce.

When doing so you must ensure that the same value can never be re-used (for example you may have multiple threads or even hosts generating messages using the same key pairs).

As stated above, senders can decrypt their own messages, and compute a valid authentication tag for any messages encrypted with a given shared secret key. This is generally not an issue for online protocols.

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'.



A Box key pair.

class KeyPair


A Box nonce.

class Nonce


A Box public key.

class PublicKey : Destroyable


A Box secret key.

class SecretKey : Destroyable


A Box key pair seed.

class Seed



fun close(): Unit


Decrypt a message using a given key.

fun decrypt(cipherText: Bytes!, nonce: Nonce!): Bytes?
fun decrypt(cipherText: ByteArray!, nonce: Nonce!): ByteArray?
static fun decrypt(cipherText: Bytes!, sender: PublicKey!, receiver: SecretKey!, nonce: Nonce!): Bytes?
static fun decrypt(cipherText: ByteArray!, sender: PublicKey!, receiver: SecretKey!, nonce: Nonce!): ByteArray?


Decrypt a message using a detached message authentication code.

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

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

static fun decryptDetached(cipherText: Bytes!, mac: Bytes!, sender: PublicKey!, receiver: SecretKey!, nonce: Nonce!): Bytes?
static fun decryptDetached(cipherText: ByteArray!, mac: ByteArray!, sender: PublicKey!, receiver: SecretKey!, nonce: Nonce!): ByteArray?


Decrypt a sealed message using a given key.

static fun decryptSealed(cipherText: Bytes!, sender: PublicKey!, receiver: SecretKey!): Bytes?
static fun decryptSealed(cipherText: ByteArray!, sender: PublicKey!, receiver: SecretKey!): ByteArray?


Encrypt a message for a given key.

fun encrypt(message: Bytes!, nonce: Nonce!): Bytes!
fun encrypt(message: ByteArray!, nonce: Nonce!): ByteArray!
static fun encrypt(message: Bytes!, receiver: PublicKey!, sender: SecretKey!, nonce: Nonce!): Bytes!
static fun encrypt(message: ByteArray!, receiver: PublicKey!, sender: SecretKey!, nonce: Nonce!): ByteArray!


Encrypt a message, generating a detached message authentication code.

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

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

static fun encryptDetached(message: Bytes!, receiver: PublicKey!, sender: SecretKey!, nonce: Nonce!): DetachedEncryptionResult!
static fun encryptDetached(message: ByteArray!, receiver: PublicKey!, sender: SecretKey!, nonce: Nonce!): DetachedEncryptionResult!


Encrypt a sealed message for a given key.

static fun encryptSealed(message: Bytes!, receiver: PublicKey!): Bytes!
static fun encryptSealed(message: ByteArray!, receiver: PublicKey!): ByteArray!


fun finalize(): Unit


Precompute the shared key for a given sender and receiver.

static fun forKeys(receiver: PublicKey!, sender: SecretKey!): Box!