libstodium

The API can be considered stable.

Libstodium provides Java (JNI) bindings for the libsodium methods.

Implementation note

This library implements JNI wrappers to functions from the libsodium library. The library tries to implement zero-copy wherever possible through the use of direct ByteBuffers. For applications using byte[] arrays, calls to libstodium methods can still be made by wrapping each array with a call to ByteBuffer.wrap(). When using arrays, the library will try to keep the amount of copying to a minimum, but specifics depend entirely on the JVM used to run the code.

Credits to:

• Libsodium: author Frank Denis and Contributors
• libsodium-jni: author joshjdevl and Contributors
• Robosodium: author GerardSoleCa and Contributors

Implemented primitives

• AEAD
  • aes256gcm
  • chacha20poly1305
  • chacha20poly1305_ietf
  • xchacha20poly1305_ietf
• Auth
  • hmacsha256
  • hmacsha512
  • hmacsha256256
• Box
  • curve25519xchacha20poly1305
  • curve25519xsalsa20poly1305
• Core
  • hchacha20
  • hsalsa20
• Generic Hash
  • blake2b
• Hash
  • sha256
  • sha512
• KDF (Key Derivation Function)
  • blake2b
• KX (Key Exchange)
  • x25519blake2b
• OneTimeAuth
  • poly1305
• Password Hash
  • argon2i
  • scrypt
• Random bytes
  • sodium randombytes
• Scalar Mult
  • curve25519
• Secret Box
  • xchacha20poly1305
  • xsalsa20poly1305
• Secret Stream
  • TODO
• Short Hash
  • siphash24
  • siphashx24
• Signature
  • ed25519 (EdDSA-25519)
• Stream
  • TODO
• Misc/Util
  • Multipart API interface
  • hex encode/decode
  • base64 encode/decode

Target platform

The library is heavily focussed on intergration with Android Studio and working on Android systems.

The supported Android API versions are:

• Min SDK Version: 16 (4.1 Jelly Bean)
• Target SDK Version: 26 (8.0 Oreo)

How to install

When you plan to use libstodium in an Android Studio project, I would recommend cloning the repository into a subdirectory of the project root.

1. To start, download this repository (there is no need to download libsodium, the setup script handles this):

$ git clone https://github.com/ArteMisc/libstodium.git

2. (Optional) on Ubuntu, you can run this command to make sure everything is setup on your machine:

$ ./install_system_dependencies.sh

3. Next, run the setup script:

$ ./setup.sh # load Ndk and Swig, install libsodium and JNI bindings, cleanup

In order for setup to run correctly, the environment variable JAVA_HOME should be set. If this is not the case, the script will quit. You can set the JAVA_HOME value using export JAVA_HOME=/path/to/java or by running the command like this:

$ JAVA_HOME=/path/to/java ./setup.sh

Notes:

• Do NOT run the script as root. You will be asked to allow sudo for a few specific commands during the script's execution.
• Currently supported architectures are:
  • mips
  • arm
  • arm-v7a
  • x86

License

Each part has its own software license, including:

• Libsodium ISC License
• libsodium-jni Apache License. Version 2.0
• Robosodium Apache License. Version 2.0
• libstodium Apache License. Version 2.0

TODO

• Add tests.
• Support more architectures (64-bits archs).
• Add code examples to the Readme.
• Add support for Maven.