From 333fb1024e20fa10ec3e85cbd196cbdff059000d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 31 Oct 2013 10:27:35 -0700 Subject: Docs --- docs/fernet.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 49 insertions(+) create mode 100644 docs/fernet.rst (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst new file mode 100644 index 00000000..938ba0cb --- /dev/null +++ b/docs/fernet.rst @@ -0,0 +1,48 @@ +Fernet +====== + +.. currentmodule:: cryptography.fernet + +.. testsetup:: + + import binascii + key = binascii.unhexlify(b"0" * 32) + + +`Fernet`_ is an implementation of symmetric (also known as "secret key") +authenticated cryptography. Fernet provides guarntees that a message encrypted +using it cannot be manipulated or read without the key. + +.. class:: Fernet(key) + + This class provides both encryption and decryption facilities. + + .. doctest:: + + >>> from cryptography.fernet import Fernet + >>> f = Fernet(key) + >>> ciphertext = f.encrypt(b"my deep dark secret") + >>> f.decrypt(ciphertext) + 'my deep dark secret' + + :param bytes key: A 32-byte key. This **must** be kept secret. Anyone with + this key is able to create and read messages. + + + .. 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. + + .. method:: decrypt(ciphertext, ttl=None) + + :param bytes ciphertext: An encrypted message. + :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. + :returns bytes: The original plaintext. + + +.. _`Fernet`: https://github.com/fernet/spec/ diff --git a/docs/index.rst b/docs/index.rst index 4fd5d3be..b9c5b5fb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,6 +30,7 @@ Contents .. toctree:: :maxdepth: 2 + fernet architecture contributing security -- cgit v1.2.3 From de475eb9f56a34868c7debb707427ab5678eda6c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 31 Oct 2013 10:35:19 -0700 Subject: Improve the docs --- docs/fernet.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 938ba0cb..ac610eb8 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -22,6 +22,9 @@ using it cannot be manipulated or read without the key. >>> from cryptography.fernet import Fernet >>> f = Fernet(key) >>> ciphertext = f.encrypt(b"my deep dark secret") + # Secret bytes. + >>> ciphertext + '...' >>> f.decrypt(ciphertext) 'my deep dark secret' @@ -33,7 +36,7 @@ using it cannot be manipulated or read without the key. :param bytes plaintext: The message you would like to encrypt. :returns bytes: A secure message which cannot be read or altered - without the key. + without the key. It is URL safe base64-encoded. .. method:: decrypt(ciphertext, ttl=None) -- cgit v1.2.3 From 13e0d54510d3f939c749d3efc810bad675f4f908 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 31 Oct 2013 10:38:04 -0700 Subject: Be explicit --- docs/fernet.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index ac610eb8..d44e737b 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -44,7 +44,9 @@ using it cannot be manipulated or read without the key. :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. + 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. -- cgit v1.2.3 From 36e2df0955aa1c6534049be21868c24e93569b8b Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 31 Oct 2013 10:40:17 -0700 Subject: Fixed keylength in example --- docs/fernet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index d44e737b..33488891 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -6,7 +6,7 @@ Fernet .. testsetup:: import binascii - key = binascii.unhexlify(b"0" * 32) + key = binascii.unhexlify(b"0" * 64) `Fernet`_ is an implementation of symmetric (also known as "secret key") -- cgit v1.2.3 From 5ac6524f790713090754572fb775405f64a87df2 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 31 Oct 2013 11:28:13 -0700 Subject: fix --- docs/fernet.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 33488891..02b99705 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -22,7 +22,6 @@ using it cannot be manipulated or read without the key. >>> from cryptography.fernet import Fernet >>> f = Fernet(key) >>> ciphertext = f.encrypt(b"my deep dark secret") - # Secret bytes. >>> ciphertext '...' >>> f.decrypt(ciphertext) -- cgit v1.2.3 From 43307c7b57b5d2cbee01f1a89eae212d2325ca40 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 21 Nov 2013 21:50:14 -0800 Subject: Fixed a typo --- docs/fernet.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 02b99705..e4756c09 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -5,12 +5,13 @@ Fernet .. testsetup:: + import base64 import binascii - key = binascii.unhexlify(b"0" * 64) + key = base64.urlsafe_b64encode(binascii.unhexlify(b"0" * 64)) `Fernet`_ is an implementation of symmetric (also known as "secret key") -authenticated cryptography. Fernet provides guarntees that a message encrypted +authenticated cryptography. Fernet provides guarantees that a message encrypted using it cannot be manipulated or read without the key. .. class:: Fernet(key) @@ -27,8 +28,9 @@ using it cannot be manipulated or read without the key. >>> f.decrypt(ciphertext) 'my deep dark secret' - :param bytes key: A 32-byte key. This **must** be kept secret. Anyone with - this key is able to create and read messages. + :param bytes key: A base64 encoded 32-byte key. This **must** be kept + secret. Anyone with this key is able to create and read + messages. .. method:: encrypt(plaintext) -- cgit v1.2.3 From 7a121fce784efb6d436816d84ed01e873f251490 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 22 Nov 2013 10:18:30 -0800 Subject: More info in the docs --- docs/fernet.rst | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index e4756c09..c95077bb 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -28,16 +28,16 @@ using it cannot be manipulated or read without the key. >>> f.decrypt(ciphertext) 'my deep dark secret' - :param bytes key: A base64 encoded 32-byte key. This **must** be kept - secret. Anyone with this key is able to create and read - messages. + :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. .. 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. + without the key. It is URL-safe base64-encoded. .. method:: decrypt(ciphertext, ttl=None) @@ -49,6 +49,16 @@ using it cannot be manipulated or read without the key. provided (or is ``None``), the age of the message is not considered. :returns bytes: The original plaintext. + :raises InvalidToken: If the ``ciphertext`` is in any way invalid, this + exception is raised. A ciphertext 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/ -- cgit v1.2.3 From 36597b4379bd62e520b9076072a030c73b85f471 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 22 Nov 2013 10:25:13 -0800 Subject: An API for generating keys --- docs/fernet.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index c95077bb..241bf1ea 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -3,13 +3,6 @@ Fernet .. currentmodule:: cryptography.fernet -.. testsetup:: - - import base64 - import binascii - key = base64.urlsafe_b64encode(binascii.unhexlify(b"0" * 64)) - - `Fernet`_ is an implementation of symmetric (also known as "secret key") authenticated cryptography. Fernet provides guarantees that a message encrypted using it cannot be manipulated or read without the key. @@ -21,6 +14,7 @@ using it cannot be manipulated or read without the key. .. doctest:: >>> from cryptography.fernet import Fernet + >>> key = Fernet.generate_key() >>> f = Fernet(key) >>> ciphertext = f.encrypt(b"my deep dark secret") >>> ciphertext @@ -32,6 +26,11 @@ using it cannot be manipulated or read without the key. 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. .. method:: encrypt(plaintext) -- cgit v1.2.3 From 6cf242bee212b5b6069865a48c6bdc4836f78ff6 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 16 Dec 2013 11:17:07 -0800 Subject: Document the other consequence of losing your key --- docs/contributing.rst | 3 ++- docs/fernet.rst | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index cb9c7283..036043f5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -244,7 +244,8 @@ Use `tox`_ to build the documentation. For example: docs: commands succeeded congratulations :) -The HTML documentation index can now be found at ``docs/_build/html/index.html`` +The HTML documentation index can now be found at +``docs/_build/html/index.html``. .. _`GitHub`: https://github.com/pyca/cryptography diff --git a/docs/fernet.rst b/docs/fernet.rst index 241bf1ea..3f0cdded 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -30,7 +30,9 @@ using it cannot be manipulated or read without the 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. + 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) -- cgit v1.2.3 From e9083291b9dac1c1ab7b0a2da38f9455536a807d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 17 Dec 2013 16:56:29 -0800 Subject: Include more info in the title --- docs/fernet.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 3f0cdded..287c991b 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -1,5 +1,5 @@ -Fernet -====== +Fernet (Symmetric encryption) +============================= .. currentmodule:: cryptography.fernet -- cgit v1.2.3 From 0d0896319f59fe7b03d8ef6a153275f87816976b Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 17 Dec 2013 20:23:43 -0800 Subject: Use the term fernet token --- docs/fernet.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 287c991b..0122e364 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -16,10 +16,10 @@ using it cannot be manipulated or read without the key. >>> from cryptography.fernet import Fernet >>> key = Fernet.generate_key() >>> f = Fernet(key) - >>> ciphertext = f.encrypt(b"my deep dark secret") - >>> ciphertext + >>> token = f.encrypt(b"my deep dark secret") + >>> token '...' - >>> f.decrypt(ciphertext) + >>> f.decrypt(token) 'my deep dark secret' :param bytes key: A URL-safe base64-encoded 32-byte key. This **must** be @@ -38,11 +38,13 @@ using it cannot be manipulated or read without the key. :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. + without the key. It is URL-safe base64-encoded. This is + refered to as a "Fernet token". - .. method:: decrypt(ciphertext, ttl=None) + .. method:: decrypt(token, ttl=None) - :param bytes ciphertext: An encrypted message. + :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 @@ -50,11 +52,11 @@ using it cannot be manipulated or read without the key. provided (or is ``None``), the age of the message is not considered. :returns bytes: The original plaintext. - :raises InvalidToken: If the ``ciphertext`` is in any way invalid, this - exception is raised. A ciphertext 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. + :raises 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 -- cgit v1.2.3 From 05515723738870170b05b47ee260564b9ebe62f9 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 17 Dec 2013 20:43:59 -0800 Subject: Mention that the timestamp is plaintext --- docs/fernet.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 0122e364..a47ae2e3 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -39,7 +39,10 @@ using it cannot be manipulated or read without the key. :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". + refered to as a "Fernet token". Note that this *does* + contain 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) -- cgit v1.2.3 From 3ef458ac7dc021378d8ca14bfcf654c0d51d9a0d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 20 Dec 2013 13:19:43 -0800 Subject: Reword slightly --- docs/fernet.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index a47ae2e3..4e618f59 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -39,10 +39,10 @@ using it cannot be manipulated or read without the key. :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 that this *does* - contain the current time when it was generated in - plaintext, the time a message was created will - therefore be visible to a possible attacker. + refered to as a "Fernet token". Note that this 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) -- cgit v1.2.3 From 32dc4e4e9f3036f04598134369af50fd70143dae Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 20 Dec 2013 13:26:12 -0800 Subject: Make into a warning as suggested by @dstufft --- docs/fernet.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 4e618f59..68184b3a 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -39,10 +39,13 @@ using it cannot be manipulated or read without the key. :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 that this contains - the current time when it was generated in *plaintext*, - the time a message was created will therefore be - visible to a possible attacker. + refered to as a "Fernet token". + + .. warning:: + + 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) -- cgit v1.2.3 From 719eb6a412b5d3eab3ca84a9d4e8af76955bcbcc Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 20 Dec 2013 13:35:57 -0800 Subject: Linkify this --- docs/fernet.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 68184b3a..2fe2b860 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -41,7 +41,7 @@ using it cannot be manipulated or read without the key. without the key. It is URL-safe base64-encoded. This is refered to as a "Fernet token". - .. warning:: + .. note:: The encrypted message contains the current time when it was generated in *plaintext*, the time a message was created will @@ -58,11 +58,14 @@ using it cannot be manipulated or read without the key. provided (or is ``None``), the age of the message is not considered. :returns bytes: The original plaintext. - :raises 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. + :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 -- cgit v1.2.3 From 2724ff6af8ba5f8dfd1f0f511ed95fab5cd8abd8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 20 Dec 2013 13:51:42 -0800 Subject: Link from symmetric encryption to fernet --- docs/cryptography-docs.py | 17 +++++++++++++++-- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 2 files changed, 16 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py index ea7e8eef..f07c18bb 100644 --- a/docs/cryptography-docs.py +++ b/docs/cryptography-docs.py @@ -6,17 +6,30 @@ 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/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index f4d0457a..7b012975 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -1,4 +1,4 @@ -.. hazmat:: +.. hazmat:: /fernet Symmetric Encryption -- cgit v1.2.3 From 3ac297e4c9b655b3222da1830e9677c9d03a3926 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 20 Dec 2013 14:16:34 -0800 Subject: flake8 fix --- docs/cryptography-docs.py | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py index f07c18bb..0252d693 100644 --- a/docs/cryptography-docs.py +++ b/docs/cryptography-docs.py @@ -15,7 +15,6 @@ You may instead be interested in :doc:`{alternate}`. """ - class HazmatDirective(Directive): has_content = True -- cgit v1.2.3 From 681fca8f43f9cbed97ce2df0b871447953c7edda Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 31 Dec 2013 14:13:39 -0800 Subject: Rearange sentence on recommendation of @jacobian --- docs/cryptography-docs.py | 3 +++ docs/fernet.rst | 6 +++--- 2 files changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py index 0252d693..f27a8467 100644 --- a/docs/cryptography-docs.py +++ b/docs/cryptography-docs.py @@ -23,6 +23,9 @@ class HazmatDirective(Directive): if self.content: message += DANGER_ALTERNATE.format(alternate=self.content[0]) + import pdb + pdb.set_trace() + ad = make_admonition( Hazmat, self.name, diff --git a/docs/fernet.rst b/docs/fernet.rst index 2fe2b860..4e94e212 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -3,9 +3,9 @@ Fernet (Symmetric encryption) .. currentmodule:: cryptography.fernet -`Fernet`_ is an implementation of symmetric (also known as "secret key") -authenticated cryptography. Fernet provides guarantees that a message encrypted -using it cannot be manipulated or read without the key. +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) -- cgit v1.2.3 From 09aa74635f54ace5480a6d502b0da92651f516b6 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 31 Dec 2013 15:18:34 -0800 Subject: Remove this one weird debugger --- docs/cryptography-docs.py | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs') diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py index f27a8467..0252d693 100644 --- a/docs/cryptography-docs.py +++ b/docs/cryptography-docs.py @@ -23,9 +23,6 @@ class HazmatDirective(Directive): if self.content: message += DANGER_ALTERNATE.format(alternate=self.content[0]) - import pdb - pdb.set_trace() - ad = make_admonition( Hazmat, self.name, -- cgit v1.2.3 From 3aa243cddc5cbe4e4205b019946dc6c4f271f589 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 6 Jan 2014 13:13:18 -0800 Subject: Spell a word correctly --- docs/fernet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 4e94e212..13295c0c 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -39,7 +39,7 @@ symmetric (also known as "secret key") authenticated cryptography. :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". + referred to as a "Fernet token". .. note:: -- cgit v1.2.3 From 2b22fae990513eeb4026cd0883bc2e244af8b56a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 6 Jan 2014 13:19:33 -0800 Subject: Compute the version in the same way as setup.py does --- docs/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'docs') 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. -- cgit v1.2.3 From 89063f687893417e1e5dac2e854a02d92037b6a0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 6 Jan 2014 15:52:38 -0800 Subject: Update procedure --- docs/doing-a-release.rst | 27 +++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 28 insertions(+) create mode 100644 docs/doing-a-release.rst (limited to 'docs') diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst new file mode 100644 index 00000000..81349a70 --- /dev/null +++ b/docs/doing-a-release.rst @@ -0,0 +1,27 @@ +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`` and + ``docs/conf.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. Once this has happened: + +* Run ``invoke release {version}``. + +That's all, the release should now be available on PyPI and a tag should be +available in the repository. diff --git a/docs/index.rst b/docs/index.rst index 5eb3de7d..24d6d204 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -78,4 +78,5 @@ The ``cryptography`` open source project contributing security api-stability + doing-a-release community -- cgit v1.2.3 From ce0b5a3a8a5d2bb9de1680a9e9ea6e488d33da27 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 6 Jan 2014 16:53:31 -0800 Subject: Update release docs --- docs/doing-a-release.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst index 81349a70..d790523b 100644 --- a/docs/doing-a-release.rst +++ b/docs/doing-a-release.rst @@ -9,8 +9,7 @@ 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`` and - ``docs/conf.py``. +* 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. -- cgit v1.2.3 From b3794dbe97a6f4e088244adfdd6a06b2d4e185e0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 7 Jan 2014 09:25:54 -0800 Subject: You need a gpg key to do a release --- docs/doing-a-release.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst index d790523b..77582a48 100644 --- a/docs/doing-a-release.rst +++ b/docs/doing-a-release.rst @@ -18,7 +18,8 @@ Performing the release ---------------------- The commit which merged the version number bump is now the official release -commit for this release. Once this has happened: +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}``. -- cgit v1.2.3 From fea893c7060c57fe5ed9e0f9df58fee5c306681b Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 7 Jan 2014 11:06:51 -0800 Subject: More stuff --- docs/doing-a-release.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst index 77582a48..e52c2728 100644 --- a/docs/doing-a-release.rst +++ b/docs/doing-a-release.rst @@ -23,5 +23,6 @@ key in order to do a release. Once this has happened: * Run ``invoke release {version}``. -That's all, the release should now be available on PyPI and a tag should be -available in the repository. +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. -- cgit v1.2.3 From 41c14d55ea2d17e3e9968acfa93d442615f7cda0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 7 Jan 2014 11:19:08 -0800 Subject: How to verify that your released correctly --- docs/doing-a-release.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst index e52c2728..0f382064 100644 --- a/docs/doing-a-release.rst +++ b/docs/doing-a-release.rst @@ -25,4 +25,12 @@ key in order to do a release. Once this has happened: 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. +correctly: + +.. code-block:: pycon + + >>> import cryptography + >>> cryptography.__version__ + '...' + +Verify that this is the version you just released. -- cgit v1.2.3