certisigma 1.4.0

Official Python SDK for the CertiSigma attestation & verification API

CertiSigma Python SDK

Official Python client for the CertiSigma cryptographic attestation API.

Installation

pip install certisigma

Or from source:

cd sdk/python
pip install -e .

Quick Start

from certisigma import CertiSigmaClient, hash_file, hash_bytes

client = CertiSigmaClient(api_key="cs_live_your_key_here")

# 1. Compute the SHA-256 hash of your file
file_hash = hash_file("contract.pdf")

# 2. Attest — creates a timestamped, signed proof of existence
result = client.attest(file_hash, source="my-app")
print(f"Attestation: {result.id} at {result.timestamp}")
print(f"ECDSA signature: {result.signature}")

# 3. Verify — confirm the hash was attested
check = client.verify(file_hash)
print(f"Exists: {check.exists}, Level: {check.level}")

# Or hash raw bytes
data_hash = hash_bytes(b"any raw content")
result = client.attest(data_hash)

Public Verification (No API Key)

Verification endpoints are public. You can verify attestations without any API key:

from certisigma import CertiSigmaClient, hash_file

# No api_key needed — works out of the box
client = CertiSigmaClient()

file_hash = hash_file("contract.pdf")
check = client.verify(file_hash)
print(f"Exists: {check.exists}, Level: {check.level}")

# Batch verify also works without a key
results = client.batch_verify([file_hash])
print(f"Found: {results.found}/{results.count}")

Hashing Utilities

Standalone SHA-256 hash functions -- compute hashes without attestation:

from certisigma import hash_file, hash_bytes

# Hash a file (streamed, constant memory)
file_hash = hash_file("/path/to/document.pdf")
print(f"SHA-256: {file_hash}")

# Hash raw bytes
data_hash = hash_bytes(b"raw content")

# Verify a file against a known hash
assert hash_file("/path/to/document.pdf") == file_hash

Or hash + attest in one step:

result = client.attest_file("/path/to/document.pdf")
print(f"Attested: {result.hash_hex}")

Async Support

import asyncio
from certisigma import AsyncCertiSigmaClient

async def main():
    async with AsyncCertiSigmaClient(api_key="cs_live_xxx") as client:
        result = await client.attest("abcdef..." * 4 + "0" * 16)
        print(result.id)

asyncio.run(main())

Batch Operations

# Attest up to 100 hashes in one call
batch = client.batch_attest(
    ["aabb..." * 4, "ccdd..." * 4],
    source="monthly-invoices"
)
print(f"Created: {batch.created}, Existing: {batch.existing}")

# Verify batch
results = client.batch_verify(["aabb..." * 4, "ccdd..." * 4])
print(f"Found: {results.found}/{results.count}")

Metadata Management

# Update claim metadata
result = client.update_metadata("att_1234", source="pipeline-v2", extra_data={"project": "alpha"})

# Soft-delete claim
client.delete_metadata("att_1234")

# Get evidence
evidence = client.get_evidence("att_1234")
print(evidence.level, evidence.t0)

Evidence & OTS Verification

from certisigma import CertiSigmaClient, get_blockchain_url, save_ots_proof

client = CertiSigmaClient(api_key="cs_live_xxx")

# Get full cryptographic evidence (T0 + T1 + T2)
evidence = client.get_evidence("att_1234")

if evidence.level == "T2":
    # Bitcoin block explorer link
    print(get_blockchain_url(evidence))        # mempool.space/block/...
    print(get_blockchain_url(evidence, "tx"))   # mempool.space/tx/...

    # Save the raw .ots proof for independent verification
    save_ots_proof(evidence, "contract.pdf.ots")
    # Then verify with: ots verify contract.pdf.ots

Client-Side Encryption (Zero Knowledge)

Requires: pip install certisigma[crypto]

from certisigma.crypto import generate_key, encrypt_metadata, decrypt_metadata

# Generate a key (store securely — server never sees it)
key = generate_key()

# Encrypt before sending
encrypted = encrypt_metadata({"secret": "classified"}, key)
result = client.attest(hash_hex, extra_data=encrypted, client_encrypted=True)

# Decrypt after retrieving
plaintext = decrypt_metadata(result.extra_data, key)

Error Handling

from certisigma import (
    CertiSigmaError,
    AuthenticationError,
    RateLimitError,
    QuotaExceededError,
)

try:
    client.attest(hash_hex)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except QuotaExceededError:
    print("Monthly quota reached")
except CertiSigmaError as e:
    print(f"API error {e.status_code}: {e}")

Configuration

Parameter	Default	Description
api_key	None	Bearer token (cs_live_...). Optional for verify/health.
base_url	https://api.certisigma.ch	API endpoint
timeout	30.0	Request timeout in seconds

Requirements

• Python 3.10+
• httpx >= 0.25.0
• cryptography >= 44.0.0 (optional, for certisigma.crypto)

License

MIT — Ten Sigma Sagl, Lugano, Switzerland