miscreant.rb

The best crypto you've never heard of, brought to you by Phil Rogaway

Ruby implementation of Miscreant: Advanced symmetric encryption using the AES-SIV (RFC 5297) and CHAIN constructions, providing easy-to-use (or rather, hard-to-misuse) encryption of individual messages or message streams.

AES-SIV provides nonce-reuse misuse-resistance: accidentally reusing a nonce with this construction is not a security catastrophe, unlike it is with more popular AES encryption modes like AES-GCM. With AES-SIV, the worst outcome of reusing a nonce is an attacker can see you've sent the same plaintext twice, as opposed to almost all other AES modes where it can facilitate chosen ciphertext attacks and/or full plaintext recovery.

For more information, see the toplevel README.md.

Help and Discussion

Have questions? Want to suggest a feature or change?

Gitter: web-based chat about miscreant projects including miscreant.rb
Google Group: join via web or email ([email protected])

Security Notice

Though this library is written by cryptographic professionals, it has not undergone a thorough security audit, and cryptographic professionals are still humans that make mistakes. Use this library at your own risk.

Requirements

This library is tested against the following MRI versions:

Other Ruby versions may work, but are not officially supported.

Installation

Add this line to your application's Gemfile:

gem "miscreant"

And then execute:

$ bundle

Or install it yourself as:

$ gem install miscreant

API

Miscreant::AES::SIV

The Miscreant::AES::SIV class provides the main interface to the AES-SIV misuse resistant authenticated encryption function.

To make a new instance, pass in a 32-byte or 64-byte key. Note that these options are twice the size of what you might be expecting (AES-SIV uses two AES keys).

You can generate a random key using the generate_key method (default 32 bytes):

key_bytes = Miscreant::AES::SIV.generate_key
key = Miscreant::AES::SIV.new(key_bytes)
# => #<Miscreant::AES::SIV:0x007fe0109e85e8>

Encryption (#seal)

The Miscreant::AES::SIV#seal method encrypts a message along with a set of associated data message headers.

It's recommended to include a unique "nonce" value with each message. This prevents those who may be observing your ciphertexts from being able to tell if you encrypted the same message twice. However, unlike other cryptographic algorithms where using a nonce has catastrophic security implications such as key recovery, reusing a nonce with AES-SIV only leaks repeated ciphertexts to attackers.

Example:

message = "Hello, world!"
nonce = SecureRandom.random_bytes(16)
ciphertext = key.seal(message, nonce)

Decryption (#open)

The Miscreant::AES::SIV#open method decrypts a ciphertext with the given key.