Crystal bindings for the argon2 hashing algorithm


Linux CI

This Crystal shard provides C bindings, and a simplified interface, to the Argon2 algorithm. Argon2 is the official winner of the Password Hashing Competition, a several year project to identify a successor to bcrypt/PBKDF/scrypt methods of securely storing passwords. This is an independent project and not official from the PHC team.

This project is mostly a clone of this awesome ruby project technion/ruby-argon2


  1. Add the dependency to your shard.yml:
    github: sushichain/crystal-argon2
  1. Run shards install


This project has several key tenants to its design:

  • The reference Argon2 implementation is to be used "unaltered". To ensure compliance with this goal, and encourage regular updates from upstream, the upstream library is implemented as a git submodule, and is intended to stay that way.
  • Security and maintainability take top priority. This can have an impact on platform support. A PR that contains platform specific code paths is unlikely to be accepted.
  • Tested versions are Crystal 0.27.0 on MacOS and Linux. No assertions are made on other platforms.
  • Errors from the C interface are raised as Exceptions. There are a lot of exception classes, but they tend to relate to things like very broken input, and code bugs. Calls to this library should generally not require a rescue.
  • Test suite should aim for 100% code coverage.
  • Default work values should not be considered constants. They may change.
  • Not exposing the threads parameter is a design choice. I believe there is significant risk, and minimal gain in using a value other than '1'. Four threads on a four core box completely ties up the entire server to process one user logon. If you want more security, increase m_cost.


require "crystal-argon2"

To generate a hash using specific time and memory cost:

hasher = 2, m_cost: 16)
    => "$argon2i$v=19$m=65536,t=2,p=1$jL7lLEAjDN+pY2cG1N8D2g$iwj1ueduCvm6B9YVjBSnAHu+6mKzqGmDW745ALR38Uo"

To utilise default costs:

hasher =

If you follow this pattern, it is important to create a new Argon2::Password every time you generate a hash, in order to ensure a unique salt. See issue 23 for more information. Alternatively, use this shotcut:

    => "$argon2i$v=19$m=65536,t=2,p=1$61qkSyYNbUgf3kZH3GtHRw$4CQff9AZ0lWd7uF24RKMzqEiGpzhte1Hp8SO7X8bAew"

You can then use this function to verify a password against a given hash. Will return either Argon2::Response::ARGON2_OK for success or raise and exception with then appropriate error code e.g. ARGON2_VERIFY_MISMATCH.

Argon2::Password.verify_password("password", secure_password)


  • build the C library cd ext && make
  • run specs: crystal spec

Using crystal_lib

To generate the initial crystal bindings using this library: example

# export LLVM_CONFIG=/usr/local/opt/llvm/bin/llvm-config
lib LibArgon2
  fun argon2i_hash_raw
  fun argon2i_hash_encoded
  fun argon2d_hash_raw
  fun argon2d_hash_encoded
  fun argon2id_hash_raw
  fun argon2id_hash_encoded

  fun argon2i_verify
  fun argon2d_verify
  fun argon2id_verify


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


github statistic
  • 5
  • 1
  • 2
  • 0
  • 2 days ago
  • November 24, 2018

MIT License

Synced at

Fri, 14 May 2021 06:42:50 GMT