Quick Start - Steel-SecAdv-LLC/AMA-Cryptography GitHub Wiki
Get up and running with AMA Cryptography in 5 minutes.
Prerequisites: Complete Installation before proceeding.
from ama_cryptography.pqc_backends import (
generate_dilithium_keypair,
dilithium_sign,
dilithium_verify,
get_pqc_status,
get_pqc_backend_info,
)
from ama_cryptography.crypto_api import (
AmaCryptography,
AlgorithmType,
)
from ama_cryptography.key_management import KeyRotationManagerstatus = get_pqc_status()
print(status)
# PQCStatus.AVAILABLE โ at least one PQC backend loaded
# Detailed backend info dict (see ama_cryptography/pqc_backends.py::get_pqc_backend_info).
# Top-level keys: status, <algo>_available, <algo>_backend, algorithms,
# SHA3-256, HMAC-SHA3-256 (+ legacy flat 'backend'/'algorithm' aliases).
info = get_pqc_backend_info()
print(info["status"]) # "AVAILABLE" / "UNAVAILABLE" (PQCStatus.value, uppercase โ see pqc_backends.py:76-77)
print(info["dilithium_available"], info["dilithium_backend"]) # True, "native"
print(info["kyber_available"], info["kyber_backend"]) # True, "native"
print(info["sphincs_available"], info["sphincs_backend"]) # True, "native"
# Per-algorithm matrix lives under info["algorithms"]:
for name, meta in info["algorithms"].items():
print(name, meta["available"], meta["backend"], meta["security_level"])
# ML-DSA-65 True native 3
# Kyber-1024 True native 5
# SPHINCS+-256f True native 5The legacy multi-layer orchestrator lives in
ama_cryptography.legacy_compat; it drives the same codes + helix
pipeline used by historical AMA deployments. For new code prefer
AmaCryptography from section 4 below.
from ama_cryptography.legacy_compat import (
generate_key_management_system,
create_crypto_package,
verify_crypto_package,
export_public_keys,
)
from pathlib import Path
# Step 1: Generate cryptographic keys
kms = generate_key_management_system("MyOrganization")
# Step 2: Define your Omni-Codes (data to protect)
codes = """
1. ๐20A07โ_XฮEฮX_ฯต19A89ฯ
Omni-Directional System
"""
helix_params = [(20.0, 0.7), (15.0, 1.0)]
# Step 3: Create the multi-layer crypto package
package = create_crypto_package(codes, helix_params, kms)
print(f"Package created: {package['package_id']}")
# Step 4: Verify the package
results = verify_crypto_package(codes, helix_params, package, kms.hmac_key)
# Step 5: Check all verification results
if all([
results["content_hash"],
results["hmac"],
results["ed25519"],
results["dilithium"] is True,
]):
print("โ ALL VERIFICATIONS PASSED")
else:
print("โ Verification failed:", results)
# Step 6: Export public keys for distribution
export_public_keys(kms, Path("public_keys"))For direct use of the PQC signing API:
from ama_cryptography.pqc_backends import (
generate_dilithium_keypair,
dilithium_sign,
dilithium_verify,
)
# Generate ML-DSA-65 key pair (DilithiumKeyPair dataclass)
kp = generate_dilithium_keypair()
print(f"Public key: {len(kp.public_key)} bytes") # 1952
print(f"Secret key: {len(kp.secret_key)} bytes") # 4032
# Sign a message
message = b"Hello, quantum-resistant world!"
signature = dilithium_sign(message, kp.secret_key)
print(f"Signature: {len(signature)} bytes") # 3309
# Verify the signature
valid = dilithium_verify(message, signature, kp.public_key)
print(f"Valid: {valid}") # Truefrom ama_cryptography.crypto_api import AESGCMProvider
import os
aead = AESGCMProvider()
# Generate a 256-bit key
key = os.urandom(32)
# Encrypt โ nonce is auto-generated when omitted.
# Returns a dict: {'ciphertext', 'nonce', 'tag', 'aad', 'backend'}
plaintext = b"Sensitive data to protect"
result = aead.encrypt(plaintext, key, aad=b"header")
# Decrypt โ caller passes nonce and tag back in; raises on tag mismatch
recovered = aead.decrypt(
ciphertext=result["ciphertext"],
key=key,
nonce=result["nonce"],
tag=result["tag"],
aad=b"header",
)
assert recovered == plaintext
print("Encryption/decryption successful!")from datetime import timedelta
from ama_cryptography.key_management import KeyRotationManager
# Create a rotation manager with a 90-day policy
mgr = KeyRotationManager(rotation_period=timedelta(days=90))
# Register a key under rotation policy (key material lives elsewhere;
# the manager tracks metadata, expiry, and usage counts)
meta = mgr.register_key(
key_id="signing-key-v1",
purpose="document-signatures",
expires_in=timedelta(days=90),
max_usage=100_000,
)
print(f"Status: {meta.status}, created: {meta.created_at}")
# Later: check whether it needs rotating. initiate_rotation() requires
# BOTH key ids to be registered first (key_management.py:435 raises
# ValueError otherwise), so register the replacement before rotating.
if mgr.should_rotate("signing-key-v1"):
mgr.register_key(
key_id="signing-key-v2",
purpose="document-signatures",
expires_in=timedelta(days=90),
max_usage=100_000,
)
mgr.initiate_rotation("signing-key-v1", "signing-key-v2")
# ... provision new key material ...
mgr.complete_rotation("signing-key-v1") # old key -> DEPRECATEDFor HD seed derivation, use HDKeyDerivation(seed=...) from the
same module.
from ama_cryptography.crypto_api import AmaCryptography, AlgorithmType
# One-liner hybrid KEM: drives X25519 + ML-KEM-1024 internally and
# length-prefix-binds both shared secrets through HKDF-SHA3-256.
hybrid = AmaCryptography(algorithm=AlgorithmType.HYBRID_KEM)
recipient = hybrid.generate_keypair() # public = X25519_pk || ML-KEM_pk
enc = hybrid.encapsulate(recipient.public_key)
print(f"Combined secret: {enc.shared_secret.hex()[:16]}...")
# Receiver
recovered = hybrid.decapsulate(enc.ciphertext, recipient.secret_key)
assert recovered == enc.shared_secret
print("Hybrid KEM key agreement successful!")See Hybrid Cryptography if you need to drive the combiner with custom classical and PQC KEM callables.
from ama_cryptography.secure_memory import SecureBuffer, secure_memzero
import os
# Use context manager for automatic zeroing on exit
with SecureBuffer(32) as buf:
# buf.data is a bytearray of 32 zeroed bytes
buf.data[:] = os.urandom(32)
print(f"Using key: {buf.data.hex()[:8]}...")
# buf.data is automatically zeroed here
# Manual zeroing
sensitive = bytearray(os.urandom(32))
# ... use sensitive ...
secure_memzero(sensitive) # Multi-pass overwrite
print(f"After zeroing: {sensitive.hex()}") # 000000...Choose the verification profile appropriate for your deployment:
| Profile | Requirements | Use Case |
|---|---|---|
dev |
None | Local testing, prototyping |
classical |
Ed25519 only | Legacy environments |
hybrid |
Ed25519 + ML-DSA-65 | Typical production |
strict |
All layers + RFC 3161 | High-assurance, regulatory |
# Strict profile: require all layers
results = verify_crypto_package(codes, helix_params, pkg, hmac_key)
if not (results["content_hash"] and results["hmac"]
and results["ed25519"] and results["dilithium"] is True
and results["rfc3161"] is True):
raise ValueError("Package failed strict verification profile")- Architecture โ Understand the multi-layer defense design
- API Reference โ Complete Python API documentation
- Key Management โ HD key derivation and lifecycle management
- Post-Quantum Cryptography โ Deep dive into PQC algorithms
- Security Model โ Threat model and security properties