Update docs and changelog

Author: jobselko

CHANGES/1340.feature

@@ -1 +1 @@
-Added support for verifying SLSA attestations with a configured public key.
+Added custom (non-PEP 740) support for verifying attestations signed with a server-configured public key via `ATTESTATION_VERIFICATION_KEY`, with optional embedded key in `verification_material`.

docs/user/guides/attestation.md

@@ -89,3 +89,44 @@ http $PULP_API/pypi/foo/simple/twine/ "Accept:application/vnd.pypi.simple.v1+jso
 
 http $PULP_API/pypi/foo/integrity/twine/6.2.0/twine-6.2.0.tar.gz/provenance/
 ```
+
+## Custom Key Verification (non-PEP 740)
+
+!!! note
+    This is a custom extension outside the PEP 740 spec. Standard PEP 740 users using Sigstore
+    keyless signing do not need this feature.
+
+Pulp Python supports verifying attestations signed with a custom public key instead of a Sigstore
+certificate. This is useful for environments that sign packages with their own key (e.g. internal
+build systems) rather than using Sigstore's keyless signing.
+
+To enable this, configure the `ATTESTATION_VERIFICATION_KEY` setting with the path to a PEM public
+key file:
+
+```
+PULP_ATTESTATION_VERIFICATION_KEY=/path/to/public-key.pem
+```
+
+When this setting is configured, Pulp uses two verification paths that coexist on the same server:
+
+- **Attestations with a Sigstore certificate** are verified through the standard PEP 740 path,
+  regardless of whether `ATTESTATION_VERIFICATION_KEY` is set.
+- **Attestations without a Sigstore certificate** are verified against the server-configured key using RSA
+  PKCS1v15 signatures.
+
+This means a single Pulp instance can host packages with Sigstore certificates and
+internally-signed packages with key-based attestations. Each attestation is independently
+routed to the appropriate verification path based on whether it contains a certificate.
+
+### Embedded public key
+
+Uploaders may optionally include the public key in the attestation's `verification_material` field.
+This makes the attestation self-contained for consumers who want to verify offline without fetching
+the key separately. The embedded key must match the server-configured key.  Also, the `certificate`
+and `public_key` fields are mutually exclusive — an attestation's `verification_material` cannot contain both.
+
+### Limitations
+
+- A single key is used across all repositories and domains.
+- The key-based path only supports RSA PKCS1v15 with SHA-256 signatures.
+- Publisher enrichment is supported for SLSA v0.2 provenance statements only.

pulp_python/app/provenance.py

@@ -232,11 +232,11 @@ def _verify_embedded_key(attestation, server_key):
 def verify_provenance(filename, sha256, provenance, offline=True):
     """Verify the provenance object is valid for the package.
 
-    Attestations with valid Sigstore certificates are verified through the
-    standard Sigstore path. Attestations without certificates are verified
-    against a custom public key configured via ATTESTATION_VERIFICATION_KEY.
-    Currently, it supports RSA PKCS1v15 signatures and SLSA v0.2 provenance
-    publisher enrichment.
+    Each attestation is routed to one of two coexisting verification paths:
+    1. Attestations with a valid Sigstore certificate follow the standard PEP 740 path.
+    2. Attestations without a certificate are verified against the server-configured
+    ATTESTATION_VERIFICATION_KEY using RSA PKCS1v15 signatures, with support for SLSA
+    v0.2 publisher enrichment and optional embedded public key in verification_material.
     """
     dist = Distribution(name=filename, digest=sha256)
     verification_key = _load_verification_key()
@@ -257,7 +257,7 @@ def verify_provenance(filename, sha256, provenance, offline=True):
                 _verify_embedded_key(attestation, verification_key)
             else:
                 raise VerificationError(
-                    "Attestation has no Sigstore certificate or no custom "
+                    "Attestation has no Sigstore certificate and no custom "
                     "verification key configured via ATTESTATION_VERIFICATION_KEY "
                     "(embedded key in verification_material is optional)"
                 )