<img alt="miscreant." src="https://miscreant.io/images/miscreant.svg">

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 (RFC 5297), AES-PMAC-SIV, and STREAM constructions.

Miscreant is available for several programming languages, including C#, 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 (NIST SP 800-38A) mode of encryption with the AES-CMAC(NIST SP 800-38B) 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 <img src="https://raw.githubusercontent.com/miscreant/miscreant.github.io/master/images/thisisfine.png" width="16" height="16"> | | 💔 | 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 | |------------------------|--------------------------------------| | C# | | | Go | N/A | | JavaScript | | | Python | | | Ruby | | | Rust | |

Documentation

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

Related Projects

• XSTREAM: public-key cryptography built on Miscreant and the X25519 elliptic curve Diffie-Hellman function.
• minc (the MIscreaNt Cryptotool): a command-line encryption utility built on Miscreant and XSTREAM.

Help and Discussion

Have questions? Want to suggest a feature or change?

• Gitter: web-based chat about Miscreant
• Google Group: join via web or email (miscreant-crypto+subscribe@googlegroups.com)

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<br> We gonna’ wrap ’em all up looks like some ran’om gup<br> Make somethin’ gnarly and funky won’t fool no half-wit junkie<br> So the game’s like AE but there’s one major hitch<br> No coins can be pitched there’s no state to enrich<br> the IV’s in a ditch dead drunk on cheap wine<br> Now NIST and X9 and their friends at the fort<br> suggest that you stick it in a six-layer torte<br> S/MIME has a scheme there’s even one more<br> So many ways that it’s hard to keep score<br> And maybe they work and maybe they’re fine<br> but I want some proofs for spendin’ my time<br> After wrappin’ them keys gonna’ help out some losers<br> chronic IV abusers don’t read no directions<br> risk a deadly infection If a rusty IV’s drippin’ into yo’ veins<br> and ya never do manage to get it exchanged<br> Then we got ya somethin’ and it comes at low cost<br> 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-2018 [The Miscreant Developers][AUTHORS]. Distributed under the MIT license. See [LICENSE.txt] for further details.

Some language-specific subprojec