miscreant.

Build Status MIT Licensed Gitter Chat

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

A misuse resistant symmetric encryption library designed to support authenticated encryption of individual messages, encryption keys, message streams, or large files using the AES-SIV, AES-PMAC-SIV, and STREAM constructions.

Miscreant is available for several programming languages, including Go, JavaScript, Python, Ruby, and Rust.

What is Miscreant?

Miscreant is a set of interoperable libraries implemented in several languages providing a high-level API for misuse-resistant symmetric encryption. Additionally, it provides support for "online" [authenticated encryption] use cases such as streaming or incrementally encryption/decryption of large files.

The following algorithms are provided by Miscreant:

  • AES-SIV: an authenticated mode of AES which provides nonce reuse misuse resistance. Described in RFC 5297, it combines the AES-CTR mode of encryption with the AES-CMAC function for integrity.

  • AES-PMAC-SIV: a fully parallelizable variant of AES-SIV which substitutes the AES-PMAC function for integrity, providing effectively identical security properties as the original construction, but much better performance on systems which provide parallel hardware implementations of AES, namely Intel/AMD CPUs.

  • STREAM: a construction which, when combined with AES-SIV or AES-PMAC-SIV, provides online/streaming [authenticated encryption] and defends against reordering and truncation attacks.

Cipher Comparison

Miscreant Ciphers

Name Authenticated Misuse Resistance x86 Speed IoT Speedโ€  Standardization
AES-SIV ๐Ÿ’š ๐Ÿ’š ๐Ÿ’› ๐Ÿ’š RFC 5297
AES-PMAC-SIV ๐Ÿ’š ๐Ÿ’š ๐Ÿ’š ๐Ÿ’š None

Other Constructions

Name Authenticated Misuse Resistance x86 Speed IoT Speedโ€  Standardization
AES-GCM-SIV ๐Ÿ’š ๐Ÿ’š ๐Ÿ’š ๐Ÿ’› Forthcomingโ€ก
AES-GCM ๐Ÿ’š ๐Ÿ’” ๐Ÿ’š ๐Ÿ’› NIST SP 800-38D
AES-CCM ๐Ÿ’š ๐Ÿ’” ๐Ÿ’› ๐Ÿ’š NIST SP 800-38C
AES-CBC ๐Ÿ’” ๐Ÿ’” ๐Ÿ’š ๐Ÿ’š NIST SP 800-38A
AES-CTR ๐Ÿ’” ๐Ÿ’” ๐Ÿ’š ๐Ÿ’š NIST SP 800-38A
ChaCha20+Poly1305 ๐Ÿ’š ๐Ÿ’” ๐Ÿ’š ๐Ÿ’› RFC 7539
XSalsa20+Poly1305 ๐Ÿ’š ๐Ÿ’” ๐Ÿ’š ๐Ÿ’› None

Legend

Heart Meaning
๐Ÿ’š Great
๐Ÿ’› Fine
๐Ÿ’” Bad

โ€  Assumes hardware acceleration for the AES block cipher function

โ€ก Work is underway in the IRTF CFRG to provide an informational RFC for AES-GCM-SIV. For more information, see draft-irtf-cfrg-gcmsiv. When standardization work around AES-GCM-SIV is complete, it will be considered for inclusion in this library.

Language Support

Miscreant libraries are available for the following languages:

Language Version
Go N/A
JavaScript npm
Python pypi
Ruby gem
Rust crate

Documentation

Please see the Miscreant Wiki for more detailed documentation and usage notes.

Help and Discussion

Have questions? Want to suggest a feature or change?

Code of Conduct

We abide by the Contributor Covenant and ask that you do as well.

For more information, please see CODE_OF_CONDUCT.md.

Key Rap

The paper describing AES-SIV, Deterministic Authenticated-Encryption: A Provable-Security Treatment of the Key-Wrap Problem contains this explanatory rap song at the end, which goes out to all the chronic IV misusing miscreants in the land:

Yo! Weโ€™z gonnaโ€™ take them keys anโ€™ whatever you pleaze
We gonnaโ€™ wrap โ€™em all up looks like some ranโ€™om gup
Make somethinโ€™ gnarly and funky wonโ€™t fool no half-wit junkie
So the gameโ€™s like AE but thereโ€™s one major hitch
No coins can be pitched thereโ€™s no state to enrich
the IVโ€™s in a ditch dead drunk on cheap wine
Now NIST and X9 and their friends at the fort
suggest that you stick it in a six-layer torte
S/MIME has a scheme thereโ€™s even one more
So many ways that itโ€™s hard to keep score
And maybe they work and maybe theyโ€™re fine
but I want some proofs for spendinโ€™ my time
After wrappinโ€™ them keys gonnaโ€™ help out some losers
chronic IV abusers donโ€™t read no directions
risk a deadly infection If a rusty IVโ€™s drippinโ€™ into yoโ€™ veins
and ya never do manage to get it exchanged
Then we got ya somethinโ€™ and it comes at low cost
When you screw up again not all โ€™ill be lost

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/miscreant/miscreant

Copyright

Copyright (c) 2017 The Miscreant Developers. Distributed under the MIT license. See LICENSE.txt for further details.

Some language-specific subprojects include sources from other authors with more specific licensing requirements, though all projects are MIT licensed. Please see the respective LICENSE.txt files in each project for more information.