diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 11 | ||||
| -rw-r--r-- | docs/cryptography-docs.py | 16 | ||||
| -rw-r--r-- | docs/doing-a-release.rst | 36 | ||||
| -rw-r--r-- | docs/fernet.rst | 76 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 2 | ||||
| -rw-r--r-- | docs/index.rst | 2 |
6 files changed, 136 insertions, 7 deletions
diff --git a/docs/conf.py b/docs/conf.py index 5dbcdab8..00660314 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,10 +60,13 @@ copyright = '2013-2014, Individual Contributors' # |version| and |release|, also used in various other places throughout the # built documents. # -# The short X.Y version. -version = '0.1dev' -# The full version, including alpha/beta/rc tags. -release = '0.1dev' + +base_dir = os.path.join(os.path.dirname(__file__), os.pardir) +about = {} +with open(os.path.join(base_dir, "cryptography", "__about__.py")) as f: + exec(f.read(), about) + +version = release = about["__version__"] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. 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/doing-a-release.rst b/docs/doing-a-release.rst new file mode 100644 index 00000000..0f382064 --- /dev/null +++ b/docs/doing-a-release.rst @@ -0,0 +1,36 @@ +Doing a Release +=============== + +Doing a release of ``cryptography`` is a two part process. + +Bumping the version number +-------------------------- + +The first step in doing a release is bumping the version number in the +software. + +* Update the version number in ``cryptography/__about__.py``. +* Do a commit indicating this. +* Send a pull request with this. +* Wait for it to be merged. + +Performing the release +---------------------- + +The commit which merged the version number bump is now the official release +commit for this release. You will need to have ``gpg`` installed and a ``gpg`` +key in order to do a release. Once this has happened: + +* Run ``invoke release {version}``. + +The release should now be available on PyPI and a tag should be available in +the repository. You should verify that ``pip install cryptography`` works +correctly: + +.. code-block:: pycon + + >>> import cryptography + >>> cryptography.__version__ + '...' + +Verify that this is the version you just released. diff --git a/docs/fernet.rst b/docs/fernet.rst new file mode 100644 index 00000000..13295c0c --- /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 + referred 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..4bbfe7fd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -56,6 +56,7 @@ The recipes layer .. toctree:: :maxdepth: 2 + fernet exceptions glossary @@ -78,4 +79,5 @@ The ``cryptography`` open source project contributing security api-stability + doing-a-release community |