Merge pull request #203 from alex/fernet

[WIP][POC] Implement Fernet

4 files changed, 92 insertions, 3 deletions

diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py
index ea7e8eef..0252d693 100644
--- a/docs/cryptography-docs.py
+++ b/docs/cryptography-docs.py
@@ -6,17 +6,29 @@ from sphinx.util.compat import Directive, make_admonition
 DANGER_MESSAGE = """
 This is a "Hazardous Materials" module. You should **ONLY** use it if you're
 100% absolutely sure that you know what you're doing because this module is
-full of land mines, dragons, and dinosaurs with laser guns. """
+full of land mines, dragons, and dinosaurs with laser guns.
+"""
+
+DANGER_ALTERNATE = """
+
+You may instead be interested in :doc:`{alternate}`.
+"""
 
 
 class HazmatDirective(Directive):
+    has_content = True
+
     def run(self):
+        message = DANGER_MESSAGE
+        if self.content:
+            message += DANGER_ALTERNATE.format(alternate=self.content[0])
+
         ad = make_admonition(
             Hazmat,
             self.name,
             [],
             self.options,
-            nodes.paragraph("", DANGER_MESSAGE),
+            nodes.paragraph("", message),
             self.lineno,
             self.content_offset,
             self.block_text,
diff --git a/docs/fernet.rst b/docs/fernet.rst
new file mode 100644
index 00000000..4e94e212
--- /dev/null
+++ b/docs/fernet.rst
@@ -0,0 +1,76 @@
+Fernet (Symmetric encryption)
+=============================
+
+.. currentmodule:: cryptography.fernet
+
+Fernet provides guarantees that a message encrypted using it cannot be
+manipulated or read without the key. `Fernet`_ is an implementation of
+symmetric (also known as "secret key") authenticated cryptography.
+
+.. class:: Fernet(key)
+
+    This class provides both encryption and decryption facilities.
+
+    .. doctest::
+
+        >>> from cryptography.fernet import Fernet
+        >>> key = Fernet.generate_key()
+        >>> f = Fernet(key)
+        >>> token = f.encrypt(b"my deep dark secret")
+        >>> token
+        '...'
+        >>> f.decrypt(token)
+        'my deep dark secret'
+
+    :param bytes key: A URL-safe base64-encoded 32-byte key. This **must** be
+                      kept secret. Anyone with this key is able to create and
+                      read messages.
+
+    .. classmethod:: generate_key()
+
+        Generates a fresh fernet key. Keep this some place safe! If you lose it
+        you'll no longer be able to decrypt messages; if anyone else gains
+        access to it, they'll be able to decrypt all of your messages, and
+        they'll also be able forge arbitrary messages which will be
+        authenticated and decrypted.
+
+    .. method:: encrypt(plaintext)
+
+        :param bytes plaintext: The message you would like to encrypt.
+        :returns bytes: A secure message which cannot be read or altered
+                        without the key. It is URL-safe base64-encoded. This is
+                        refered to as a "Fernet token".
+
+        .. note::
+
+            The encrypted message contains the current time when it was
+            generated in *plaintext*, the time a message was created will
+            therefore be visible to a possible attacker.
+
+    .. method:: decrypt(token, ttl=None)
+
+        :param bytes token: The Fernet token. This is the result of calling
+                            :meth:`encrypt`.
+        :param int ttl: Optionally, the number of seconds old a message may be
+                        for it to be valid. If the message is older than
+                        ``ttl`` seconds (from the time it was originally
+                        created) an exception will be raised. If ``ttl`` is not
+                        provided (or is ``None``), the age of the message is
+                        not considered.
+        :returns bytes: The original plaintext.
+        :raises cryptography.fernet.InvalidToken: If the ``token`` is in any
+                                                  way invalid, this exception
+                                                  is raised. A token may be
+                                                  invalid for a number of
+                                                  reasons: it is older than the
+                                                  ``ttl``, it is malformed, or
+                                                  it does not have a valid
+                                                  signature.
+
+
+.. class:: InvalidToken
+
+    See :meth:`Fernet.decrypt` for more information.
+
+
+.. _`Fernet`: https://github.com/fernet/spec/
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 30896a05..e05248ff 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -1,4 +1,4 @@
-.. hazmat::
+.. hazmat:: /fernet
 
 
 Symmetric Encryption
diff --git a/docs/index.rst b/docs/index.rst
index 5eb3de7d..9682337c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -56,6 +56,7 @@ The recipes layer
 .. toctree::
     :maxdepth: 2
 
+    fernet
     exceptions
     glossary