Commit 84a8cc88 authored by Tristan Seligmann's avatar Tristan Seligmann

Import python-cryptography_2.0.3.orig.tar.gz

parent 4005c5bd
Changelog
=========
2.0.3 - 2017-08-03
~~~~~~~~~~~~~~~~~~
* Fixed an issue with weak linking symbols when compiling on macOS
versions older than 10.12.
2.0.2 - 2017-07-27
~~~~~~~~~~~~~~~~~~
* Marked all symbols as hidden in the ``manylinux1`` wheel to avoid a
bug with symbol resolution in certain scenarios.
2.0.1 - 2017-07-26
~~~~~~~~~~~~~~~~~~
* Fixed a compilation bug affecting OpenBSD.
* Altered the ``manylinux1`` wheels to statically link OpenSSL instead of
dynamically linking and bundling the shared object. This should resolve
crashes seen when using ``uwsgi`` or other binaries that link against
OpenSSL independently.
* Fixed the stack level for the ``signer`` and ``verifier`` warnings.
2.0 - 2017-07-17
~~~~~~~~~~~~~~~~
* **BACKWARDS INCOMPATIBLE:** Support for Python 3.3 has been dropped.
* We now ship ``manylinux1`` wheels linked against OpenSSL 1.1.0f. These wheels
will be automatically used with most Linux distributions if you are running
the latest pip.
* Deprecated the use of ``signer`` on
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`,
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
and
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`
in favor of ``sign``.
* Deprecated the use of ``verifier`` on
:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`,
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`,
and
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
in favor of ``verify``.
* Added support for parsing
:class:`~cryptography.x509.certificate_transparency.SignedCertificateTimestamp`
objects from X.509 certificate extensions.
* Added support for
:class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305`.
* Added support for
:class:`~cryptography.hazmat.primitives.ciphers.aead.AESCCM`.
* Added
:class:`~cryptography.hazmat.primitives.ciphers.aead.AESGCM`, a "one shot"
API for AES GCM encryption.
* Added support for :doc:`/hazmat/primitives/asymmetric/x25519`.
* Added support for serializing and deserializing Diffie-Hellman parameters
with
:func:`~cryptography.hazmat.primitives.serialization.load_pem_parameters`,
:func:`~cryptography.hazmat.primitives.serialization.load_der_parameters`,
and
:meth:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters.parameter_bytes`
.
* The ``extensions`` attribute on :class:`~cryptography.x509.Certificate`,
:class:`~cryptography.x509.CertificateSigningRequest`,
:class:`~cryptography.x509.CertificateRevocationList`, and
:class:`~cryptography.x509.RevokedCertificate` now caches the computed
``Extensions`` object. There should be no performance change, just a
performance improvement for programs accessing the ``extensions`` attribute
multiple times.
1.9 - 2017-05-29
~~~~~~~~~~~~~~~~
......@@ -64,9 +131,9 @@ Changelog
to
:class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKeyWithSerialization`.
* Added
:meth:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKeyWithSerialization.public_bytes`
:meth:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey.public_bytes`
to
:class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKeyWithSerialization`.
:class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey`.
* :func:`~cryptography.hazmat.primitives.serialization.load_pem_private_key`
and
:func:`~cryptography.hazmat.primitives.serialization.load_der_private_key`
......@@ -613,12 +680,9 @@ Changelog
:class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`
was moved from ``cryptography.hazmat.primitives.interfaces`` to
:mod:`~cryptography.hazmat.primitives.asymmetric.padding`.
*
:class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext`
and
:class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext`
* ``AsymmetricSignatureContext`` and ``AsymmetricVerificationContext``
were moved from ``cryptography.hazmat.primitives.interfaces`` to
:mod:`~cryptography.hazmat.primitives.asymmetric`.
``cryptography.hazmat.primitives.asymmetric``.
* :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters`,
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParametersWithNumbers`,
:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`,
......
Metadata-Version: 1.1
Name: cryptography
Version: 1.9
Version: 2.0.3
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.6-2.7, Python 3.3+, and PyPy 5.3+.
standard library". It supports Python 2.6-2.7, Python 3.4+, and PyPy 5.3+.
``cryptography`` includes both high level recipes and low level interfaces to
common cryptographic algorithms such as symmetric ciphers, message digests, and
......@@ -86,7 +86,6 @@ Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
......
......@@ -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.6-2.7, Python 3.3+, and PyPy 5.3+.
standard library". It supports Python 2.6-2.7, Python 3.4+, and PyPy 5.3+.
``cryptography`` includes both high level recipes and low level interfaces to
common cryptographic algorithms such as symmetric ciphers, message digests, and
......
......@@ -176,7 +176,7 @@ epub_theme = 'epub'
# Retry requests in the linkcheck builder so that we're resillient against
# transient network errors.
linkcheck_retries = 2
linkcheck_retries = 5
linkcheck_ignore = [
# Certificate is issued by a Japanese CA that isn't publicly trusted
......
......@@ -128,9 +128,7 @@ opaque struct::
...;
} QM_TRANSMOGRIFICATION_CTX;
Confusingly, functions that aren't always available on all supported
versions of the library, should be defined in ``MACROS`` and *not* in
``FUNCTIONS``. Fortunately, you just have to copy the signature::
For functions just add the signature to ``FUNCTIONS``::
int QM_transmogrify(QM_TRANSMOGRIFICATION_CTX *, int);
......@@ -169,15 +167,22 @@ the necessarily type definitions are in place.
Finally, add an entry to ``CONDITIONAL_NAMES`` with all of the things
you want to conditionally export::
CONDITIONAL_NAMES = {
...
"Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION": [
def cryptography_has_quantum_transmogrification():
return [
"QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT",
"QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT",
"QM_transmogrify"
"QM_transmogrify",
]
CONDITIONAL_NAMES = {
...
"Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION": (
cryptography_has_quantum_transmogrification
),
}
Caveats
~~~~~~~
......
......@@ -35,6 +35,7 @@ Asymmetric ciphers
* `Botan's ECC private keys`_.
* `asymmetric/public/PKCS1/dsa.pub.pem`_ is a PKCS1 DSA public key from the
Ruby test suite.
* X25519 test vectors from :rfc:`7748`.
Custom asymmetric vectors
......@@ -88,6 +89,9 @@ Custom asymmetric vectors
Key exchange
~~~~~~~~~~~~
* ``vectors/cryptography_vectors/asymmetric/DH/rfc3526.txt`` contains
several standardized Diffie-Hellman groups from :rfc:`3526`.
* ``vectors/cryptography_vectors/asymmetric/DH/RFC5114.txt`` contains
Diffie-Hellman examples from appendix A.1, A.2 and A.3 of :rfc:`5114`.
......@@ -407,7 +411,7 @@ Recipes
Symmetric ciphers
~~~~~~~~~~~~~~~~~
* AES (CBC, CFB, ECB, GCM, OFB) from `NIST CAVP`_.
* AES (CBC, CFB, ECB, GCM, OFB, CCM) from `NIST CAVP`_.
* AES CTR from :rfc:`3686`.
* 3DES (CBC, CFB, ECB, OFB) from `NIST CAVP`_.
* ARC4 (KEY-LENGTH: 40, 56, 64, 80, 128, 192, 256) from :rfc:`6229`.
......@@ -419,6 +423,8 @@ Symmetric ciphers
* CAST5 (ECB) from :rfc:`2144`.
* CAST5 (CBC, CFB, OFB) generated by this project.
See: :doc:`/development/custom-vectors/cast5`
* ChaCha20Poly1305 from :rfc:`7539`, `OpenSSL's evpciph.txt`_, and the
`BoringSSL ChaCha20Poly1305 tests`_.
* IDEA (ECB) from the `NESSIE IDEA vectors`_ created by `NESSIE`_.
* IDEA (CBC, CFB, OFB) generated by this project.
See: :doc:`/development/custom-vectors/idea`
......@@ -476,6 +482,8 @@ header format (substituting the correct information):
.. _`Camellia page`: https://info.isl.ntt.co.jp/crypt/eng/camellia/
.. _`CRYPTREC`: https://www.cryptrec.go.jp
.. _`OpenSSL's test vectors`: https://github.com/openssl/openssl/blob/97cf1f6c2854a3a955fd7dd3a1f113deba00c9ef/crypto/evp/evptests.txt#L232
.. _`OpenSSL's evpciph.txt`: https://github.com/openssl/openssl/blob/5a7bc0be97dee9ac715897fe8180a08e211bc6ea/test/evpciph.txt#L2362
.. _`BoringSSL ChaCha20Poly1305 tests`: https://boringssl.googlesource.com/boringssl/+/2e2a226ac9201ac411a84b5e79ac3a7333d8e1c9/crypto/cipher_extra/test/chacha20_poly1305_tests.txt
.. _`RIPEMD website`: https://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
......
......@@ -6,9 +6,11 @@ Doing a release of ``cryptography`` requires a few steps.
Verifying and upgrading OpenSSL version
---------------------------------------
The release process uses a static build for Windows and macOS wheels. Check
that the Windows and macOS Jenkins builders have the latest version of OpenSSL
installed before performing the release. If they do not:
The release process creates wheels bundling OpenSSL for Windows, macOS, and
Linux. Check that the Windows and macOS Jenkins builders have the latest
version of OpenSSL installed and verify that the latest version is present in
the ``pyca/cryptography-manylinux1`` docker containers. If anything is out
of date:
Upgrading Windows
~~~~~~~~~~~~~~~~~
......@@ -21,6 +23,13 @@ Upgrading macOS
Run the ``update-brew-openssl`` Jenkins job.
Upgrading ``manylinux1`` docker containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Send a pull request to the ``pyca/infra`` project updating the version and
file hash in ``cryptography-manylinux1/install_openssl.sh``. Once this is
merged the updated image will be available to the wheel builder.
Bumping the version number
--------------------------
......
Frequently asked questions
==========================
``cryptography`` failed to install!
-----------------------------------
If you are having issues installing ``cryptography`` the first troubleshooting
step is to upgrade ``pip`` and then try to install again. For most users this will
take the form of ``pip install -U pip``, but on Windows you should do
``python -m pip install -U pip``. If you are still seeing errors after upgrading
and trying ``pip install cryptography`` again, please see the :doc:`/installation`
documentation.
How does ``cryptography`` compare to NaCl (Networking and Cryptography Library)?
--------------------------------------------------------------------------------
......@@ -28,7 +38,6 @@ legacy libraries:
* Lack of maintenance.
* Lack of high level APIs.
* Lack of PyPy and Python 3 support.
* Poor introspectability and thus poor testability.
* Absence of algorithms such as
:class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and
:class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
......
......@@ -37,6 +37,9 @@ has support for implementing key rotation via :class:`MultiFernet`.
.. method:: encrypt(data)
Encrypts data passed. The result of this encryption is known as a
"Fernet token" and has strong privacy and authenticity guarantees.
:param bytes data: The message you would like to encrypt.
:returns bytes: A secure message that cannot be read or altered
without the key. It is URL-safe base64-encoded. This is
......@@ -52,6 +55,11 @@ has support for implementing key rotation via :class:`MultiFernet`.
.. method:: decrypt(token, ttl=None)
Decrypts a Fernet token. If successfully decrypted you will receive the
original plaintext as the result, otherwise an exception will be
raised. It is safe to use this data immediately as Fernet verifies
that the data has not been tampered with prior to returning it.
: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
......
......@@ -72,3 +72,12 @@ Glossary
or pseudo-random number (see :doc:`Random number generation
</random-numbers>`). Since a nonce does not have to be unpredictable,
it can also take a form of a counter.
opaque key
An opaque key is a type of key that allows you to perform cryptographic
operations such as encryption, decryption, signing, and verification,
but does not allow access to the key itself. Typically an opaque key is
loaded from a `hardware security module`_ (HSM).
.. _`hardware security module`: https://en.wikipedia.org/wiki/Hardware_security_module
......@@ -452,6 +452,15 @@ A specific ``backend`` may provide one or more of these interfaces.
serialized data contains.
:raises ValueError: If the data could not be deserialized.
.. method:: load_pem_parameters(data)
.. versionadded:: 2.0
:param bytes data: PEM data to load.
:return: A new instance of the appropriate type of asymmetric
parameters the serialized data contains.
:raises ValueError: If the data could not be deserialized.
.. class:: DERSerializationBackend
.. versionadded:: 0.8
......@@ -476,6 +485,16 @@ A specific ``backend`` may provide one or more of these interfaces.
serialized data contains.
:raises ValueError: If the data could not be deserialized.
.. method:: load_der_parameters(data)
.. versionadded:: 2.0
:param bytes data: DER data to load.
:return: A new instance of the appropriate type of asymmetric
parameters the serialized data contains.
:raises ValueError: If the data could not be deserialized.
.. class:: X509Backend
.. versionadded:: 0.7
......
......@@ -92,8 +92,9 @@ When importing only the binding it is added to the engine list but
OS random sources
-----------------
On macOS and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and
utilizes the `Yarrow`_ algorithm.
On macOS and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random``. The
implementation on macOS uses the `Yarrow`_ algorithm. FreeBSD uses the
`Fortuna`_ algorithm.
On Windows the implementation of ``CryptGenRandom`` depends on which version of
the operation system you are using. See the `Microsoft documentation`_ for more
......@@ -120,5 +121,6 @@ seeded from the same pool as ``/dev/random``.
.. _`OpenSSL`: https://www.openssl.org/
.. _`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
.. hazmat::
Authenticated encryption
========================
.. module:: cryptography.hazmat.primitives.ciphers.aead
Authenticated encryption with associated data (AEAD) are encryption schemes
which provide both confidentiality and integrity for their ciphertext. They
also support providing integrity for associated data which is not encrypted.
.. class:: ChaCha20Poly1305(key)
.. versionadded:: 2.0
The ChaCha20Poly1305 construction is defined in :rfc:`7539` section 2.8.
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.
:raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
OpenSSL does not support ChaCha20Poly1305.
.. doctest::
>>> import os
>>> from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
>>> data = b"a secret message"
>>> aad = b"authenticated but unencrypted data"
>>> key = ChaCha20Poly1305.generate_key()
>>> chacha = ChaCha20Poly1305(key)
>>> nonce = os.urandom(12)
>>> ct = chacha.encrypt(nonce, data, aad)
>>> chacha.decrypt(nonce, ct, aad)
'a secret message'
.. classmethod:: generate_key()
Securely generates a random ChaCha20Poly1305 key.
:returns bytes: A 32 byte key.
.. method:: encrypt(nonce, data, associated_data)
.. warning::
Reuse of a ``nonce`` with a given ``key`` compromises the security
of any message with that ``nonce`` and ``key`` pair.
Encrypts the ``data`` provided and authenticates the
``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 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
be ``None``.
:returns bytes: The ciphertext bytes with the 16 byte tag appended.
.. method:: decrypt(nonce, data, associated_data)
Decrypts the ``data`` and authenticates the ``associated_data``. If you
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
key.
: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.
:returns bytes: The original plaintext.
:raises cryptography.exceptions.InvalidTag: If the authentication tag
doesn't validate this exception will be raised. This will occur
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
.. class:: AESGCM(key)
.. versionadded:: 2.0
The AES-GCM construction is composed of the
: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.
.. doctest::
>>> import os
>>> from cryptography.hazmat.primitives.ciphers.aead import AESGCM
>>> data = b"a secret message"
>>> aad = b"authenticated but unencrypted data"
>>> key = AESGCM.generate_key(bit_length=128)
>>> aesgcm = AESGCM(key)
>>> nonce = os.urandom(12)
>>> ct = aesgcm.encrypt(nonce, data, aad)
>>> aesgcm.decrypt(nonce, ct, aad)
'a secret message'
.. classmethod:: generate_key(bit_length)
Securely generates a random AES-GCM key.
:param bit_length: The bit length of the key to generate. Must be
128, 192, or 256.
:returns bytes: The generated key.
.. method:: encrypt(nonce, data, associated_data)
.. warning::
Reuse of a ``nonce`` with a given ``key`` compromises the security
of any message with that ``nonce`` and ``key`` pair.
Encrypts and authenticates the ``data`` provided as well as
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
performance but it can be up to 2\ :sup:`64` - 1 bits.
**NEVER REUSE A NONCE** with a key.
: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``.
:returns bytes: The ciphertext bytes with the 16 byte tag appended.
.. method:: decrypt(nonce, data, associated_data)
Decrypts the ``data`` and authenticates the ``associated_data``. If you
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
performance but it can be up to 2\ :sup:`64` - 1 bits.
**NEVER REUSE A NONCE** with a key.
: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.
:returns bytes: The original plaintext.
:raises cryptography.exceptions.InvalidTag: If the authentication tag
doesn't validate this exception will be raised. This will occur
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
.. class:: AESCCM(key, tag_length=16)
.. versionadded:: 2.0
.. note:
AES-CCM is provided largely for compatibility with existing protocols.
Due to its construction it is not as computationally efficient as
other AEAD ciphers.
The AES-CCM construction is composed of the
: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 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.
:raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
OpenSSL does not support AES-CCM.
.. doctest::
>>> import os
>>> from cryptography.hazmat.primitives.ciphers.aead import AESCCM
>>> data = b"a secret message"
>>> aad = b"authenticated but unencrypted data"
>>> key = AESCCM.generate_key(bit_length=128)
>>> aesccm = AESCCM(key)
>>> nonce = os.urandom(13)
>>> ct = aesccm.encrypt(nonce, data, aad)
>>> aesccm.decrypt(nonce, ct, aad)
'a secret message'
.. classmethod:: generate_key(bit_length)
Securely generates a random AES-CCM key.
:param bit_length: The bit length of the key to generate. Must be
128, 192, or 256.
:returns bytes: The generated key.
.. method:: encrypt(nonce, data, associated_data)
.. warning::
Reuse of a ``nonce`` with a given ``key`` compromises the security
of any message with that ``nonce`` and ``key`` pair.
Encrypts and authenticates the ``data`` provided as well as
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
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.
: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``.
:returns bytes: The ciphertext bytes with the tag appended.
.. method:: decrypt(nonce, data, associated_data)
Decrypts the ``data`` and authenticates the ``associated_data``. If you
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
is the same value used when you originally called encrypt.
**NEVER REUSE A NONCE** with a key.
: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.
:returns bytes: The original plaintext.
:raises cryptography.exceptions.InvalidTag: If the authentication tag
doesn't validate this exception will be raised. This will occur
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
.. _`recommends a 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf
......@@ -102,18 +102,37 @@ Group parameters
:return: An instance of
:class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`.
.. method:: parameter_numbers()
.. class:: DHParametersWithSerialization
Return the numbers that make up this set of parameters.
.. versionadded:: 0.9
:return: A :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers`.
Inherits from :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`.
.. method:: parameter_bytes(encoding, format)
.. method:: parameter_numbers()
.. versionadded:: 2.0
Return the numbers that make up this set of parameters.
Allows serialization of the parameters to bytes. Encoding (
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or
:attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`) and
format (
:attr:`~cryptography.hazmat.primitives.serialization.ParameterFormat.PKCS3`)
are chosen to define the exact serialization.
:return: A :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers`.
:param encoding: A value from the
:class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
:param format: A value from the
:class:`~cryptography.hazmat.primitives.serialization.ParameterFormat`
enum. At the moment only ``PKCS3`` is supported.
:return bytes: Serialized parameters.
.. class:: DHParametersWithSerialization
.. versionadded:: 0.9
Alias for :class:`DHParameters`.
Key interfaces
......@@ -123,6 +142,9 @@ Key interfaces
.. versionadded:: 0.9
A DH private key that is not an :term:`opaque key` also implements
:class:`DHPrivateKeyWithSerialization` to provide serialization methods.
.. attribute:: key_size
The bit length of the prime modulus.
......@@ -143,7 +165,7 @@ Key interfaces
.. versionadded:: 1.7
:param DHPublicKeyWithSerialization peer_public_key: The public key for
:param DHPublicKey peer_public_key: The public key for
the peer.
:return bytes: The agreed key. The bytes are ordered in 'big' endian.
......@@ -153,8 +175,9 @@ Key interfaces
.. versionadded:: 0.9
Inherits from
:class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`.
This interface contains additional methods relating to serialization.
Any object with this interface also has all the methods from
:class:`DHPrivateKey`.
.. method:: private_numbers()
......@@ -204,13 +227,6 @@ Key interfaces
:return: A :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`.
.. class:: DHPublicKeyWithSerialization
.. versionadded:: 0.9
Inherits from :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey`.
.. method:: public_numbers()
Return the numbers that make up this public key.
......@@ -236,6 +252,12 @@ Key interfaces
:return bytes: Serialized key.
.. class:: DHPublicKeyWithSerialization
.. versionadded:: 0.9
Alias for :class:`DHPublicKey`.
Numbers
~~~~~~~
......@@ -256,7 +278,7 @@ Numbers
:type: int
The generator value. Must be 2 or 5 (Unless q is given).
The generator value. Must be 2 or greater.
.. attribute:: q
......@@ -266,6 +288,15 @@ Numbers
p subgroup order value.
.. method:: parameters(backend)
.. versionadded:: 1.7
:param backend: An instance of
:class:`~cryptography.hazmat.backends.interfaces.DHBackend`.
:returns: A new instance of :class:`DHParameters`.
.. class:: DHPrivateNumbers(x, public_numbers)
.. versionadded:: 0.8
......@@ -285,6 +316,15 @@ Numbers
The private value.