• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. hazmat::
2
3X448 key exchange
4===================
5
6.. currentmodule:: cryptography.hazmat.primitives.asymmetric.x448
7
8
9X448 is an elliptic curve `Diffie-Hellman key exchange`_ using `Curve448`_.
10It allows two parties to jointly agree on a shared secret using an insecure
11channel.
12
13
14Exchange Algorithm
15~~~~~~~~~~~~~~~~~~
16
17For most applications the ``shared_key`` should be passed to a key
18derivation function. This allows mixing of additional information into the
19key, derivation of multiple keys, and destroys any structure that may be
20present.
21
22.. doctest::
23
24    >>> from cryptography.hazmat.primitives import hashes
25    >>> from cryptography.hazmat.primitives.asymmetric.x448 import X448PrivateKey
26    >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
27    >>> # Generate a private key for use in the exchange.
28    >>> private_key = X448PrivateKey.generate()
29    >>> # In a real handshake the peer_public_key will be received from the
30    >>> # other party. For this example we'll generate another private key and
31    >>> # get a public key from that. Note that in a DH handshake both peers
32    >>> # must agree on a common set of parameters.
33    >>> peer_public_key = X448PrivateKey.generate().public_key()
34    >>> shared_key = private_key.exchange(peer_public_key)
35    >>> # Perform key derivation.
36    >>> derived_key = HKDF(
37    ...     algorithm=hashes.SHA256(),
38    ...     length=32,
39    ...     salt=None,
40    ...     info=b'handshake data',
41    ... ).derive(shared_key)
42    >>> # For the next handshake we MUST generate another private key.
43    >>> private_key_2 = X448PrivateKey.generate()
44    >>> peer_public_key_2 = X448PrivateKey.generate().public_key()
45    >>> shared_key_2 = private_key_2.exchange(peer_public_key_2)
46    >>> derived_key_2 = HKDF(
47    ...     algorithm=hashes.SHA256(),
48    ...     length=32,
49    ...     salt=None,
50    ...     info=b'handshake data',
51    ... ).derive(shared_key_2)
52
53Key interfaces
54~~~~~~~~~~~~~~
55
56.. class:: X448PrivateKey
57
58    .. versionadded:: 2.5
59
60    .. classmethod:: generate()
61
62        Generate an X448 private key.
63
64        :returns: :class:`X448PrivateKey`
65
66    .. classmethod:: from_private_bytes(data)
67
68        :param data: 56 byte private key.
69        :type data: :term:`bytes-like`
70
71        :returns: :class:`X448PrivateKey`
72
73        .. doctest::
74
75            >>> from cryptography.hazmat.primitives import serialization
76            >>> from cryptography.hazmat.primitives.asymmetric import x448
77            >>> private_key = x448.X448PrivateKey.generate()
78            >>> private_bytes = private_key.private_bytes(
79            ...     encoding=serialization.Encoding.Raw,
80            ...     format=serialization.PrivateFormat.Raw,
81            ...     encryption_algorithm=serialization.NoEncryption()
82            ... )
83            >>> loaded_private_key = x448.X448PrivateKey.from_private_bytes(private_bytes)
84
85    .. method:: public_key()
86
87        :returns: :class:`X448PublicKey`
88
89    .. method:: exchange(peer_public_key)
90
91        :param X448PublicKey peer_public_key: The public key for the
92            peer.
93
94        :returns bytes: A shared key.
95
96    .. method:: private_bytes(encoding, format, encryption_algorithm)
97
98        Allows serialization of the key to bytes. Encoding (
99        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
100        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, or
101        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
102        format (
103        :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`
104        or
105        :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
106        ) are chosen to define the exact serialization.
107
108        :param encoding: A value from the
109            :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
110
111        :param format: A value from the
112            :class:`~cryptography.hazmat.primitives.serialization.PrivateFormat`
113            enum. If the ``encoding`` is
114            :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
115            then ``format`` must be
116            :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
117            , otherwise it must be
118            :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`.
119
120        :param encryption_algorithm: An instance of an object conforming to the
121            :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption`
122            interface.
123
124        :return bytes: Serialized key.
125
126.. class:: X448PublicKey
127
128    .. versionadded:: 2.5
129
130    .. classmethod:: from_public_bytes(data)
131
132        :param bytes data: 56 byte public key.
133
134        :returns: :class:`X448PublicKey`
135
136        .. doctest::
137
138            >>> from cryptography.hazmat.primitives import serialization
139            >>> from cryptography.hazmat.primitives.asymmetric import x448
140            >>> private_key = x448.X448PrivateKey.generate()
141            >>> public_key = private_key.public_key()
142            >>> public_bytes = public_key.public_bytes(
143            ...     encoding=serialization.Encoding.Raw,
144            ...     format=serialization.PublicFormat.Raw
145            ... )
146            >>> loaded_public_key = x448.X448PublicKey.from_public_bytes(public_bytes)
147
148    .. method:: public_bytes(encoding, format)
149
150        Allows serialization of the key to bytes. Encoding (
151        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
152        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, or
153        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
154        format (
155        :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`
156        or
157        :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`
158        ) are chosen to define the exact serialization.
159
160        :param encoding: A value from the
161            :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
162
163        :param format: A value from the
164            :class:`~cryptography.hazmat.primitives.serialization.PublicFormat`
165            enum. If the ``encoding`` is
166            :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
167            then ``format`` must be
168            :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`
169            , otherwise it must be
170            :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`.
171
172        :returns bytes: The public key bytes.
173
174
175.. _`Diffie-Hellman key exchange`: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
176.. _`Curve448`: https://en.wikipedia.org/wiki/Curve448
177