Debian Codegraph @

x3dh/identity_key_pair.py

raw
1 from __future__ import annotations
2
3 from abc import ABC, abstractmethod
4 import json
5 from typing import cast
6 from typing_extensions import assert_never
7
8 import xeddsa
9
10 from .migrations import parse_identity_key_pair_model
11 from .models import IdentityKeyPairModel
12 from .types import JSONObject, SecretType
13
14
15 __all__ = [
16 "IdentityKeyPair",
17 "IdentityKeyPairPriv",
18 "IdentityKeyPairSeed"
19 ]
20
21
22 class IdentityKeyPair(ABC):
23 """
24 An identity key pair.
25
26 There are following requirements for the identity key pair:
27
28 * It must be able to create and verify Ed25519-compatible signatures.
29 * It must be able to perform X25519-compatible Diffie-Hellman key agreements.
30
31 There are at least two different kinds of key pairs that can fulfill these requirements: Ed25519 key pairs
32 and Curve25519 key pairs. The birational equivalence of both curves can be used to "convert" one pair to
33 the other.
34
35 Both types of key pairs share the same private key, however instead of a private key, a seed can be used
36 which the private key is derived from using SHA-512. This is standard practice for Ed25519, where the
37 other 32 bytes of the SHA-512 seed hash are used as a nonce during signing. If a new key pair has to be
38 generated, this implementation generates a seed.
39 """
40
41 @property
42 def model(self) -> IdentityKeyPairModel:
43 """
44 Returns:
45 The internal state of this :class:`IdentityKeyPair` as a pydantic model.
46 """
47
48 return IdentityKeyPairModel(secret=self.secret, secret_type=self.secret_type)
49
50 @property
51 def json(self) -> JSONObject:
52 """
53 Returns:
54 The internal state of this :class:`IdentityKeyPair` as a JSON-serializable Python object.
55 """
56
57 return cast(JSONObject, json.loads(self.model.json()))
58
59 @staticmethod
60 def from_model(model: IdentityKeyPairModel) -> "IdentityKeyPair":
61 """
62 Args:
63 model: The pydantic model holding the internal state of an :class:`IdentityKeyPair`, as produced
64 by :attr:`model`.
65
66 Returns:
67 A configured instance of :class:`IdentityKeyPair`, with internal state restored from the model.
68
69 Warning:
70 Migrations are not provided via the :attr:`model`/:meth:`from_model` API. Use
71 :attr:`json`/:meth:`from_json` instead. Refer to :ref:`serialization_and_migration` in the
72 documentation for details.
73 """
74
75 if model.secret_type is SecretType.PRIV:
76 return IdentityKeyPairPriv(model.secret)
77 if model.secret_type is SecretType.SEED:
78 return IdentityKeyPairSeed(model.secret)
79
80 return assert_never(model.secret_type)
81
82 @staticmethod
83 def from_json(serialized: JSONObject) -> "IdentityKeyPair":
84 """
85 Args:
86 serialized: A JSON-serializable Python object holding the internal state of an
87 :class:`IdentityKeyPair`, as produced by :attr:`json`.
88
89 Returns:
90 A configured instance of :class:`IdentityKeyPair`, with internal state restored from the
91 serialized data.
92 """
93
94 return IdentityKeyPair.from_model(parse_identity_key_pair_model(serialized))
95
96 @property
97 @abstractmethod
98 def secret_type(self) -> SecretType:
99 """
100 Returns:
101 The type of secret used by this identity key (i.e. a seed or private key).
102 """
103
104 @property
105 @abstractmethod
106 def secret(self) -> bytes:
107 """
108 Returns:
109 The secret used by this identity key, i.e. the seed or private key.
110 """
111
112 @abstractmethod
113 def as_priv(self) -> "IdentityKeyPairPriv":
114 """
115 Returns:
116 An :class:`IdentityKeyPairPriv` derived from this instance, or the instance itself if it already
117 is an :class:`IdentityKeyPairPriv`.
118 """
119
120
121 class IdentityKeyPairPriv(IdentityKeyPair):
122 """
123 An :class:`IdentityKeyPair` represented by a Curve25519/Ed25519 private key.
124 """
125
126 def __init__(self, priv: bytes) -> None:
127 """
128 Args:
129 priv: The Curve25519/Ed25519 private key.
130 """
131
132 if len(priv) != 32:
133 raise ValueError("Expected the private key to be 32 bytes long.")
134
135 self.__priv = priv
136
137 @property
138 def secret_type(self) -> SecretType:
139 return SecretType.PRIV
140
141 @property
142 def secret(self) -> bytes:
143 return self.priv
144
145 def as_priv(self) -> "IdentityKeyPairPriv":
146 return self
147
148 @property
149 def priv(self) -> bytes:
150 """
151 Returns:
152 The Curve25519/Ed25519 private key.
153 """
154
155 return self.__priv
156
157
158 class IdentityKeyPairSeed(IdentityKeyPair):
159 """
160 An :class:`IdentityKeyPair` represented by a Curve25519/Ed25519 seed.
161 """
162
163 def __init__(self, seed: bytes) -> None:
164 """
165 Args:
166 seed: The Curve25519/Ed25519 seed.
167 """
168
169 if len(seed) != 32:
170 raise ValueError("Expected the seed to be 32 bytes long.")
171
172 self.__seed = seed
173
174 @property
175 def secret_type(self) -> SecretType:
176 return SecretType.SEED
177
178 @property
179 def secret(self) -> bytes:
180 return self.seed
181
182 def as_priv(self) -> "IdentityKeyPairPriv":
183 return IdentityKeyPairPriv(xeddsa.seed_to_priv(self.__seed))
184
185 @property
186 def seed(self) -> bytes:
187 """
188 Returns:
189 The Curve25519/Ed25519 seed.
190 """
191
192 return self.__seed