diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/fernet.rst | 44 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 8 | ||||
| -rw-r--r-- | docs/installation.rst | 55 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 2 | ||||
| -rw-r--r-- | docs/x509/tutorial.rst | 19 |
5 files changed, 101 insertions, 27 deletions
diff --git a/docs/fernet.rst b/docs/fernet.rst index eacbc2ae..a2bab32a 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`. @@ -106,6 +106,47 @@ 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 such as +:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`, bcrypt or +scrypt. + +.. 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. + +The iteration count used should be adjusted to be as high as your server can +tolerate. A good default is at least 100,000 iterations which is what Django +`recommends`_ in 2014. + Implementation -------------- @@ -125,3 +166,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 diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 323f4c3f..01671d44 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -126,9 +126,9 @@ 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`_. +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 @@ -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 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 -------------------------------- diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 1eed7c7a..75497840 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -1,6 +1,7 @@ affine backend backends +bcrypt Backends Blowfish boolean @@ -22,6 +23,7 @@ deserialize deserialized Diffie Docstrings +Django Encodings fernet Fernet diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index 6e587d8b..0fa061a2 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, @@ -67,15 +67,18 @@ 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", "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. |