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'.
class KeyPair
A Box key pair. |
|
class Nonce
A Box nonce. |
|
class PublicKey
A Box public key. |
|
class SecretKey : Destroyable
A Box secret key. |
|
class Seed
A Box key pair seed. |
fun close(): Unit |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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 |