Merge pull request #632 from jku/add-unstable-api-notes

Sigstore, Spx: Add notes about metadata format stability

Author: jku

Diff for: securesystemslib/signer/__init__.py

@@ -38,6 +38,10 @@
     }
 )
 
+# Signers with currently unstable metadata formats, not supported by default:
+#   SigstoreSigner,
+#   SpxSigner (also does not yet support private key uri scheme)
+
 # Register supported key types and schemes, and the Keys implementing them
 KEY_FOR_TYPE_AND_SCHEME.update(
     {
@@ -54,9 +58,12 @@
         ("rsa", "rsa-pkcs1v15-sha256"): SSlibKey,
         ("rsa", "rsa-pkcs1v15-sha384"): SSlibKey,
         ("rsa", "rsa-pkcs1v15-sha512"): SSlibKey,
-        ("sphincs", "sphincs-shake-128s"): SpxKey,
         ("rsa", "pgp+rsa-pkcsv1.5"): GPGKey,
         ("dsa", "pgp+dsa-fips-180-2"): GPGKey,
         ("eddsa", "pgp+eddsa-ed25519"): GPGKey,
     }
 )
+
+# Keys with currently unstable metadata formats, not supported by default:
+#       ("sphincs", "sphincs-shake-128s"): SpxKey,
+#       ("sigstore-oidc", "Fulcio"): SigstoreKey,

Diff for: securesystemslib/signer/_sigstore_signer.py

@@ -28,7 +28,9 @@
 class SigstoreKey(Key):
     """Sigstore verifier.
 
-    NOTE: unstable API - routines and metadata formats may change!
+    NOTE: The Sigstore key and signature serialization formats are not yet
+    considered stable in securesystemslib. They may change in future releases
+    and may not be supported by other implementations.
     """
 
     DEFAULT_KEY_TYPE = "sigstore-oidc"
@@ -87,7 +89,9 @@ def verify_signature(self, signature: Signature, data: bytes) -> None:
 class SigstoreSigner(Signer):
     """Sigstore signer.
 
-    NOTE: unstable API - routines and metadata formats may change!
+    NOTE: The Sigstore key and signature serialization formats are not yet
+    considered stable in securesystemslib. They may change in future releases
+    and may not be supported by other implementations.
 
     All signers should be instantiated with ``Signer.from_priv_key_uri()``.
     Unstable ``SigstoreSigner`` currently requires opt-in via
@@ -183,8 +187,8 @@ def import_(
         key should be stored for later use.
 
         Arguments:
-            identity: The OIDC identity used to create a signing token.
-            issuer: The OIDC issuer URL used to create a signing token.
+            identity: The OIDC identity to use when verifying a signature.
+            issuer: The OIDC issuer to use when verifying a signature.
             ambient: Toggle usage of ambient credentials in returned URI.
         """
         keytype = SigstoreKey.DEFAULT_KEY_TYPE

Diff for: securesystemslib/signer/_spx_signer.py

@@ -38,7 +38,12 @@ def generate_spx_key_pair() -> Tuple[bytes, bytes]:
 
 
 class SpxKey(Key):
-    """SPHINCS+ verifier."""
+    """SPHINCS+ verifier.
+
+    NOTE: The SPHINCS+ key and signature serialization formats are not yet
+    considered stable in securesystemslib. They may change in future releases
+    and may not be supported by other implementations.
+    """
 
     DEFAULT_KEY_TYPE = "sphincs"
     DEFAULT_SCHEME = "sphincs-shake-128s"
@@ -89,6 +94,10 @@ def verify_signature(self, signature: Signature, data: bytes) -> None:
 class SpxSigner(Signer):
     """SPHINCS+ signer.
 
+    NOTE: The SPHINCS+ key and signature serialization formats are not yet
+    considered stable in securesystemslib. They may change in future releases
+    and may not be supported by other implementations.
+
     Usage::
 
         public_bytes, private_bytes = generate_spx_key_pair()