class AES256GCM : AutoCloseable
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 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 Allocated : Destroyable
Allocated objects track allocation of memory using Sodium. |
|
class Auth
Secret-key authentication. These operations computes an authentication tag for a message and a secret key, and provides a way to verify that a given tag is valid for a given message and a key. The function computing the tag is deterministic: the same (message, key) tuple will always produce the same output. However, even if the message is public, knowing the key is required in order to be able to compute a valid tag. Therefore, the key should remain confidential. The tag, however, can be public. A typical use case is:
This operation does not encrypt the message. It only computes and verifies an authentication tag. |
|
class Box : AutoCloseable
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 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 Concatenate
Concatenate elements allocated to Sodium memory. |
|
interface DetachedEncryptionResult
The result from a detached encryption. |
|
class DiffieHelman
Sodium provides an API to perform scalar multiplication of elliptic curve points. This can be used as a building block to construct key exchange mechanisms, or more generally to compute a public key from a secret key. On current libsodium versions, you generally want to use the crypto_kx API for key exchange instead. |
|
class GenericHash
Generic hashing utility (BLAKE2b). |
|
class HMACSHA256
Message authentication code support for HMAC-SHA-256. |
|
class HMACSHA512
Message authentication code support for HMAC-SHA-512. |
|
class HMACSHA512256
Message authentication code support for HMAC-SHA-512-256. HMAC-SHA-512-256 is implemented as HMAC-SHA-512 with the output truncated to 256 bits. This is slightly faster than HMAC-SHA-256. Note that this construction is not the same as HMAC-SHA-512/256, which is HMAC using the SHA-512/256 function. |
|
class KeyDerivation
Key derivation. Multiple secret subkeys can be derived from a single master key. Given the master key and a key identifier, a subkey can be deterministically computed. However, given a subkey, an attacker cannot compute the master key nor any other subkeys. |
|
class KeyExchange
Key exchange. Allows two parties to securely compute a set of shared keys using their peer's public key and their own secret key. |
|
interface LibSodium |
|
class PasswordHash
The Argon2 memory-hard hashing function. Argon2 summarizes the state of the art in the design of memory-hard functions. It aims at the highest memory filling rate and effective use of multiple computing units, while still providing defense against tradeoff attacks. It prevents ASICs from having a significant advantage over software implementations. Guidelines for choosing the parametersStart by determining how much memory the function can use. What will be the highest number of threads/processes evaluating the function simultaneously (ideally, no more than 1 per CPU core)? How much physical memory is guaranteed to be available? Set memlimit to the amount of memory you want to reserve for password hashing. Then, set opslimit to 3 and measure the time it takes to hash a password. If this it is way too long for your application, reduce memlimit, but keep opslimit set to 3. If the function is so fast that you can afford it to be more computationally intensive without any usability issues, increase opslimit. For online use (e.g. login in on a website), a 1 second computation is likely to be the acceptable maximum. For interactive use (e.g. a desktop application), a 5 second pause after having entered a password is acceptable if the password doesn't need to be entered more than once per session. For non-interactive use and infrequent use (e.g. restoring an encrypted backup), an even slower computation can be an option. 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'. |
|
open class SHA256Hash
SHA-256 hashing. The SHA-256 and SHA-512 functions are provided for interoperability with other applications. If you are looking for a generic hash function and not specifically SHA-2, using crypto_generichash() (BLAKE2b) might be a better choice. These functions are also not suitable for hashing passwords or deriving keys from passwords. Use one of the password hashing APIs instead. These functions are not keyed and are thus deterministic. In addition, the untruncated versions are vulnerable to length extension attacks. |
|
class SecretBox
Secret-key authenticated encryption. Encrypts a message with a key and a nonce to keep it confidential, and computes an authentication tag. The tag is used to make sure that the message hasn't been tampered with before decrypting it. A single key is used both to encrypt/sign and verify/decrypt messages. For this reason, it is critical to keep the key confidential. The nonce doesn't have to be confidential, but it should never ever be reused with the same key. The easiest way to generate a nonce is to use randombytes_buf(). Messages encrypted are assumed to be independent. If multiple messages are sent using this API and random nonces, there will be no way to detect if a message has been received twice, or if messages have been reordered. 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'. |
|
interface SecretDecryptionStream : Destroyable
Used to decrypt a sequence of messages, or a single message split into arbitrary chunks. |
|
interface SecretEncryptionStream : Destroyable
Used to encrypt a sequence of messages, or a single message split into arbitrary chunks. |
|
class Signature
Public-key signatures. In this system, a signer generates a key pair:
Verifiers need to already know and ultimately trust a public key before messages signed using it can be verified. Warning: this is different from authenticated encryption. Appending a signature does not change the representation of the message itself. 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 Sodium
Access to the sodium native library. This class provides static methods for checking or loading the sodium native library. |
|
class SodiumVersion : Comparable<SodiumVersion>
Details of a sodium native library version. |
|
class XChaCha20Poly1305
Authenticated Encryption with Additional Data using XChaCha20-Poly1305. The XChaCha20-Poly1305 construction can safely encrypt a practically unlimited number of messages with the same key, without any practical limit to the size of a message (up to ~ 2^64 bytes). As an alternative to counters, its large nonce size (192-bit) allows random nonces to be safely used. For this reason, and if interoperability with other libraries is not a concern, this is the recommended AEAD construction. 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 SodiumException : RuntimeException
An exception that is thrown when an error occurs using the native sodium library. |