Skip to content
This repository has been archived by the owner on Feb 5, 2021. It is now read-only.
/ miscreant.py Public archive

Python implementation of Miscreant: misuse-resistant encryption library with AES-SIV (RFC 5297) and AES-PMAC-SIV support

License

Notifications You must be signed in to change notification settings

miscreant/miscreant.py

 
 

Repository files navigation

miscreant.py Latest Version Build Status MIT licensed Gitter Chat

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

Python implementation of Miscreant: Advanced symmetric encryption library which provides the AES-SIV (RFC 5297), AES-PMAC-SIV, and STREAM constructions. These algorithms are easy-to-use (or rather, hard-to-misuse) and support encryption of individual messages or message streams.

AES-SIV provides nonce-reuse misuse-resistance (NRMR): 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.

Help and Discussion

Have questions? Want to suggest a feature or change?

Security Notice

This library implements some portions of the construction in pure Python and therefore these parts are not constant time: though the core cryptography is provided by the Python cryptography library including the AES function, various other parts, particularly the s2v and dbl functions are Python.

These functions act on Python integers, which are boxed. They may reveal timing information which may help an attacker compromise this implementation, possibly even facilitating complete plaintext recovery. The exact extent to which this is possible has not been thoroughly investigated, nor has this library been professionally audited by cryptography experts.

Use this library at your own risk.

Requirements

This library is tested on Python 3.6.

It depends on the Python cryptography library. For more information on installing this library, please see:

https://cryptography.io/en/latest/installation/

Installation

Install Miscreant with pip using:

$ pip install miscreant

API

Import the SIV class from miscreant.aes.siv using:

from miscreant.aes.siv import SIV

The 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 = SIV.generate_key()
siv = SIV(key)

Encryption (seal)

The seal method encrypts a message along with a set of associated data which acts as 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:

import os
from miscreant.aes.siv import SIV

key = SIV.generate_key()
siv = SIV(key)

message = "Hello, world!"
nonce = os.urandom(16)
ciphertext = siv.seal(message, [nonce])

Decryption (open)

The open method decrypts a ciphertext with the given key.

Example:

import os
from miscreant.aes.siv import SIV

key = SIV.generate_key()
siv = SIV(key)

message = "Hello, world!"
nonce = os.urandom(16)

ciphertext = siv.seal(message, [nonce])
plaintext = siv.open(message, [nonce])

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.

Contributing

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

Copyright

Copyright (c) 2017-2019 The Miscreant Developers. See LICENSE.txt for further details.

About

Python implementation of Miscreant: misuse-resistant encryption library with AES-SIV (RFC 5297) and AES-PMAC-SIV support

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages