From 06f360feedb740aa0b4db7683d02accd14bc1732 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 12 Oct 2015 11:00:30 -0500 Subject: add some links to public key loading in the RSA/DSA verification sections --- docs/hazmat/primitives/asymmetric/dsa.rst | 8 ++++++-- docs/hazmat/primitives/asymmetric/rsa.rst | 10 +++++++--- 2 files changed, 13 insertions(+), 5 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 4eb17e30..9431ff57 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -86,8 +86,12 @@ described in :rfc:`3279`. This can be decoded using Verification ~~~~~~~~~~~~ -Using a :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` -provider. +Verification is performed using a +:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` provider. +Public keys are obtained by using +:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`, +:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, or +:meth:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.public_key`. .. doctest:: diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index f88750cf..de8b2fd0 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -163,9 +163,13 @@ Verification ~~~~~~~~~~~~ The previous section describes what to do if you have a private key and want to -sign something. If you have a public key, a message, and a signature, you can -check that the public key genuinely was used to sign that specific message. You -also need to know which signing algorithm was used: +sign something. If you have a public key, a message, a signature, and the +signing algorithm that was used you can check that the private key associated +with a given public key was used to sign that specific message. You can obtain +a public key to use in verification using +:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`, +:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, or +:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey.public_key`. .. doctest:: -- cgit v1.2.3 From 3697db262cb5f9c61840139f37c34e24c3dfb7d1 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 12 Oct 2015 12:42:08 -0500 Subject: address review comments --- docs/hazmat/primitives/asymmetric/dsa.rst | 6 ++++-- docs/hazmat/primitives/asymmetric/rsa.rst | 4 +++- 2 files changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 9431ff57..1429cb09 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -88,9 +88,11 @@ Verification Verification is performed using a :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` provider. -Public keys are obtained by using +You can get a public key object with :func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`, -:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, or +:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, +:meth:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers.public_key` +, or :meth:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.public_key`. .. doctest:: diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index de8b2fd0..bc2402de 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -168,7 +168,9 @@ signing algorithm that was used you can check that the private key associated with a given public key was used to sign that specific message. You can obtain a public key to use in verification using :func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`, -:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, or +:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`, +:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers.public_key` +, or :meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey.public_key`. .. doctest:: -- cgit v1.2.3 From e6abbfd2ad055b8be81c49a1d9cd4c01a890dd55 Mon Sep 17 00:00:00 2001 From: Simo Sorce Date: Thu, 15 Oct 2015 22:58:52 -0400 Subject: Kill Key Exchange as a separate interface Ultimately it was decided that ECDH and the others can be implemented as simple classes without the overhead of an interface. So ... let's kill it, it was a fun process. Signed-off-by: Simo Sorce --- docs/hazmat/primitives/index.rst | 1 - docs/hazmat/primitives/key-exchange-agreements.rst | 23 ---------------------- 2 files changed, 24 deletions(-) delete mode 100644 docs/hazmat/primitives/key-exchange-agreements.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 675111bb..a9ab38a0 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -15,4 +15,3 @@ 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 deleted file mode 100644 index 8d79fbad..00000000 --- a/docs/hazmat/primitives/key-exchange-agreements.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. 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` -- cgit v1.2.3 From 0d6a74ea07a599371faddc2e33d746484dbaf92b Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 17 Oct 2015 09:33:27 -0500 Subject: make it clearer when PEM and DER encoding support was added --- docs/hazmat/primitives/asymmetric/serialization.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 8d51f0d7..6d354dff 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -337,8 +337,6 @@ Serialization Encodings .. class:: Encoding - .. versionadded:: 0.8 - An enumeration for encoding types. Used with the ``private_bytes`` method available on :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization` @@ -353,10 +351,14 @@ Serialization Encodings .. attribute:: PEM + .. versionadded:: 0.8 + For PEM format. This is a base64 format with delimiters. .. attribute:: DER + .. versionadded :: 0.9 + For DER format. This is a binary format. -- cgit v1.2.3 From 943c7a8dc0d047c43109331ba79fa7b7bed36c03 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 17 Oct 2015 09:52:55 -0500 Subject: fix extra space --- docs/hazmat/primitives/asymmetric/serialization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 6d354dff..f14f4037 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -357,7 +357,7 @@ Serialization Encodings .. attribute:: DER - .. versionadded :: 0.9 + .. versionadded:: 0.9 For DER format. This is a binary format. -- cgit v1.2.3 From 9aaeee0dc62189204f38097c815a0913fabe006c Mon Sep 17 00:00:00 2001 From: Simo Sorce Date: Thu, 30 Apr 2015 14:06:47 -0400 Subject: Add an Elliptic Curve Key Exchange Algorithm(ECDH) The ECDH Key Exchange algorithm as standardized in NIST publication 800-56A Revision 2 Includes tests with vectors from NIST. Signed-off-by: Simo Sorce --- docs/hazmat/primitives/asymmetric/ec.rst | 44 ++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 6356c278..910ce5d8 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -122,6 +122,48 @@ Elliptic Curve Signature Algorithms :returns: A new instance of a :class:`EllipticCurvePublicKey` provider. +Elliptic Curve Key Exchange algorithm +------------------------------------- + +.. class:: ECDH(private_key) + + .. versionadded:: 1.1 + + The ECDH Key Exchange algorithm first standardized in NIST publication + `800-56A`_, and later in `800-56Ar2`_. + + :param private_key: An instance of :class:`EllipticCurvePrivateKey`. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives.asymmetric import ec + >>> private_key = ec.generate_private_key( + ... ec.SECP384R1(), default_backend() + ... ) + >>> peer_public_key = ec.generate_private_key( + ... ec.SECP384R1(), default_backend() + ... ).public_key() + >>> ecdh = ec.ECDH(private_key) + >>> sharedkey = ecdh.compute_key(peer_public_key) + + .. attribute:: private_key + + :type: :class:`EllipticCurvePrivateKey` + + The private key associated to this object + + .. method:: public_key() + + The public key associated to the object's private key. + + .. method:: compute_key(peer_public_key) + + :param peer_public_key: A :class:`EllipticCurvePublicKey` object. + + :returns: A ``bytes`` object containing the computed key. + + Elliptic Curves --------------- @@ -419,6 +461,8 @@ Key Interfaces .. _`FIPS 186-3`: http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf +.. _`800-56A`: http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf +.. _`800-56Ar2`: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.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 .. _`elliptic curve diffie-hellman is faster than diffie-hellman`: http://digitalcommons.unl.edu/cgi/viewcontent.cgi?article=1100&context=cseconfwork -- cgit v1.2.3 From 5cdfba5c8d06ed10510310de03e1df0265a89bcc Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 17 Oct 2015 16:33:04 -0400 Subject: a refactor to the API --- docs/hazmat/primitives/asymmetric/ec.rst | 27 ++++----------------------- 1 file changed, 4 insertions(+), 23 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 910ce5d8..9b2e61fb 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -125,14 +125,12 @@ Elliptic Curve Signature Algorithms Elliptic Curve Key Exchange algorithm ------------------------------------- -.. class:: ECDH(private_key) +.. class:: ECDH() .. versionadded:: 1.1 - The ECDH Key Exchange algorithm first standardized in NIST publication - `800-56A`_, and later in `800-56Ar2`_. - - :param private_key: An instance of :class:`EllipticCurvePrivateKey`. + The Elliptic Curve Diffie-Hellman Key Exchange algorithm first standardized + in NIST publication `800-56A`_, and later in `800-56Ar2`_. .. doctest:: @@ -144,24 +142,7 @@ Elliptic Curve Key Exchange algorithm >>> peer_public_key = ec.generate_private_key( ... ec.SECP384R1(), default_backend() ... ).public_key() - >>> ecdh = ec.ECDH(private_key) - >>> sharedkey = ecdh.compute_key(peer_public_key) - - .. attribute:: private_key - - :type: :class:`EllipticCurvePrivateKey` - - The private key associated to this object - - .. method:: public_key() - - The public key associated to the object's private key. - - .. method:: compute_key(peer_public_key) - - :param peer_public_key: A :class:`EllipticCurvePublicKey` object. - - :returns: A ``bytes`` object containing the computed key. + >>> shared_key = private_key.exchange(ec.ECDH(), peer_public_key) Elliptic Curves -- cgit v1.2.3 From 68b3441d90fa4230b62d19a43c49dd2aa155db47 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 17 Oct 2015 18:09:03 -0400 Subject: better document hte iface --- docs/hazmat/primitives/asymmetric/ec.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 9b2e61fb..525bd6cb 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -132,6 +132,9 @@ Elliptic Curve Key Exchange algorithm The Elliptic Curve Diffie-Hellman Key Exchange algorithm first standardized in NIST publication `800-56A`_, and later in `800-56Ar2`_. + For most applications the ``shared_key`` should be passed to a key + derivation function. + .. doctest:: >>> from cryptography.hazmat.backends import default_backend @@ -337,6 +340,22 @@ Key Interfaces :returns: :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` + .. method:: exchange(algorithm, peer_public_key) + + Perform's a key exchange operation using the provided algorithm with + the peer's public key. + + For most applications the result should be passed to a key derivation + function. + + :param algorithm: The key exchange algorithm, currently only + :class:`~cryptography.hazmat.primitives.asymmetric.ec.ECDH` is + supported. + :param EllipticCurvePublicKey peer_public_key: The public key for the + peer. + + :returns bytes: A shared key. + .. method:: public_key() :return: :class:`EllipticCurvePublicKey` -- cgit v1.2.3 From cb87f62eed3dee7fcc903f545652623e41bda50a Mon Sep 17 00:00:00 2001 From: simo5 Date: Sat, 17 Oct 2015 16:49:40 -0400 Subject: Fix EC's generate_private_key param name The first parameter is curve, not backend Signed-off-by: Simo Sorce --- docs/hazmat/primitives/asymmetric/ec.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 6356c278..7c67229c 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -12,7 +12,7 @@ Elliptic curve cryptography Generate a new private key on ``curve`` for use with ``backend``. - :param backend: A :class:`EllipticCurve` provider. + :param curve: A :class:`EllipticCurve` provider. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend` -- cgit v1.2.3