From 238c191b849ddd67732d0ad5ea26a0bc96c01305 Mon Sep 17 00:00:00 2001 From: Fran Fitzpatrick Date: Tue, 25 Aug 2015 21:22:30 -0400 Subject: Update fernet.rst - removed a word! --- 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 eacbc2ae..8ea33eef 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -3,7 +3,7 @@ Fernet (symmetric encryption) .. currentmodule:: cryptography.fernet -Fernet provides guarantees that a message encrypted using it cannot be +Fernet 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. Fernet also has support for implementing key rotation via :class:`MultiFernet`. -- cgit v1.2.3 From e7820613494bd856a84e46333b43716e5028bdbc Mon Sep 17 00:00:00 2001 From: Tim Buchwaldt Date: Wed, 26 Aug 2015 19:15:03 +0200 Subject: Write as binary At least on Python3 it fails otherwise. --- docs/x509/tutorial.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index 6e587d8b..d1c8ba14 100644 --- a/docs/x509/tutorial.rst +++ b/docs/x509/tutorial.rst @@ -37,7 +37,7 @@ are the most common types of keys on the web right now): ... backend=default_backend() ... ) >>> # Write our key to disk for safe keeping - >>> with open("path/to/store/key.pem", "w") as f: + >>> with open("path/to/store/key.pem", "wb") as f: ... f.write(key.private_bytes( ... encoding=serialization.Encoding.PEM, ... format=serialization.PrivateFormat.TraditionalOpenSSL, @@ -75,7 +75,7 @@ a few details: ... # Sign the CSR with our private key. ... ])).sign(key, hashes.SHA256(), default_backend()) >>> # Write our CSR out to disk. - >>> with open("path/to/csr.pem", "w") as f: + >>> with open("path/to/csr.pem", "wb") as f: ... f.write(csr.public_bytes(serialization.Encoding.PEM)) Now we can give our CSR to a CA, who will give a certificate to us in return. -- cgit v1.2.3 From b964a5cfb006229c1cdb1a4cf97df845ef5e754e Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 18:53:47 +0800 Subject: Add some text regarding using passwords with Fernet. --- docs/fernet.rst | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 8ea33eef..b6ee87f7 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -106,6 +106,43 @@ has support for implementing key rotation via :class:`MultiFernet`. See :meth:`Fernet.decrypt` for more information. + +Using passwords with Fernet +--------------------------- + +It is possible to use passwords with Fernet. To do this, you need to run the +password through a key derivation function like +:class:`~cryptography.hazmat.primitives.kdf.PBKDF2`: + +.. code-block:: python + + import base64 + import os + from cryptography.hazmat.primitives import hashes + from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC + from cryptography.hazmat.backends import default_backend + from cryptography.fernet import Fernet + + password = b"password" + salt = os.urandom(16) + + kdf = PBKDF2HMAC( + algorithm=hashes.SHA256(), + length=32, + salt=salt, + iterations=100000, + backend=default_backend + ) + key = base64.urlsafe_b64encode(kdf.derive(password)) + f = Fernet(key) + +In this scheme, the salt has to be stored in a retrievable location in order +to derive the same key from the password in the future. + +The iteration count used should be adjusted to be as high as your server can +tolerate. A good default is at least 100k iterations which is what Django +`recommends`_. + Implementation -------------- @@ -125,3 +162,4 @@ For complete details consult the `specification`_. .. _`Fernet`: https://github.com/fernet/spec/ .. _`specification`: https://github.com/fernet/spec/blob/master/Spec.md +.. _`recommends`_: https://github.com/django/django/blob/master/django/utils/crypto.py#L148 -- cgit v1.2.3 From 1ef3aa3ea3bfe10f234aa4292d6f65d76c89b192 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 19:04:57 +0800 Subject: Fix link. --- 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 b6ee87f7..1cea0a7a 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -162,4 +162,4 @@ For complete details consult the `specification`_. .. _`Fernet`: https://github.com/fernet/spec/ .. _`specification`: https://github.com/fernet/spec/blob/master/Spec.md -.. _`recommends`_: https://github.com/django/django/blob/master/django/utils/crypto.py#L148 +.. _`recommends`: https://github.com/django/django/blob/master/django/utils/crypto.py#L148 -- cgit v1.2.3 From d9f8bfaaa8c0f416a468e47e7b494661b30f42c8 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 19:08:39 +0800 Subject: Fixed PBKDF2 class target. --- 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 1cea0a7a..d4a7d284 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -112,7 +112,7 @@ Using passwords with Fernet It is possible to use passwords with Fernet. To do this, you need to run the password through a key derivation function like -:class:`~cryptography.hazmat.primitives.kdf.PBKDF2`: +:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`: .. code-block:: python -- cgit v1.2.3 From 4678604fe39078e89e9a20931e64e1a2ac48bab5 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 19:12:14 +0800 Subject: Add Django to wordlist. --- docs/spelling_wordlist.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 1eed7c7a..a78b99f0 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -22,6 +22,7 @@ deserialize deserialized Diffie Docstrings +Django Encodings fernet Fernet -- cgit v1.2.3 From 7126e61fc31d9684314c3749f4b552f6d43e39fc Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 22:28:51 +0800 Subject: Fix imports and wordings. --- docs/fernet.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index d4a7d284..18aab439 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -111,17 +111,18 @@ Using passwords with Fernet --------------------------- It is possible to use passwords with Fernet. To do this, you need to run the -password through a key derivation function like +password through a key derivation function such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`: .. code-block:: python import base64 import os + + from cryptography.fernet import Fernet + from cryptography.hazmat.backends import default_backend from cryptography.hazmat.primitives import hashes from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC - from cryptography.hazmat.backends import default_backend - from cryptography.fernet import Fernet password = b"password" salt = os.urandom(16) @@ -140,8 +141,8 @@ In this scheme, the salt has to be stored in a retrievable location in order to derive the same key from the password in the future. The iteration count used should be adjusted to be as high as your server can -tolerate. A good default is at least 100k iterations which is what Django -`recommends`_. +tolerate. A good default is at least 100,000 iterations which is what Django +`recommends`_ in 2014. Implementation -------------- -- cgit v1.2.3 From 72ccef56791f4f5fe80980728cc953b6ce81efad Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 29 Aug 2015 12:30:33 -0400 Subject: Fixed #2270 -- update citation to something that works --- docs/hazmat/primitives/asymmetric/ec.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 323f4c3f..d5131df6 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -125,10 +125,10 @@ Elliptic Curve Signature Algorithms Elliptic Curves --------------- -Elliptic curves provide equivalent security at much smaller key sizes than -asymmetric cryptography systems such as RSA or DSA. For some operations they -can also provide higher performance at every security level. According to NIST -they can have as much as a `64x lower computational cost than DH`_. +Elliptic curves provide equivalent security at much smaller key sizes than other +asymmetric cryptography systems such as RSA or DSA. For many operations elliptic +curves are also signfiicantly faster; `elliptic curve diffie-hellman is faster +than diffie-hellman`_. .. note:: Curves with a size of `less than 224 bits`_ should not be used. You should @@ -421,7 +421,7 @@ Key Interfaces .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf .. _`some concern`: https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters .. _`less than 224 bits`: http://www.ecrypt.eu.org/ecrypt2/documents/D.SPA.20.pdf -.. _`64x lower computational cost than DH`: https://www.nsa.gov/business/programs/elliptic_curve.shtml +.. _`elliptic curve diffie-hellman is faster than diffie-hellman`: http://digitalcommons.unl.edu/cgi/viewcontent.cgi?article=1100&context=cseconfwork .. _`minimize the number of security concerns for elliptic-curve cryptography`: http://cr.yp.to/ecdh/curve25519-20060209.pdf .. _`SafeCurves`: http://safecurves.cr.yp.to/ .. _`ECDSA`: https://en.wikipedia.org/wiki/ECDSA -- cgit v1.2.3 From fd07919bf6c462e40fdbd536a204f42a0dbbeaa5 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 29 Aug 2015 12:36:51 -0400 Subject: spelling --- docs/hazmat/primitives/asymmetric/ec.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index d5131df6..176bf301 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -127,7 +127,7 @@ Elliptic Curves Elliptic curves provide equivalent security at much smaller key sizes than other asymmetric cryptography systems such as RSA or DSA. For many operations elliptic -curves are also signfiicantly faster; `elliptic curve diffie-hellman is faster +curves are also significantly faster; `elliptic curve diffie-hellman is faster than diffie-hellman`_. .. note:: -- cgit v1.2.3 From 40d56b2d98b96ef3c086db710f363953eac2d26e Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 29 Aug 2015 12:39:12 -0400 Subject: line length --- docs/hazmat/primitives/asymmetric/ec.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 176bf301..01671d44 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -125,10 +125,10 @@ Elliptic Curve Signature Algorithms Elliptic Curves --------------- -Elliptic curves provide equivalent security at much smaller key sizes than other -asymmetric cryptography systems such as RSA or DSA. For many operations elliptic -curves are also significantly faster; `elliptic curve diffie-hellman is faster -than diffie-hellman`_. +Elliptic curves provide equivalent security at much smaller key sizes than +other asymmetric cryptography systems such as RSA or DSA. For many operations +elliptic curves are also significantly faster; `elliptic curve diffie-hellman +is faster than diffie-hellman`_. .. note:: Curves with a size of `less than 224 bits`_ should not be used. You should -- cgit v1.2.3 From b1903b0d4caaac29f78b7421704caf01255b3c13 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sun, 30 Aug 2015 11:09:22 +0800 Subject: Mention bcrypt and scrypt. --- docs/fernet.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 18aab439..a066ae63 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -112,7 +112,8 @@ Using passwords with Fernet It is possible to use passwords with Fernet. To do this, you need to run the password through a key derivation function such as -:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`: +:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`, bcrypt or +scrypt. .. code-block:: python -- cgit v1.2.3 From 69382a045a1647a78ab8a6a00d95ea85c9f93147 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sun, 30 Aug 2015 13:09:36 +0800 Subject: Add bcrypt to word list. --- docs/spelling_wordlist.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index a78b99f0..75497840 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -1,6 +1,7 @@ affine backend backends +bcrypt Backends Blowfish boolean -- cgit v1.2.3 From f648734d1a0da965983e42e96437b99acd7dd1ea Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 3 Sep 2015 10:10:49 -0400 Subject: Fixed #2318 -- added the missing critical flag to the x509 tutorial --- docs/x509/tutorial.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index d1c8ba14..0fa061a2 100644 --- a/docs/x509/tutorial.rst +++ b/docs/x509/tutorial.rst @@ -67,13 +67,16 @@ a few details: ... x509.NameAttribute(NameOID.LOCALITY_NAME, u"San Francisco"), ... x509.NameAttribute(NameOID.ORGANIZATION_NAME, u"My Company"), ... x509.NameAttribute(NameOID.COMMON_NAME, u"mysite.com"), - ... ])).add_extension(x509.SubjectAlternativeName([ - ... # Describe what sites we want this certificate for. - ... x509.DNSName(u"mysite.com"), - ... x509.DNSName(u"www.mysite.com"), - ... x509.DNSName(u"subdomain.mysite.com"), + ... ])).add_extension( + ... x509.SubjectAlternativeName([ + ... # Describe what sites we want this certificate for. + ... x509.DNSName(u"mysite.com"), + ... x509.DNSName(u"www.mysite.com"), + ... x509.DNSName(u"subdomain.mysite.com"), + ... ]), + ... critical=False, ... # Sign the CSR with our private key. - ... ])).sign(key, hashes.SHA256(), default_backend()) + ... ).sign(key, hashes.SHA256(), default_backend()) >>> # Write our CSR out to disk. >>> with open("path/to/csr.pem", "wb") as f: ... f.write(csr.public_bytes(serialization.Encoding.PEM)) -- cgit v1.2.3 From 8d242c78255eb872f53c685230459a2670217e19 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 4 Sep 2015 14:08:10 -0500 Subject: fix a docs typo and convert it to a doctest to prevent future problems --- docs/fernet.rst | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index a066ae63..a2bab32a 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -115,28 +115,30 @@ password through a key derivation function such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`, bcrypt or scrypt. -.. code-block:: python - - import base64 - import os - - from cryptography.fernet import Fernet - from cryptography.hazmat.backends import default_backend - from cryptography.hazmat.primitives import hashes - from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC - - password = b"password" - salt = os.urandom(16) - - kdf = PBKDF2HMAC( - algorithm=hashes.SHA256(), - length=32, - salt=salt, - iterations=100000, - backend=default_backend - ) - key = base64.urlsafe_b64encode(kdf.derive(password)) - f = Fernet(key) +.. doctest:: + + >>> import base64 + >>> import os + >>> from cryptography.fernet import Fernet + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC + >>> password = b"password" + >>> salt = os.urandom(16) + >>> kdf = PBKDF2HMAC( + ... algorithm=hashes.SHA256(), + ... length=32, + ... salt=salt, + ... iterations=100000, + ... backend=default_backend() + ... ) + >>> key = base64.urlsafe_b64encode(kdf.derive(password)) + >>> f = Fernet(key) + >>> token = f.encrypt(b"Secret message!") + >>> token + '...' + >>> f.decrypt(token) + 'Secret message!' In this scheme, the salt has to be stored in a retrievable location in order to derive the same key from the password in the future. -- cgit v1.2.3 From 1e071ac064c1f9edf450c18836cd16e8f336a926 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 5 Sep 2015 16:30:25 -0500 Subject: rework OS X install docs to describe static/dynamic linking --- docs/installation.rst | 55 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/installation.rst b/docs/installation.rst index f7a88b98..277e021b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -118,38 +118,65 @@ build. Building cryptography on OS X ----------------------------- -Building cryptography requires the presence of a C compiler and development -headers. On OS X this is typically provided by Apple's Xcode development tools. -To install the Xcode command line tools on open a terminal window and run: +The wheel package on OS X is a statically linked build (as of 1.0.1) so for +users on 10.10 (Yosemite) and above you need two steps: .. code-block:: console $ xcode-select --install -This will install a compiler (clang) along with the required development -headers. If you wish to compile against a more recent OpenSSL than the -version shipped with OS X see the next section. +followed by -Using your own OpenSSL on OS X -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. code-block:: console + + $ pip install cryptography + +If you want to build cryptography yourself or are on an older OS X version +cryptography requires the presence of a C compiler, development headers, and +the proper libraries. On OS X much of this is provided by Apple's Xcode +development tools. To install the Xcode command line tools open a terminal +window and run: + +.. code-block:: console + + $ xcode-select --install + +This will install a compiler (clang) along with (most of) the required +development headers. + +You'll also need OpenSSL, which you can obtain from `Homebrew`_ or `MacPorts`_. + +To build cryptography and dynamically link it: + +`Homebrew`_ + +.. code-block:: console + + $ brew install openssl + $ env LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include" pip install cryptography + +`MacPorts`_: + +.. code-block:: console + + $ sudo port install openssl + $ env LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography -To link cryptography against a custom version of OpenSSL you'll need to set -``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via -`Homebrew`_ or `MacPorts`_: +You can also build cryptography statically: `Homebrew`_ .. code-block:: console $ brew install openssl - $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include" pip install cryptography + $ env CRYPTOGRAPHY_OSX_NO_LINK_FLAGS=1 LDFLAGS="$(brew --prefix openssl)/lib/libssl.a $(brew --prefix openssl)/lib/libcrypto.a" CFLAGS="-I$(brew --prefix openssl)/include" pip install cryptography -or `MacPorts`_: +`MacPorts`_: .. code-block:: console $ sudo port install openssl - $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography + $ env CRYPTOGRAPHY_OSX_NO_LINK_FLAGS=1 LDFLAGS="/opt/local/lib/libssl.a /opt/local/lib/libcrypto.a" CFLAGS="-I/opt/local/include" pip install cryptography Building cryptography with conda -------------------------------- -- cgit v1.2.3