Commit a29f29f5 authored by Tristan Seligmann's avatar Tristan Seligmann

New upstream version 2.6.1

parent 66e2b735
......@@ -41,3 +41,4 @@ PGP key fingerprints are enclosed in parentheses.
* Jeremy Lainé <jeremy.laine@m4x.org>
* Denis Gladkikh <denis@gladkikh.email>
* John Pacific <me@johnpacific.com> (2CF6 0381 B5EF 29B7 D48C 2020 7BB9 71A0 E891 44D9)
* Marti Raudsepp <marti@juffo.org>
Changelog
=========
.. _v2-6-1:
2.6.1 - 2019-02-27
~~~~~~~~~~~~~~~~~~
* Resolved an error in our build infrastructure that broke our Python3 wheels
for macOS and Linux.
.. _v2-6:
2.6 - 2019-02-27
~~~~~~~~~~~~~~~~
* **BACKWARDS INCOMPATIBLE:** Removed
``cryptography.hazmat.primitives.asymmetric.utils.encode_rfc6979_signature``
and
``cryptography.hazmat.primitives.asymmetric.utils.decode_rfc6979_signature``,
which had been deprecated for nearly 4 years. Use
:func:`~cryptography.hazmat.primitives.asymmetric.utils.encode_dss_signature`
and
:func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`
instead.
* **BACKWARDS INCOMPATIBLE**: Removed ``cryptography.x509.Certificate.serial``,
which had been deprecated for nearly 3 years. Use
:attr:`~cryptography.x509.Certificate.serial_number` instead.
* Updated Windows, macOS, and ``manylinux1`` wheels to be compiled with
OpenSSL 1.1.1b.
* Added support for :doc:`/hazmat/primitives/asymmetric/ed448` when using
OpenSSL 1.1.1b or newer.
* Added support for :doc:`/hazmat/primitives/asymmetric/ed25519` when using
OpenSSL 1.1.1b or newer.
* :func:`~cryptography.hazmat.primitives.serialization.load_ssh_public_key` can
now load ``ed25519`` public keys.
* Add support for easily mapping an object identifier to its elliptic curve
class via
:func:`~cryptography.hazmat.primitives.asymmetric.ec.get_curve_for_oid`.
* Add support for OpenSSL when compiled with the ``no-engine``
(``OPENSSL_NO_ENGINE``) flag.
.. _v2-5:
2.5 - 2019-01-22
~~~~~~~~~~~~~~~~
* **BACKWARDS INCOMPATIBLE:** :term:`U-label` strings were deprecated in
version 2.1, but this version removes the default ``idna`` dependency as
well. If you still need this deprecated path please install cryptography
with the ``idna`` extra: ``pip install cryptography[idna]``.
* **BACKWARDS INCOMPATIBLE:** The minimum supported PyPy version is now 5.4.
* Numerous classes and functions have been updated to allow :term:`bytes-like`
types for keying material and passwords, including symmetric algorithms, AEAD
ciphers, KDFs, loading asymmetric keys, and one time password classes.
* Updated Windows, macOS, and ``manylinux1`` wheels to be compiled with
OpenSSL 1.1.1a.
* Added support for :class:`~cryptography.hazmat.primitives.hashes.SHA512_224`
and :class:`~cryptography.hazmat.primitives.hashes.SHA512_256` when using
OpenSSL 1.1.1.
* Added support for :class:`~cryptography.hazmat.primitives.hashes.SHA3_224`,
:class:`~cryptography.hazmat.primitives.hashes.SHA3_256`,
:class:`~cryptography.hazmat.primitives.hashes.SHA3_384`, and
:class:`~cryptography.hazmat.primitives.hashes.SHA3_512` when using OpenSSL
1.1.1.
* Added support for :doc:`/hazmat/primitives/asymmetric/x448` when using
OpenSSL 1.1.1.
* Added support for :class:`~cryptography.hazmat.primitives.hashes.SHAKE128`
and :class:`~cryptography.hazmat.primitives.hashes.SHAKE256` when using
OpenSSL 1.1.1.
* Added initial support for parsing PKCS12 files with
:func:`~cryptography.hazmat.primitives.serialization.pkcs12.load_key_and_certificates`.
* Added support for :class:`~cryptography.x509.IssuingDistributionPoint`.
* Added ``rfc4514_string()`` method to
:meth:`x509.Name <cryptography.x509.Name.rfc4514_string>`,
:meth:`x509.RelativeDistinguishedName
<cryptography.x509.RelativeDistinguishedName.rfc4514_string>`, and
:meth:`x509.NameAttribute <cryptography.x509.NameAttribute.rfc4514_string>`
to format the name or component an :rfc:`4514` Distinguished Name string.
* Added
:meth:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey.from_encoded_point`,
which immediately checks if the point is on the curve and supports compressed
points. Deprecated the previous method
:meth:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers.from_encoded_point`.
* Added :attr:`~cryptography.x509.ocsp.OCSPResponse.signature_hash_algorithm`
to ``OCSPResponse``.
* Updated :doc:`/hazmat/primitives/asymmetric/x25519` support to allow
additional serialization methods. Calling
:meth:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PublicKey.public_bytes`
with no arguments has been deprecated.
* Added support for encoding compressed and uncompressed points via
:meth:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey.public_bytes`. Deprecated the previous method
:meth:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers.encode_point`.
.. _v2-4-2:
2.4.2 - 2018-11-21
~~~~~~~~~~~~~~~~~~
* Updated Windows, macOS, and ``manylinux1`` wheels to be compiled with
OpenSSL 1.1.0j.
.. _v2-4-1:
2.4.1 - 2018-11-11
~~~~~~~~~~~~~~~~~~
* Fixed a build breakage in our ``manylinux1`` wheels.
.. _v2-4:
2.4 - 2018-11-11
~~~~~~~~~~~~~~~~
* **BACKWARDS INCOMPATIBLE:** Dropped support for LibreSSL 2.4.x.
* Deprecated OpenSSL 1.0.1 support. OpenSSL 1.0.1 is no longer supported by
the OpenSSL project. At this time there is no time table for dropping
support, however we strongly encourage all users to upgrade or install
``cryptography`` from a wheel.
* Added initial :doc:`OCSP </x509/ocsp>` support.
* Added support for :class:`~cryptography.x509.PrecertPoison`.
.. _v2-3-1:
2.3.1 - 2018-08-14
~~~~~~~~~~~~~~~~~~
* Updated Windows, macOS, and ``manylinux1`` wheels to be compiled with
OpenSSL 1.1.0i.
.. _v2-3:
2.3 - 2018-07-18
......@@ -11,6 +139,7 @@ Changelog
allowed tag truncation by default which can allow tag forgery in some cases.
The method now enforces the ``min_tag_length`` provided to the
:class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` constructor.
*CVE-2018-10903*
* Added support for Python 3.7.
* Added :meth:`~cryptography.fernet.Fernet.extract_timestamp` to get the
authenticated timestamp of a :doc:`Fernet </fernet>` token.
......
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
https://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
......@@ -193,7 +193,7 @@
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
......
......@@ -6,6 +6,8 @@ include LICENSE.APACHE
include LICENSE.BSD
include README.rst
include pyproject.toml
recursive-include docs *
recursive-include src/_cffi_src *.py *.c *.h
prune docs/_build
......
Metadata-Version: 2.1
Name: cryptography
Version: 2.3
Version: 2.6.1
Summary: cryptography is a package which provides cryptographic recipes and primitives to Python developers.
Home-page: https://github.com/pyca/cryptography
Author: The cryptography developers
......@@ -26,7 +26,7 @@ Description: pyca/cryptography
``cryptography`` is a package which provides cryptographic recipes and
primitives to Python developers. Our goal is for it to be your "cryptographic
standard library". It supports Python 2.7, Python 3.4+, and PyPy 5.3+.
standard library". It supports Python 2.7, Python 3.4+, and PyPy 5.4+.
``cryptography`` includes both high level recipes and low level interfaces to
common cryptographic algorithms such as symmetric ciphers, message digests, and
......@@ -101,7 +101,8 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Provides-Extra: idna
Provides-Extra: docstest
Provides-Extra: test
Provides-Extra: docs
Provides-Extra: pep8test
Provides-Extra: docs
Provides-Extra: test
......@@ -18,7 +18,7 @@ pyca/cryptography
``cryptography`` is a package which provides cryptographic recipes and
primitives to Python developers. Our goal is for it to be your "cryptographic
standard library". It supports Python 2.7, Python 3.4+, and PyPy 5.3+.
standard library". It supports Python 2.7, Python 3.4+, and PyPy 5.4+.
``cryptography`` includes both high level recipes and low level interfaces to
common cryptographic algorithms such as symmetric ciphers, message digests, and
......
......@@ -176,9 +176,9 @@ epub_theme = 'epub'
# Retry requests in the linkcheck builder so that we're resillient against
# transient network errors.
linkcheck_retries = 5
linkcheck_retries = 10
linkcheck_ignore = [
# Certificate is issued by a Japanese CA that isn't publicly trusted
"https://www.cryptrec.go.jp",
# Small DH key results in a TLS failure on modern OpenSSL
"https://info.isl.ntt.co.jp/crypt/eng/camellia/",
]
......@@ -191,7 +191,7 @@ version, and it's impractical to create ``#ifdef`` statements for each
one. In that case, it may make sense to either check for a particular
version. For example, to check for OpenSSL 1.1.0 or newer::
#if OPENSSL_VERSION_NUMBER >= 0x10100000L
#if CRYPTOGRAPHY_OPENSSL_110_OR_GREATER
Sometimes, the version of a library on a particular platform will have
features that you thought it wouldn't, based on its version.
......
......@@ -2,14 +2,14 @@ ARC4 vector creation
====================
This page documents the code that was used to generate the ARC4 test
vectors for key lengths not available in RFC 6229. All the vectors
vectors for key lengths not available in :rfc:`6229`. All the vectors
were generated using OpenSSL and verified with Go.
Creation
--------
``cryptography`` was modified to support ARC4 key lengths not listed
in RFC 6229. Then the following Python script was run to generate the
in :rfc:`6229`. Then the following Python script was run to generate the
vector files.
.. literalinclude:: /development/custom-vectors/arc4/generate_arc4.py
......
......@@ -2,7 +2,7 @@ HKDF vector creation
====================
This page documents the code that was used to generate a longer
HKDF test vector (1200 bytes) than is available in RFC 5869. All
HKDF test vector (1200 bytes) than is available in :rfc:`5869`. All
the vectors were generated using OpenSSL and verified with Go.
Creation
......
......@@ -19,6 +19,10 @@ mode. For example:
$ pip install --requirement dev-requirements.txt
$ pip install --editable .
Make sure that ``pip install --requirement ...`` has installed the Python
package ``vectors/`` and packages on ``tests/`` . If it didn't, you may
install them manually by using ``pip`` on each directory.
You will also need to install ``enchant`` using your system's package manager
to check spelling in the documentation.
......@@ -111,5 +115,5 @@ The HTML documentation index can now be found at
.. _`virtualenv`: https://pypi.org/project/virtualenv/
.. _`pip`: https://pypi.org/project/pip/
.. _`sphinx`: https://pypi.org/project/Sphinx/
.. _`reStructured Text`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
.. _`reStructured Text`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
.. _`this Github issue`: https://github.com/rfk/pyenchant/issues/42
......@@ -17,4 +17,4 @@ bug check out `what to put in your bug report`_.
c-bindings
.. _`GitHub`: https://github.com/pyca/cryptography
.. _`what to put in your bug report`: http://www.contribution-guide.org/#what-to-put-in-your-bug-report
.. _`what to put in your bug report`: https://www.contribution-guide.org/#what-to-put-in-your-bug-report
......@@ -155,7 +155,7 @@ So, specifically:
.. _`Write comments as complete sentences.`: https://nedbatchelder.com/blog/201401/comments_should_be_sentences.html
.. _`syntax`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
.. _`syntax`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
.. _`Studies have shown`: https://smartbear.com/SmartBear/media/pdfs/11_Best_Practices_for_Peer_Code_Review.pdf
.. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
.. _`doc8`: https://github.com/openstack/doc8
This diff is collapsed.
......@@ -3,6 +3,20 @@ Doing a release
Doing a release of ``cryptography`` requires a few steps.
Security Releases
-----------------
In addition to the other steps described below, for a release which fixes a
security vulnerability, you should also include the following steps:
* Request a `CVE from MITRE`_. Once you have received the CVE, it should be
included in the :doc:`changelog`. Ideally you should request the CVE before
starting the release process so that the CVE is available at the time of the
release.
* Ensure that the :doc:`changelog` entry credits whoever reported the issue.
* The release should be announced on the `oss-security`_ mailing list, in
addition to the regular announcement lists.
Verifying OpenSSL version
-------------------------
......@@ -78,6 +92,8 @@ Post-release tasks
* Send an email to the `mailing list`_ and `python-announce`_ announcing the
release.
.. _`CVE from MITRE`: https://cveform.mitre.org/
.. _`oss-security`: https://www.openwall.com/lists/oss-security/
.. _`upgrading OpenSSL issue template`: https://github.com/pyca/cryptography/issues/new?template=openssl-release.md
.. _`milestone`: https://github.com/pyca/cryptography/milestones
.. _`mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
......
......@@ -22,7 +22,8 @@ features a collection of hand selected algorithms.
``cryptography``'s :ref:`recipes <cryptography-layout>` layer has similar goals
to NaCl.
If you prefer NaCl's design, we highly recommend `PyNaCl`_.
If you prefer NaCl's design, we highly recommend `PyNaCl`_, which is also
maintained by the PyCA team.
Why use ``cryptography``?
-------------------------
......@@ -55,11 +56,6 @@ If you are using PyPy, we do not currently ship ``cryptography`` wheels for
PyPy. You will need to install your own copy of OpenSSL -- we recommend using
Homebrew.
Starting ``cryptography`` using ``mod_wsgi`` produces an ``InternalError`` during a call in ``_register_osrandom_engine``
-------------------------------------------------------------------------------------------------------------------------
Upgrade to the latest ``cryptography`` and this issue should be resolved.
``cryptography`` raised an ``InternalError`` and I'm not sure what to do?
-------------------------------------------------------------------------
......@@ -70,11 +66,6 @@ If you have no other libraries using OpenSSL in your process, or they do not
appear to be at fault, it's possible that this is a bug in ``cryptography``.
Please file an `issue`_ with instructions on how to reproduce it.
Installing ``cryptography`` fails with ``ImportError: No module named setuptools_ext``
--------------------------------------------------------------------------------------
Your ``cffi`` package is out of date. ``pip install -U cffi`` to update it.
error: ``-Werror=sign-conversion``: No option ``-Wsign-conversion`` during installation
---------------------------------------------------------------------------------------
......@@ -97,9 +88,61 @@ Installing cryptography with OpenSSL 0.9.8 or 1.0.0 fails
The OpenSSL project has dropped support for the 0.9.8 and 1.0.0 release series.
Since they are no longer receiving security patches from upstream,
``cryptography`` is also dropping support for them. To fix this issue you
should upgrade to a newer version of OpenSSL (1.0.1 or later). This may require
should upgrade to a newer version of OpenSSL (1.0.2 or later). This may require
you to upgrade to a newer operating system.
Why are there no wheels for Python 3.5+ on Linux or macOS?
----------------------------------------------------------
Our Python3 wheels, for macOS and Linux, are ``abi3`` wheels. This means they
support multiple versions of Python. The Python 3.4 ``abi3`` wheel can be used
with any version of Python greater than or equal to 3.4. Recent versions of
``pip`` will automatically install ``abi3`` wheels.
``ImportError``: ``idna`` is not installed
------------------------------------------
``cryptography`` deprecated passing :term:`U-label` strings to various X.509
constructors in version 2.1 and in version 2.5 moved the ``idna`` dependency
to a ``setuptools`` extra. If you see this exception you should upgrade your
software so that it no longer depends on this deprecated feature. If that is
not yet possible you can also install ``cryptography`` with
``pip install cryptography[idna]`` to automatically install the missing
dependency. This workaround will be available until the feature is fully
removed.
Why can't I import my PEM file?
-------------------------------
PEM is a format (defined by several RFCs, but originally :rfc:`1421`) for
encoding keys, certificates and others cryptographic data into a regular form.
The data is encoded as base64 and wrapped with a header and footer.
If you are having trouble importing PEM files, make sure your file fits
the following rules:
* has a one-line header like this: ``-----BEGIN [FILE TYPE]-----``
(where ``[FILE TYPE]`` is ``CERTIFICATE``, ``PUBLIC KEY``, ``PRIVATE KEY``,
etc.)
* has a one-line footer like this: ``-----END [FILE TYPE]-----``
* all lines, except for the final one, must consist of exactly 64
characters.
For example, this is a PEM file for a RSA Public Key: ::
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7CsKFSzq20NLb2VQDXma
9DsDXtKADv0ziI5hT1KG6Bex5seE9pUoEcUxNv4uXo2jzAUgyRweRl/DLU8SoN8+
WWd6YWik4GZvNv7j0z28h9Q5jRySxy4dmElFtIRHGiKhqd1Z06z4AzrmKEzgxkOk
LJjY9cvwD+iXjpK2oJwNNyavvjb5YZq6V60RhpyNtKpMh2+zRLgIk9sROEPQeYfK
22zj2CnGBMg5Gm2uPOsGDltl/I/Fdh1aO3X4i1GXwCuPf1kSAg6lPJD0batftkSG
v0X0heUaV0j1HSNlBWamT4IR9+iJfKJHekOqvHQBcaCu7Ja4kXzx6GZ3M2j/Ja3A
2QIDAQAB
-----END PUBLIC KEY-----
.. _`NaCl`: https://nacl.cr.yp.to/
.. _`PyNaCl`: https://pynacl.readthedocs.io
.. _`WSGIApplicationGroup`: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIApplicationGroup.html
......
......@@ -94,6 +94,11 @@ Glossary
bit key, you can calculate the number of bytes by dividing by 8. 128
divided by 8 is 16, so a 128 bit key is a 16 byte key.
bytes-like
A bytes-like object contains binary data and supports the
`buffer protocol`_. This includes ``bytes``, ``bytearray``, and
``memoryview`` objects.
U-label
The presentational unicode form of an internationalized domain
name. U-labels use unicode characters outside the ASCII range and
......@@ -101,3 +106,4 @@ Glossary
.. _`hardware security module`: https://en.wikipedia.org/wiki/Hardware_security_module
.. _`idna`: https://pypi.org/project/idna/
.. _`buffer protocol`: https://docs.python.org/3/c-api/buffer.html
......@@ -106,7 +106,7 @@ seeded from the same pool as ``/dev/random``.
+------------------------------------------+------------------------------+
| Windows | ``CryptGenRandom()`` |
+------------------------------------------+------------------------------+
| Linux >= 3.4.17 with working | ``getrandom(GRND_NONBLOCK)`` |
| Linux >= 3.17 with working | ``getrandom(GRND_NONBLOCK)`` |
| ``SYS_getrandom`` syscall | |
+------------------------------------------+------------------------------+
| OpenBSD >= 5.6 | ``getentropy()`` |
......@@ -123,4 +123,4 @@ seeded from the same pool as ``/dev/random``.
.. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_private_keys_.28Debian-specific.29
.. _`Fortuna`: https://en.wikipedia.org/wiki/Fortuna_(PRNG)
.. _`Yarrow`: https://en.wikipedia.org/wiki/Yarrow_algorithm
.. _`Microsoft documentation`: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx
.. _`Microsoft documentation`: https://docs.microsoft.com/en-us/windows/desktop/api/wincrypt/nf-wincrypt-cryptgenrandom
......@@ -33,16 +33,15 @@ OpenSSL version 1.0.1 and greater.
Threading
---------
``cryptography`` enables OpenSSLs `thread safety facilities`_ in two different
ways depending on the configuration of your system. Normally the locking
callbacks provided by your Python implementation specifically for OpenSSL will
be used. However, if you have linked ``cryptography`` to a different version of
OpenSSL than that used by your Python implementation we enable an alternative
locking callback. This version is implemented in Python and so may result in
lower performance in some situations. In particular parallelism is reduced
because it has to acquire the GIL whenever any lock operations occur within
OpenSSL.
``cryptography`` enables OpenSSLs `thread safety facilities`_ in several
different ways depending on the configuration of your system. For users on
OpenSSL 1.1.0 or newer (including anyone who uses a binary wheel) the OpenSSL
internal locking callbacks are automatically used. Otherwise, we first attempt
to use the callbacks provided by your Python implementation specifically for
OpenSSL. This will work in every case except where ``cryptography`` is linked
against a different version of OpenSSL than the one used by your Python
implementation. For this final case we have a C-based locking callback.
.. _`CFFI`: https://cffi.readthedocs.io
.. _`OpenSSL`: https://www.openssl.org/
.. _`thread safety facilities`: https://www.openssl.org/docs/man1.0.2/crypto/threads.html
.. _`thread safety facilities`: https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_THREADID_set_callback.html
......@@ -18,7 +18,8 @@ also support providing integrity for associated data which is not encrypted.
It is a stream cipher combined with a MAC that offers strong integrity
guarantees.
:param bytes key: A 32-byte key. This **must** be kept secret.
:param key: A 32-byte key. This **must** be kept secret.
:type key: :term:`bytes-like`
:raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
OpenSSL does not support ChaCha20Poly1305.
......@@ -53,8 +54,8 @@ also support providing integrity for associated data which is not encrypted.
``associated_data``. The output of this can be passed directly
to the ``decrypt`` method.
:param bytes nonce: A 12 byte value. **NEVER REUSE A NONCE** with a
key.
:param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to encrypt.
:param bytes associated_data: Additional data that should be
authenticated with the key, but does not need to be encrypted. Can
......@@ -69,8 +70,9 @@ also support providing integrity for associated data which is not encrypted.
called encrypt with ``associated_data`` you must pass the same
``associated_data`` in decrypt or the integrity check will fail.
:param bytes nonce: A 12 byte value. **NEVER REUSE A NONCE** with a
:param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a
key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to decrypt (with tag appended).
:param bytes associated_data: Additional data to authenticate. Can be
``None`` if none was passed during encryption.
......@@ -88,7 +90,8 @@ also support providing integrity for associated data which is not encrypted.
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
cipher utilizing Galois Counter Mode (GCM).
:param bytes key: A 128, 192, or 256-bit key. This **must** be kept secret.
:param key: A 128, 192, or 256-bit key. This **must** be kept secret.
:type key: :term:`bytes-like`
.. doctest::
......@@ -123,9 +126,10 @@ also support providing integrity for associated data which is not encrypted.
authenticating the ``associated_data``. The output of this can be
passed directly to the ``decrypt`` method.
:param bytes nonce: NIST `recommends a 96-bit IV length`_ for best
:param nonce: NIST `recommends a 96-bit IV length`_ for best
performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to encrypt.
:param bytes associated_data: Additional data that should be
authenticated with the key, but is not encrypted. Can be ``None``.
......@@ -139,9 +143,10 @@ also support providing integrity for associated data which is not encrypted.
called encrypt with ``associated_data`` you must pass the same
``associated_data`` in decrypt or the integrity check will fail.
:param bytes nonce: NIST `recommends a 96-bit IV length`_ for best
:param nonce: NIST `recommends a 96-bit IV length`_ for best
performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to decrypt (with tag appended).
:param bytes associated_data: Additional data to authenticate. Can be
``None`` if none was passed during encryption.
......@@ -165,11 +170,12 @@ also support providing integrity for associated data which is not encrypted.
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
cipher utilizing Counter with CBC-MAC (CCM) (specified in :rfc:`3610`).
:param bytes key: A 128, 192, or 256-bit key. This **must** be kept secret.
:param key: A 128, 192, or 256-bit key. This **must** be kept secret.
:type key: :term:`bytes-like`
:param int tag_length: The length of the authentication tag. This
defaults to 16 bytes and it is **strongly** recommended that you
do not make it shorter unless absolutely necessary. Valid tag
lengths are 4, 6, 8, 12, 14, and 16.
lengths are 4, 6, 8, 10, 12, 14, and 16.
:raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
OpenSSL does not support AES-CCM.
......@@ -207,11 +213,12 @@ also support providing integrity for associated data which is not encrypted.
authenticating the ``associated_data``. The output of this can be
passed directly to the ``decrypt`` method.
:param bytes nonce: A value of between 7 and 13 bytes. The maximum
:param nonce: A value of between 7 and 13 bytes. The maximum
length is determined by the length of the ciphertext you are
encrypting and must satisfy the condition:
``len(data) < 2 ** (8 * (15 - len(nonce)))``
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to encrypt.
:param bytes associated_data: Additional data that should be
authenticated with the key, but is not encrypted. Can be ``None``.
......@@ -225,9 +232,10 @@ also support providing integrity for associated data which is not encrypted.
called encrypt with ``associated_data`` you must pass the same
``associated_data`` in decrypt or the integrity check will fail.
:param bytes nonce: A value of between 7 and 13 bytes. This
:param nonce: A value of between 7 and 13 bytes. This
is the same value used when you originally called encrypt.
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to decrypt (with tag appended).
:param bytes associated_data: Additional data to authenticate. Can be
``None`` if none was passed during encryption.
......
......@@ -23,6 +23,56 @@ derivation function. This allows mixing of additional information into the
key, derivation of multiple keys, and destroys any structure that may be
present.
.. warning::
This example does not give `forward secrecy`_ and is only provided as a
demonstration of the basic Diffie-Hellman construction. For real world
applications always use the ephemeral form described after this example.
.. code-block:: pycon
>>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import dh
>>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
>>> # Generate some parameters. These can be reused.
>>> parameters = dh.generate_parameters(generator=2, key_size=2048,
... backend=default_backend())
>>> # Generate a private key for use in the exchange.
>>> server_private_key = parameters.generate_private_key()
>>> # In a real handshake the peer is a remote client. For this
>>> # example we'll generate another local private key though. Note that in
>>> # a DH handshake both peers must agree on a common set of parameters.
>>> peer_private_key = parameters.generate_private_key()
>>> shared_key = server_private_key.exchange(peer_private_key.public_key())
>>> # Perform key derivation.
>>> derived_key = HKDF(
... algorithm=hashes.SHA256(),
... length=32,
... salt=None,
... info=b'handshake data',
... backend=default_backend()
... ).derive(shared_key)
>>> # And now we can demonstrate that the handshake performed in the
>>> # opposite direction gives the same final value
>>> same_shared_key = peer_private_key.exchange(
... server_private_key.public_key()
... )
>>> same_derived_key = HKDF(
... algorithm=hashes.SHA256(),
... length=32,
... salt=None,
... info=b'handshake data',
... backend=default_backend()
... ).derive(same_shared_key)
>>> derived_key == same_derived_key
DHE (or EDH), the ephemeral form of this exchange, is **strongly
preferred** over simple DH and provides `forward secrecy`_ when used. You must
generate a new private key using :func:`~DHParameters.generate_private_key` for
each :meth:`~DHPrivateKey.exchange` when performing an DHE key exchange. An
example of the ephemeral form:
.. code-block:: pycon
>>> from cryptography.hazmat.backends import default_backend
......@@ -61,12 +111,6 @@ present.
... backend=default_backend()
... ).derive(shared_key_2)
DHE (or EDH), the ephemeral form of this exchange, is **strongly
preferred** over simple DH and provides `forward secrecy`_ when used. You must
generate a new private key using :func:`~DHParameters.generate_private_key` for
each :meth:`~DHPrivateKey.exchange` when performing an DHE key exchange. This
is demonstrated in the previous example.
To assemble a :class:`~DHParameters` and a :class:`~DHPublicKey` from
primitive integers, you must first create the
:class:`~DHParameterNumbers` and :class:`~DHPublicNumbers` objects. For
......
......@@ -444,4 +444,4 @@ Key interfaces
.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm
.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
.. _`FIPS 186-4`: https://csrc.nist.gov/publications/detail/fips/186/4/final
.. _`at least 2048`: http://www.ecrypt.eu.org/ecrypt2/documents/D.SPA.20.pdf
.. _`at least 2048`: https://www.cosic.esat.kuleuven.be/ecrypt/ecrypt2/documents/D.SPA.20.pdf
This diff is collapsed.
.. hazmat::
Ed25519 signing
===============
.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ed25519
Ed25519 is an elliptic curve signing algorithm using `EdDSA`_ and
`Curve25519`_. If you do not have legacy interoperability concerns then you
should strongly consider using this signature algorithm.
Signing & Verification
~~~~~~~~~~~~~~~~~~~~~~
.. doctest::
>>> from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
>>> private_key = Ed25519PrivateKey.generate()
>>> signature = private_key.sign(b"my authenticated message")
>>> public_key = private_key.public_key()
>>> # Raises InvalidSignature if verification fails
>>> public_key.verify(signature, b"my authenticated message")
Key interfaces
~~~~~~~~~~~~~~