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

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

Types

KeyPair

class KeyPair

A Box key pair.

Nonce

class Nonce

A Box nonce.

PublicKey

class PublicKey

A Box public key.

SecretKey

class SecretKey : Destroyable

A Box secret key.

Seed

class Seed

A Box key pair seed.

Functions

close

fun close(): Unit

decrypt

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 given key.

decryptDetached

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

Decrypt a message using 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 message using a given key and a detached message authentication code.

decryptSealed

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

Decrypt a sealed message using a given key.

encrypt

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 for a given key.

encryptDetached

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

Encrypt a message, 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 message for a given key, generating a detached message authentication code.

encryptSealed

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

Encrypt a sealed message for a given key.

Sealed boxes are designed to anonymously send messages to a recipient given its public key.

Only the recipient can decrypt these messages, using its private key. While the recipient can verify the integrity of the message, it cannot verify the identity of the sender.

A message is encrypted using an ephemeral key pair, whose secret part is destroyed right after the encryption process.

Without knowing the secret key used for a given message, the sender cannot decrypt its own message later. And without additional data, a message cannot be correlated with the identity of its sender.

forKeys

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

Precompute the shared key for a given sender and receiver.

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