ib1-provenance 0.1__tar.gz

ib1_provenance-0.1/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Icebreaker One
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

ib1_provenance-0.1/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.1
+Name: ib1-provenance
+Version: 0.1
+Summary: Tools to encode, decode, and sign provenance data
+Author: Ben Summers
+Author-email: ben.summers@icebreakerone.org
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: asn1crypto (>=1.5.1,<2.0.0)
+Requires-Dist: cryptography (>=43.0.1,<44.0.0)
+Description-Content-Type: text/markdown
+
+# Provenance
+
+```
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+
+pipx install poetry
+poetry install
+
+mkdir certs
+cd certs
+sh ../scripts/certmaker.sh
+
+python3 main.py
+```
+
+## Provenance record decoder
+
+```
+python3 decode-self-contained-provenance.py path/to/signing-CA-root.pem < record.json
+```
+

ib1_provenance-0.1/README.md

@@ -0,0 +1,22 @@
+# Provenance
+
+```
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+
+pipx install poetry
+poetry install
+
+mkdir certs
+cd certs
+sh ../scripts/certmaker.sh
+
+python3 main.py
+```
+
+## Provenance record decoder
+
+```
+python3 decode-self-contained-provenance.py path/to/signing-CA-root.pem < record.json
+```

ib1_provenance-0.1/pyproject.toml

@@ -0,0 +1,25 @@
+[tool.poetry]
+name = "ib1-provenance"
+version = "0.1"
+description = "Tools to encode, decode, and sign provenance data"
+authors = ["Ben Summers <ben.summers@icebreakerone.org>"]
+readme = "README.md"
+packages = [{include = "ib1", from = "src"}]
+
+
+[tool.poetry.dependencies]
+python = "^3.10"
+cryptography = "^43.0.1"
+asn1crypto = "^1.5.1"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.3"
+mypy = "^1.12.0"
+ruff = "^0.6.9"
+pytest-cov = "^5.0.0"
+tox = "^4.23.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

ib1_provenance-0.1/src/ib1/provenance/__init__.py

@@ -0,0 +1,2 @@
+
+from .record import Record

ib1_provenance-0.1/src/ib1/provenance/certificates.py

@@ -0,0 +1,107 @@
+
+import json
+import base64
+import datetime
+
+from cryptography import x509
+from cryptography.x509.oid import NameOID, ExtensionOID
+from cryptography.x509.verification import PolicyBuilder, Store
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+import asn1crypto.core as asn1
+
+# ---------------------------------------------------------------------------
+
+OID_IB1_ROLES = x509.ObjectIdentifier("1.3.6.1.4.1.62329.1.1")
+OID_IB1_APPLICATION = x509.ObjectIdentifier("1.3.6.1.4.1.62329.1.2")
+
+class CertExtUTF8Sequence(asn1.SequenceOf):
+    _child_spec = asn1.UTF8String
+
+class SigningCertificate:
+    def __init__(self, x509_certificate: x509.Certificate):
+        self._x509_certificate = x509_certificate
+
+    def subject(self):
+        san_extension = self._x509_certificate.extensions.get_extension_for_oid(ExtensionOID.SUBJECT_ALTERNATIVE_NAME)
+        uri = san_extension.value.get_values_for_type(x509.UniformResourceIdentifier)
+        if len(uri) != 1:
+            raise Exception("Certificate doesn't contain exactly one URI subject alternative name")
+        return uri[0]
+
+    def organisation_name(self):
+        return self._x509_certificate.subject.get_attributes_for_oid(NameOID.ORGANIZATION_NAME)[0].value
+
+    def application(self):
+        value = self._x509_certificate.extensions.get_extension_for_oid(OID_IB1_APPLICATION).value.value # type: ignore [attr-defined]
+        return str(asn1.UTF8String.load(value))
+
+    def roles(self):
+        value = self._x509_certificate.extensions.get_extension_for_oid(OID_IB1_ROLES).value.value # type: ignore [attr-defined]
+        return list(map(str, CertExtUTF8Sequence.load(value)))
+
+# ---------------------------------------------------------------------------
+
+class CertificateProviderBase:
+    def __init__(self, root_ca_certificate):
+        with open(root_ca_certificate, "rb") as f:
+            self._ca_store = Store(x509.load_pem_x509_certificates(f.read()))
+
+    def policy_include_certificates_in_record(self):
+        return False
+
+    def _verify(self, certificates_from_record, serial, sign_timestamp, data, signature):
+        certs = self.certificates_for_serial(certificates_from_record, serial)
+        # first certificate in file is signing certificate
+        signing_cert, *issuer_chain = certs
+        # 1) check certificate chain validity at the time of signature
+        verification_time = datetime.datetime.fromisoformat(sign_timestamp)
+        verifier = (PolicyBuilder().
+                        store(self._ca_store).
+                        time(verification_time).
+                        build_client_verifier())
+        verifier.verify(signing_cert, issuer_chain)
+        # 2) check signature on data
+        pubkey = signing_cert.public_key()
+        pubkey.verify(signature, data, ec.ECDSA(hashes.SHA256()))
+        # Return information about the signer
+        cert_info = SigningCertificate(signing_cert)
+        return {
+            "member": cert_info.subject(),
+            "name": cert_info.organisation_name(),
+            "application": cert_info.application(),
+            "roles": cert_info.roles()
+        }
+
+# ---------------------------------------------------------------------------
+
+class CertificatesProviderLocal(CertificateProviderBase):
+    def __init__(self, root_ca_certificate, directory):
+        CertificateProviderBase.__init__(self, root_ca_certificate)
+        self._directory = directory
+
+    def certificates_for_serial(self, certificates_from_record, serial):
+        certificate_filename = self._directory + '/' + str(int(serial)) + '-bundle.pem'
+        with open(certificate_filename, "rb") as f:
+            return x509.load_pem_x509_certificates(f.read())
+
+# ---------------------------------------------------------------------------
+
+class CertificatesProviderSelfContainedRecord(CertificateProviderBase):
+    def policy_include_certificates_in_record(self):
+        return True
+
+    def certificates_for_serial(self, certificates_from_record, serial):
+        certs = certificates_from_record.get(serial)
+        if certs is None:
+            raise Exception("Certificate serial "+serial+" is not present in record")
+        signing_cert, *path_serials = certs
+        cert_chain = [signing_cert]
+        cert_chain.extend(list(map(
+            lambda s: certificates_from_record[s][0],
+            path_serials
+        )))
+        return list(map(
+            lambda c: x509.load_pem_x509_certificate(c.encode("utf-8")),
+            cert_chain
+        ))

ib1_provenance-0.1/src/ib1/provenance/identifier.py

@@ -0,0 +1,5 @@
+
+import secrets
+
+def globally_unique_step_identifier():
+    return secrets.token_urlsafe(15)

ib1_provenance-0.1/src/ib1/provenance/record.py

@@ -0,0 +1,290 @@
+import base64
+import json
+import copy
+import datetime
+
+from cryptography.hazmat.primitives import serialization
+
+from .identifier import globally_unique_step_identifier
+
+
+CURRENT_CONTAINER_FORMAT_VERSION = 0
+
+
+class Record:
+
+    # data attributes:
+    #   _record -- signed record as output from JSON decoding
+    #   _additional_records -- array of signed records to add to the record
+    #   _additional_steps -- array of steps to add to the record
+    #   _signed -- whether the record is completely signed
+    #   _verified -- whether the record has had signatures verified
+
+    def __init__(self, trust_framework, record=None):
+        if record is not None:
+            if not isinstance(record.get("steps"), list):
+                raise Exception("Not an encoded Provenance record")
+            if trust_framework != record["ib1:provenance"]:
+                raise Exception("Unexpected trust framework when creating Record from encoded form")
+        self.trust_framework = trust_framework
+        self._record = record
+        self._additional_records = []
+        self._additional_steps = []
+        self._signed = True
+        self._verified = None
+
+    def verify(self, certificate_provider):
+        self._require_signed()
+        # Recursively verify record
+        steps = []
+        origins = []
+        signer_stack = []
+        certificates_from_record = self._record.get("certificates")
+        if certificates_from_record is None:
+            certificates_from_record = {}
+        self._verify_record_container(self._record["steps"], certificates_from_record, certificate_provider, steps, origins, signer_stack)
+        if self._record["origins"] != origins:
+            raise Exception("origins property does not match origin steps in record")
+        self._verified = steps
+
+    def _verify_record_container(self, container, certificates_from_record, certificate_provider, steps, origins, signer_stack):
+        *data, sig_block = container
+        container_format_version, serial, sign_timestamp, signature = sig_block
+        # Check it's an understood format (multiple versions of formats may be included in a single record)
+        if container_format_version != CURRENT_CONTAINER_FORMAT_VERSION:
+            raise Exception("Cannot decode container format version: "+str(container_format_version))
+        # Serial number must only be a number
+        if str(int(serial)) != serial:
+            raise Exception("Bad certificate serial number in record: "+serial)
+        # Check signatures at this level and get signer information
+        data_for_signing = self._data_for_signing(data, [str(container_format_version), serial, sign_timestamp])
+        signer_info = certificate_provider._verify(certificates_from_record, serial, sign_timestamp, data_for_signing.encode("utf-8"), base64.urlsafe_b64decode(signature))
+        # Recurse into signed data, collecting decoded steps and adding signer info
+        for e in data:
+            if not isinstance(e, str):
+                signer_stack.append(signer_info)
+                self._verify_record_container(e, certificates_from_record, certificate_provider, steps, origins, signer_stack)
+                del signer_stack[-1]
+            else:
+                decoded_step = json.loads(base64.urlsafe_b64decode(e))
+                if decoded_step["type"] == "origin":
+                    origins.append(decoded_step["id"])
+                decoded_step["_signature"] = {
+                    "signed": signer_info,
+                    "includedBy": copy.copy(signer_stack)
+                }
+                steps.append(decoded_step)
+
+    def add_record(self, record):
+        self._signed = False
+        self._verified = None
+        if not isinstance(record, Record):
+            raise Exception("Not a Record object")
+        if self.trust_framework != record.trust_framework:
+            raise Exception("Incompatible trust frameworks in added Record")
+        self._additional_records.append(record.encoded())
+
+    def add_step(self, step_in):
+        self._signed = False
+        self._verified = None
+        step = copy.deepcopy(step_in)
+        # Step identifier
+        if "id" in step:
+            raise Exception("Step may not contain an id key. Identifiers are allocated automatically and returned by this function.")
+        id = globally_unique_step_identifier()
+        # Step timestamp
+        # TODO: Verify timestamp is in the right format (but signing cert does not need to be valid at that time?)
+        timestamp = step.pop("timestamp", None)
+        if not timestamp:
+            timestamp = self._timestamp_now_iso8601()
+        # Step type
+        step_type = step.pop("type")
+        # No keys with _ prefix allowed
+        prohibited_keys_present = list(filter(
+            lambda k: k.startswith('_'),
+            step.keys()
+        ))
+        if prohibited_keys_present:
+            raise Exception("Step may not contain keys beginning with an underscore. Prohibited keys present: "+(", ".join(prohibited_keys_present)))
+        # Add to list of steps pending addition
+        self._additional_steps.append({
+            "id": id,
+            "timestamp": timestamp,
+            "type": step_type,
+            **step
+        })
+        return id
+
+    def find_step(self, required_values):
+        steps = self.filter_steps(required_values)
+        if len(steps) == 0:
+            raise Exception("No step matches required values")
+        if len(steps) > 1:
+            raise Exception("More than one step matches required values")
+        return steps[0]
+
+    def filter_steps(self, required_values):
+        self._require_verified()
+        return list(filter(
+            lambda s: self._filter_step_contains(s, required_values),
+            self._verified
+        ))
+
+    def _filter_step_contains(self, step, required_values):
+        if isinstance(required_values, dict):
+            # If required_values is a dict, ensure step is a dict and contains all keys/values of required_values
+            if not isinstance(step, dict):
+                return False
+            for key, value in required_values.items():
+                if key not in step or not self._filter_step_contains(step[key], value):
+                    return False
+            return True
+        elif isinstance(required_values, list):
+            # If required_values is a list, ensure step is a list and contains all elements of required_values
+            if not isinstance(step, list):
+                return False
+            for item in required_values:
+                if not any(self._filter_step_contains(x, item) for x in step):
+                    return False
+            return True
+        else:
+            # If required_values is a primitive, ensure it matches the value in step
+            return step == required_values
+
+    def sign(self, signer):
+        output = []
+        certificates = {}
+        if self._record is not None:
+            if "certificates" in self._record:
+                certificates.update(self._record["certificates"])
+            output.append(self._record["steps"]) # signed and encoded
+        for r in self._additional_records:
+            if "certificates" in r:
+                certificates.update(r["certificates"])
+            output.append(r["steps"]) # signed and encoded
+        for s in self._additional_steps:
+            output.append(self._encode_step(s)) # unencoded, not signed
+        serial = signer.serial()
+        sign_timestamp = self._timestamp_now_iso8601()
+        data_for_signing = self._data_for_signing(output, [str(CURRENT_CONTAINER_FORMAT_VERSION), serial, sign_timestamp])
+        signature = signer.sign(data_for_signing.encode("utf-8"))
+        output.append([
+            CURRENT_CONTAINER_FORMAT_VERSION,
+            serial,
+            sign_timestamp,
+            base64.urlsafe_b64encode(signature).decode('utf-8')
+        ])
+        if not serial in certificates:
+            certs_for_record = signer.certificates_for_record()
+            if certs_for_record is not None:
+                # Represent path as [pem encoded cert, serials of issuer chain ...]
+                first_cert, *other_certs = certs_for_record
+                cert_path = [first_cert.public_bytes(serialization.Encoding.PEM).decode("utf-8")]
+                cert_path.extend(list(map(
+                    lambda c: str(c.serial_number), other_certs
+                )))
+                certificates[serial] = cert_path
+                for c in other_certs:
+                    certificates[str(c.serial_number)] = [c.public_bytes(serialization.Encoding.PEM).decode("utf-8")]
+        origins = []
+        self._gather_origins(output, origins)
+        encoded = {
+            "ib1:provenance": self.trust_framework,
+            "origins": origins,
+            "steps": copy.deepcopy(output)
+        }
+        if certificates:
+            encoded["certificates"] = certificates
+        return Record(self.trust_framework, encoded)
+
+    def _gather_origins(self, container, origins):
+        *data, sig_block = container
+        for e in data:
+            if not isinstance(e, str):
+                self._gather_origins(e, origins)
+            else:
+                decoded_step = json.loads(base64.urlsafe_b64decode(e))
+                if decoded_step["type"] == "origin":
+                    origins.append(decoded_step["id"])
+
+    def _encode_step(self, step):
+        return base64.urlsafe_b64encode(json.dumps(step, separators=(",", ":")).encode("utf-8")).decode('utf-8')
+
+    def _data_for_signing(self, data, additional=None, is_root=True):
+        gather = []
+        if is_root:
+            gather.append(self.trust_framework)
+        for e in data:
+            if isinstance(e, str):
+                gather.append(e)
+            elif isinstance(e, int):
+                gather.append(str(e))
+            else:
+                gather.append("%")
+                gather.append(self._data_for_signing(e, None, False))
+                gather.append("&")
+        if additional is not None:
+            gather.extend(additional)
+        return ".".join(gather)
+
+    def encoded(self): # TODO name
+        self._require_signed()
+        return self._record
+
+    def decoded(self): # TODO name
+        self._require_verified()
+        return copy.deepcopy(self._verified)
+
+    def _require_signed(self):
+        if not self._signed:
+            raise Exception("Record is not signed, call sign() and use returned object")
+
+    def _require_verified(self):
+        if not (self._signed and (self._verified != None)):
+            raise Exception("Record is not verified, call verify() first")
+
+    def _timestamp_now_iso8601(self):
+        return (datetime.datetime.now(datetime.UTC).
+            replace(microsecond=0).
+            isoformat().
+            replace("+00:00", "Z")
+        )
+
+    def to_graphviz(self):
+        self._require_verified()
+        signers = {}
+        dot = ["digraph ProvenanceRecord {"]
+        for s in self._verified:
+            id = s["id"]
+            shape = "box"
+            match s["type"]:
+                case "permission":
+                    shape = "invhouse"
+                case "origin":
+                    shape = "diamond"
+                case "transfer":
+                    dot.append("  \""+s["of"]+"\" -> \""+id+"\" [label=of];")
+                case "receipt":
+                    shape = "box3d"
+                    dot.append("  \""+s["transfer"]+"\" -> \""+id+"\" [label=transfer];")
+                case "process":
+                    shape = "parallelogram"
+            for key in ["inputs", "permissions"]:
+                for i in s.get(key, []):
+                    dot.append("  \""+i+"\" -> \""+id+"\" [label="+key+"];")
+            dot.append("  \""+id+"\" [shape="+shape+",label=\""+s["type"]+"\\n"+id+"\"];")
+            signer = s["_signature"]["signed"]["name"]
+            if signer not in signers:
+                signers[signer] = []
+            signers[signer].append(id)
+        index = 0
+        for signer in signers:
+            dot.append("  subgraph cluster_"+str(index)+" {")
+            index += 1
+            dot.append("    graph[style=dashed];")
+            dot.append("    label = \""+signer+"\";")
+            for i in signers[signer]:
+                dot.append("    \""+i+"\";")
+            dot.append("  }")
+        dot.append("}")
+        return "\n".join(dot)

ib1_provenance-0.1/src/ib1/provenance/signing.py

@@ -0,0 +1,32 @@
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+
+
+class SignerInMemory:
+    def __init__(self, certificate_provider, certificates, private_key):
+        self._certificate_provider = certificate_provider
+        self._certificates = certificates
+        self._private_key = private_key
+
+    def serial(self):
+        return str(self._certificates[0].serial_number) # String, as JSON rounds large integers
+
+    def certificates_for_record(self):
+        if not self._certificate_provider.policy_include_certificates_in_record():
+            return None
+        return self._certificates.copy();
+
+    def sign(self, data):
+        # TODO: Use correct algorithm for type of key in certificate, assuming EC crypto
+        return self._private_key.sign(data, ec.ECDSA(hashes.SHA256()))
+
+class SignerFiles(SignerInMemory):
+    def __init__(self, certificate_provider, certificate_file, key_file):
+        with open(certificate_file, "rb") as certs:
+            certificates = x509.load_pem_x509_certificates(certs.read())
+        with open(key_file, "rb") as key:
+            private_key = serialization.load_pem_private_key(key.read(), password=None)
+        super().__init__(certificate_provider, certificates, private_key)