Skip to content
An Android/Kotlin binding for the Argon2 hash
C Kotlin C++ Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
app
gradle/wrapper
lib
scripts
.gitignore
LICENSE
README.md
build.gradle
dummy_release_keys.jks
gradle.properties
gradlew
gradlew.bat
settings.gradle

README.md

Argon2Kt: An Android/Kotlin binding for the Argon2 hash

Argon2Kt is a binding for the Argon2 password hash that allows to use it easily and securely on Android.

It uses JNI to bridge JVM/C and allows relying solely on direct-allocated ByteBuffers (see below). Naturally, it comes with an extensive test coverage and a sample app.

Argon2Kt is licensed under the MIT license. See the LICENSE file in the root directory.

CircleCI

Quick start 👩‍💻 👨‍💻

Add the dependency to your gradle.build file:

implementation 'com.lambdapioneer.argon2kt:argon2kt:1.0.0'

Use the Argon2Kt class to hash and verify using Argon2:

// initialize Argon2Kt and load the native library
val argon2Kt = Argon2Kt()

// hash a password
val hashResult : Argon2KtResult = argon2Kt.hash(
  mode = Argon2Mode.ARGON2_I,
  password = passwordByteArray,
  salt = saltByteArray,
  tCostInIterations = 5,
  mCostInKibibyte = 65536
)

println("Raw hash: ${hashResult.rawHashAsHexadecimal()}")
println("Encoded string: ${hashResult.encodedOutputAsString()}")

// verify a password against an encoded string representation
val verificationResult : Boolean = argon2Kt.verify(
  mode = Argon2Mode.ARGON2_I,
  encodedString = hashResult.encodedOutputAsString()
  password = passwordByteArray,
)

FAQ 🤔

How do I reduce the exposure of secrets in memory?

Internally, Argon2Kt uses direct-allocated ByteBuffers for passing around both secrets (e.g. password, hash), and outputs (e.g. raw hash).

In contrast to ByteArrays and Strings, direct-allocated ByteBuffers (usually) reside outside the JVM heap and maintain a fixed position. This allows easy passing between native libraries through the JVM world. For our purposes, it allows us to overwrite the content with confidence once we no longer need them. Therefore, using them is preferable.

Argon2Kt offers convenience methods to use ByteArrays and Strings instead. However, the JVM might move these in memory without overwriting the old location. Therefore, you can no longer make sure that the secrets are removed once they are no longer needed.

Can I use Argon2Kt in Java?

Of course. Checkout the SampleJavaClass.java source file for an example. Note that it is not included in the sample app APK although it compiles just fine.

I have problems with an UnsatisfiedLinkError in production. What can I do?

By default Argon2Kt uses the system's loader for .so files. However, for some models and configurations it is known to fail. You can use an alternative SoLoader such as ReLinker using the callback provided by the Argon2Kt constructor.

Contribute 👋

When contributing, please follow the following (common-sense) steps:

  • Create an issue before you write any code. This allows to guide you in the right direction.
    • If you are after a 1-5 line fix, you might ignore this.
  • In the pull-request explain the high-level goal and your approach. That provides valuable context.
  • Convince others (and yourself) that the change is safe and sound.
    • Run ./gradlew connectedAndroidTest and manually test the APK in release configuration using ./gradlew installRelease.

Sample app 📱

The repository comes with a sample app that you can install both in debug and release configuration. Just run ./gradlew installDebug or ./gradlew installRelease respectively.

Reference/BibText 📚

If you want to reference Argon2Kt in documentation or articles, feel free to use this suggested BibTex snippet:

@misc{hugenroth2019argon2kt,
  author={{Daniel Hugenroth}},
  title={Argon2Kt},
  year={2019},
  url={https://github.com/lambdapioneer/argon2kt},
}
You can’t perform that action at this time.