Install & Compatibility
Where this runs
tested against v1.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 0.142s · 79MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 3.9s · import 0.133s · 78MB
78MB installed
● package 78MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CryptoSigner
✓ from securesystemslib.signer import CryptoSigner
SSLibSigner
✓ from securesystemslib.signer import SSLibSigner
✗ from securesystemslib.interface import generate_and_write_rsa_keypair
`SSLibSigner` is deprecated in favor of `CryptoSigner`. Old `interface` functions like `generate_and_write_rsa_keypair` are part of the legacy key API and should be replaced by the `signer` API for modern usage.
Key
✓ from securesystemslib.signer import Key
This quickstart demonstrates how to generate an RSA key pair, sign arbitrary data, and then verify that signature using the recommended `securesystemslib.signer.CryptoSigner` API. The private key is saved locally, and a placeholder passphrase is used for demonstration purposes. In a production environment, private keys should be securely managed, potentially using a Key Management System (KMS).
import os
import json
from securesystemslib.signer import CryptoSigner, Key
from securesystemslib.formats import encode_canonical_json
# 1. Generate a new key pair using the CryptoSigner (e.g., RSA)
# In a real scenario, you'd protect the private key with a strong password
# or use a KMS. For quickstart, we'll use a placeholder password.
# Create a temporary directory for keys
if not os.path.exists("temp_keys"): os.makedirs("temp_keys")
passphrase = os.environ.get('SECURESYSTEMSLIB_PASSPHRASE', 'secret-password')
# Generate an RSA key pair
private_key_path = os.path.join("temp_keys", "example_key")
signer = CryptoSigner.generate_and_write_key(private_key_path, keytype="rsa", algorithm="rsassa-pss-sha256", passphrase=passphrase)
# The public key details are part of the signer object
public_key = signer.public_key
print(f"Generated public key ID: {public_key.keyid}")
# 2. Prepare some data to sign
data_to_sign = {"message": "Hello, securesystemslib!", "timestamp": 1678886400}
canonical_data = encode_canonical_json(data_to_sign).encode("utf-8")
# 3. Sign the data
signature = signer.sign(canonical_data)
print(f"Generated signature: {signature.signature[:20]}...")
# 4. Verify the signature
# A Key object can be created from the public_key dictionary
verifier_key = Key.from_dict(public_key.keyid, public_key.to_dict())
# Verify using the signer and the original data
try:
CryptoSigner.verify_signature(signature, verifier_key, canonical_data)
print("Signature verification successful!")
except Exception as e:
print(f"Signature verification failed: {e}")
# Clean up temporary files (optional)
os.remove(private_key_path)
os.remove(private_key_path + ".pub")
os.rmdir("temp_keys")
Debug
Known issues
breakingPython 3.7 reached End-of-Life on June 27, 2023, and `securesystemslib` officially dropped support for it in version `0.30.0`. Running on Python 3.7 or older will lead to compatibility issues and lack of security updates.fixUpgrade your Python environment to 3.8 or newer. The library currently supports Python ~=3.8.
affects: >=0.30.0
deprecatedThe `securesystemslib.keys`, `securesystemslib.ecdsa_keys`, `securesystemslib.rsa_keys`, and `securesystemslib.ed25519_keys` modules, along with `SSLibSigner`, are deprecated in favor of the new `securesystemslib.signer` API, specifically `CryptoSigner`.fixMigrate to the `securesystemslib.signer` module and use `CryptoSigner` for key generation, signing, and verification. Use the `migrate_keys` script to convert legacy keys.
affects: >=0.29.0
breakingSupport for weak cryptographic hash algorithms `md5` and `sha1` was removed in `securesystemslib` version `0.28.0` due to security concerns. [GitHub release notes]fixUpdate your code to use stronger hash algorithms like `sha256` or `sha512`.
affects: >=0.28.0
breakingThe `SigstoreSigner` API was adapted to `sigstore-python 2.0` in version `0.30.0`, changing how signing identities are managed, particularly for interactive credential handling.fixUpdate your `SigstoreSigner` usage to the new API, specifically `SigstoreSigner.import_via_auth()` for interactive logins. Consult the official documentation for the latest `sigstore-python` integration details.
affects: >=0.30.0
gotchaBy default, functions like `securesystemslib.interface.generate_and_write_unencrypted_ed25519_keypair()` (from the legacy API) might create private key files with world-readable permissions, depending on the system's umask. This can expose private keys to other users on a shared system.fixAlways ensure appropriate file permissions (e.g., `0o600` or `0o400`) are set for private key files immediately after creation. Prefer using the `signer` API, which generally handles security better, or ensure keys are passphrase-protected.
affects: <1.0.0 (and legacy API usage)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'securesystemslib.keys'
Attempting to import a deprecated module (`keys`, `ecdsa_keys`, `rsa_keys`, or `ed25519_keys`). These modules were marked for deprecation in v0.29.0.
fixRefactor your code to use the `securesystemslib.signer` API, specifically `CryptoSigner` or other specific signers for your use case.
securesystemslib.exceptions.UnsupportedAlgorithmError: md5 is not a supported hash algorithm
Attempting to use `md5` or `sha1` as a hash algorithm, which were removed in version 0.28.0. [GitHub release notes]
fixUpdate your code to use stronger, supported hash algorithms like `sha256` or `sha512`.
TypeError: SigstoreSigner.import_via_auth() takes 0 positional arguments but 1 was given
Using the old `SigstoreSigner` API with a `sigstore-python` version that expects a different interface, likely due to the breaking change in `securesystemslib v0.30.0` adapting to `sigstore-python 2.0`.
fixReview the `sigstore-python` documentation and the `securesystemslib` `0.30.0` changelog. The `import_via_auth` method now expects no arguments, or the signature has changed. Adapt your call accordingly.
RuntimeError: Python 3.7 is no longer supported
Running `securesystemslib` version `0.30.0` or higher on a Python 3.7 environment. Python 3.7 reached EOL and support was dropped.
fixUpgrade your Python installation to version 3.8 or newer to meet the library's minimum requirements.
Upgrade
Version history
1.4.0latest on PyPI · released May 27, 2026
Audit
Dependencies
cryptographyoptionalRequired for RSA, ECDSA key generation and signing. Installed with '[crypto]' extra.
PyNaCloptionalRequired for Ed25519 key generation and signing. Installed with '[crypto]' or '[pynacl]' extra.
sigstore-pythonoptionalRequired for Sigstore signing and verification. Installed with '[sigstore]' extra.