From 6b3480397b7046f3b5164745a8206648881acb84 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Fri, 1 Sep 2023 10:56:52 +0300 Subject: [PATCH 1/4] Sigstore, Spx: Add notes about metadata format stability Both of these metadata formats (e.g. the data encoding and field names) are bsaically invented in securesystemslib: there is no community consensus on them yet. --- securesystemslib/signer/_sigstore_signer.py | 10 ++++++++-- securesystemslib/signer/_spx_signer.py | 13 ++++++++++++- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/securesystemslib/signer/_sigstore_signer.py b/securesystemslib/signer/_sigstore_signer.py index f090b60d..3b5f2bcf 100644 --- a/securesystemslib/signer/_sigstore_signer.py +++ b/securesystemslib/signer/_sigstore_signer.py @@ -28,7 +28,10 @@ class SigstoreKey(Key): """Sigstore verifier. - NOTE: unstable API - routines and metadata formats may change! + NOTE: The Sigstore key and signature metadata formats are not part of the + TUF specification and are not 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 +90,10 @@ 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 metadata formats are not part of the + TUF specification and are not 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 diff --git a/securesystemslib/signer/_spx_signer.py b/securesystemslib/signer/_spx_signer.py index 95edf73d..b449222b 100644 --- a/securesystemslib/signer/_spx_signer.py +++ b/securesystemslib/signer/_spx_signer.py @@ -38,7 +38,13 @@ def generate_spx_key_pair() -> Tuple[bytes, bytes]: class SpxKey(Key): - """SPHINCS+ verifier.""" + """SPHINCS+ verifier. + + NOTE: The SPHINCS+ key and signature metadata formats are not part of the + TUF specification and are not 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 +95,11 @@ def verify_signature(self, signature: Signature, data: bytes) -> None: class SpxSigner(Signer): """SPHINCS+ signer. + NOTE: The SPHINCS+ key and signature metadata formats are not part of the + TUF specification and are not 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() From e7f7c891cb6c228068ac1631b753c8f885786159 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Fri, 1 Sep 2023 11:06:51 +0300 Subject: [PATCH 2/4] Sigstore: improve docstring language The identity/issuer in the public key are the details that we verify in the signing certificate. The OIDC identity of the authentication token may be slightly different: * because of identity federation the OIDC issuer may be sigstore.dev but the verified (federated) issuer may be github.com * in the ambient credential case the authentication token identity does not necessarily match the sertificate identity Make it clear that import_() takes the "verifying identity" details. --- securesystemslib/signer/_sigstore_signer.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/securesystemslib/signer/_sigstore_signer.py b/securesystemslib/signer/_sigstore_signer.py index 3b5f2bcf..c8df0348 100644 --- a/securesystemslib/signer/_sigstore_signer.py +++ b/securesystemslib/signer/_sigstore_signer.py @@ -189,8 +189,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 From 936bc04738f7121030336e77c1c28e90818caef3 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Fri, 1 Sep 2023 15:52:30 +0300 Subject: [PATCH 3/4] Spx: Make SpxKey not part of default keyset Clients that want to enable SPHINCS keys can easily do that with KEY_FOR_TYPE_AND_SCHEME[("sphincs", "sphincs-shake-128s")]: SpxKey This makes Spx and Sigstore behave similarly. --- securesystemslib/signer/__init__.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/securesystemslib/signer/__init__.py b/securesystemslib/signer/__init__.py index 2ededf4c..6f8afbcc 100644 --- a/securesystemslib/signer/__init__.py +++ b/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, From f2a39f530e59a5a53bb4ee2e888b8385de6176e0 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Mon, 4 Sep 2023 10:42:00 +0300 Subject: [PATCH 4/4] Sigstore, Spx: Improve docstring phrasing No need to talk about TUF specification here: the point is that we're not sure if the key formats are final and have community consensus yet -- wherever that may form. --- securesystemslib/signer/_sigstore_signer.py | 14 ++++++-------- securesystemslib/signer/_spx_signer.py | 14 ++++++-------- 2 files changed, 12 insertions(+), 16 deletions(-) diff --git a/securesystemslib/signer/_sigstore_signer.py b/securesystemslib/signer/_sigstore_signer.py index c8df0348..5e6e0a84 100644 --- a/securesystemslib/signer/_sigstore_signer.py +++ b/securesystemslib/signer/_sigstore_signer.py @@ -28,10 +28,9 @@ class SigstoreKey(Key): """Sigstore verifier. - NOTE: The Sigstore key and signature metadata formats are not part of the - TUF specification and are not considered stable in securesystemslib. They - may change in future releases and may not be supported by other - implementations. + 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" @@ -90,10 +89,9 @@ def verify_signature(self, signature: Signature, data: bytes) -> None: class SigstoreSigner(Signer): """Sigstore signer. - NOTE: The Sigstore key and signature metadata formats are not part of the - TUF specification and are not considered stable in securesystemslib. They - may change in future releases and may not be supported by other - implementations. + 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 diff --git a/securesystemslib/signer/_spx_signer.py b/securesystemslib/signer/_spx_signer.py index b449222b..0cc33db1 100644 --- a/securesystemslib/signer/_spx_signer.py +++ b/securesystemslib/signer/_spx_signer.py @@ -40,10 +40,9 @@ def generate_spx_key_pair() -> Tuple[bytes, bytes]: class SpxKey(Key): """SPHINCS+ verifier. - NOTE: The SPHINCS+ key and signature metadata formats are not part of the - TUF specification and are not considered stable in securesystemslib. They - may change in future releases and may not be supported by other - implementations. + 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" @@ -95,10 +94,9 @@ def verify_signature(self, signature: Signature, data: bytes) -> None: class SpxSigner(Signer): """SPHINCS+ signer. - NOTE: The SPHINCS+ key and signature metadata formats are not part of the - TUF specification and are not considered stable in securesystemslib. They - may change in future releases and may not be supported by other - implementations. + 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::