This README is the one indexed from the repository at its latest ref, not from the tag for this version.

rfc8439

Pure crystal implementation of the ChaCha20 stream cipher and Poly1305 authenticator defined in RFC 8439. Includes multiple backends with automatic compile-time selection of the fastest available.

Architecture

Both ChaCha20 and Poly1305 expose abstract base classes (Crypto::ChaCha20::Cipher, Crypto::Poly1305::MAC) with multiple backend implementations. The best backend is selected at compile time and exposed as Default:

ChaCha20::Cipher (abstract)          Poly1305::MAC (abstract)
  ├── Native (pure Crystal)            ├── Native (BigInt)
  │     └── Neon (aarch64 SIMD)        ├── Fast (limb arithmetic)
  └── OpenSSL (>= 1.1.0)               └── OpenSSL (>= 3.0.0)

Compile-time priority:

Component	1st choice	2nd choice	3rd choice
ChaCha20	OpenSSL (>= 1.1.0)	Neon (aarch64)	Native
Poly1305	OpenSSL (>= 3.0.0)	Fast	-

The factory methods (Crypto::ChaCha20.new, Crypto::Poly1305.new, Crypto::Poly1305.chacha20) return the abstract type using Default, so callers program against the common interface. You can also instantiate a specific backend directly (e.g. Crypto::ChaCha20::Native.new).

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     rfc8439:
       github: threez/rfc8439.cr

2. Run shards install

Usage

ChaCha20

require "rfc8439"

# key and nonce are usually given using Bytes,
# but for convinience can be done as a hex string
key = "00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f:10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f"
nonce = "00:00:00:09:00:00:00:4a:00:00:00:00"
msg = "Hello World".to_slice

cipher = Crypto::ChaCha20.new(key, nonce)
encrypted = cipher.encrypt(msg)

# encryption is done using XOR so decryption is done
# by encrypting the cypher text
cipher = Crypto::ChaCha20.new(key, nonce)
plaintext = cipher.encrypt(encrypted)

puts plaintext

Poly1305

require "rfc8439"

key = "85:d6:be:78:57:55:6d:33:7f:44:52:fe:42:d5:06:a8:01:03:80:8a:fb:0d:b2:fd:4a:bf:f6:af:41:49:f5:1b"
msg = "Cryptographic Forum Research Group".to_slice

mac = Crypto::Poly1305.new(key)
mac.update(msg)
tag = mac.final

puts tag

AEADChaCha20Poly1305

Writes the cipher text to ciphertext an IO target and returns the 16 byte (128 bit) Tag for the text.

require "rfc8439"

key = Crypto::Hex.bytes("00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f:10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f")
nonce = Crypto::Hex.bytes("00:00:00:09:00:00:00:4a:00:00:00:00")
ciphertext = IO::Memory.new
aead = Crypto::AeadChacha20Poly1305.new(key, nonce, ciphertext)
aead.aad("Header".to_slice)
aead.update("Hello World!".to_slice)
tag = aead.final

puts tag

Benchmarks

Measured on Apple M1 Pro, Crystal 1.19.1, OpenSSL 3.6.1, compiled with --release:

                                    user     system      total        real
CHACHA20 Native (1GB)           1.546549   0.012450   1.558999 (  1.564214)
CHACHA20 NEON (1GB)             0.819080   0.006326   0.825406 (  0.827881)
CHACHA20 OpenSSL (1GB)          0.539303   0.006543   0.545846 (  0.549548)
POLY1305 Native (64MB)          0.547995   0.005824   0.553819 (  0.555176)
POLY1305 Fast (64MB)            0.041017   0.000254   0.041271 (  0.041274)
POLY1305 OpenSSL (64MB)         0.010014   0.000124   0.010138 (  0.010501)
AEAD_CHACHA20_POLY1305 (64MB)   0.047310   0.000826   0.048136 (  0.048204)

Throughput (real time):

Backend	Throughput
ChaCha20 Native	~654 MB/s
ChaCha20 NEON	~1.24 GB/s
ChaCha20 OpenSSL	~1.86 GB/s
Poly1305 Native	~118 MB/s
Poly1305 Fast	~1.58 GB/s
Poly1305 OpenSSL	~6.23 GB/s

Run benchmarks yourself:

crystal build bench/chacha20.cr --release -o bench/chacha20_bench && bench/chacha20_bench

Contributing

1. Fork it (https://github.com/threez/rfc8439/fork)
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

Contributors

• Vincent Landgraf - creator and maintainer