diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cryptography-docs.py | 16 | ||||
| -rw-r--r-- | docs/fernet.rst | 76 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 2 | ||||
| -rw-r--r-- | docs/index.rst | 1 |
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 |