### Install Securesystemslib with Crypto Support

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/README.md

Install the library with support for ed25519, RSA, and ECDSA signing and verification. This is the default installation.

```bash
pip install securesystemslib[crypto]
```

--------------------------------

### Install Securesystemslib with Sigstore Support

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Install the library with support for Sigstore, which uses OIDC for authentication.

```bash
pip install securesystemslib[sigstore]
```

--------------------------------

### Install Securesystemslib with HashiCorp Vault Support

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Install the library with support for HashiCorp Vault.

```bash
pip install securesystemslib[vault]
```

--------------------------------

### Install Securesystemslib with Azure Key Vault Support

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Install the library with support for Azure Key Vault.

```bash
pip install securesystemslib[azurekms]
```

--------------------------------

### Install Securesystemslib with SPHINCS+ Support

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Install the library with support for SPHINCS+, a post-quantum signature scheme.

```bash
pip install securesystemslib[PySPX]
```

--------------------------------

### Install Securesystemslib with Google Cloud KMS Support

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Install the library with support for Google Cloud Key Management Service (KMS).

```bash
pip install securesystemslib[gcpkms]
```

--------------------------------

### Install Securesystemslib with HSM Support

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/README.md

Install the library with support for Hardware Security Module (HSM) operations, such as those provided by a Yubikey. This enables secure key management and signing operations using hardware.

```bash
pip install securesystemslib[hsm]
```

--------------------------------

### Install Securesystemslib with AWS KMS Support

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Install the library with support for Amazon Web Services Key Management Service (KMS).

```bash
pip install securesystemslib[awskms]
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/CONTRIBUTING.md

Install project dependencies for local development using pip. It is recommended to use a virtual environment.

```bash
python3 -m pip install -r requirements-dev.txt
```

--------------------------------

### Inspect and Extend Dispatch Tables

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Shows how to inspect the registered URI schemes and key types/schemes in dispatch tables. Includes an example of registering a custom Key implementation.

```python
from securesystemslib.signer import (
    SIGNER_FOR_URI_SCHEME,
    KEY_FOR_TYPE_AND_SCHEME,
    Key, Signer, SSlibKey, Signature
)

# Inspect registered URI schemes
print(list(SIGNER_FOR_URI_SCHEME.keys()))
# ['file2', 'gcpkms', 'hsm', 'gnupg', 'azurekms', 'awskms', 'hv']

# Inspect registered key types/schemes
print(list(KEY_FOR_TYPE_AND_SCHEME.keys())[:4])
# [('ecdsa', 'ecdsa-sha2-nistp256'), ('ed25519', 'ed25519'), ...]

# Register a custom Key implementation
class MyKey(Key):
    @classmethod
    def from_dict(cls, keyid, key_dict):
        keytype, scheme, keyval = cls._from_dict(key_dict)
        return cls(keyid, keytype, scheme, keyval, key_dict)

    def to_dict(self):
        return self._to_dict()

    def verify_signature(self, signature: Signature, data: bytes) -> None:
        # Custom verification logic
        pass

KEY_FOR_TYPE_AND_SCHEME[("mytype", "myscheme")] = MyKey

# Now Key.from_dict() dispatches to MyKey for matching keytype/scheme
key = Key.from_dict("kid", {"keytype": "mytype", "scheme": "myscheme", "keyval": {}})
```

--------------------------------

### Sign with Google Cloud KMS

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Demonstrates signing data using Google Cloud KMS. It covers importing a key from KMS to get its URI and public key, then using a Signer object for signing. Verification is performed locally.

```python
from securesystemslib.signer import GCPSigner, Signer

# One-time setup: import key from KMS (requires roles/cloudkms.publicKeyViewer)
gcp_key_id = (
    "projects/my-project/locations/global/keyRings/my-ring"
    "/cryptoKeys/my-key/cryptoKeyVersions/1"
)
pub_key = GCPSigner.import_(gcp_key_id)
# Store uri and pub_key.to_dict() for later use

# Signing (requires roles/cloudkms.signer)
signer = Signer.from_priv_key_uri(uri, pub_key)
# uri format: "gcpkms:<full-kms-key-name>"
sig = signer.sign(b"data to sign")

# Verification (local, no KMS access needed)
pub_key.verify_signature(sig, b"data to sign")
```

--------------------------------

### Run Ed25519 Tests with Tox

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/securesystemslib/_vendor/ed25519/README.rst

Use this command to execute the test suite for the ed25519.py library. Ensure tox is installed in your environment.

```bash
$ tox
```

--------------------------------

### Sign with Azure Key Vault

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Shows how to sign data using Azure Key Vault with EC keys. The process involves importing a key from Azure Key Vault to get its URI and public key, then using a Signer for signing. Verification is performed locally.

```python
from securesystemslib.signer import AzureSigner, Signer

# One-time setup: import key from Azure Key Vault
vault_name = "my-vault"
key_name = "my-ec-key"
pub_key = AzureSigner.import_(vault_name, key_name)
# uri format: "azurekms:https://<vault>.vault.azure.net/keys/<key>/<version>"

# Signing
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"data to sign")

# Verification (local)
pub_key.verify_signature(sig, b"data to sign")
```

--------------------------------

### Load and Use a Signer

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Instantiate a signer from a private key URI and use it to sign data. Ensure the URI scheme is registered in SIGNER_FOR_URI_SCHEME.

```default
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"data")
```

--------------------------------

### Create and Use Signature Object

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Demonstrates how to create a Signature object directly or deserialize it from a dictionary, and how to access its keyid and signature attributes.

```python
from securesystemslib.signer import Signature

# Create directly
sig = Signature(keyid="abc123", sig="deadbeef...")

# Deserialize from dict
sig = Signature.from_dict({"keyid": "abc123", "sig": "deadbeef..."})

# Serialize to dict
sig_dict = sig.to_dict()
# {"keyid": "abc123", "sig": "deadbeef..."}

print(sig.keyid)     # "abc123"
print(sig.signature) # "deadbeef..."
```

--------------------------------

### Load and Use Signer from URI

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/CRYPTO_SIGNER.md

Loads a signer using a URI pointing to private key bytes and then uses it to sign data. Ensure the public key is available for verification.

```python
from securesystemslib.signer import Signer

# Load signer using URI that points to private key bytes
signer = Signer.from_priv_key_uri("file2:privkey.pem", pubkey)
signature = signer.sign(b"data")
print(signature.to_dict())
```

--------------------------------

### Import and Use GPGSigner

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Import a public key from a local GnuPG keyring. Optionally specify a non-default GnuPG home directory.

```python
keyid = "ABCDEF1234567890ABCDEF1234567890ABCDEF12"  # GnuPG key fingerprint
uri, pub_key = GPGSigner.import_(keyid)
# Optionally specify a non-default GnuPG home dir:
uri, pub_key = GPGSigner.import_(keyid, homedir="/path/to/gnupghome")
# uri format: "gnupg:[/path/to/gnupghome]"

# Signing
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"data to sign")

# Verification (local)
pub_key.verify_signature(sig, b"data to sign")
```

--------------------------------

### Load Existing Private Key with CryptoSigner

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/CRYPTO_SIGNER.md

Loads an existing PEM-encoded private key from disk and uses it to initialize a CryptoSigner. The public key is then accessible.

```python
from cryptography.hazmat.primitives.serialization import load_pem_private_key
from securesystemslib.signer import CryptoSigner

# Load a PEM encoded key from disk
with open("privkey.pem", "rb") as f:
    private_key = load_pem_private_key(f.read(), None)

signer = CryptoSigner(private_key)

# Publish the public key
pubkey = signer.public_key
print(pubkey.to_dict())
```

--------------------------------

### Import and Use HSMSigner with PyKCS11

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Use the PKCS#11 API via PyKCS11 to sign with a hardware token. Requires 'securesystemslib[hsm]' and PYKCS11LIB environment variable. Supports ECDSA P-256 and P-384.

```python
from securesystemslib.signer import HSMSigner, Signer
from getpass import getpass

# One-time setup: export public key and URI from the hardware token
uri, pub_key = HSMSigner.import_()
# With specific slot and token filter:
uri, pub_key = HSMSigner.import_(
    hsm_keyid=2,
    token_filter={"label": "YubiKey PIV #15835999"}
)
# uri format: "hsm:<keyid>?label=<token-label>"

# Signing (prompts for PIN)
def pin_handler(secret: str) -> str:
    return getpass(f"Enter {secret}: ")

signer = Signer.from_priv_key_uri(uri, pub_key, pin_handler)
sig = signer.sign(b"data to sign")

# Verification (local, no hardware needed)
pub_key.verify_signature(sig, b"data to sign")
```

--------------------------------

### Generate and Use CryptoSigner with Local Keys

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Shows how to generate Ed25519, RSA, and ECDSA key pairs using CryptoSigner, sign data, and verify signatures. It also covers persisting keys to PEM files and reloading them using URIs.

```python
from securesystemslib.signer import CryptoSigner, Signer
import os

# --- Generate new key pairs ---
ed_signer = CryptoSigner.generate_ed25519()
rsa_signer = CryptoSigner.generate_rsa(scheme="rsassa-pss-sha256", size=3072)
ec_signer  = CryptoSigner.generate_ecdsa()

# Sign and verify
sig = ed_signer.sign(b"my payload")
ed_signer.public_key.verify_signature(sig, b"my payload")

# --- Persist and reload via URI ---
key_path = "/tmp/my_ed25519_key.pem"
with open(key_path, "wb") as f:
    f.write(ed_signer.private_bytes)

pub_key = ed_signer.public_key
priv_key_uri = f"file2:{key_path}"

reloaded = Signer.from_priv_key_uri(priv_key_uri, pub_key)
sig2 = reloaded.sign(b"my payload")
pub_key.verify_signature(sig2, b"my payload")

# --- From an existing pyca/cryptography private key ---
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
raw_key = Ed25519PrivateKey.generate()
signer = CryptoSigner(raw_key)

# --- Path prefix via environment variable ---
os.environ["CRYPTO_SIGNER_PATH_PREFIX"] = "/secure/keys"
# Now "file2:my_key.pem" resolves to "/secure/keys/my_key.pem"
signer = Signer.from_priv_key_uri("file2:my_key.pem", pub_key)
```

--------------------------------

### Run Test Suite Locally

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/CONTRIBUTING.md

Execute the project's test suite locally using tox. Some tests may be excluded by default.

```bash
tox
```

--------------------------------

### Load and Use a Signer

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Load a signer from a private key URI and public key, then use it to sign a payload. An optional secrets handler can be provided for interactive prompts. Custom signer implementations can be registered.

```python
from securesystemslib.signer import Signer, SIGNER_FOR_URI_SCHEME
from securesystemslib.exceptions import UnverifiedSignatureError

# Generic load: any registered signer can be loaded from a URI + public key
# (uri and pub_key are obtained from a specific signer's import_() method)
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"payload to sign")

# Optional secrets handler for interactive PIN / passphrase prompts
from getpass import getpass

def secrets_handler(secret_name: str) -> str:
    return getpass(f"Enter {secret_name}: ")

signer = Signer.from_priv_key_uri(uri, pub_key, secrets_handler)

# Register a custom signer implementation
from mylib import MySigner
SIGNER_FOR_URI_SCHEME[MySigner.MY_SCHEME] = MySigner
```

--------------------------------

### Signer.from_priv_key_uri

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Factory constructor for creating a Signer instance from a private key URI. It supports various URI schemes and can optionally use a secrets handler for additional security prompts.

```APIDOC
## from_priv_key_uri(priv_key_uri, public_key, secrets_handler=None)

### Description
Factory constructor for a given private key URI. Returns a specific Signer instance based on the private key URI and the supported uri schemes.

### Parameters
* **priv_key_uri** (str) – URI that identifies the private key
* **public_key** (Key) – Key that is the public portion of this private key
* **secrets_handler** (Callable[[str], str] | None) – Optional function that may be called if the signer needs additional secrets (like a PIN or passphrase). secrets_handler should return the requested secret string.

### Raises
* **ValueError** – Incorrect arguments
* **Other Signer-specific errors** – These could include OSErrors for reading files or network errors for connecting to a KMS.

### Return type
Signer
```

--------------------------------

### Handle Signature Verification Exceptions

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Illustrates how to catch and handle different exceptions during signature verification, including UnverifiedSignatureError and VerificationError.

```python
from securesystemslib.exceptions import (
    UnverifiedSignatureError,  # Signature failed verification
    VerificationError,         # Subclass: process error during verification
    UnsupportedAlgorithmError, # Unsupported algorithm requested
    UnsupportedLibraryError,   # Optional dependency not installed
    FormatError,               # Object format validation error
    StorageError,              # Storage backend interaction error
)

from securesystemslib.signer import CryptoSigner
from securesystemslib.exceptions import UnverifiedSignatureError, VerificationError

signer = CryptoSigner.generate_ed25519()
sig = signer.sign(b"correct data")

try:
    signer.public_key.verify_signature(sig, b"tampered data")
except UnverifiedSignatureError as e:
    # Catches both invalid signatures AND process errors (VerificationError is a subclass)
    print(f"Signature not valid: {e}")
except VerificationError as e:
    print(f"Verification process failed: {e}")
```

--------------------------------

### Sign with GPGSigner

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

This snippet is a placeholder for GPGSigner usage. GPGSigner invokes the gpg/gpg2 command-line tool for signing operations.

```python
from securesystemslib.signer import GPGSigner, Signer

```

--------------------------------

### Create and Use SSlibKey with Crypto Public Keys

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Create an SSlibKey from a pyca/cryptography public key object, automatically computing the key ID and determining key type and scheme. Allows overriding the scheme for specific key types like RSA.

```python
from securesystemslib.signer import SSlibKey
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

# Build SSlibKey from a pyca/cryptography public key object
private_key = Ed25519PrivateKey.generate()
pub_key = SSlibKey.from_crypto(private_key.public_key())

print(pub_key.keyid)    # auto-computed hex digest
print(pub_key.keytype)  # "ed25519"
print(pub_key.scheme)   # "ed25519"
print(pub_key.keyval)   # {"public": "<hex-encoded bytes>"}

# Override scheme for RSA key (default is rsassa-pss-sha256)
from cryptography.hazmat.primitives.asymmetric.rsa import generate_private_key as gen_rsa
rsa_private = gen_rsa(public_exponent=65537, key_size=3072)
rsa_pub = SSlibKey.from_crypto(rsa_private.public_key(), scheme="rsa-pkcs1v15-sha256")
```

--------------------------------

### Use SigstoreSigner with OIDC/Fulcio

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Uses Sigstore's Fulcio CA to issue ephemeral certificates and produce Bundle-based signatures. Key identity is an OIDC identity. Note: Sigstore key and signature formats are not yet stable.

```python
from securesystemslib.signer import (
    SigstoreSigner, SigstoreKey, SIGNER_FOR_URI_SCHEME
)

# Opt in to the (currently unstable) Sigstore signer
SIGNER_FOR_URI_SCHEME[SigstoreSigner.SCHEME] = SigstoreSigner

# --- Interactive OAuth2 login (browser) ---
uri, pub_key = SigstoreSigner.import_(
    identity="user@example.com",
    issuer="https://github.com/login/oauth",
    ambient=False,
)
signer = SigstoreSigner.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"data")
pub_key.verify_signature(sig, b"data")

# --- GitHub Actions ambient credentials ---
uri, pub_key = SigstoreSigner.import_github_actions(
    project="my-org/my-repo",
    workflow_path=".github/workflows/release.yml",
    ref="refs/heads/main",
)
# In a GitHub Actions job with id-token: write permission:
signer = SigstoreSigner.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"artifact bytes")
pub_key.verify_signature(sig, b"artifact bytes")
```

--------------------------------

### Sign with AWS Key Management Service

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Illustrates signing data using AWS KMS. It includes importing a key from AWS KMS to obtain its URI and public key, followed by using a Signer for the signing operation. Verification is a local process.

```python
from securesystemslib.signer import AWSSigner, Signer

# One-time setup: import key from AWS KMS (requires kms:GetPublicKey)
aws_key_id = "arn:aws:kms:us-east-1:123456789012:key/my-key-id"
pub_key = AWSSigner.import_(aws_key_id)
# Optionally specify scheme: AWSSigner.import_(aws_key_id, local_scheme="rsassa-pss-sha256")

# Signing (requires kms:Sign)
signer = Signer.from_priv_key_uri(uri, pub_key)
# uri format: "awskms:<key-id-or-arn>"
sig = signer.sign(b"data to sign")

# Verification (local)
pub_key.verify_signature(sig, b"data to sign")
```

--------------------------------

### Deserialize and Verify a Key

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Deserialize a public key from a dictionary representation and use it to verify a signature. Handles potential verification errors.

```python
from securesystemslib.signer import Key
from securesystemslib.exceptions import UnverifiedSignatureError, VerificationError

# Deserialize a key from a metadata dict (dispatches to correct subclass)
key_dict = {
    "keytype": "ed25519",
    "scheme": "ed25519",
    "keyval": {"public": "abcdef0123456789..."},  # hex-encoded raw public bytes
}
pub_key = Key.from_dict(keyid="abc123", key_dict=key_dict)

# Serialize back to dict
serialized = pub_key.to_dict()

# Verify a signature
try:
    pub_key.verify_signature(sig, b"payload to sign")
    print("Signature valid")
except UnverifiedSignatureError:
    print("Signature invalid")
except VerificationError as e:
    print(f"Verification process error: {e}")
```

--------------------------------

### Key Interface

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

The Key interface stores public key material and exposes `verify_signature()`. Implementations are registered in the `KEY_FOR_TYPE_AND_SCHEME` dispatch table and can be round-tripped through dict serialization.

```APIDOC
## Key Interface

`Key` stores public key material (keyid, keytype, scheme, keyval) and exposes `verify_signature()`. Implementations are registered in the `KEY_FOR_TYPE_AND_SCHEME` dispatch table and can be round-tripped through dict serialization.

```python
from securesystemslib.signer import Key
from securesystemslib.exceptions import UnverifiedSignatureError, VerificationError

# Deserialize a key from a metadata dict (dispatches to correct subclass)
key_dict = {
    "keytype": "ed25519",
    "scheme": "ed25519",
    "keyval": {"public": "abcdef0123456789..."},  # hex-encoded raw public bytes
}
pub_key = Key.from_dict(keyid="abc123", key_dict=key_dict)

# Serialize back to dict
serialized = pub_key.to_dict()

# Verify a signature
try:
    pub_key.verify_signature(sig, b"payload to sign")
    print("Signature valid")
except UnverifiedSignatureError:
    print("Signature invalid")
except VerificationError as e:
    print(f"Verification process error: {e}")
```
```

--------------------------------

### GPGSigner

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

GPGSigner invokes the 'gpg'/'gpg2' command-line tool to sign. It supports RSA, DSA, and EdDSA key types.

```APIDOC
## GPGSigner / GPGKey — OpenPGP / GnuPG

### Description

`GPGSigner` invokes the `gpg`/`gpg2` command-line tool to sign. Supports RSA (`pgp+rsa-pkcsv1.5`), DSA (`pgp+dsa-fips-180-2`), and EdDSA (`pgp+eddsa-ed25519`) with SHA-256. The `GNUPG` environment variable overrides the default gpg executable.

### Methods

- `sign(payload: bytes) -> bytes`: Signs the given payload using the GPG key.
- `public_key.verify_signature(signature: bytes, payload: bytes)`: Verifies a signature against the payload using the public key.

### Example

```python
from securesystemslib.signer import GPGSigner, Signer

# Example usage would typically involve initializing GPGSigner with a key ID or path
# and then using its sign method. Verification would use the corresponding public key.
# Note: The provided source only shows the import statement for GPGSigner and Signer.
# Detailed usage examples for GPGSigner are not present in the source text.
```
```

--------------------------------

### Key.from_dict

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Factory constructor for creating a Key object from a serialization dictionary. This method dispatches to the appropriate subclass based on key type and scheme.

```APIDOC
## from_dict(keyid, key_dict)

### Description
Creates `Key` object from a serialization dict. Key implementations must override this factory constructor that is used as a deserialization helper. Users should call `Key.from_dict()`: it dispatches to the actual subclass implementation based on supported keys in `KEY_FOR_TYPE_AND_SCHEME`.

### Parameters
* **keyid** (str)
* **key_dict** (dict[str, Any])

### Raises
* **KeyError**, **TypeError** – Invalid arguments.

### Return type
Key
```

--------------------------------

### Signer.from_priv_key_uri

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Loads a specific signer from a URI. The signer implementation is responsible for URI format and resolution. Custom signers can be registered.

```APIDOC
## Signer.from_priv_key_uri

### Description
Loads a specific signer from a URI.

### Method
Signer.from_priv_key_uri

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **uri** (str) - Required - The URI of the private key.
- **pub_key** (PublicKey) - Required - The public key associated with the signer.
- **secrets_handler** (callable, optional) - A function to handle secrets if needed.

### Request Example
```python
from securesystemslib.signer import Signer

# Assuming pub_key is an instance of a PublicKey class
pub_key = ... 

signer = Signer.from_priv_key_uri("some_uri", pub_key)
```

### Response
#### Success Response (Signer)
- **signer_instance** (Signer) - An instance of a Signer implementation.

#### Response Example
```python
# Returns a Signer object
<securesystemslib.signer.Signer object at ...>
```
```

--------------------------------

### Generate and Use SpxSigner for SPHINCS+ Signatures

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Provides post-quantum digital signatures using SPHINCS+ 'shake-128s' via PySPX. Note: SPHINCS+ key and signature formats are not yet stable. Serializes/deserializes public keys.

```python
from securesystemslib.signer import SpxSigner, SpxKey, generate_spx_key_pair, Key

# Generate a SPHINCS+ key pair
public_bytes, private_bytes = generate_spx_key_pair()

# Build key objects and sign
pub_key = SpxKey.from_bytes(public_bytes)
signer = SpxSigner(private_bytes, pub_key)
sig = signer.sign(b"payload")

# Verify
pub_key.verify_signature(sig, b"payload")

# Serialize / deserialize public key
key_dict = pub_key.to_dict()
# {"keytype": "sphincs", "scheme": "sphincs-shake-128s", "keyval": {"public": "<hex>"}}

restored_key = Key.from_dict(pub_key.keyid, key_dict)
restored_key.verify_signature(sig, b"payload")
```

--------------------------------

### Import and Use VaultSigner with HashiCorp Vault

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Sign via the HashiCorp Vault Transit engine using ambient credentials. Currently supports Ed25519 keys. Requires VAULT_ADDR and VAULT_TOKEN environment variables.

```python
from securesystemslib.signer import VaultSigner, Signer
import os

os.environ["VAULT_ADDR"] = "https://vault.example.com"
os.environ["VAULT_TOKEN"] = "s.mytoken"

# One-time setup: import key from Vault
hv_key_name = "my-transit-key"
uri, pub_key = VaultSigner.import_(hv_key_name)
# uri format: "hv:<key-name>/<version>"

# Signing
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"data to sign")

# Verification (local)
pub_key.verify_signature(sig, b"data to sign")
```

--------------------------------

### Update Vendored ed25519

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/securesystemslib/_vendor/README.md

Use this bash script to remove the old ed25519 copy, clone the new one, and prepare it for commit. Ensure to manually add any new implementation files and update the expected upstream hash.

```bash
cd securesystemslib/_vendor
rm -rf ed25519/
git clone git@github.com:pyca/ed25519.git
touch ed25519/__init__.py # needed by python<3.3
git clean -f ed25519/
git commit -a
```

--------------------------------

### Signature.from_dict

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Creates a Signature object from its dictionary representation. Expects keys 'keyid' and 'sig'.

```APIDOC
## from_dict(signature_dict)

### Description
Creates a Signature object from its JSON/dict representation.

### Parameters
#### Path Parameters
* **signature_dict** (*dict*) – A dict containing a valid keyid and a signature. Note that the fields in it should be named “keyid” and “sig” respectively.

### Raises
* **KeyError** – If any of the “keyid” and “sig” fields are missing from the signature_dict.

### Returns
* **Signature** – A “Signature” instance.

### Side Effects
Destroys the metadata dict passed by reference.
```

--------------------------------

### AWSSigner

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

AWSSigner signs using AWS KMS. Hashing is done locally; only the digest is sent to AWS.

```APIDOC
## AWSSigner — AWS Key Management Service

### Description

`AWSSigner` signs using AWS KMS. Hashing is done locally; only the digest is sent to AWS. Requires the `awskms` extra and ambient AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, etc.).

### Methods

- `import_(aws_key_id: str, local_scheme: str = None)`: Class method to import a key from AWS KMS. Returns the URI and public key. Optionally specify the local signing scheme.
- `sign(payload: bytes) -> bytes`: Signs the given payload using the AWS KMS key.
- `public_key.verify_signature(signature: bytes, payload: bytes)`: Verifies a signature against the payload using the public key.

### Attributes

- `uri` (str): The URI for the AWS KMS key.
- `public_key`: The public key object associated with the KMS key.

### Example

```python
from securesystemslib.signer import AWSSigner, Signer

# One-time setup: import key from AWS KMS (requires kms:GetPublicKey)
aws_key_id = "arn:aws:kms:us-east-1:123456789012:key/my-key-id"
uri, pub_key = AWSSigner.import_(aws_key_id)
# Optionally specify scheme: AWSSigner.import_(aws_key_id, local_scheme="rsassa-pss-sha256")

# Signing (requires kms:Sign)
signer = Signer.from_priv_key_uri(uri, pub_key)
# uri format: "awskms:<key-id-or-arn>"
sig = signer.sign(b"data to sign")

# Verification (local)
pub_key.verify_signature(sig, b"data to sign")
```
```

--------------------------------

### CryptoSigner

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

CryptoSigner supports Ed25519, RSA, and ECDSA using local private keys stored as PEM files. It provides methods for key generation, signing, and verification.

```APIDOC
## CryptoSigner — Local keys via pyca/cryptography

### Description

`CryptoSigner` supports Ed25519, RSA (PSS and PKCS1v15), and ECDSA (P-256) using private keys stored as PEM files. Provides `generate_*` factory methods for quick key generation and a `private_bytes` property for exporting the key to PEM/PKCS8 format.

### Methods

- `generate_ed25519()`: Factory method to generate a new Ed25519 key pair.
- `generate_rsa(scheme: str, size: int)`: Factory method to generate a new RSA key pair.
- `generate_ecdsa()`: Factory method to generate a new ECDSA key pair.
- `sign(payload: bytes) -> bytes`: Signs the given payload using the private key.
- `public_key.verify_signature(signature: bytes, payload: bytes)`: Verifies a signature against the payload using the public key.
- `from_priv_key_uri(uri: str, public_key: PublicKey)`: Class method to load a signer from a private key URI.

### Attributes

- `private_bytes`: Exports the private key in PEM/PKCS8 format.

### Example

```python
from securesystemslib.signer import CryptoSigner, Signer
import os

# --- Generate new key pairs ---
ed_signer = CryptoSigner.generate_ed25519()
rsa_signer = CryptoSigner.generate_rsa(scheme="rsassa-pss-sha256", size=3072)
ec_signer  = CryptoSigner.generate_ecdsa()

# Sign and verify
sig = ed_signer.sign(b"my payload")
ed_signer.public_key.verify_signature(sig, b"my payload")

# --- Persist and reload via URI ---
key_path = "/tmp/my_ed25519_key.pem"
with open(key_path, "wb") as f:
    f.write(ed_signer.private_bytes)

pub_key = ed_signer.public_key
priv_key_uri = f"file2:{key_path}"

reloaded = Signer.from_priv_key_uri(priv_key_uri, pub_key)
sig2 = reloaded.sign(b"my payload")
pub_key.verify_signature(sig2, b"my payload")

# --- From an existing pyca/cryptography private key ---
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
raw_key = Ed25519PrivateKey.generate()
signer = CryptoSigner(raw_key)

# --- Path prefix via environment variable ---
os.environ["CRYPTO_SIGNER_PATH_PREFIX"] = "/secure/keys"
# Now "file2:my_key.pem" resolves to "/secure/keys/my_key.pem"
signer = Signer.from_priv_key_uri("file2:my_key.pem", pub_key)
```
```

--------------------------------

### Register Custom Signer Implementation

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Register a custom signer implementation with the SIGNER_FOR_URI_SCHEME dispatch table to make it discoverable by URI scheme.

```python
from securesystemslib.signer import Signer, SIGNER_FOR_URI_SCHEME
from mylib import MySigner

SIGNER_FOR_URI_SCHEME[MySigner.MY_SCHEME] = MySigner
```

--------------------------------

### Signer.sign

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Signs data using the configured private key. The private key is treated as an implementation detail and may be managed locally or remotely.

```APIDOC
## Signer.sign

### Description
Signs data using the configured private key.

### Method
Signer.sign

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **data** (bytes) - Required - The data to sign.

### Request Example
```python
signer.sign(b"data_to_sign")
```

### Response
#### Success Response (bytes)
- **signature** (bytes) - The generated signature.

#### Response Example
```python
b'signature_bytes'
```
```

--------------------------------

### Sign and Verify Payload with Envelope

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

Demonstrates signing a payload with multiple signers and verifying it using a threshold. The payload is serialized to a JSON-compatible dictionary.

```python
signer_a = CryptoSigner.generate_ed25519()
signer_b = CryptoSigner.generate_ed25519()

payload = json.dumps({"version": "1.0", "artifact": "myapp"}).encode()
envelope = Envelope(payload, "application/vnd.myapp+json", {})

envelope.sign(signer_a)
envelope.sign(signer_b)

# Serialize to JSON-compatible dict
env_dict = envelope.to_dict()
# { 
#   "payload": "<base64>", 
#   "payloadType": "application/vnd.myapp+json", 
#   "signatures": [{"keyid": "...", "sig": "<base64>"}, ...] 
# }

# --- Deserialize ---
restored = Envelope.from_dict(env_dict)

# --- Verify with threshold ---
keys = [signer_a.public_key, signer_b.public_key]
try:
    accepted = restored.verify(keys, threshold=2)
    print(f"Verified by {len(accepted)} keys: {list(accepted.keys())}")
except VerificationError as e:
    print(f"Verification failed: {e}")

# --- Access Pre-Authentication Encoding ---
pae = envelope.pae()
# b"DSSEv1 <payloadType-len> <payloadType> <payload-len> <payload>"
```

--------------------------------

### Key.verify_signature

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Abstract method to verify a signature against a given payload using the key.

```APIDOC
## verify_signature(signature, data)

### Description
Raises if verification of signature over data fails.

### Parameters
* **signature** (Signature) – Signature object.
* **data** (bytes) – Payload bytes.

### Raises
* **UnverifiedSignatureError** – Failed to verify signature.
* **VerificationError** – Signature verification process error. If you are only interested in the verify result, just handle UnverifiedSignatureError: it contains VerificationError as well.

### Return type
None
```

--------------------------------

### Key.from_dict

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Loads a specific key from a serialized format (dictionary). The key implementation is responsible for deserialization. Custom keys can be registered.

```APIDOC
## Key.from_dict

### Description
Loads a specific key from a serialized format.

### Method
Key.from_dict

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key_data** (dict) - Required - A dictionary containing the serialized key data.

### Request Example
```python
from securesystemslib.signer import Key

key_dict = {"keytype": "rsa", "scheme": "pkcs1v15", "keyval": {"public": "..."}}
key = Key.from_dict(key_dict)
```

### Response
#### Success Response (Key)
- **key_instance** (Key) - An instance of a Key implementation.

#### Response Example
```python
# Returns a Key object
<securesystemslib.signer.Key object at ...>
```
```

--------------------------------

### Signer with Secrets Handler

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Load a signer that uses a custom secrets handler for interactive secret input, such as a password prompt.

```python
from getpass import getpass

def sec_handler(secret_name:str) -> str:
    return getpass(f"Enter {secret_name}: ")

signer = Signer.from_priv_key_uri(uri, pub_key, sec_handler)
```

--------------------------------

### Generate RSA Key with Cryptography API

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/CRYPTO_SIGNER.md

Generates a new RSA key pair with non-default arguments using the cryptography library. The private key is then used to initialize a CryptoSigner.

```python
from cryptography.hazmat.primitives.asymmetric import rsa
from securesystemslib.signer import CryptoSigner

# Generate key pair with non-default arguments
private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=4096,
)

signer = CryptoSigner(private_key)

# store private key securely
with open ("privkey.pem", "wb") as f:
    f.write(signer.private_bytes)

# Publish the public key
pubkey = signer.public_key
print(pubkey.to_dict())
```

--------------------------------

### Key.verify_signature

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Verifies a signature against the public key. This method is part of the Key class, which acts as a container for public key data.

```APIDOC
## Key.verify_signature

### Description
Verifies a signature against the public key.

### Method
Key.verify_signature

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **data** (bytes) - Required - The original data that was signed.
- **signature** (bytes) - Required - The signature to verify.

### Request Example
```python
key.verify_signature(b"data_to_sign", b"signature_bytes")
```

### Response
#### Success Response (boolean)
- **is_valid** (boolean) - True if the signature is valid, False otherwise.

#### Response Example
```python
True
```
```

--------------------------------

### Signer.public_key

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Abstract property that returns the public key associated with the Signer instance.

```APIDOC
## public_key

### Description
Returns the public key the signer is based off.

### Return type
Key
```

--------------------------------

### GCPSigner

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

GCPSigner delegates signing to Google Cloud KMS. It hashes the payload locally and sends only the digest to the KMS.

```APIDOC
## GCPSigner — Google Cloud KMS

### Description

`GCPSigner` delegates signing to GCP KMS. It hashes the payload locally and sends only the digest to the KMS. Requires the `gcpkms` extra and ambient GCP credentials (e.g., `GOOGLE_APPLICATION_CREDENTIALS`).

### Methods

- `import_(gcp_key_id: str)`: Class method to import a key from GCP KMS. Returns the URI and public key.
- `sign(payload: bytes) -> bytes`: Signs the given payload using the GCP KMS key.
- `public_key.verify_signature(signature: bytes, payload: bytes)`: Verifies a signature against the payload using the public key.

### Attributes

- `uri` (str): The URI for the GCP KMS key.
- `public_key`: The public key object associated with the KMS key.

### Example

```python
from securesystemslib.signer import GCPSigner, Signer

# One-time setup: import key from KMS (requires roles/cloudkms.publicKeyViewer)
gcp_key_id = (
    "projects/my-project/locations/global/keyRings/my-ring"
    "/cryptoKeys/my-key/cryptoKeyVersions/1"
)
uri, pub_key = GCPSigner.import_(gcp_key_id)
# Store uri and pub_key.to_dict() for later use

# Signing (requires roles/cloudkms.signer)
signer = Signer.from_priv_key_uri(uri, pub_key)
# uri format: "gcpkms:<full-kms-key-name>"
sig = signer.sign(b"data to sign")

# Verification (local, no KMS access needed)
pub_key.verify_signature(sig, b"data to sign")
```
```

--------------------------------

### Signer.sign

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Abstract method to sign a given payload using the key assigned to the Signer instance.

```APIDOC
## sign(payload)

### Description
Signs a given payload by the key assigned to the Signer instance.

### Parameters
* **payload** (bytes) – The bytes to be signed.

### Returns
Returns a “Signature” class instance.

### Return type
Signature
```

--------------------------------

### SSlibKey Concrete Key

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

SSlibKey is the default Key implementation for RSA, Ed25519, and ECDSA. It stores public key material and can be built from pyca/cryptography public key objects.

```APIDOC
## SSlibKey Concrete Key

`SSlibKey` is the default `Key` implementation used by `CryptoSigner`, `GCPSigner`, `AWSSigner`, `AzureSigner`, `HSMSigner`, and `VaultSigner`. It stores the PEM-encoded (RSA/ECDSA) or hex-encoded (Ed25519) public key under `keyval["public"]`.

```python
from securesystemslib.signer import SSlibKey
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

# Build SSlibKey from a pyca/cryptography public key object
private_key = Ed25519PrivateKey.generate()
pub_key = SSlibKey.from_crypto(private_key.public_key())

print(pub_key.keyid)    # auto-computed hex digest
print(pub_key.keytype)  # "ed25519"
print(pub_key.scheme)   # "ed25519"
print(pub_key.keyval)   # {"public": "<hex-encoded bytes>"}

# Override scheme for RSA key (default is rsassa-pss-sha256)
from cryptography.hazmat.primitives.asymmetric.rsa import generate_private_key as gen_rsa
rsa_private = gen_rsa(public_exponent=65537, key_size=3072)
rsa_pub = SSlibKey.from_crypto(rsa_private.public_key(), scheme="rsa-pkcs1v15-sha256")
```
```

--------------------------------

### Signer Interface

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

The Signer interface defines the contract for signing payloads and loading signers from URI strings. Concrete implementations are registered in the SIGNER_FOR_URI_SCHEME dispatch table.

```APIDOC
## Signer Interface

`Signer` defines the contract for signing payloads and loading signers from URI strings. All signer implementations derive from this class and are registered in the `SIGNER_FOR_URI_SCHEME` dispatch table.

```python
from securesystemslib.signer import Signer, SIGNER_FOR_URI_SCHEME
from securesystemslib.exceptions import UnverifiedSignatureError

# Generic load: any registered signer can be loaded from a URI + public key
# (uri and pub_key are obtained from a specific signer's import_() method)
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"payload to sign")

# Optional secrets handler for interactive PIN / passphrase prompts
from getpass import getpass

def secrets_handler(secret_name: str) -> str:
    return getpass(f"Enter {secret_name}: ")

signer = Signer.from_priv_key_uri(uri, pub_key, secrets_handler)

# Register a custom signer implementation
from mylib import MySigner
SIGNER_FOR_URI_SCHEME[MySigner.MY_SCHEME] = MySigner
```
```

--------------------------------

### Key.to_dict

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Abstract method that returns a serialization dictionary representation of the Key object.

```APIDOC
## to_dict()

### Description
Returns a serialization dict. Key implementations must override this serialization helper.

### Return type
dict[str, Any]
```

--------------------------------

### AzureSigner

Source: https://context7.com/secure-systems-lab/securesystemslib/llms.txt

AzureSigner signs using Azure Key Vault with EC keys. It requires the 'azurekms' extra and DefaultAzureCredential.

```APIDOC
## AzureSigner — Azure Key Vault

### Description

`AzureSigner` signs using Azure Key Vault with EC keys (P-256, P-384, P-521). Requires the `azurekms` extra and `DefaultAzureCredential`. Requires the "Key Vault Crypto User" role.

### Methods

- `import_(vault_name: str, key_name: str)`: Class method to import a key from Azure Key Vault. Returns the URI and public key.
- `sign(payload: bytes) -> bytes`: Signs the given payload using the Azure Key Vault key.
- `public_key.verify_signature(signature: bytes, payload: bytes)`: Verifies a signature against the payload using the public key.

### Attributes

- `uri` (str): The URI for the Azure Key Vault key.
- `public_key`: The public key object associated with the Key Vault key.

### Example

```python
from securesystemslib.signer import AzureSigner, Signer

# One-time setup: import key from Azure Key Vault
vault_name = "my-vault"
key_name = "my-ec-key"
uri, pub_key = AzureSigner.import_(vault_name, key_name)
# uri format: "azurekms:https://<vault>.vault.azure.net/keys/<key>/<version>"

# Signing
signer = Signer.from_priv_key_uri(uri, pub_key)
sig = signer.sign(b"data to sign")

# Verification (local)
pub_key.verify_signature(sig, b"data to sign")
```
```

--------------------------------

### Generate Ed25519 Key with CryptoSigner

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/CRYPTO_SIGNER.md

Generates a new Ed25519 private key using CryptoSigner. The private key is stored securely, and the public key is published.

```python
from securesystemslib.signer import CryptoSigner

signer = CryptoSigner.generate_ed25519()

# store private key securely
with open ("privkey.pem", "wb") as f:
    f.write(signer.private_bytes)

# Publish the public key
pubkey = signer.public_key
print(pubkey.to_dict())
```

--------------------------------

### Signature.to_dict

Source: https://github.com/secure-systems-lab/securesystemslib/blob/main/docs/signer.md

Returns the JSON-serializable dictionary representation of the Signature object.

```APIDOC
## to_dict()

### Description
Returns the JSON-serializable dictionary representation of self.

### Returns
* **dict** – The dictionary representation of the Signature object.
```