| 1 |
from __future__ import annotations |
| 2 |
|
| 3 |
import enum |
| 4 |
from typing import FrozenSet, List, Mapping, NamedTuple, Optional, Union |
| 5 |
from typing_extensions import TypeAlias |
| 6 |
|
| 7 |
|
| 8 |
__all__ = [ |
| 9 |
"Bundle", |
| 10 |
"IdentityKeyFormat", |
| 11 |
"Header", |
| 12 |
"JSONType", |
| 13 |
"JSONObject", |
| 14 |
"SecretType" |
| 15 |
] |
| 16 |
|
| 17 |
|
| 18 |
################ |
| 19 |
# Type Aliases # |
| 20 |
################ |
| 21 |
|
| 22 |
JSONType: TypeAlias = Union[Mapping[str, "JSONType"], List["JSONType"], str, int, float, bool, None] |
| 23 |
JSONObject: TypeAlias = Mapping[str, "JSONType"] |
| 24 |
|
| 25 |
|
| 26 |
############################ |
| 27 |
# Structures (NamedTuples) # |
| 28 |
############################ |
| 29 |
|
| 30 |
class Bundle(NamedTuple): |
| 31 |
""" |
| 32 |
The bundle is a collection of public keys and signatures used by the X3DH protocol to achieve asynchronous |
| 33 |
key agreements while providing forward secrecy and cryptographic deniability. Parties that want to be |
| 34 |
available for X3DH key agreements have to publish their bundle somehow. Other parties can then use that |
| 35 |
bundle to perform a key agreement. |
| 36 |
""" |
| 37 |
|
| 38 |
identity_key: bytes |
| 39 |
signed_pre_key: bytes |
| 40 |
signed_pre_key_sig: bytes |
| 41 |
pre_keys: FrozenSet[bytes] |
| 42 |
|
| 43 |
|
| 44 |
class Header(NamedTuple): |
| 45 |
""" |
| 46 |
The header generated by the active party as part of the key agreement, and consumed by the passive party |
| 47 |
to derive the same shared secret. |
| 48 |
""" |
| 49 |
|
| 50 |
identity_key: bytes |
| 51 |
ephemeral_key: bytes |
| 52 |
signed_pre_key: bytes |
| 53 |
pre_key: Optional[bytes] |
| 54 |
|
| 55 |
|
| 56 |
################ |
| 57 |
# Enumerations # |
| 58 |
################ |
| 59 |
|
| 60 |
@enum.unique |
| 61 |
class IdentityKeyFormat(enum.Enum): |
| 62 |
""" |
| 63 |
The two supported public key formats for the identity key: |
| 64 |
|
| 65 |
* Curve25519 public keys: 32 bytes, the little-endian encoding of the u coordinate as per `RFC 7748, |
| 66 |
section 5 "The X25519 and X448 Functions" <https://www.rfc-editor.org/rfc/rfc7748.html#section-5>`_. |
| 67 |
* Ed25519 public keys: 32 bytes, the little-endian encoding of the y coordinate with the sign bit of the x |
| 68 |
coordinate stored in the most significant bit as per `RFC 8032, section 3.2 "Keys" |
| 69 |
<https://www.rfc-editor.org/rfc/rfc8032.html#section-3.2>`_. |
| 70 |
""" |
| 71 |
|
| 72 |
CURVE_25519 = "CURVE_25519" |
| 73 |
ED_25519 = "ED_25519" |
| 74 |
|
| 75 |
|
| 76 |
@enum.unique |
| 77 |
class SecretType(enum.Enum): |
| 78 |
""" |
| 79 |
The two types of secrets that an :class:`~x3dh.identity_key_pair.IdentityKeyPair` can use internally: a |
| 80 |
seed or a private key. |
| 81 |
""" |
| 82 |
|
| 83 |
SEED = "SEED" |
| 84 |
PRIV = "PRIV" |