Merge pull request #10 from dstufft/secret-key-encryption

Add nacl.secret.SecretBox - Secret Key Encryption for PyNaCl

docs/index.rst

@@ -6,6 +6,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   secret
    signing
 
 

docs/secret.rst

+Secret Key Encryption
+=====================
+
+Secret key encryption is analogous to a safe. You can store something secret
+through it and anyone who has the key can open it and view the contents.
+:class:`~nacl.secret.SecretBox` functions as just such a safe, and like any
+good safe any attempts to tamper with the contents is easily detected.
+
+Secret Key Encryption allows you to store or transmit data over insecure
+channels without leaking the contents of that message, nor anything about it
+other than the length.
+
+Example
+-------
+
+.. code:: python
+
+    import nacl
+    import nacl.secret
+
+    # This must be kept secret, this is the combination to your safe
+    key = nacl.random(nacl.secret.SecretBox.KEY_SIZE)
+
+    # This is your safe, you can use it to encrypt or decrypt messages
+    box = nacl.secret.SecretBox(key)
+
+    # This is our message to send, it must be a bytestring as SecretBox will
+    #   treat is as just a binary blob of data.
+    message = b"The president will be exiting through the lower levels"
+
+    # This is a nonce, it *MUST* only be used once, but it is not considered
+    #   secret and can be transmitted or stored alongside the ciphertext. A
+    #   good source of nonce is just 24 random bytes.
+    nonce = nacl.random(24)
+
+    # Encrypt our message, it will be exactly 16 bytes longer than the original
+    #   message as it stores authentication information alongside it.
+    ciphertext = box.encrypt(message, nonce)
+
+    # Decrypt our message, an exception will be raised if the encryption was
+    #   tampered with or there was otherwise an error.
+    plaintext = box.decrypt(ciphertext, nonce)
+
+
+Usage Information
+-----------------
+
+* :class:`~nacl.secret.SecretBox` requires a 32 byte key that must be kept
+  secret. It is the combination to your "safe" and anyone with this key will
+  be able to decrypt the data.
+* :class:`~nacl.secret.SecretBox` requires a new 24 bytes nonce with every
+  encrypted message. This nonce is *not* secret and be freely transfered or
+  stored in plaintext alongside the ciphertext. However it is absolutely
+  imperative that you **NEVER** reuse a nonce with the same key. Reusing the
+  nonce with the same key provides enough information for an attacker
+  to decrypt any and all messages made with your key.
+
+
+Reference
+---------
+
+.. autoclass:: nacl.secret.SecretBox
+    :members:
+
+
+Algorithm details
+-----------------
+
+:Encryption: `Salsa20 steam cipher <https://en.wikipedia.org/wiki/Salsa20>`_
+:Authentication: `Poly1305 MAC <https://en.wikipedia.org/wiki/Poly1305-AES>`_

nacl/nacl.py

@@ -14,7 +14,16 @@ __all__ = ["ffi", "lib"]
 
 ffi = FFI()
 ffi.cdef(
-    # pylint: disable=C0301
+    # Secret Key Encryption
+    """
+        static const int crypto_secretbox_KEYBYTES;
+        static const int crypto_secretbox_NONCEBYTES;
+        static const int crypto_secretbox_ZEROBYTES;
+        static const int crypto_secretbox_BOXZEROBYTES;
+
+        int crypto_secretbox(unsigned char *c, const unsigned char *m, unsigned long long mlen, const unsigned char *n, const unsigned char *k);
+        int crypto_secretbox_open(unsigned char *m, const unsigned char *c, unsigned long long clen, const unsigned char *n, const unsigned char *k);
+    """
 
     # Public Key Encryption - Signatures
     """
@@ -59,6 +68,8 @@ def wrap_nacl_function(func):
         return ret == 0
     return wrapper
 
+lib.crypto_secretbox = wrap_nacl_function(lib.crypto_secretbox)
+lib.crypto_secretbox_open = wrap_nacl_function(lib.crypto_secretbox_open)
 
 lib.crypto_sign_seed_keypair = wrap_nacl_function(lib.crypto_sign_seed_keypair)
 lib.crypto_sign = wrap_nacl_function(lib.crypto_sign)

nacl/secret.py

+from __future__ import absolute_import
+from __future__ import division
+
+from . import six
+
+from . import nacl, encoding
+from .exceptions import CryptoError
+
+
+class SecretBox(encoding.Encodable, six.StringFixer, object):
+    """
+    The SecretBox class encrypted and decrypts messages using the given secret
+    key.
+
+    The ciphertexts generated by :class:`~nacl.secret.Secretbox` include a 16
+    byte authenticator which is checked as part of the decryption. An invalid
+    authenticator will cause the decrypt function to raise an exception. The
+    authenticator is not a signature. Once you've decrypted the message you've
+    demonstrated the ability to create arbitrary valid message, so messages you
+    send are repudiable. For non-repudiable messages, sign them after
+    encryption.
+
+    :param key: The secret key used to encrypt and decrypt messages
+    :param encoder: The encoder class used to decode the given key
+
+    :cvar KEY_SIZE: The size that the key is required to be.
+    :cvar NONCE_SIZE: The size that the nonce is required to be.
+    """
+
+    KEY_SIZE = nacl.lib.crypto_secretbox_KEYBYTES
+    NONCE_SIZE = nacl.lib.crypto_secretbox_NONCEBYTES
+
+    def __init__(self, key, encoder=encoding.RawEncoder):
+        key = encoder.decode(key)
+
+        if len(key) != self.KEY_SIZE:
+            raise ValueError("The key must be exactly %s bytes long" %
+                                nacl.lib.crypto_secretbox_KEYBYTES)
+
+        self._key = key
+
+    def __bytes__(self):
+        return self._key
+
+    def encrypt(self, plaintext, nonce, encoder=encoding.RawEncoder):
+        """
+        Encrypts the plaintext message using the given nonce and returns the
+        ciphertext encoded with the encoder.
+
+        .. warning:: It is **VITALLY** important that the nonce is a nonce,
+            i.e. itis a number used only once for any given key. If you fail to
+            do this, you compromise the privacy of the messages encrypted. Give
+            your nonces a different prefix, or have one side use an odd counter
+            and one an even counter. Just make sure they are different.
+
+        :param plaintext: [:class:`bytes`] The plaintext message to encrypt
+        :param nonce: [:class:`bytes`] The nonce to use in the encryption
+        :param encoder: The encoder to use to encode the ciphertext
+        :rtype: [:class:`bytes`]
+        """
+        if len(nonce) != self.NONCE_SIZE:
+            raise ValueError("The nonce must be exactly %s bytes long" %
+                                nacl.lib.crypto_secretbox_NONCEBYTES)
+
+        padded = b"\x00" * nacl.lib.crypto_secretbox_ZEROBYTES + plaintext
+        ciphertext = nacl.ffi.new("unsigned char[]", len(padded))
+
+        if not nacl.lib.crypto_secretbox(
+                    ciphertext, padded, len(padded), nonce, self._key,
+                ):
+            raise CryptoError("Encryption failed")
+
+        box_zeros = nacl.lib.crypto_secretbox_BOXZEROBYTES
+        ciphertext = nacl.ffi.buffer(ciphertext, len(padded))[box_zeros:]
+
+        return encoder.encode(ciphertext)
+
+    def decrypt(self, ciphertext, nonce, encoder=encoding.RawEncoder):
+        """
+        Decrypts the ciphertext using the given nonce and returns the plaintext
+        message.
+
+        :param ciphertext: [:class:`bytes`] The encrypted message to decrypt
+        :param nonce: [:class:`bytes`] The nonce used when encrypting the
+            ciphertext
+        :param encoder: The encoder used to decode the ciphertext.
+        :rtype: [:class:`bytes`]
+        """
+        if len(nonce) != self.NONCE_SIZE:
+            raise ValueError("The nonce must be exactly %s bytes long" %
+                                nacl.lib.crypto_secretbox_NONCEBYTES)
+
+        ciphertext = encoder.decode(ciphertext)
+
+        padded = b"\x00" * nacl.lib.crypto_secretbox_BOXZEROBYTES + ciphertext
+        plaintext = nacl.ffi.new("unsigned char[]", len(padded))
+
+        if not nacl.lib.crypto_secretbox_open(
+                    plaintext, padded, len(padded), nonce, self._key,
+                ):
+            raise CryptoError(
+                        "Decryption failed. Ciphertext failed verification")
+
+        box_zeros = nacl.lib.crypto_secretbox_ZEROBYTES
+        plaintext = nacl.ffi.buffer(plaintext, len(padded))[box_zeros:]
+
+        return plaintext

tests/test_secret.py

+import binascii
+import pytest
+
+from nacl.encoding import HexEncoder
+from nacl.secret import SecretBox
+
+
+VECTORS = [
+    # Key, Nonce, Plaintext, Ciphertext
+    (
+        b"1b27556473e985d462cd51197a9a46c76009549eac6474f206c4ee0844f68389",
+        b"69696ee955b62b73cd62bda875fc73d68219e0036b7a0b37",
+        b"be075fc53c81f2d5cf141316ebeb0c7b5228c52a4c62cbd44b66849b64244ffce5ecbaaf33bd751a1ac728d45e6c61296cdc3c01233561f41db66cce314adb310e3be8250c46f06dceea3a7fa1348057e2f6556ad6b1318a024a838f21af1fde048977eb48f59ffd4924ca1c60902e52f0a089bc76897040e082f937763848645e0705",
+        b"f3ffc7703f9400e52a7dfb4b3d3305d98e993b9f48681273c29650ba32fc76ce48332ea7164d96a4476fb8c531a1186ac0dfc17c98dce87b4da7f011ec48c97271d2c20f9b928fe2270d6fb863d51738b48eeee314a7cc8ab932164548e526ae90224368517acfeabd6bb3732bc0e9da99832b61ca01b6de56244a9e88d5f9b37973f622a43d14a6599b1f654cb45a74e355a5",
+    ),
+]
+
+
+def test_secret_box_creation():
+    SecretBox(
+        b"ec2bee2d5be613ca82e377c96a0bf2220d823ce980cdff6279473edc52862798",
+        encoder=HexEncoder,
+    )
+
+
+@pytest.mark.parametrize(("key", "nonce", "plaintext", "ciphertext"), VECTORS)
+def test_secret_box_encryption(key, nonce, plaintext, ciphertext):
+    box = SecretBox(key, encoder=HexEncoder)
+
+    plaintext = binascii.unhexlify(plaintext)
+    nonce = binascii.unhexlify(nonce)
+
+    assert box.encrypt(plaintext, nonce, encoder=HexEncoder) == ciphertext
+
+
+@pytest.mark.parametrize(("key", "nonce", "plaintext", "ciphertext"), VECTORS)
+def test_secret_box_decryption(key, nonce, plaintext, ciphertext):
+    box = SecretBox(key, encoder=HexEncoder)
+
+    nonce = binascii.unhexlify(nonce)
+    decrypted = binascii.hexlify(
+                    box.decrypt(ciphertext, nonce, encoder=HexEncoder))
+
+    assert decrypted == plaintext