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 ++++++++++ src/cryptography/exceptions.py | 1 + src/cryptography/hazmat/backends/interfaces.py | 6 ++ src/cryptography/hazmat/backends/multibackend.py | 6 ++ .../hazmat/backends/openssl/backend.py | 20 +++++ .../hazmat/primitives/asymmetric/ec.py | 25 ++++++ tests/hazmat/backends/test_multibackend.py | 12 ++- tests/hazmat/backends/test_openssl.py | 14 ++++ tests/hazmat/primitives/test_ec.py | 94 +++++++++++++++++++++- 9 files changed, 219 insertions(+), 3 deletions(-) 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 diff --git a/src/cryptography/exceptions.py b/src/cryptography/exceptions.py index 29be22be..3bf8a75b 100644 --- a/src/cryptography/exceptions.py +++ b/src/cryptography/exceptions.py @@ -20,6 +20,7 @@ class _Reasons(Enum): UNSUPPORTED_ELLIPTIC_CURVE = 6 UNSUPPORTED_SERIALIZATION = 7 UNSUPPORTED_X509 = 8 + UNSUPPORTED_EXCHANGE_ALGORITHM = 9 class UnsupportedAlgorithm(Exception): diff --git a/src/cryptography/hazmat/backends/interfaces.py b/src/cryptography/hazmat/backends/interfaces.py index a43621a7..faa0b313 100644 --- a/src/cryptography/hazmat/backends/interfaces.py +++ b/src/cryptography/hazmat/backends/interfaces.py @@ -215,6 +215,12 @@ class EllipticCurveBackend(object): Return an EllipticCurvePublicKey provider using the given numbers. """ + @abc.abstractmethod + def elliptic_curve_exchange_algorithm_supported(self): + """ + Returns whether the exchange algorithm is supported by this backend. + """ + @six.add_metaclass(abc.ABCMeta) class PEMSerializationBackend(object): diff --git a/src/cryptography/hazmat/backends/multibackend.py b/src/cryptography/hazmat/backends/multibackend.py index 9db32aa5..77a45ccd 100644 --- a/src/cryptography/hazmat/backends/multibackend.py +++ b/src/cryptography/hazmat/backends/multibackend.py @@ -271,6 +271,12 @@ class MultiBackend(object): _Reasons.UNSUPPORTED_ELLIPTIC_CURVE ) + def elliptic_curve_exchange_algorithm_supported(self): + return any( + b.elliptic_curve_exchange_algorithm_supported() + for b in self._filtered_backends(EllipticCurveBackend) + ) + def load_pem_private_key(self, data, password): for b in self._filtered_backends(PEMSerializationBackend): return b.load_pem_private_key(data, password) diff --git a/src/cryptography/hazmat/backends/openssl/backend.py b/src/cryptography/hazmat/backends/openssl/backend.py index 0d3b3dd4..d82f3834 100644 --- a/src/cryptography/hazmat/backends/openssl/backend.py +++ b/src/cryptography/hazmat/backends/openssl/backend.py @@ -1671,6 +1671,26 @@ class Backend(object): return _EllipticCurvePublicKey(self, ec_cdata, evp_pkey) + def elliptic_curve_exchange_algorithm_supported(self): + return (self._lib.Cryptography_HAS_EC == 1 and + self._lib.Cryptography_HAS_ECDH == 1) + + def ecdh_compute_key(self, private_key, peer_public_key): + pri_key = private_key._ec_key + pub_key = peer_public_key._ec_key + + group = self._lib.EC_KEY_get0_group(pri_key) + z_len = (self._lib.EC_GROUP_get_degree(group) + 7) // 8 + self.openssl_assert(z_len > 0) + z_buf = self._ffi.new("uint8_t[]", z_len) + peer_key = self._lib.EC_KEY_get0_public_key(pub_key) + + r = self._lib.ECDH_compute_key(z_buf, z_len, + peer_key, pri_key, + self._ffi.NULL) + self.openssl_assert(r > 0) + return self._ffi.buffer(z_buf)[:z_len] + def _ec_cdata_to_evp_pkey(self, ec_cdata): evp_pkey = self._lib.EVP_PKEY_new() self.openssl_assert(evp_pkey != self._ffi.NULL) diff --git a/src/cryptography/hazmat/primitives/asymmetric/ec.py b/src/cryptography/hazmat/primitives/asymmetric/ec.py index f1d39eed..978a7c41 100644 --- a/src/cryptography/hazmat/primitives/asymmetric/ec.py +++ b/src/cryptography/hazmat/primitives/asymmetric/ec.py @@ -8,6 +8,7 @@ import abc import six +from cryptography import exceptions from cryptography import utils @@ -302,3 +303,27 @@ class EllipticCurvePrivateNumbers(object): def __ne__(self, other): return not self == other + + +class ECDH(object): + def __init__(self, private_key): + if not isinstance(private_key, EllipticCurvePrivateKey): + raise TypeError("Private Key must be a EllipticCurvePrivateKey") + self._private_key = private_key + self._backend = private_key._backend + if not self._backend.elliptic_curve_exchange_algorithm_supported(): + raise exceptions.UnsupportedAlgorithm( + "This backend does not support the ECDH algorithm.", + exceptions._Reasons.UNSUPPORTED_EXCHANGE_ALGORITHM + ) + + private_key = utils.read_only_property("_private_key") + + def public_key(self): + return self._private_key.public_key() + + def compute_key(self, peer_public_key): + if not isinstance(peer_public_key, EllipticCurvePublicKey): + raise TypeError("Peer Public Key must be a EllipticCurvePublicKey") + return self._backend.ecdh_compute_key(self._private_key, + peer_public_key) diff --git a/tests/hazmat/backends/test_multibackend.py b/tests/hazmat/backends/test_multibackend.py index 4d17cdb0..57aa7f44 100644 --- a/tests/hazmat/backends/test_multibackend.py +++ b/tests/hazmat/backends/test_multibackend.py @@ -138,8 +138,9 @@ class DummyCMACBackend(object): @utils.register_interface(EllipticCurveBackend) class DummyEllipticCurveBackend(object): - def __init__(self, supported_curves): + def __init__(self, supported_curves, exchange_supported): self._curves = supported_curves + self.exchange_supported = exchange_supported def elliptic_curve_supported(self, curve): return any( @@ -170,6 +171,9 @@ class DummyEllipticCurveBackend(object): if not self.elliptic_curve_supported(numbers.curve): raise UnsupportedAlgorithm(_Reasons.UNSUPPORTED_ELLIPTIC_CURVE) + def elliptic_curve_exchange_algorithm_supported(self): + return self.exchange_supported + @utils.register_interface(PEMSerializationBackend) class DummyPEMSerializationBackend(object): @@ -400,7 +404,7 @@ class TestMultiBackend(object): backend = MultiBackend([ DummyEllipticCurveBackend([ ec.SECT283K1 - ]) + ], True) ]) assert backend.elliptic_curve_supported(ec.SECT283K1()) is True @@ -462,6 +466,10 @@ class TestMultiBackend(object): ) ) + assert backend.elliptic_curve_exchange_algorithm_supported() is True + backend2 = MultiBackend([DummyEllipticCurveBackend([], False)]) + assert backend2.elliptic_curve_exchange_algorithm_supported() is False + def test_pem_serialization_backend(self): backend = MultiBackend([DummyPEMSerializationBackend()]) diff --git a/tests/hazmat/backends/test_openssl.py b/tests/hazmat/backends/test_openssl.py index 8fd0d711..13162046 100644 --- a/tests/hazmat/backends/test_openssl.py +++ b/tests/hazmat/backends/test_openssl.py @@ -534,6 +534,11 @@ class DummyLibrary(object): Cryptography_HAS_EC = 0 +class DummyLibraryECDH(object): + Cryptography_HAS_EC = 1 + Cryptography_HAS_ECDH = 0 + + class TestOpenSSLEllipticCurve(object): def test_elliptic_curve_supported(self, monkeypatch): monkeypatch.setattr(backend, "_lib", DummyLibrary()) @@ -551,6 +556,15 @@ class TestOpenSSLEllipticCurve(object): with raises_unsupported_algorithm(_Reasons.UNSUPPORTED_ELLIPTIC_CURVE): _sn_to_elliptic_curve(backend, b"fake") + def test_elliptic_curve_exchange_algorithm_supported(self, monkeypatch): + monkeypatch.setattr(backend, "_lib", DummyLibrary()) + + assert backend.elliptic_curve_exchange_algorithm_supported() is False + + monkeypatch.setattr(backend, "_lib", DummyLibraryECDH()) + + assert backend.elliptic_curve_exchange_algorithm_supported() is False + @pytest.mark.requires_backend_interface(interface=RSABackend) class TestRSAPEMSerialization(object): diff --git a/tests/hazmat/primitives/test_ec.py b/tests/hazmat/primitives/test_ec.py index 5467464a..c3a99e5d 100644 --- a/tests/hazmat/primitives/test_ec.py +++ b/tests/hazmat/primitives/test_ec.py @@ -7,6 +7,8 @@ from __future__ import absolute_import, division, print_function import itertools import os +from binascii import hexlify + import pytest from cryptography import exceptions, utils @@ -21,7 +23,8 @@ from cryptography.hazmat.primitives.asymmetric.utils import ( from ...utils import ( load_fips_ecdsa_key_pair_vectors, load_fips_ecdsa_signing_vectors, - load_vectors_from_file, raises_unsupported_algorithm + load_kasvs_ecdh_vectors, load_vectors_from_file, + raises_unsupported_algorithm ) _HASH_TYPES = { @@ -54,6 +57,15 @@ def _skip_curve_unsupported(backend, curve): ) +def _skip_exchange_algorithm_unsupported(backend): + if not backend.elliptic_curve_exchange_algorithm_supported(): + pytest.skip( + "Exchange algorithm is not supported by this backend {0}".format( + backend + ) + ) + + @utils.register_interface(ec.EllipticCurve) class DummyCurve(object): name = "dummy-curve" @@ -749,3 +761,83 @@ class TestECDSAVerification(object): public_key = key.public_key() with pytest.raises(TypeError): public_key.verifier(1234, ec.ECDSA(hashes.SHA256())) + + +class DummyECDHBackend(object): + @classmethod + def elliptic_curve_exchange_algorithm_supported(cls): + return False + + +@pytest.mark.requires_backend_interface(interface=EllipticCurveBackend) +class TestECDHVectors(object): + + def test_unsupported_ecdh_arguments(self, backend): + with pytest.raises(TypeError): + ec.ECDH(None) + curve = ec.SECP521R1 + _skip_curve_unsupported(backend, curve) + prikey = ec.generate_private_key(curve, backend) + ecdh = ec.ECDH(prikey) + ecdh.compute_key(ecdh.public_key()) + with pytest.raises(TypeError): + ecdh.compute_key(None) + with pytest.raises(exceptions.UnsupportedAlgorithm): + prikey._backend = DummyECDHBackend() + ecdh = ec.ECDH(prikey) + _skip_exchange_algorithm_unsupported(DummyECDHBackend()) + + def key_exchange(self, backend, vector): + key_numbers = vector['IUT'] + peer_numbers = vector['CAVS'] + + prikey = ec.EllipticCurvePrivateNumbers( + key_numbers['d'], + ec.EllipticCurvePublicNumbers( + key_numbers['x'], + key_numbers['y'], + ec._CURVE_TYPES[vector['curve']]() + ) + ).private_key(backend) + + peerkey = ec.EllipticCurvePrivateNumbers( + peer_numbers['d'], + ec.EllipticCurvePublicNumbers( + peer_numbers['x'], + peer_numbers['y'], + ec._CURVE_TYPES[vector['curve']]() + ) + ).private_key(backend) + peerpubkey = peerkey.public_key() + + ecdh = ec.ECDH(prikey) + z = ecdh.compute_key(peerpubkey) + + return int(hexlify(z).decode('ascii'), 16) + + @pytest.mark.parametrize( + "vector", + load_vectors_from_file( + os.path.join( + "asymmetric", "ECDH", + "KASValidityTest_ECCStaticUnified_NOKC_ZZOnly_init.fax"), + load_kasvs_ecdh_vectors + ) + ) + def test_key_exchange_with_vectors(self, backend, vector): + _skip_curve_unsupported(backend, ec._CURVE_TYPES[vector['curve']]) + _skip_exchange_algorithm_unsupported(backend) + + try: + z = self.key_exchange(backend, vector) + except ValueError: + assert vector['fail'] is True + + if vector['fail']: + # Errno 7 denotes a changed private key. Errno 8 denotes a changed + # shared key. Both these errors will not cause a failure in the + # exchange but should lead to a non-matching derived shared key. + if vector['errno'] in [7, 8]: + assert z != vector['Z'] + else: + assert z == vector['Z'] -- cgit v1.2.3