tro-utils 0.5.4__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.
- tro_utils/__init__.py +72 -0
- tro_utils/_version.py +24 -0
- tro_utils/certs/freetsa-root.pem +52 -0
- tro_utils/certs/freetsa-tsa.pem +100 -0
- tro_utils/cli.py +738 -0
- tro_utils/default.jinja2 +86 -0
- tro_utils/models/__init__.py +36 -0
- tro_utils/models/_base.py +68 -0
- tro_utils/models/agent.py +176 -0
- tro_utils/models/arrangement.py +378 -0
- tro_utils/models/artifact.py +101 -0
- tro_utils/models/attribute.py +51 -0
- tro_utils/models/composition.py +144 -0
- tro_utils/models/hash_value.py +101 -0
- tro_utils/models/performance.py +195 -0
- tro_utils/models/tro.py +509 -0
- tro_utils/models/trs.py +329 -0
- tro_utils/models/tsa.py +44 -0
- tro_utils/replication_package.py +179 -0
- tro_utils/static/trace-logo.png +0 -0
- tro_utils/tro_utils.py +740 -0
- tro_utils/trs_keys.py +251 -0
- tro_utils/tsa.py +149 -0
- tro_utils-0.5.4.dist-info/METADATA +222 -0
- tro_utils-0.5.4.dist-info/RECORD +29 -0
- tro_utils-0.5.4.dist-info/WHEEL +5 -0
- tro_utils-0.5.4.dist-info/entry_points.txt +2 -0
- tro_utils-0.5.4.dist-info/licenses/LICENSE +32 -0
- tro_utils-0.5.4.dist-info/top_level.txt +1 -0
tro_utils/tro_utils.py
ADDED
|
@@ -0,0 +1,740 @@
|
|
|
1
|
+
"""Main module — TRO facade.
|
|
2
|
+
|
|
3
|
+
The :class:`TRO` class is a thin facade that delegates data-model operations
|
|
4
|
+
to :class:`~tro_utils.models.TransparentResearchObject` while keeping
|
|
5
|
+
signing, timestamping, and report-generation logic here.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import base64
|
|
11
|
+
import datetime
|
|
12
|
+
import hashlib
|
|
13
|
+
import importlib.resources
|
|
14
|
+
import json
|
|
15
|
+
import os
|
|
16
|
+
import pathlib
|
|
17
|
+
import subprocess
|
|
18
|
+
import tempfile
|
|
19
|
+
from dataclasses import dataclass, field
|
|
20
|
+
|
|
21
|
+
from jinja2 import Template
|
|
22
|
+
import graphviz
|
|
23
|
+
|
|
24
|
+
from . import __version__, tsa
|
|
25
|
+
from .models import TransparentResearchObject
|
|
26
|
+
from .models.agent import ORGANIZATION, Agent
|
|
27
|
+
from .models.trs import TrustedResearchSystem
|
|
28
|
+
from .trs_keys import TRSKeyList, normalize_fingerprint
|
|
29
|
+
|
|
30
|
+
#: TRACE logo shown in report headers, bundled so reports don't depend on a
|
|
31
|
+
#: remote URL. Reduced to a 16-color palette to keep reports small; the
|
|
32
|
+
#: full-color original is at
|
|
33
|
+
#: https://transparency-certified.github.io/img/logo/trace-logo.png
|
|
34
|
+
_LOGO = importlib.resources.files(__package__) / "static" / "trace-logo.png"
|
|
35
|
+
|
|
36
|
+
GPG_HOME = os.environ.get("GPG_HOME")
|
|
37
|
+
|
|
38
|
+
# A key gpg fetches by itself, from a key server or a URL in the signature,
|
|
39
|
+
# is found by the fingerprint the signer chose, so it vouches for nothing.
|
|
40
|
+
_VERIFY_OPTIONS = ["--no-auto-key-retrieve"]
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _kill_gpg_agent(gnupghome):
|
|
44
|
+
"""Stop the gpg-agent serving *gnupghome*, which would outlive its removal."""
|
|
45
|
+
try:
|
|
46
|
+
subprocess.run(
|
|
47
|
+
["gpgconf", "--homedir", gnupghome, "--kill", "all"],
|
|
48
|
+
check=False,
|
|
49
|
+
capture_output=True,
|
|
50
|
+
)
|
|
51
|
+
except FileNotFoundError:
|
|
52
|
+
pass
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class SignatureVerification:
|
|
57
|
+
"""Result of :meth:`TRO.verify_signature`."""
|
|
58
|
+
|
|
59
|
+
valid: bool
|
|
60
|
+
status: str
|
|
61
|
+
fingerprint: str | None
|
|
62
|
+
username: str | None = None
|
|
63
|
+
trust: str | None = None
|
|
64
|
+
#: Whether something other than the TRO vouches for the key: an expected
|
|
65
|
+
#: fingerprint it matched, a keyring file it was found in, or at least
|
|
66
|
+
#: marginal validity in the keyring. Mere presence in the keyring does not.
|
|
67
|
+
trusted: bool = False
|
|
68
|
+
used_embedded_key: bool = False
|
|
69
|
+
embedded_key_matches: bool | None = None
|
|
70
|
+
#: The keyring file the key was looked up in, if one was given.
|
|
71
|
+
keyring: str | None = None
|
|
72
|
+
#: Whether the key matched an expected fingerprint; ``None`` if none given.
|
|
73
|
+
fingerprint_matches: bool | None = None
|
|
74
|
+
#: The key's status in the key list, if one was given and lists it.
|
|
75
|
+
listed_status: str | None = None
|
|
76
|
+
#: Time of the TRO's trusted timestamp, when a key list needed it.
|
|
77
|
+
timestamp: datetime.datetime | None = None
|
|
78
|
+
#: Conditions that did not fail the verification but should be reported.
|
|
79
|
+
warnings: list[str] = field(default_factory=list)
|
|
80
|
+
|
|
81
|
+
@property
|
|
82
|
+
def key_missing(self) -> bool:
|
|
83
|
+
"""``True`` when the signing key is not in the keyring used."""
|
|
84
|
+
return self.status == "no public key"
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class TRO:
|
|
88
|
+
gpg_fingerprint = None
|
|
89
|
+
gpg_key_id = None
|
|
90
|
+
gpg_passphrase = None
|
|
91
|
+
basename = None
|
|
92
|
+
profile = None
|
|
93
|
+
_gpg_obj = None
|
|
94
|
+
|
|
95
|
+
def __init__(
|
|
96
|
+
self,
|
|
97
|
+
filepath=None,
|
|
98
|
+
gpg_fingerprint=None,
|
|
99
|
+
gpg_passphrase=None,
|
|
100
|
+
profile=None,
|
|
101
|
+
tro_creator=None,
|
|
102
|
+
tro_creator_type=None,
|
|
103
|
+
tro_name=None,
|
|
104
|
+
tro_description=None,
|
|
105
|
+
extra_context=None,
|
|
106
|
+
):
|
|
107
|
+
if filepath is None:
|
|
108
|
+
self.basename = "some_tro"
|
|
109
|
+
self.dirname = "."
|
|
110
|
+
else:
|
|
111
|
+
filepath_obj = pathlib.Path(filepath)
|
|
112
|
+
self.basename = filepath_obj.stem
|
|
113
|
+
self.dirname = (
|
|
114
|
+
str(filepath_obj.parent)
|
|
115
|
+
if filepath_obj.parent != pathlib.Path(".")
|
|
116
|
+
else "."
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
if profile is not None and pathlib.Path(profile).exists():
|
|
120
|
+
print(f"Loading profile from {profile}")
|
|
121
|
+
self.profile = json.load(open(profile))
|
|
122
|
+
else:
|
|
123
|
+
self.profile = {
|
|
124
|
+
"schema:description": "Default TRS with no capabilities",
|
|
125
|
+
"trov:hasCapability": [],
|
|
126
|
+
"trov:publicKey": None,
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
if not pathlib.Path(self.tro_filename).exists():
|
|
130
|
+
trs = TrustedResearchSystem.from_profile(self.profile)
|
|
131
|
+
# A bare name carries no type, so honour tro_creator_type and fall
|
|
132
|
+
# back to an organization. None lets the model credit the TRS.
|
|
133
|
+
creator = None
|
|
134
|
+
if tro_creator:
|
|
135
|
+
creator = Agent(
|
|
136
|
+
name=tro_creator,
|
|
137
|
+
agent_type=tro_creator_type or ORGANIZATION,
|
|
138
|
+
)
|
|
139
|
+
self._model = TransparentResearchObject(
|
|
140
|
+
creator=creator,
|
|
141
|
+
name=tro_name or "Some TRO",
|
|
142
|
+
description=tro_description or "Some description",
|
|
143
|
+
trs=trs,
|
|
144
|
+
created_with_name="tro-utils",
|
|
145
|
+
created_with_version=__version__,
|
|
146
|
+
)
|
|
147
|
+
else:
|
|
148
|
+
self._model = TransparentResearchObject.load(self.tro_filename)
|
|
149
|
+
|
|
150
|
+
if extra_context:
|
|
151
|
+
self._model.extra_context.update(extra_context)
|
|
152
|
+
|
|
153
|
+
# GPG configuration is only recorded here; nothing touches the keyring
|
|
154
|
+
# until a signature is actually produced. See _gpg() and
|
|
155
|
+
# attach_public_key().
|
|
156
|
+
if gpg_fingerprint:
|
|
157
|
+
self.gpg_fingerprint = gpg_fingerprint
|
|
158
|
+
if gpg_passphrase:
|
|
159
|
+
self.gpg_passphrase = gpg_passphrase
|
|
160
|
+
|
|
161
|
+
# ------------------------------------------------------------------
|
|
162
|
+
# File path helpers
|
|
163
|
+
# ------------------------------------------------------------------
|
|
164
|
+
|
|
165
|
+
@property
|
|
166
|
+
def base_filename(self):
|
|
167
|
+
if not self.basename:
|
|
168
|
+
raise ValueError("basename is not set")
|
|
169
|
+
return str((pathlib.Path(self.dirname) / self.basename).resolve())
|
|
170
|
+
|
|
171
|
+
@property
|
|
172
|
+
def tro_filename(self):
|
|
173
|
+
return f"{self.base_filename}.jsonld"
|
|
174
|
+
|
|
175
|
+
@property
|
|
176
|
+
def sig_filename(self):
|
|
177
|
+
return f"{self.base_filename}.sig"
|
|
178
|
+
|
|
179
|
+
@property
|
|
180
|
+
def tsr_filename(self):
|
|
181
|
+
return f"{self.base_filename}.tsr"
|
|
182
|
+
|
|
183
|
+
# ------------------------------------------------------------------
|
|
184
|
+
# data property — computed from the underlying model
|
|
185
|
+
# ------------------------------------------------------------------
|
|
186
|
+
|
|
187
|
+
@property
|
|
188
|
+
def data(self) -> dict:
|
|
189
|
+
"""Return the current JSON-LD representation of the TRO.
|
|
190
|
+
|
|
191
|
+
Computed on every access from the underlying
|
|
192
|
+
:class:`~tro_utils.models.TransparentResearchObject`.
|
|
193
|
+
"""
|
|
194
|
+
return self._model.to_jsonld()
|
|
195
|
+
|
|
196
|
+
# ------------------------------------------------------------------
|
|
197
|
+
# Delegation helpers
|
|
198
|
+
# ------------------------------------------------------------------
|
|
199
|
+
|
|
200
|
+
def get_composition_seq(self):
|
|
201
|
+
return len(self._model.composition.artifacts)
|
|
202
|
+
|
|
203
|
+
def get_arrangement_seq(self):
|
|
204
|
+
return len(self._model.arrangements)
|
|
205
|
+
|
|
206
|
+
def list_arrangements(self):
|
|
207
|
+
return self.data["@graph"][0]["trov:hasArrangement"]
|
|
208
|
+
|
|
209
|
+
def list_performances(self):
|
|
210
|
+
"""Return the performances as JSON-LD dicts, in insertion order.
|
|
211
|
+
|
|
212
|
+
Unlike the serialised declaration, ``trov:accessedArrangement`` and
|
|
213
|
+
``trov:contributedToArrangement`` are always lists (possibly empty), so
|
|
214
|
+
callers need not special-case a single binding.
|
|
215
|
+
"""
|
|
216
|
+
performances = []
|
|
217
|
+
for perf in self._model.performances:
|
|
218
|
+
data = perf.to_jsonld()
|
|
219
|
+
data["trov:accessedArrangement"] = [
|
|
220
|
+
b.to_jsonld() for b in perf.accessed_arrangements
|
|
221
|
+
]
|
|
222
|
+
data["trov:contributedToArrangement"] = [
|
|
223
|
+
b.to_jsonld() for b in perf.contributed_to_arrangements
|
|
224
|
+
]
|
|
225
|
+
performances.append(data)
|
|
226
|
+
return performances
|
|
227
|
+
|
|
228
|
+
def get_arrangement_path_hash_map(self, arrangement_id):
|
|
229
|
+
arrangement = next(
|
|
230
|
+
(a for a in self._model.arrangements if a.arrangement_id == arrangement_id),
|
|
231
|
+
None,
|
|
232
|
+
)
|
|
233
|
+
if arrangement is None:
|
|
234
|
+
available = [a.arrangement_id for a in self._model.arrangements]
|
|
235
|
+
raise ValueError(
|
|
236
|
+
f"Arrangement '{arrangement_id}' not found. "
|
|
237
|
+
f"Available arrangements: {available}"
|
|
238
|
+
)
|
|
239
|
+
return arrangement.to_path_hash_map(self._model.composition)
|
|
240
|
+
|
|
241
|
+
def add_arrangement(
|
|
242
|
+
self, directory, ignore_dirs=None, comment=None, resolve_symlinks=True
|
|
243
|
+
):
|
|
244
|
+
self._model.add_arrangement(
|
|
245
|
+
directory=directory,
|
|
246
|
+
comment=comment,
|
|
247
|
+
ignore_dirs=ignore_dirs,
|
|
248
|
+
resolve_symlinks=resolve_symlinks,
|
|
249
|
+
)
|
|
250
|
+
|
|
251
|
+
def add_arrangement_from_snapshot(self, filepath, comment=None):
|
|
252
|
+
self._model.add_arrangement_from_snapshot(filepath=filepath, comment=comment)
|
|
253
|
+
|
|
254
|
+
def save(self):
|
|
255
|
+
self._model.save(self.tro_filename)
|
|
256
|
+
|
|
257
|
+
# ------------------------------------------------------------------
|
|
258
|
+
# Hashing utilities
|
|
259
|
+
# ------------------------------------------------------------------
|
|
260
|
+
|
|
261
|
+
@staticmethod
|
|
262
|
+
def sha256_for_file(filepath, resolve_symlinks=True):
|
|
263
|
+
from .models.arrangement import ArtifactArrangement
|
|
264
|
+
|
|
265
|
+
return ArtifactArrangement._sha256_for_file(filepath, resolve_symlinks)
|
|
266
|
+
|
|
267
|
+
# ------------------------------------------------------------------
|
|
268
|
+
# Signing and timestamping
|
|
269
|
+
# ------------------------------------------------------------------
|
|
270
|
+
|
|
271
|
+
def _gpg(self):
|
|
272
|
+
"""Return the GPG interface, constructing it on first use.
|
|
273
|
+
|
|
274
|
+
Instantiating :class:`gnupg.GPG` spawns the ``gpg`` binary, so it is
|
|
275
|
+
deferred until a key is actually needed. Creating, mutating, saving,
|
|
276
|
+
reporting on and verifying a TRO therefore require neither the binary
|
|
277
|
+
nor a keyring.
|
|
278
|
+
"""
|
|
279
|
+
if self._gpg_obj is None:
|
|
280
|
+
import gnupg
|
|
281
|
+
|
|
282
|
+
self._gpg_obj = gnupg.GPG(gnupghome=GPG_HOME, verbose=False)
|
|
283
|
+
return self._gpg_obj
|
|
284
|
+
|
|
285
|
+
def _resolve_key_id(self):
|
|
286
|
+
"""Resolve the configured fingerprint against the local keyring."""
|
|
287
|
+
if self.gpg_fingerprint is None:
|
|
288
|
+
raise RuntimeError("GPG fingerprint was not provided")
|
|
289
|
+
if self.gpg_key_id is None:
|
|
290
|
+
try:
|
|
291
|
+
self.gpg_key_id = (
|
|
292
|
+
self._gpg().list_keys().key_map[self.gpg_fingerprint]["keyid"]
|
|
293
|
+
)
|
|
294
|
+
except KeyError:
|
|
295
|
+
raise RuntimeError(
|
|
296
|
+
f"GPG key {self.gpg_fingerprint} was not found in the keyring"
|
|
297
|
+
) from None
|
|
298
|
+
return self.gpg_key_id
|
|
299
|
+
|
|
300
|
+
def attach_public_key(self):
|
|
301
|
+
"""Record the public half of the signing key in the declaration.
|
|
302
|
+
|
|
303
|
+
Called by :meth:`request_timestamp` before the declaration is hashed or
|
|
304
|
+
signed, so that ``trov:publicKey`` is by construction the public half of
|
|
305
|
+
the key that produced the signature. A value supplied by a TRS profile
|
|
306
|
+
acts as a default until it is replaced here.
|
|
307
|
+
"""
|
|
308
|
+
self._model.trs.public_key = self._gpg().export_keys(self._resolve_key_id())
|
|
309
|
+
|
|
310
|
+
def trs_signature(self):
|
|
311
|
+
if self.gpg_fingerprint is None:
|
|
312
|
+
raise RuntimeError("GPG fingerprint was not provided")
|
|
313
|
+
if self.gpg_passphrase is None:
|
|
314
|
+
raise RuntimeError("GPG passphrase was not provided")
|
|
315
|
+
signature = self._gpg().sign(
|
|
316
|
+
json.dumps(self.data, indent=2, sort_keys=True),
|
|
317
|
+
keyid=self._resolve_key_id(),
|
|
318
|
+
passphrase=self.gpg_passphrase,
|
|
319
|
+
detach=True,
|
|
320
|
+
)
|
|
321
|
+
# The timestamp covers the LF-terminated signature, as for save().
|
|
322
|
+
with open(self.sig_filename, "w", newline="\n") as fp:
|
|
323
|
+
fp.write(str(signature))
|
|
324
|
+
return signature
|
|
325
|
+
|
|
326
|
+
def request_timestamp(self):
|
|
327
|
+
"""Request a timestamp from a remote TSA and store the result in a file.
|
|
328
|
+
|
|
329
|
+
The public key is attached and the declaration written out *before*
|
|
330
|
+
anything is hashed, so that the signature and the timestamp both cover
|
|
331
|
+
the declaration exactly as it ends up on disk. Injecting the key any
|
|
332
|
+
later — inside :meth:`trs_signature`, say — would make every TRO fail
|
|
333
|
+
its own :meth:`verify_timestamp`.
|
|
334
|
+
"""
|
|
335
|
+
self.attach_public_key()
|
|
336
|
+
self.save()
|
|
337
|
+
ts_data = {
|
|
338
|
+
"tro_declaration": hashlib.sha512(
|
|
339
|
+
json.dumps(self.data, indent=2, sort_keys=True).encode("utf-8")
|
|
340
|
+
).hexdigest(),
|
|
341
|
+
"trs_signature": hashlib.sha512(
|
|
342
|
+
str(self.trs_signature()).encode("utf-8")
|
|
343
|
+
).hexdigest(),
|
|
344
|
+
}
|
|
345
|
+
tsr_payload = json.dumps(ts_data, indent=2, sort_keys=True).encode()
|
|
346
|
+
tsr = tsa.request_token(tsr_payload)
|
|
347
|
+
with open(self.tsr_filename, "wb") as fs:
|
|
348
|
+
fs.write(tsr)
|
|
349
|
+
|
|
350
|
+
def get_composition_info(self):
|
|
351
|
+
return self.data["@graph"][0]["trov:hasComposition"]
|
|
352
|
+
|
|
353
|
+
def created_with_mismatch(self):
|
|
354
|
+
"""Explain why this TRO may not verify with the running tro-utils.
|
|
355
|
+
|
|
356
|
+
tro-utils makes no backward-compatibility guarantee, so a TRO is only
|
|
357
|
+
guaranteed to verify with the version recorded in ``trov:createdWith``.
|
|
358
|
+
|
|
359
|
+
Returns:
|
|
360
|
+
A human-readable message if the TRO was created by different
|
|
361
|
+
software or a different tro-utils version, otherwise ``None``.
|
|
362
|
+
"""
|
|
363
|
+
name = self._model.created_with_name
|
|
364
|
+
version = self._model.created_with_version
|
|
365
|
+
if name == "tro-utils" and version == __version__:
|
|
366
|
+
return None
|
|
367
|
+
if not name and not version:
|
|
368
|
+
return (
|
|
369
|
+
"The TRO does not record which software created it "
|
|
370
|
+
"(no trov:createdWith); it may not verify with "
|
|
371
|
+
f"tro-utils {__version__}."
|
|
372
|
+
)
|
|
373
|
+
created = " ".join(filter(None, [name or "unknown software", version]))
|
|
374
|
+
msg = (
|
|
375
|
+
f"The TRO was created with {created}, but this is "
|
|
376
|
+
f"tro-utils {__version__}."
|
|
377
|
+
)
|
|
378
|
+
if name == "tro-utils" and version:
|
|
379
|
+
msg += f" Verify it with: pip install tro-utils=={version}"
|
|
380
|
+
return msg
|
|
381
|
+
|
|
382
|
+
def verify_timestamp(self, quiet=False):
|
|
383
|
+
"""Verify that a run is valid and signed.
|
|
384
|
+
|
|
385
|
+
Args:
|
|
386
|
+
quiet: Don't pass on what openssl prints.
|
|
387
|
+
"""
|
|
388
|
+
|
|
389
|
+
try:
|
|
390
|
+
with open(self.sig_filename, "rb") as fp:
|
|
391
|
+
trs_signature = fp.read()
|
|
392
|
+
except FileNotFoundError:
|
|
393
|
+
raise RuntimeError("Signature file does not exist")
|
|
394
|
+
# Hash the declaration as stored, as verify_signature() does: the
|
|
395
|
+
# re-serialized model need not match the bytes that were timestamped.
|
|
396
|
+
with open(self.tro_filename, "rb") as fp:
|
|
397
|
+
declaration = fp.read()
|
|
398
|
+
|
|
399
|
+
ts_data = {
|
|
400
|
+
"tro_declaration": hashlib.sha512(declaration).hexdigest(),
|
|
401
|
+
"trs_signature": hashlib.sha512(trs_signature).hexdigest(),
|
|
402
|
+
}
|
|
403
|
+
tsr_payload = json.dumps(ts_data, indent=2, sort_keys=True).encode()
|
|
404
|
+
try:
|
|
405
|
+
with open(self.tsr_filename, "rb") as fp:
|
|
406
|
+
response = fp.read()
|
|
407
|
+
except FileNotFoundError:
|
|
408
|
+
raise RuntimeError("Timestamp file does not exist")
|
|
409
|
+
|
|
410
|
+
try:
|
|
411
|
+
tsa.verify_token(tsr_payload, response, quiet=quiet)
|
|
412
|
+
except subprocess.CalledProcessError as err:
|
|
413
|
+
mismatch = self.created_with_mismatch()
|
|
414
|
+
if mismatch is None:
|
|
415
|
+
raise
|
|
416
|
+
raise RuntimeError(f"Timestamp verification failed. {mismatch}") from err
|
|
417
|
+
|
|
418
|
+
def timestamp_time(self):
|
|
419
|
+
"""Return the time in the TRO's timestamp, without verifying it."""
|
|
420
|
+
with open(self.tsr_filename, "rb") as fp:
|
|
421
|
+
return tsa.token_time(fp.read())
|
|
422
|
+
|
|
423
|
+
def verify_signature(
|
|
424
|
+
self,
|
|
425
|
+
use_embedded_key=False,
|
|
426
|
+
gnupghome=None,
|
|
427
|
+
keyring=None,
|
|
428
|
+
fingerprints=None,
|
|
429
|
+
trs_keys=None,
|
|
430
|
+
):
|
|
431
|
+
"""Verify the TRS signature against the declaration as stored on disk.
|
|
432
|
+
|
|
433
|
+
The signing key is looked up in the verifier's keyring: tro-utils does
|
|
434
|
+
not decide how a TRS key comes to be trusted. The ``trov:publicKey``
|
|
435
|
+
embedded in the TRO is only attested by the TRO itself, so it is used
|
|
436
|
+
for verification only when explicitly requested.
|
|
437
|
+
|
|
438
|
+
Args:
|
|
439
|
+
use_embedded_key: Verify with a throwaway keyring holding only the
|
|
440
|
+
key embedded in the TRO instead of the verifier's keyring.
|
|
441
|
+
gnupghome: GnuPG home of the keyring to use; defaults to
|
|
442
|
+
``GPG_HOME`` or GnuPG's own default.
|
|
443
|
+
keyring: A key file (armored or binary) to verify with instead,
|
|
444
|
+
through a throwaway keyring holding only the keys in it.
|
|
445
|
+
fingerprints: Fingerprints the signing key is expected to have,
|
|
446
|
+
e.g. as published by the TRS. A signature by any other key is
|
|
447
|
+
reported as invalid.
|
|
448
|
+
trs_keys: A key list (path or :class:`TRSKeyList`) saying which
|
|
449
|
+
keys the TRS signed with and when. The key is then judged by
|
|
450
|
+
the list at the time of the TRO's trusted timestamp, which is
|
|
451
|
+
verified too, instead of by its current OpenPGP state. Unless
|
|
452
|
+
``gnupghome`` or ``keyring`` is given, the key embedded in
|
|
453
|
+
the TRO is used, since the list vouches for its fingerprint.
|
|
454
|
+
|
|
455
|
+
Returns:
|
|
456
|
+
A :class:`SignatureVerification`.
|
|
457
|
+
"""
|
|
458
|
+
import gnupg
|
|
459
|
+
|
|
460
|
+
if use_embedded_key + bool(gnupghome) + bool(keyring) > 1:
|
|
461
|
+
raise ValueError(
|
|
462
|
+
"use_embedded_key, gnupghome and keyring are mutually exclusive"
|
|
463
|
+
)
|
|
464
|
+
expected = {normalize_fingerprint(fp) for fp in fingerprints or ()}
|
|
465
|
+
key_list = None
|
|
466
|
+
if trs_keys is not None:
|
|
467
|
+
key_list = (
|
|
468
|
+
trs_keys
|
|
469
|
+
if isinstance(trs_keys, TRSKeyList)
|
|
470
|
+
else TRSKeyList.load(trs_keys)
|
|
471
|
+
)
|
|
472
|
+
if not gnupghome and not keyring:
|
|
473
|
+
use_embedded_key = True
|
|
474
|
+
if not os.path.exists(self.sig_filename):
|
|
475
|
+
raise RuntimeError("Signature file does not exist")
|
|
476
|
+
with open(self.tro_filename, "rb") as fp:
|
|
477
|
+
declaration = fp.read()
|
|
478
|
+
public_key = self._model.trs.public_key
|
|
479
|
+
|
|
480
|
+
if use_embedded_key and not public_key:
|
|
481
|
+
raise RuntimeError("The TRO does not embed a public key")
|
|
482
|
+
|
|
483
|
+
throwaway = use_embedded_key or keyring is not None
|
|
484
|
+
with tempfile.TemporaryDirectory() as tmp_home:
|
|
485
|
+
try:
|
|
486
|
+
if throwaway:
|
|
487
|
+
gpg = gnupg.GPG(gnupghome=tmp_home, options=_VERIFY_OPTIONS)
|
|
488
|
+
imported = (
|
|
489
|
+
gpg.import_keys(public_key)
|
|
490
|
+
if use_embedded_key
|
|
491
|
+
else gpg.import_keys_file(keyring)
|
|
492
|
+
)
|
|
493
|
+
if keyring is not None and not imported.fingerprints:
|
|
494
|
+
raise RuntimeError(f"No public keys found in {keyring}")
|
|
495
|
+
else:
|
|
496
|
+
gpg = gnupg.GPG(
|
|
497
|
+
gnupghome=gnupghome or GPG_HOME, options=_VERIFY_OPTIONS
|
|
498
|
+
)
|
|
499
|
+
|
|
500
|
+
result = gpg.verify_data(self.sig_filename, declaration)
|
|
501
|
+
embedded = set()
|
|
502
|
+
if public_key:
|
|
503
|
+
for key in gpg.scan_keys_mem(public_key):
|
|
504
|
+
embedded.add(key["fingerprint"])
|
|
505
|
+
embedded.update(s[2] for s in key.get("subkeys", []) if s[2])
|
|
506
|
+
finally:
|
|
507
|
+
if throwaway:
|
|
508
|
+
_kill_gpg_agent(tmp_home)
|
|
509
|
+
|
|
510
|
+
fingerprint = (
|
|
511
|
+
getattr(result, "pubkey_fingerprint", None)
|
|
512
|
+
or result.fingerprint
|
|
513
|
+
or result.key_id
|
|
514
|
+
)
|
|
515
|
+
# gpg reports VALIDSIG after EXPKEYSIG/REVKEYSIG, which overwrites
|
|
516
|
+
# status with "signature valid"; key_status keeps the reason.
|
|
517
|
+
status = result.key_status or result.status or "signature error"
|
|
518
|
+
valid = bool(result.valid)
|
|
519
|
+
# Before GnuPG 2.2.7 a missing key is reported by key ID only, which is
|
|
520
|
+
# the tail of its fingerprint.
|
|
521
|
+
signer = {result.fingerprint, fingerprint} - {None}
|
|
522
|
+
|
|
523
|
+
warnings = []
|
|
524
|
+
listed = None
|
|
525
|
+
signed_at = None
|
|
526
|
+
# VALIDSIG, i.e. the signature is cryptographically correct, whatever
|
|
527
|
+
# gpg thinks of the key's expiry or revocation today.
|
|
528
|
+
if key_list is not None and result.status == "signature valid":
|
|
529
|
+
if os.path.exists(self.tsr_filename):
|
|
530
|
+
try:
|
|
531
|
+
self.verify_timestamp(quiet=True)
|
|
532
|
+
except subprocess.CalledProcessError as err:
|
|
533
|
+
raise RuntimeError(
|
|
534
|
+
"Timestamp verification failed, so the time of signing "
|
|
535
|
+
"is unknown"
|
|
536
|
+
) from err
|
|
537
|
+
signed_at = self.timestamp_time()
|
|
538
|
+
trs_id = self._model.trs.trs_id
|
|
539
|
+
listed_keys = key_list.keys_for(trs_id)
|
|
540
|
+
listed = next(
|
|
541
|
+
(k for k in listed_keys or () if k.fingerprint in signer), None
|
|
542
|
+
)
|
|
543
|
+
if listed_keys is None:
|
|
544
|
+
valid = False
|
|
545
|
+
status = f"the key list has no TRS with @id {trs_id}"
|
|
546
|
+
elif listed is None:
|
|
547
|
+
valid = False
|
|
548
|
+
status = f"the signing key is not listed for {trs_id}"
|
|
549
|
+
else:
|
|
550
|
+
valid, message = listed.check(signed_at)
|
|
551
|
+
if not valid:
|
|
552
|
+
status = message
|
|
553
|
+
else:
|
|
554
|
+
status = "signature valid"
|
|
555
|
+
if message:
|
|
556
|
+
warnings.append(message)
|
|
557
|
+
if result.key_status:
|
|
558
|
+
warnings.append(
|
|
559
|
+
f"GnuPG reports: {result.key_status}; the key was "
|
|
560
|
+
"judged by the key list instead"
|
|
561
|
+
)
|
|
562
|
+
if result.trust_level == result.TRUST_NEVER:
|
|
563
|
+
valid = False
|
|
564
|
+
status = "signing key is marked as never trusted"
|
|
565
|
+
# The primary key or the subkey that made the signature may be named.
|
|
566
|
+
fingerprint_matches = bool(signer & expected) if expected else None
|
|
567
|
+
if valid and fingerprint_matches is False:
|
|
568
|
+
valid = False
|
|
569
|
+
status = "signing key does not have the expected fingerprint"
|
|
570
|
+
return SignatureVerification(
|
|
571
|
+
valid=valid,
|
|
572
|
+
status=status,
|
|
573
|
+
fingerprint=fingerprint,
|
|
574
|
+
username=result.username,
|
|
575
|
+
trust=result.trust_text if valid else None,
|
|
576
|
+
trusted=valid
|
|
577
|
+
and (
|
|
578
|
+
fingerprint_matches is True
|
|
579
|
+
or listed is not None
|
|
580
|
+
or keyring is not None
|
|
581
|
+
or (
|
|
582
|
+
not use_embedded_key
|
|
583
|
+
and result.trust_level is not None
|
|
584
|
+
and result.trust_level >= result.TRUST_MARGINAL
|
|
585
|
+
)
|
|
586
|
+
),
|
|
587
|
+
used_embedded_key=use_embedded_key,
|
|
588
|
+
keyring=keyring,
|
|
589
|
+
fingerprint_matches=fingerprint_matches,
|
|
590
|
+
listed_status=listed.status if listed is not None else None,
|
|
591
|
+
timestamp=signed_at,
|
|
592
|
+
warnings=warnings,
|
|
593
|
+
embedded_key_matches=(
|
|
594
|
+
any(fp.endswith(s) for fp in embedded for s in signer)
|
|
595
|
+
if embedded
|
|
596
|
+
else None
|
|
597
|
+
),
|
|
598
|
+
)
|
|
599
|
+
|
|
600
|
+
# ------------------------------------------------------------------
|
|
601
|
+
# Replication package verification
|
|
602
|
+
# ------------------------------------------------------------------
|
|
603
|
+
|
|
604
|
+
def verify_replication_package(self, arrangement_id, package, subpath=None):
|
|
605
|
+
from .replication_package import ReplicationPackage
|
|
606
|
+
|
|
607
|
+
arrangement = next(
|
|
608
|
+
(a for a in self._model.arrangements if a.arrangement_id == arrangement_id),
|
|
609
|
+
None,
|
|
610
|
+
)
|
|
611
|
+
if arrangement is None:
|
|
612
|
+
available = [a.arrangement_id for a in self._model.arrangements]
|
|
613
|
+
raise ValueError(
|
|
614
|
+
f"Arrangement '{arrangement_id}' not found. "
|
|
615
|
+
f"Available arrangements: {available}"
|
|
616
|
+
)
|
|
617
|
+
result = ReplicationPackage.verify(
|
|
618
|
+
arrangement, self._model.composition, package, subpath
|
|
619
|
+
)
|
|
620
|
+
return (
|
|
621
|
+
result.files_missing_in_arrangement,
|
|
622
|
+
result.mismatched_hashes,
|
|
623
|
+
result.files_missing_in_package,
|
|
624
|
+
result.is_valid,
|
|
625
|
+
)
|
|
626
|
+
|
|
627
|
+
# ------------------------------------------------------------------
|
|
628
|
+
# Performance recording
|
|
629
|
+
# ------------------------------------------------------------------
|
|
630
|
+
|
|
631
|
+
def add_performance(
|
|
632
|
+
self,
|
|
633
|
+
start_time,
|
|
634
|
+
end_time,
|
|
635
|
+
comment=None,
|
|
636
|
+
accessed_arrangement=None, # str | (str, str|None) | list[...] | None
|
|
637
|
+
modified_arrangement=None, # str | (str, str|None) | list[...] | None
|
|
638
|
+
attrs=None,
|
|
639
|
+
extra_attributes=None,
|
|
640
|
+
):
|
|
641
|
+
self._model.add_performance(
|
|
642
|
+
start_time=start_time,
|
|
643
|
+
end_time=end_time,
|
|
644
|
+
comment=comment,
|
|
645
|
+
accessed_arrangement=accessed_arrangement,
|
|
646
|
+
modified_arrangement=modified_arrangement,
|
|
647
|
+
attrs=attrs,
|
|
648
|
+
extra_attributes=extra_attributes,
|
|
649
|
+
)
|
|
650
|
+
|
|
651
|
+
# ------------------------------------------------------------------
|
|
652
|
+
# Report generation
|
|
653
|
+
# ------------------------------------------------------------------
|
|
654
|
+
|
|
655
|
+
def generate_report(self, template, report):
|
|
656
|
+
graph = self.data["@graph"][0]
|
|
657
|
+
artifact_lookup = {a.artifact_id: a for a in self._model.composition.artifacts}
|
|
658
|
+
arrangements = {}
|
|
659
|
+
for arr in self._model.arrangements:
|
|
660
|
+
artifacts = {
|
|
661
|
+
loc.path: {
|
|
662
|
+
"hash": artifact_lookup[loc.artifact_id].hash.to_string(),
|
|
663
|
+
"creator": "trs",
|
|
664
|
+
"createdDate": "None",
|
|
665
|
+
}
|
|
666
|
+
for loc in sorted(arr.locations, key=lambda _: _.path)
|
|
667
|
+
}
|
|
668
|
+
arrangements[arr.arrangement_id] = {
|
|
669
|
+
"name": arr.comment,
|
|
670
|
+
"artifacts": artifacts,
|
|
671
|
+
}
|
|
672
|
+
|
|
673
|
+
dot = graphviz.Digraph("TRO")
|
|
674
|
+
dot.graph_attr["rankdir"] = "LR"
|
|
675
|
+
dot.attr("edge", color="black")
|
|
676
|
+
dot.graph_attr["dpi"] = "200"
|
|
677
|
+
|
|
678
|
+
dot.attr("node", shape="box", style="filled, rounded", fillcolor="#FFFFD1")
|
|
679
|
+
for arr_id in arrangements:
|
|
680
|
+
dot.node(arrangements[arr_id]["name"])
|
|
681
|
+
|
|
682
|
+
dot.attr("node", shape="box3d", style="filled, rounded", fillcolor="#D6FDD0")
|
|
683
|
+
for perf in self._model.performances:
|
|
684
|
+
dot.node(perf.comment)
|
|
685
|
+
for ref in perf.accessed_arrangements:
|
|
686
|
+
dot.edge(arrangements[ref.arrangement_id]["name"], perf.comment)
|
|
687
|
+
for ref in perf.contributed_to_arrangements:
|
|
688
|
+
dot.edge(perf.comment, arrangements[ref.arrangement_id]["name"])
|
|
689
|
+
|
|
690
|
+
png_bytes = dot.pipe(format="png")
|
|
691
|
+
png_base64 = base64.b64encode(png_bytes).decode("utf-8")
|
|
692
|
+
|
|
693
|
+
keys = list(arrangements.keys())
|
|
694
|
+
|
|
695
|
+
for n in reversed(range(1, len(keys))):
|
|
696
|
+
for location in arrangements[keys[n]]["artifacts"]:
|
|
697
|
+
if location in arrangements[keys[n - 1]]["artifacts"]:
|
|
698
|
+
if (
|
|
699
|
+
arrangements[keys[n]]["artifacts"][location]["hash"]
|
|
700
|
+
!= arrangements[keys[n - 1]]["artifacts"][location]["hash"]
|
|
701
|
+
):
|
|
702
|
+
arrangements[keys[n]]["artifacts"][location][
|
|
703
|
+
"status"
|
|
704
|
+
] = "Changed"
|
|
705
|
+
else:
|
|
706
|
+
arrangements[keys[n]]["artifacts"][location][
|
|
707
|
+
"status"
|
|
708
|
+
] = "Unchanged"
|
|
709
|
+
else:
|
|
710
|
+
arrangements[keys[n]]["artifacts"][location]["status"] = "Created"
|
|
711
|
+
|
|
712
|
+
data = {
|
|
713
|
+
**graph,
|
|
714
|
+
"workflow_diagram": png_base64,
|
|
715
|
+
"logo": base64.b64encode(_LOGO.read_bytes()).decode("utf-8"),
|
|
716
|
+
"trps": [
|
|
717
|
+
{
|
|
718
|
+
"id": perf.performance_id,
|
|
719
|
+
"started": perf.started_at.isoformat() if perf.started_at else None,
|
|
720
|
+
"ended": perf.ended_at.isoformat() if perf.ended_at else None,
|
|
721
|
+
"accessed": [
|
|
722
|
+
arrangements[ref.arrangement_id]["name"]
|
|
723
|
+
for ref in perf.accessed_arrangements
|
|
724
|
+
],
|
|
725
|
+
"contributed": [
|
|
726
|
+
arrangements[ref.arrangement_id]["name"]
|
|
727
|
+
for ref in perf.contributed_to_arrangements
|
|
728
|
+
],
|
|
729
|
+
"description": perf.comment,
|
|
730
|
+
}
|
|
731
|
+
for perf in self._model.performances
|
|
732
|
+
],
|
|
733
|
+
"arrangements": arrangements,
|
|
734
|
+
}
|
|
735
|
+
|
|
736
|
+
with open(template) as file_:
|
|
737
|
+
template = Template(file_.read())
|
|
738
|
+
|
|
739
|
+
with open(report, "w") as fh:
|
|
740
|
+
fh.write(template.render(tro=data))
|