diff options
| -rw-r--r-- | CHANGELOG.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/x25519.rst | 85 | ||||
| -rw-r--r-- | src/cryptography/hazmat/backends/openssl/backend.py | 54 | ||||
| -rw-r--r-- | src/cryptography/hazmat/backends/openssl/x25519.py | 71 | ||||
| -rw-r--r-- | src/cryptography/hazmat/primitives/asymmetric/x25519.py | 54 | ||||
| -rw-r--r-- | tests/hazmat/primitives/test_x25519.py | 120 |
7 files changed, 386 insertions, 0 deletions
diff --git a/CHANGELOG.rst b/CHANGELOG.rst index be9bbd89..90a5a2a2 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -23,6 +23,7 @@ Changelog objects from X.509 certificate extensions. * Added support for :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305`. +* Added support for :doc:`/hazmat/primitives/asymmetric/x25519`. 1.9 - 2017-05-29 ~~~~~~~~~~~~~~~~ diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index e14ce0d3..891e9a82 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -29,6 +29,7 @@ private key is able to decrypt it. dh serialization utils + x25519 .. _`proof of identity`: https://en.wikipedia.org/wiki/Public-key_infrastructure diff --git a/docs/hazmat/primitives/asymmetric/x25519.rst b/docs/hazmat/primitives/asymmetric/x25519.rst new file mode 100644 index 00000000..e6306ff5 --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/x25519.rst @@ -0,0 +1,85 @@ +.. hazmat:: + +X25519 key exchange +=================== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.x25519 + + +X25519 is an elliptic curve `Diffie-Hellman key exchange`_ using `Curve25519`_. +It allows two parties to jointly agree on a shared secret using an insecure +channel. + + +Exchange Algorithm +~~~~~~~~~~~~~~~~~~ + +For most applications the ``shared_key`` should be passed to a key +derivation function. + +.. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey + >>> # Generate a private key for use in the exchange. + >>> private_key = X25519PrivateKey.generate() + >>> # In a real handshake the peer_public_key will be received from the + >>> # other party. For this example we'll generate another private key and + >>> # get a public key from that. Note that in a DH handshake both peers + >>> # must agree on a common set of parameters. + >>> peer_public_key = X25519PrivateKey.generate().public_key() + >>> shared_key = private_key.exchange(peer_public_key) + >>> # For the next handshake we MUST generate another private key. + >>> private_key_2 = X25519PrivateKey.generate() + >>> peer_public_key_2 = X25519PrivateKey.generate().public_key() + >>> shared_key_2 = private_key_2.exchange(peer_public_key_2) + +Key interfaces +~~~~~~~~~~~~~~ + +.. class:: X25519PrivateKey + + .. versionadded:: 2.0 + + .. classmethod:: generate() + + Generate an X25519 private key. + + :returns: :class:`X25519PrivateKey` + + .. method:: public_key() + + :returns: :class:`X25519PublicKey` + + .. method:: exchange(peer_public_key) + + :param X25519PublicKey peer_public_key: The public key for the + peer. + + :returns bytes: A shared key. + +.. class:: X25519PublicKey + + .. versionadded:: 2.0 + + .. classmethod:: from_public_bytes(data) + + :param bytes data: 32 byte public key. + + :returns: :class:`X25519PublicKey` + + .. doctest:: + + >>> from cryptography.hazmat.primitives.asymmetric import x25519 + >>> private_key = x25519.X25519PrivateKey.generate() + >>> public_key = private_key.public_key() + >>> public_bytes = public_key.public_bytes() + >>> loaded_public_key = x25519.X25519PublicKey.from_public_bytes(public_bytes) + + .. method:: public_bytes() + + :returns bytes: The raw bytes of the public key. + + +.. _`Diffie-Hellman key exchange`: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange +.. _`Curve25519`: https://en.wikipedia.org/wiki/Curve25519 diff --git a/src/cryptography/hazmat/backends/openssl/backend.py b/src/cryptography/hazmat/backends/openssl/backend.py index c003b6d3..d17b38ca 100644 --- a/src/cryptography/hazmat/backends/openssl/backend.py +++ b/src/cryptography/hazmat/backends/openssl/backend.py @@ -43,6 +43,9 @@ from cryptography.hazmat.backends.openssl.hmac import _HMACContext from cryptography.hazmat.backends.openssl.rsa import ( _RSAPrivateKey, _RSAPublicKey ) +from cryptography.hazmat.backends.openssl.x25519 import ( + _X25519PrivateKey, _X25519PublicKey +) from cryptography.hazmat.backends.openssl.x509 import ( _Certificate, _CertificateRevocationList, _CertificateSigningRequest, _RevokedCertificate @@ -1772,6 +1775,57 @@ class Backend(object): self.openssl_assert(res > 0) return self._ffi.buffer(pp[0], res)[:] + def x25519_load_public_bytes(self, data): + evp_pkey = self._create_evp_pkey_gc() + res = self._lib.EVP_PKEY_set_type(evp_pkey, self._lib.NID_X25519) + backend.openssl_assert(res == 1) + res = self._lib.EVP_PKEY_set1_tls_encodedpoint( + evp_pkey, data, len(data) + ) + backend.openssl_assert(res == 1) + return _X25519PublicKey(self, evp_pkey) + + def x25519_load_private_bytes(self, data): + # OpenSSL only has facilities for loading PKCS8 formatted private + # keys using the algorithm identifiers specified in + # https://tools.ietf.org/html/draft-ietf-curdle-pkix-03. + # This is the standard PKCS8 prefix for a 32 byte X25519 key. + # The form is: + # 0:d=0 hl=2 l= 46 cons: SEQUENCE + # 2:d=1 hl=2 l= 1 prim: INTEGER :00 + # 5:d=1 hl=2 l= 5 cons: SEQUENCE + # 7:d=2 hl=2 l= 3 prim: OBJECT :1.3.101.110 + # 12:d=1 hl=2 l= 34 prim: OCTET STRING (the key) + # Of course there's a bit more complexity. In reality OCTET STRING + # contains an OCTET STRING of length 32! So the last two bytes here + # are \x04\x20, which is an OCTET STRING of length 32. + pkcs8_prefix = b'0.\x02\x01\x000\x05\x06\x03+en\x04"\x04 ' + bio = self._bytes_to_bio(pkcs8_prefix + data) + evp_pkey = backend._lib.d2i_PrivateKey_bio(bio.bio, self._ffi.NULL) + self.openssl_assert(evp_pkey != self._ffi.NULL) + evp_pkey = self._ffi.gc(evp_pkey, self._lib.EVP_PKEY_free) + return _X25519PrivateKey(self, evp_pkey) + + def x25519_generate_key(self): + evp_pkey_ctx = self._lib.EVP_PKEY_CTX_new_id( + self._lib.NID_X25519, self._ffi.NULL + ) + self.openssl_assert(evp_pkey_ctx != self._ffi.NULL) + evp_pkey_ctx = self._ffi.gc( + evp_pkey_ctx, self._lib.EVP_PKEY_CTX_free + ) + res = self._lib.EVP_PKEY_keygen_init(evp_pkey_ctx) + self.openssl_assert(res == 1) + evp_ppkey = self._ffi.new("EVP_PKEY **") + res = self._lib.EVP_PKEY_keygen(evp_pkey_ctx, evp_ppkey) + self.openssl_assert(res == 1) + self.openssl_assert(evp_ppkey[0] != self._ffi.NULL) + evp_pkey = self._ffi.gc(evp_ppkey[0], self._lib.EVP_PKEY_free) + return _X25519PrivateKey(self, evp_pkey) + + def x25519_supported(self): + return self._lib.CRYPTOGRAPHY_OPENSSL_110_OR_GREATER + def derive_scrypt(self, key_material, salt, length, n, r, p): buf = self._ffi.new("unsigned char[]", length) res = self._lib.EVP_PBE_scrypt( diff --git a/src/cryptography/hazmat/backends/openssl/x25519.py b/src/cryptography/hazmat/backends/openssl/x25519.py new file mode 100644 index 00000000..f92b184b --- /dev/null +++ b/src/cryptography/hazmat/backends/openssl/x25519.py @@ -0,0 +1,71 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +from cryptography import utils +from cryptography.hazmat.primitives.asymmetric.x25519 import ( + X25519PrivateKey, X25519PublicKey +) + + +@utils.register_interface(X25519PublicKey) +class _X25519PublicKey(object): + def __init__(self, backend, evp_pkey): + self._backend = backend + self._evp_pkey = evp_pkey + + def public_bytes(self): + ucharpp = self._backend._ffi.new("unsigned char **") + res = self._backend._lib.EVP_PKEY_get1_tls_encodedpoint( + self._evp_pkey, ucharpp + ) + self._backend.openssl_assert(res == 32) + self._backend.openssl_assert(ucharpp[0] != self._backend._ffi.NULL) + data = self._backend._ffi.gc( + ucharpp[0], self._backend._lib.OPENSSL_free + ) + return self._backend._ffi.buffer(data, res)[:] + + +@utils.register_interface(X25519PrivateKey) +class _X25519PrivateKey(object): + def __init__(self, backend, evp_pkey): + self._backend = backend + self._evp_pkey = evp_pkey + + def public_key(self): + bio = self._backend._create_mem_bio_gc() + res = self._backend._lib.i2d_PUBKEY_bio(bio, self._evp_pkey) + self._backend.openssl_assert(res == 1) + evp_pkey = self._backend._lib.d2i_PUBKEY_bio( + bio, self._backend._ffi.NULL + ) + return _X25519PublicKey(self._backend, evp_pkey) + + def exchange(self, peer_public_key): + if not isinstance(peer_public_key, X25519PublicKey): + raise TypeError("peer_public_key must be X25519PublicKey.") + + ctx = self._backend._lib.EVP_PKEY_CTX_new( + self._evp_pkey, self._backend._ffi.NULL + ) + self._backend.openssl_assert(ctx != self._backend._ffi.NULL) + ctx = self._backend._ffi.gc(ctx, self._backend._lib.EVP_PKEY_CTX_free) + res = self._backend._lib.EVP_PKEY_derive_init(ctx) + self._backend.openssl_assert(res == 1) + res = self._backend._lib.EVP_PKEY_derive_set_peer( + ctx, peer_public_key._evp_pkey + ) + self._backend.openssl_assert(res == 1) + keylen = self._backend._ffi.new("size_t *") + res = self._backend._lib.EVP_PKEY_derive( + ctx, self._backend._ffi.NULL, keylen + ) + self._backend.openssl_assert(res == 1) + self._backend.openssl_assert(keylen[0] > 0) + buf = self._backend._ffi.new("unsigned char[]", keylen[0]) + res = self._backend._lib.EVP_PKEY_derive(ctx, buf, keylen) + self._backend.openssl_assert(res == 1) + return self._backend._ffi.buffer(buf, keylen[0])[:] diff --git a/src/cryptography/hazmat/primitives/asymmetric/x25519.py b/src/cryptography/hazmat/primitives/asymmetric/x25519.py new file mode 100644 index 00000000..5c4652ae --- /dev/null +++ b/src/cryptography/hazmat/primitives/asymmetric/x25519.py @@ -0,0 +1,54 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import abc + +import six + +from cryptography.exceptions import UnsupportedAlgorithm, _Reasons + + +@six.add_metaclass(abc.ABCMeta) +class X25519PublicKey(object): + @classmethod + def from_public_bytes(cls, data): + from cryptography.hazmat.backends.openssl.backend import backend + if not backend.x25519_supported(): + raise UnsupportedAlgorithm( + "X25519 is not supported by this version of OpenSSL.", + _Reasons.UNSUPPORTED_EXCHANGE_ALGORITHM + ) + return backend.x25519_load_public_bytes(data) + + @abc.abstractmethod + def public_bytes(self): + pass + + +@six.add_metaclass(abc.ABCMeta) +class X25519PrivateKey(object): + @classmethod + def generate(cls): + from cryptography.hazmat.backends.openssl.backend import backend + if not backend.x25519_supported(): + raise UnsupportedAlgorithm( + "X25519 is not supported by this version of OpenSSL.", + _Reasons.UNSUPPORTED_EXCHANGE_ALGORITHM + ) + return backend.x25519_generate_key() + + @classmethod + def _from_private_bytes(cls, data): + from cryptography.hazmat.backends.openssl.backend import backend + return backend.x25519_load_private_bytes(data) + + @abc.abstractmethod + def public_key(self): + pass + + @abc.abstractmethod + def exchange(self, peer_public_key): + pass diff --git a/tests/hazmat/primitives/test_x25519.py b/tests/hazmat/primitives/test_x25519.py new file mode 100644 index 00000000..22a0ae66 --- /dev/null +++ b/tests/hazmat/primitives/test_x25519.py @@ -0,0 +1,120 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import binascii +import os + +import pytest + +from cryptography.exceptions import _Reasons +from cryptography.hazmat.backends.interfaces import DHBackend +from cryptography.hazmat.primitives.asymmetric.x25519 import ( + X25519PrivateKey, X25519PublicKey +) + +from ...utils import ( + load_nist_vectors, load_vectors_from_file, raises_unsupported_algorithm +) + + +@pytest.mark.supported( + only_if=lambda backend: not backend.x25519_supported(), + skip_message="Requires OpenSSL without X25519 support" +) +@pytest.mark.requires_backend_interface(interface=DHBackend) +def test_x25519_unsupported(backend): + with raises_unsupported_algorithm(_Reasons.UNSUPPORTED_EXCHANGE_ALGORITHM): + X25519PublicKey.from_public_bytes(b"0" * 32) + + with raises_unsupported_algorithm(_Reasons.UNSUPPORTED_EXCHANGE_ALGORITHM): + X25519PrivateKey.generate() + + +@pytest.mark.supported( + only_if=lambda backend: backend.x25519_supported(), + skip_message="Requires OpenSSL with X25519 support" +) +@pytest.mark.requires_backend_interface(interface=DHBackend) +class TestX25519Exchange(object): + @pytest.mark.parametrize( + "vector", + load_vectors_from_file( + os.path.join("asymmetric", "X25519", "rfc7748.txt"), + load_nist_vectors + ) + ) + def test_rfc7748(self, vector, backend): + private = binascii.unhexlify(vector["input_scalar"]) + public = binascii.unhexlify(vector["input_u"]) + shared_key = binascii.unhexlify(vector["output_u"]) + private_key = X25519PrivateKey._from_private_bytes(private) + public_key = X25519PublicKey.from_public_bytes(public) + computed_shared_key = private_key.exchange(public_key) + assert computed_shared_key == shared_key + + def test_rfc7748_1000_iteration(self, backend): + old_private = private = public = binascii.unhexlify( + b"090000000000000000000000000000000000000000000000000000000000" + b"0000" + ) + shared_key = binascii.unhexlify( + b"684cf59ba83309552800ef566f2f4d3c1c3887c49360e3875f2eb94d9953" + b"2c51" + ) + private_key = X25519PrivateKey._from_private_bytes(private) + public_key = X25519PublicKey.from_public_bytes(public) + for _ in range(1000): + computed_shared_key = private_key.exchange(public_key) + private_key = X25519PrivateKey._from_private_bytes( + computed_shared_key + ) + public_key = X25519PublicKey.from_public_bytes(old_private) + old_private = computed_shared_key + + assert computed_shared_key == shared_key + + # These vectors are also from RFC 7748 + # https://tools.ietf.org/html/rfc7748#section-6.1 + @pytest.mark.parametrize( + ("private_bytes", "public_bytes"), + [ + ( + binascii.unhexlify( + b"77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba" + b"51db92c2a" + ), + binascii.unhexlify( + b"8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98" + b"eaa9b4e6a" + ) + ), + ( + binascii.unhexlify( + b"5dab087e624a8a4b79e17f8b83800ee66f3bb1292618b6fd1c2f8b2" + b"7ff88e0eb" + ), + binascii.unhexlify( + b"de9edb7d7b7dc1b4d35b61c2ece435373f8343c85b78674dadfc7e1" + b"46f882b4f" + ) + ) + ] + ) + def test_public_bytes(self, private_bytes, public_bytes, backend): + private_key = X25519PrivateKey._from_private_bytes(private_bytes) + assert private_key.public_key().public_bytes() == public_bytes + public_key = X25519PublicKey.from_public_bytes(public_bytes) + assert public_key.public_bytes() == public_bytes + + def test_generate(self, backend): + key = X25519PrivateKey.generate() + assert key + assert key.public_key() + + def test_invalid_type_exchange(self, backend): + key = X25519PrivateKey.generate() + with pytest.raises(TypeError): + key.exchange(object()) |