diff options
author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2017-06-09 02:31:30 -1000 |
---|---|---|
committer | Alex Gaynor <alex.gaynor@gmail.com> | 2017-06-09 08:31:30 -0400 |
commit | 3e357f704008f38261aee011a9fe674dc43cc0ae (patch) | |
tree | f50094dd94873a50e709608da3e74cb6b459cc03 /docs/hazmat/primitives/asymmetric/x25519.rst | |
parent | 7e53d911577881d87ce30291cef68e24f3c1b763 (diff) | |
download | cryptography-3e357f704008f38261aee011a9fe674dc43cc0ae.tar.gz cryptography-3e357f704008f38261aee011a9fe674dc43cc0ae.tar.bz2 cryptography-3e357f704008f38261aee011a9fe674dc43cc0ae.zip |
X25519 Support (#3686)
* early days
* sort of working
* more things
* remove private_bytes
* public bytes, interface fix
* load public keys
* x25519 support basically done now
* private_bytes is gone
* some reminders
* doctest this too
* remove a thing that doesn't matter
* x25519 supported checks
* libressl has the NID, but a different API, so check for OpenSSL
* pep8
* add missing coverage
* update to use reasons
* expand test a little
* add changelog entry
* review feedback
Diffstat (limited to 'docs/hazmat/primitives/asymmetric/x25519.rst')
-rw-r--r-- | docs/hazmat/primitives/asymmetric/x25519.rst | 85 |
1 files changed, 85 insertions, 0 deletions
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 |