diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/test-vectors.rst | 12 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/key-exchange-agreements.rst | 23 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/index.rst | 2 | ||||
| -rw-r--r-- | docs/installation.rst | 81 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 3 | ||||
| -rw-r--r-- | docs/x509/reference.rst | 9 |
8 files changed, 108 insertions, 25 deletions
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index 0495cc77..bfe76330 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -148,6 +148,9 @@ Custom X.509 Vectors certificate containing a subject alternative name extension with the following general names: ``rfc822Name``, ``dNSName``, ``iPAddress``, ``directoryName``, and ``uniformResourceIdentifier``. +* ``san_empty_hostname.pem`` - An RSA 2048 bit self-signed certificate + containing a subject alternative extension with an empty ``dNSName`` + general name. * ``san_other_name.pem`` - An RSA 2048 bit self-signed certificate containing a subject alternative name extension with the ``otherName`` general name. * ``san_registered_id.pem`` - An RSA 1024 bit certificate containing a @@ -193,6 +196,9 @@ Custom X.509 Vectors containing an authority information access extension with an OCSP entry. * ``aia_ca_issuers.pem`` - An RSA 2048 bit self-signed certificate containing an authority information access extension with a CA issuers entry. +* ``cdp_empty_hostname.pem`` - An RSA 2048 bit self-signed certificate + containing a CRL distribution point extension with ``fullName`` URI without + a hostname. * ``cdp_fullname_reasons_crl_issuer.pem`` - An RSA 1024 bit certificate containing a CRL distribution points extension with ``fullName``, ``cRLIssuer``, and ``reasons`` data. @@ -248,6 +254,8 @@ Custom X.509 Vectors policy constraints extension with an inhibit policy mapping element. * ``pc_require.pem`` - An RSA 2048 bit self-signed certificate containing a policy constraints extension with a require explicit policy element. +* ``unsupported_subject_public_key_info.pem`` - A certificate whose public key + is an unknown OID (``1.3.6.1.4.1.8432.1.1.2``). Custom X.509 Request Vectors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -396,14 +404,14 @@ header format (substituting the correct information): .. _`IETF`: https://www.ietf.org/ .. _`NIST CAVP`: http://csrc.nist.gov/groups/STM/cavp/ .. _`Bruce Schneier's vectors`: https://www.schneier.com/code/vectors.txt -.. _`Camellia page`: http://info.isl.ntt.co.jp/crypt/eng/camellia/ +.. _`Camellia page`: https://info.isl.ntt.co.jp/crypt/eng/camellia/ .. _`CRYPTREC`: http://www.cryptrec.go.jp .. _`OpenSSL's test vectors`: https://github.com/openssl/openssl/blob/97cf1f6c2854a3a955fd7dd3a1f113deba00c9ef/crypto/evp/evptests.txt#L232 .. _`RIPEMD website`: http://homes.esat.kuleuven.be/~bosselae/ripemd160.html .. _`Whirlpool website`: http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html .. _`draft RFC`: https://tools.ietf.org/html/draft-josefsson-scrypt-kdf-01 .. _`Specification repository`: https://github.com/fernet/spec -.. _`errata`: http://www.rfc-editor.org/errata_search.php?rfc=6238 +.. _`errata`: https://www.rfc-editor.org/errata_search.php?rfc=6238 .. _`OpenSSL example key`: https://github.com/openssl/openssl/blob/d02b48c63a58ea4367a0e905979f140b7d090f86/test/testrsa.pem .. _`GnuTLS key parsing tests`: https://gitlab.com/gnutls/gnutls/commit/f16ef39ef0303b02d7fa590a37820440c466ce8d .. _`enc-rsa-pkcs8.pem`: https://gitlab.com/gnutls/gnutls/blob/f8d943b38bf74eaaa11d396112daf43cb8aa82ae/tests/pkcs8-decode/encpkcs8.pem diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index a67ea47f..f88750cf 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -652,4 +652,4 @@ Key interfaces .. _`Chinese Remainder Theorem`: https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29#Using_the_Chinese_remainder_algorithm .. _`security proof`: http://eprint.iacr.org/2001/062.pdf .. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -.. _`proven secure`: http://cseweb.ucsd.edu/~mihir/papers/oae.pdf +.. _`proven secure`: https://cseweb.ucsd.edu/~mihir/papers/oae.pdf diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index a9ab38a0..675111bb 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -15,3 +15,4 @@ Primitives constant-time interfaces twofactor + key-exchange-agreements diff --git a/docs/hazmat/primitives/key-exchange-agreements.rst b/docs/hazmat/primitives/key-exchange-agreements.rst new file mode 100644 index 00000000..8d79fbad --- /dev/null +++ b/docs/hazmat/primitives/key-exchange-agreements.rst @@ -0,0 +1,23 @@ +.. hazmat:: + +Key Exchange agreements +======================= + +.. module:: cryptography.hazmat.primitives.asymmetric.key_exchange + +Key exchange agreements are cryptographic operations, like Diffie-Hellman +key exchanges, that allow two parties to use their public-private key pairs +to establish a shared secret key over an insecure channel. Usually the +negotiated key is further derived before using it for symmetric operations. + +Interfaces +~~~~~~~~~~ + +.. class:: KeyExchangeContext + + .. versionadded:: 1.1 + + .. method:: agree(public_key) + + :param public_key: The peer public key, the type depends on the + crypto system used, for example :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey` diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst index bc54bae4..05db708c 100644 --- a/docs/hazmat/primitives/mac/index.rst +++ b/docs/hazmat/primitives/mac/index.rst @@ -9,7 +9,7 @@ recommend that HMAC should be used unless you have a good reason otherwise. For more information on why HMAC is preferred, see `Use cases for CMAC vs. HMAC?`_ -.. _`Use cases for CMAC vs. HMAC?`: http://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac +.. _`Use cases for CMAC vs. HMAC?`: https://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac .. toctree:: :maxdepth: 1 diff --git a/docs/installation.rst b/docs/installation.rst index 2f978852..5d629e9f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -15,24 +15,24 @@ Currently we test ``cryptography`` on Python 2.6, 2.7, 3.3, 3.4, 3.5, and PyPy * x86-64 CentOS 7.x, 6.4 and CentOS 5.x * x86-64 FreeBSD 10 -* OS X 10.10 Yosemite, 10.9 Mavericks, 10.8 Mountain Lion, and 10.7 Lion -* x86-64 Ubuntu 12.04 LTS -* x86-64 Debian Wheezy (7.x) and Jessie (8.x) -* 32-bit Python on 64-bit Windows Server 2008 -* 64-bit Python on 64-bit Windows Server 2012 +* OS X 10.11 El Capitan, 10.10 Yosemite, 10.9 Mavericks, 10.8 Mountain Lion, + and 10.7 Lion +* x86-64 Ubuntu 12.04 LTS and Ubuntu 14.04 LTS +* x86-64 Debian Wheezy (7.x), Jessie (8.x), and Debian Sid (unstable) +* 32-bit and 64-bit Python on 64-bit Windows Server 2012 We test compiling with ``clang`` as well as ``gcc`` and use the following OpenSSL releases: * ``OpenSSL 0.9.8e-fips-rhel5`` (``RHEL/CentOS 5``) * ``OpenSSL 0.9.8k`` -* ``OpenSSL 0.9.8za`` +* ``OpenSSL 0.9.8-latest`` (The most recent 0.9.8 release) * ``OpenSSL 1.0.0-fips`` (``RHEL/CentOS 6.4``) * ``OpenSSL 1.0.1`` * ``OpenSSL 1.0.1e-fips`` (``RHEL/CentOS 7``) * ``OpenSSL 1.0.1j-freebsd`` -* ``OpenSSL 1.0.1-latest`` (The most recent 1.0.1 release) -* ``OpenSSL 1.0.2`` +* ``OpenSSL 1.0.1f`` +* ``OpenSSL 1.0.2-latest`` On Windows ---------- @@ -58,6 +58,8 @@ to include the proper locations. For example: C:\> pip install cryptography +.. _build-on-linux: + Building cryptography on Linux ------------------------------ @@ -115,17 +117,62 @@ You'll also need to generate your own ``openssl.ld`` file. For example:: You should replace the version string on the first line as appropriate for your build. -Building cryptography on OS X ------------------------------ - -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: +Static Wheels +~~~~~~~~~~~~~ + +Cryptography ships statically-linked wheels for OS X and Windows, ensuring that +these platforms can always use the most-recent OpenSSL, regardless of what is +shipped by default on those platforms. As a result of various difficulties +around Linux binary linking, Cryptography cannot do the same on Linux. + +However, you can build your own statically-linked wheels that will work on your +own systems. This will allow you to continue to use relatively old Linux +distributions (such as LTS releases), while making sure you have the most +recent OpenSSL available to your Python programs. + +To do so, you should find yourself a machine that is as similar as possible to +your target environment (e.g. your production environment): for example, spin +up a new cloud server running your target Linux distribution. On this machine, +install the Cryptography dependencies as mentioned in :ref:`build-on-linux`. +Please also make sure you have `virtualenv`_ installed: this should be +available from your system package manager. + +Then, paste the following into a shell script. You'll need to populate the +``OPENSSL_VERSION`` variable. To do that, visit `openssl.org`_ and find the +latest non-FIPS release version number, then set the string appropriately. For +example, for OpenSSL 1.0.2d, use ``OPENSSL_VERSION="1.0.2d"``. + +When this shell script is complete, you'll find a collection of wheel files in +a directory called ``wheelhouse``. These wheels can be installed by a +sufficiently-recent version of ``pip``. The Cryptography wheel in this +directory contains a statically-linked OpenSSL binding, which ensures that you +have access to the most-recent OpenSSL releases without corrupting your system +dependencies. .. code-block:: console - $ xcode-select --install + set -e -followed by + OPENSSL_VERSION="VERSIONGOESHERE" + CWD=$(pwd) + + virtualenv env + . env/bin/activate + pip install -U setuptools + pip install -U wheel pip + curl -O https://openssl.org/source/openssl-${OPENSSL_VERSION}.tar.gz + tar xvf openssl-${OPENSSL_VERSION}.tar.gz + cd openssl-${OPENSSL_VERSION} + ./config no-shared no-ssl2 -fPIC --prefix=${CWD}/openssl + make && make install + cd .. + CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel cryptography + +Building cryptography on OS X +----------------------------- + +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 only need one step: .. code-block:: console @@ -202,8 +249,10 @@ information, consult `Greg Wilson's blog post`_ on the subject. .. _`Homebrew`: http://brew.sh -.. _`MacPorts`: http://www.macports.org +.. _`MacPorts`: https://www.macports.org .. _`32-bit`: https://jenkins.cryptography.io/job/openssl-win32-release/ .. _`64-bit`: https://jenkins.cryptography.io/job/openssl-win64-release/ .. _`bug in conda`: https://github.com/conda/conda-recipes/issues/110 .. _`Greg Wilson's blog post`: http://software-carpentry.org/blog/2014/04/mr-biczo-was-right.html +.. _virtualenv: https://virtualenv.pypa.io/en/latest/ +.. _openssl.org: https://openssl.org/source/ diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 16aa5ef2..dc8bcd0b 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -6,6 +6,7 @@ Backends Blowfish boolean Botan +Capitan Changelog ciphertext committer @@ -27,7 +28,9 @@ Django Encodings fernet Fernet +FIPS hazmat +hostname indistinguishability initialisms interoperable diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 67591d38..eec0cbcc 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -592,9 +592,8 @@ X.509 Certificate Builder Adds an X.509 extension to the certificate. - :param extension: The extension to add to the certificate. Can be one - of :class:`~cryptography.x509.BasicConstraints` or - :class:`~cryptography.x509.SubjectAlternativeName`. + :param extension: An extension conforming to the + :class:`~cryptography.x509.ExtensionType` interface. :param critical: Set to ``True`` if the extension must be understood and handled by whoever reads the certificate. @@ -780,8 +779,8 @@ X.509 CSR (Certificate Signing Request) Builder Object .. method:: add_extension(extension, critical) - :param extension: The :class:`~cryptography.x509.Extension` to add to - the request. + :param extension: An extension conforming to the + :class:`~cryptography.x509.ExtensionType` interface. :param critical: Set to `True` if the extension must be understood and handled by whoever reads the certificate. :returns: A new |