CryptoServe SDK

Zero-config cryptographic operations with managed keys and auto-registration.

Installation

pip install cryptoserve

Quick Start (Recommended)

# One-time login (stores credentials locally)
cryptoserve login

from cryptoserve import CryptoServe

# Initialize - auto-registers your app on first use
crypto = CryptoServe(
    app_name="my-service",
    team="platform",
    environment="development"
)

# Encrypt/Decrypt
encrypted = crypto.encrypt(b"sensitive data", context="user-pii")
decrypted = crypto.decrypt(encrypted, context="user-pii")

# Sign/Verify
signature = crypto.sign(b"document", key_id="signing-key")
is_valid = crypto.verify_signature(b"document", signature, key_id="signing-key")

# Hash and MAC
hash_hex = crypto.hash(b"data", algorithm="sha256")
mac_hex = crypto.mac(b"message", key=secret_key, algorithm="hmac-sha256")

Local Mode (No Server)

Run the full SDK API without a server. All operations happen locally using a password or master key.

from cryptoserve import CryptoServe

# Initialize with a password (deterministic key derivation)
crypto = CryptoServe.local(password="my-secret-password")

# Same API as server mode
encrypted = crypto.encrypt(b"sensitive data", context="user-pii")
decrypted = crypto.decrypt(encrypted, context="user-pii")

# String helpers
encoded = crypto.encrypt_string("PII data", context="user-pii")
text = crypto.decrypt_string(encoded, context="user-pii")

# JSON
crypto.encrypt_json({"email": "user@example.com"}, context="user-pii")

# Hash and MAC work locally too
hash_hex = crypto.hash(b"data")

Two instances with the same password can decrypt each other's data. Different contexts derive different keys, providing isolation.

CryptoServe Class

The CryptoServe class provides:

Performance Features

CryptoServe SDK includes built-in performance optimizations:

Local Key Caching

Keys are cached locally to reduce network round-trips:

from cryptoserve import CryptoServe

# Enable caching (default: enabled)
crypto = CryptoServe(
    app_name="my-service",
    team="platform",
    enable_cache=True,   # Default: True
    cache_ttl=300.0,     # 5 minutes (default)
    cache_size=100,      # Max cached keys (default)
)

# First call fetches key from server and caches it
encrypted = crypto.encrypt(b"data", context="user-pii")  # ~90ms

# Subsequent calls use cached key (local AES-256-GCM)
encrypted = crypto.encrypt(b"more data", context="user-pii")  # ~0.3ms

Cache Statistics

Monitor cache performance:

stats = crypto.cache_stats()
print(f"Hit rate: {stats['hit_rate']:.1%}")
print(f"Hits: {stats['hits']}, Misses: {stats['misses']}")
print(f"Cache size: {stats['size']}")

Cache Invalidation

Invalidate cached keys (e.g., after key rotation):

# Invalidate specific context
crypto.invalidate_cache("user-pii")

# Invalidate all cached keys
crypto.invalidate_cache()

Health Check

from cryptoserve import CryptoServe

crypto = CryptoServe(app_name="my-service")

if crypto.health_check():
    print("Connected!")
else:
    print("Connection failed")

FastAPI Integration

from cryptoserve import CryptoServe
from cryptoserve.fastapi import configure, EncryptedStr
from pydantic import BaseModel

# Configure once at startup
crypto = CryptoServe(app_name="my-api", team="platform")
configure(crypto)

class User(BaseModel):
    name: str
    email: EncryptedStr["user-pii"]  # Automatically encrypted

SQLAlchemy Integration

from cryptoserve import CryptoServe
from cryptoserve.fastapi import configure, EncryptedString
from sqlalchemy import Column, Integer

# Configure once at startup
crypto = CryptoServe(app_name="my-api", team="platform")
configure(crypto)

class User(Base):
    id = Column(Integer, primary_key=True)
    email = Column(EncryptedString(context="user-pii"))

Auto-Protect (Third-Party Libraries)

from cryptoserve import auto_protect

auto_protect(encryption_key=key)

# Now all outbound requests are automatically protected
import requests
requests.post(url, json={"email": "user@example.com"})  # Auto-encrypted

CLI

# Interactive context wizard
cryptoserve wizard

# Verify SDK health
cryptoserve verify

# Show identity info
cryptoserve info

# List encryption contexts
cryptoserve contexts

Offline Tools (No Server Required)

# Encrypt/decrypt strings
cryptoserve encrypt "sensitive data" --password my-secret
cryptoserve decrypt "<base64>" --password my-secret

# Encrypt/decrypt files
cryptoserve encrypt --file report.pdf --output report.enc --password my-secret
cryptoserve decrypt --file report.enc --output report.pdf --password my-secret

# Hash a password (prompts for input if no argument)
cryptoserve hash-password
cryptoserve hash-password "my-password" --algo pbkdf2

# Create a JWT token
cryptoserve token --key my-secret-key-1234 --payload '{"sub":"user-1"}' --expires 3600

Package Architecture

CryptoServe uses a modular architecture for flexibility:

Use cases:

• Most users: Install cryptoserve for the full experience
• Bring your own keys: Install cryptoserve-core only
• Custom integration: Install cryptoserve-client for API access
• Dependency protection: Add cryptoserve-auto for automatic protection

Error Handling

from cryptoserve import (
    CryptoServe,
    AuthenticationError,
    AuthorizationError,
    ContextNotFoundError,
)

crypto = CryptoServe(app_name="my-app", team="platform")

try:
    ciphertext = crypto.encrypt(data, context="user-pii")
except AuthenticationError:
    # Token expired or invalid
    pass
except AuthorizationError:
    # Not allowed to use this context
    pass
except ContextNotFoundError:
    # Context doesn't exist
    pass

License

Apache 2.0