Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit

changed order to "nonce-cyphertext-mac" in `encrypt`\`decrypt`

Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Linux CI MacOSX CI Windows CI

Crystal wrapper for a cryptographic library Monocypher (Official site, Github page)

Note: Sources of Monocypher (version 4.0.1 currently) are included in the shard and will be linked statically with application. On the other hand, if is present in library paths at the time of compilation, linker seems to prefer dynamic linking.

Also included is the standard ED25519 cryptography which Monocypher supplies as an optional component.


  1. Add this to your application's shard.yml:
    github: konovod/monocypher
  1. shards update will install a shard and compile Monocypher static library. So you need clang or gcc.

    2.1. On Windows: currently, shards way isn't supported, but you can compile monocypher manually using following commands(from visual studio development prompt):

    cd ext
    cl /c /EHsc /O2 /MT monocypher.c 
    cl /c /EHsc /O2 /MT monocypher-ed25519.c
    lib monocypher.obj monocypher-ed25519.obj

    and then copy monocypher.lib file to where your Crystal looks for lib files.


  1. The wrapper is created with an additional requirement - using a crypto library for encrypting/decrypting of messages shouldn't cause heap allocations. So it doesn't provide function plaintext = Crypto.unlock(ciphertext, key) (as it will require allocation of plaintext every time message being decrypted). Instead it provide Crypto.decrypt(key: Bytes, input: Bytes, output: Bytes) function that will operate on preallocated buffers.
  2. Most functions receive named arguments. This makes code slightly more verbose, but hopefully will prevent messing up arguments order.

Example of usage:

require "monocypher"

channel = Channel(Bytes).new # should be fixed size in real apps

alice_secret =
alice_public = alice_secret)
bob_secret =
bob_public = bob_secret)

# sender part
spawn do
  alice_shared = alice_secret, public2: bob_public)
  message = "This is a test message русский текст"
  plaintext = message.to_slice
  ciphertext = + Crypto::OVERHEAD_SYMMETRIC)
  Crypto.encrypt(key: alice_shared, input: plaintext, output: ciphertext)
  channel.send ciphertext

# receiver part
bob_shared = bob_secret, public1: alice_public)
ciphertext = channel.receive
result = - Crypto::OVERHEAD_SYMMETRIC)
Crypto.decrypt(key: bob_shared, input: ciphertext, output: result)

check spec dir for more usage examples (TODO - other examples)


Monocypher includes functions for cryptographic hashes BLAKE2b and SHA-512, they are wrapped with simple crystal functions

# "cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e"

Crypto.blake2b("abc".to_slice, key: "".to_slice, hash_size: 64).hexstring
# same as Crypto.blake2b("abc".to_slice).hexstring
# ba80a53f981c4d0d6a2797b69f12f6e94c212f14685ac4b74b12bb6fdbffa2d17d87c5392aab792dc252d5de4533cc9518d38aa8dbf1925ab92386edd4009923

There is also Digest interface used in Crystal stdlib:

  digest =
  digest << "123"  # "3c9909afec25354d551dae21590bb26e38d53f2173b8d3dc3eee4c047e7ab1c1eb8b85103e3be7ba613b31bb5c9c36214dc9f14a42fd7a2fdb84856bca5c44c2"

  digest = "".to_slice, hash_size: 64)
  digest << "123"  # "ba80a53f981c4d0d6a2797b69f12f6e94c212f14685ac4b74b12bb6fdbffa2d17d87c5392aab792dc252d5de4533cc9518d38aa8dbf1925ab92386edd4009923"

Development status

Lowlevel wrapper currently covers all of Monocypher 4.0.1 release and can be called directly.

Highlevel wrapper status:

Area Status Comment
Constant Time Comparison Not planned Already in stdlib: see
Memory Wipe Done
Authenticated Encryption Partially done TODO - streaming interface
Blake2b Hash Done
SHA-512 hash Partially done TODO - hkdf mode
Password Key Derivation Partially done TODO - expose additional options in high-level interface
X25519 Key Exchange Partially done TODO - Generating pair
Public Key Signatures Partially done TODO - XEdDSA implementation
Ed25519 Done
ChaCha20 - Is high-level wrapper needed?
Poly1305 - Is high-level wrapper needed?
Elligator - Is high-level wrapper needed?

Other planned features:

  • Inline docs for everything
  • Input size checking everywhere


Crystal bindings for Monocypher







No releases published


No packages published