cmem-plugin-graphsigning 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,259 @@
1
+ """Signature creation and verification for the key types this plugin supports.
2
+
3
+ Ed25519 is the recommended key type **on interoperability grounds**: it is small,
4
+ has no padding or hash parameters to choose, and is the key type the W3C Data
5
+ Integrity ecosystem is built around. It is recommended by no part of BSI
6
+ TR-02102-1, though, so a deployment held to that recommendation signs with RSA
7
+ instead - which is also why RSA is supported at all, organizational keys from a
8
+ corporate CA or a hardware module frequently being RSA and not replaceable.
9
+ Neither type is the right default for every deployment, so the recommendation
10
+ here is not stated unqualified anywhere a user reads it.
11
+
12
+ Which one is in use is never configured. A PEM key says what it is, so the
13
+ algorithm follows from the key itself.
14
+ """
15
+
16
+ from cryptography.exceptions import InvalidSignature
17
+ from cryptography.hazmat.primitives import hashes, serialization
18
+ from cryptography.hazmat.primitives.asymmetric import padding
19
+ from cryptography.hazmat.primitives.asymmetric.ed25519 import (
20
+ Ed25519PrivateKey,
21
+ Ed25519PublicKey,
22
+ )
23
+ from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey, RSAPublicKey
24
+
25
+ from cmem_plugin_graphsigning.graph_proof_utils import (
26
+ multibase_decode,
27
+ multibase_encode,
28
+ multibase_encode_base58btc,
29
+ )
30
+
31
+ MULTIKEY_ED25519_PREFIX = b"\xed\x01"
32
+ """Multicodec identifier for an Ed25519 public key, as Multikey requires."""
33
+
34
+ DID_KEY_PREFIX = "did:key:"
35
+
36
+ CRYPTOSUITE_ED25519 = "eddsa-rdfc-2022"
37
+ CRYPTOSUITE_RSA = "rsa-rdfc1-sha256-2026"
38
+
39
+ SUPPORTED_CRYPTOSUITES = frozenset({CRYPTOSUITE_ED25519, CRYPTOSUITE_RSA})
40
+ """Cryptosuite identifiers this plugin can verify.
41
+
42
+ A proof declaring anything else is not one this plugin's verifier implements, and
43
+ is rejected rather than checked against whichever algorithm the key it ends up
44
+ with happens to imply.
45
+ """
46
+
47
+ MINIMUM_RSA_KEY_SIZE = 3000
48
+ """Shortest RSA modulus, in bits, this plugin will sign with.
49
+
50
+ BSI TR-02102-1 puts the floor for an RSA signature at a 3000 bit modulus, which is
51
+ why the key-pair action issues 3072 bit keys. A shorter key is refused rather than
52
+ signed with, since a signature nobody should rely on is worse than no signature.
53
+
54
+ Verification applies no such floor: refusing to *check* a proof that exists leaves
55
+ whoever is investigating it without an answer at all, which is a different trade
56
+ from refusing to create one.
57
+ """
58
+
59
+ _RSA_PADDING = padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.MAX_LENGTH)
60
+
61
+
62
+ class NoDidKeyFormError(ValueError):
63
+ """Raised for a key type that has no did:key representation."""
64
+
65
+ def __init__(self, key: object) -> None:
66
+ super().__init__(
67
+ f"No did:key form exists for a {type(key).__name__}. Only Ed25519 keys can "
68
+ f"identify themselves that way, so any other key needs a Verification "
69
+ f"Method IRI of its own."
70
+ )
71
+
72
+
73
+ class UnsupportedKeyTypeError(ValueError):
74
+ """Raised for a key that is neither Ed25519 nor RSA."""
75
+
76
+ def __init__(self, key: object) -> None:
77
+ super().__init__(
78
+ f"Unsupported key type '{type(key).__name__}'. "
79
+ f"This plugin signs and verifies with Ed25519 or RSA keys."
80
+ )
81
+
82
+
83
+ class WeakRsaKeyError(ValueError):
84
+ """Raised for an RSA key too short to sign with."""
85
+
86
+ def __init__(self, key_size: int) -> None:
87
+ super().__init__(
88
+ f"This RSA key has a {key_size} bit modulus, and signing needs at least "
89
+ f"{MINIMUM_RSA_KEY_SIZE} bits. Generate a longer key - the Create RSA Key "
90
+ f"Pair action issues one - or sign with an Ed25519 key."
91
+ )
92
+
93
+
94
+ def check_signing_key_strength(private_key: object) -> None:
95
+ """Raise for a private key too short to sign with.
96
+
97
+ Only RSA has a length to check here: Ed25519 has one fixed key size, which is
98
+ why the key type decides whether the question even arises.
99
+ """
100
+ if isinstance(private_key, RSAPrivateKey) and private_key.key_size < MINIMUM_RSA_KEY_SIZE:
101
+ raise WeakRsaKeyError(private_key.key_size)
102
+
103
+
104
+ def cryptosuite_for(key: object) -> str:
105
+ """Return the cryptosuite identifier describing how *key* is used.
106
+
107
+ An Ed25519 key uses the registered ``eddsa-rdfc-2022`` cryptosuite: the proof
108
+ configuration and the document digest are canonicalized (RDFC-1.0) and hashed
109
+ exactly as that cryptosuite specifies, and signed with the same construction,
110
+ so a proof this plugin writes verifies in an independent, standards-conformant
111
+ ``eddsa-rdfc-2022`` verifier. RSA has no registered W3C Data Integrity
112
+ cryptosuite of its own, so it keeps this plugin's own ``rsa-rdfc1-sha256-2026``
113
+ identifier.
114
+ """
115
+ if isinstance(key, Ed25519PrivateKey | Ed25519PublicKey):
116
+ return CRYPTOSUITE_ED25519
117
+ if isinstance(key, RSAPrivateKey | RSAPublicKey):
118
+ return CRYPTOSUITE_RSA
119
+ raise UnsupportedKeyTypeError(key)
120
+
121
+
122
+ def sign_digest(private_key: object, payload: bytes) -> bytes:
123
+ """Sign *payload* with *private_key*, choosing the algorithm from the key."""
124
+ if isinstance(private_key, Ed25519PrivateKey):
125
+ return private_key.sign(payload)
126
+ if isinstance(private_key, RSAPrivateKey):
127
+ return private_key.sign(payload, _RSA_PADDING, hashes.SHA256())
128
+ raise UnsupportedKeyTypeError(private_key)
129
+
130
+
131
+ def verify_digest(public_key: object, payload: bytes, signature: bytes) -> bool:
132
+ """Return whether *signature* over *payload* verifies against *public_key*.
133
+
134
+ An unsupported key type is a configuration error and raises; a signature
135
+ that simply does not match returns False, since that is a verification
136
+ result rather than a fault.
137
+ """
138
+ try:
139
+ if isinstance(public_key, Ed25519PublicKey):
140
+ public_key.verify(signature, payload)
141
+ elif isinstance(public_key, RSAPublicKey):
142
+ public_key.verify(signature, payload, _RSA_PADDING, hashes.SHA256())
143
+ else:
144
+ raise UnsupportedKeyTypeError(public_key)
145
+ except InvalidSignature:
146
+ return False
147
+ else:
148
+ return True
149
+
150
+
151
+ def is_multikey(public_key: object) -> bool:
152
+ """Return whether *public_key* can be written as a conformant Multikey.
153
+
154
+ Only Ed25519 can. Multikey covers P-256, P-384, Ed25519, BLS12-381 and SM2,
155
+ and RSA is deliberately not among them, so an RSA key is written as plain
156
+ SubjectPublicKeyInfo and its verification method is not typed sec:Multikey.
157
+ """
158
+ return isinstance(public_key, Ed25519PublicKey)
159
+
160
+
161
+ def public_key_multibase(public_key: object) -> str:
162
+ """Return the multibase value written as sec:publicKeyMultibase.
163
+
164
+ An Ed25519 key becomes a conformant Multikey: base58btc over the multicodec
165
+ prefix and the 32 raw key bytes, which is what standard tooling reads. An RSA
166
+ key has no Multikey form, so it stays base64url-encoded SubjectPublicKeyInfo -
167
+ self-describing through its multibase prefix, and honest about not being a
168
+ Multikey.
169
+ """
170
+ if isinstance(public_key, Ed25519PublicKey):
171
+ raw = public_key.public_bytes(
172
+ encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw
173
+ )
174
+ return multibase_encode_base58btc(MULTIKEY_ED25519_PREFIX + raw)
175
+ if isinstance(public_key, RSAPublicKey):
176
+ return multibase_encode(
177
+ public_key.public_bytes(
178
+ encoding=serialization.Encoding.DER,
179
+ format=serialization.PublicFormat.SubjectPublicKeyInfo,
180
+ )
181
+ )
182
+ raise UnsupportedKeyTypeError(public_key)
183
+
184
+
185
+ def public_key_from_multibase(value: str) -> object:
186
+ """Return the public key a sec:publicKeyMultibase value encodes.
187
+
188
+ Which form it is follows from the bytes: a Multikey announces itself with the
189
+ multicodec prefix, anything else is SubjectPublicKeyInfo.
190
+ """
191
+ decoded = multibase_decode(value)
192
+ if decoded.startswith(MULTIKEY_ED25519_PREFIX):
193
+ return Ed25519PublicKey.from_public_bytes(decoded[len(MULTIKEY_ED25519_PREFIX) :])
194
+ return serialization.load_der_public_key(decoded)
195
+
196
+
197
+ def did_key_for(public_key: object) -> str:
198
+ """Return the ``did:key`` DID for *public_key*.
199
+
200
+ A ``did:key`` identifier *is* the key: it encodes the key material, so it names
201
+ the same key in every graph that key signs and can never name two keys. That is
202
+ exactly what a verification method identifier is for, and it is why no IRI has
203
+ to be invented for an Ed25519 key.
204
+
205
+ Only Ed25519 is supported. The current did:key specification lists Ed25519,
206
+ Secp256k1, X25519, P-256, P-384 and BLS12-381; RSA was dropped from it, so an
207
+ RSA key still needs an identifier chosen by whoever controls it.
208
+ """
209
+ if not isinstance(public_key, Ed25519PublicKey):
210
+ raise NoDidKeyFormError(public_key)
211
+ return f"{DID_KEY_PREFIX}{public_key_multibase(public_key)}"
212
+
213
+
214
+ def verification_method_id(public_key: object) -> str:
215
+ """Return the ``did:key`` verification method identifier for *public_key*.
216
+
217
+ This is the DID followed by the key as a fragment, which is how a did:key
218
+ document names the verification method it contains.
219
+ """
220
+ did = did_key_for(public_key)
221
+ return f"{did}#{did.removeprefix(DID_KEY_PREFIX)}"
222
+
223
+
224
+ def did_key_controller(verification_method: str) -> str:
225
+ """Return the controller of a ``did:key`` verification method, or empty for any other IRI.
226
+
227
+ A did:key document is controlled by the DID itself, so the controller is the
228
+ verification method without its fragment. Who controls a verification method named
229
+ by any other IRI is for its own controller document to say, not for this plugin to
230
+ guess, so none is returned.
231
+ """
232
+ if not verification_method.startswith(DID_KEY_PREFIX):
233
+ return ""
234
+ return verification_method.partition("#")[0]
235
+
236
+
237
+ def public_key_from_did_key(verification_method: str) -> Ed25519PublicKey | None:
238
+ """Return the key a ``did:key`` verification method encodes, or None for any other IRI.
239
+
240
+ A ``did:key`` needs no resolving: the identifier is the key, so it is decoded rather
241
+ than looked up, and what it names is exactly what a verifier has to check against.
242
+ Raises ValueError for a ``did:key`` that is malformed, names a key type other than
243
+ Ed25519, or whose fragment names a different key than the DID itself.
244
+ """
245
+ if not verification_method.startswith(DID_KEY_PREFIX):
246
+ return None
247
+ did, _, fragment = verification_method.partition("#")
248
+ multikey = did.removeprefix(DID_KEY_PREFIX)
249
+ if fragment and fragment != multikey:
250
+ msg = f"The fragment of {verification_method!r} names a different key than its DID"
251
+ raise ValueError(msg)
252
+ if not multikey.startswith("z"):
253
+ msg = f"{verification_method!r} is not a base58btc-encoded did:key"
254
+ raise ValueError(msg)
255
+ decoded = multibase_decode(multikey)
256
+ if not decoded.startswith(MULTIKEY_ED25519_PREFIX):
257
+ msg = f"{verification_method!r} names a key type this plugin does not verify with"
258
+ raise ValueError(msg)
259
+ return Ed25519PublicKey.from_public_bytes(decoded[len(MULTIKEY_ED25519_PREFIX) :])