Integra evidenza verificabile nel tuo prodotto

Quickstart

# Python — 4 righe e hai una prova
from certisigma import Client
import os

cs = Client(api_key=os.environ["CERTISIGMA_API_KEY"])
result = cs.attest_file("./contract.pdf")
print(result.evidence_url)

Documentazione

API groups

`/v1` e il prefisso stabile del contratto pubblico. Il modello e organizzato per gruppi di capability: attestazione, verify, batch, evidence, key material pubblico, metadata e tag, share token, webhook, scan e workflow Census.

Questa pagina non replica l'intera endpoint table: evita drift e lascia al portale developer la reference eseguibile. Qui trovi il modello mentale per progettare integrazioni robuste.

SDK Python e JavaScript

Gli SDK ufficiali `certisigma` e `@certisigma/sdk` aiutano a implementare hashing locale, attestazione, verifica, batch flow, evidence retrieval e metadata cifrati lato client.

Usa sempre variabili d'ambiente o secret manager per le credenziali. Nei repository, nei sample pubblici e nelle issue non devono comparire API key, token, PEM o bearer token reali.

Webhooks

Le notifiche async sono consegnate via webhook firmato HMAC. Ogni evento (es. T1 sealed, T2 anchored, attestation revoked) include payload canonico + timestamp + signature in header.

Verifica la firma con la shared secret configurata in console e re-check del payload prima di marcarlo trusted. Retries con backoff esponenziale, idempotency-key per evitare double-processing.

Public keys and verification

Le chiavi pubbliche ECDSA per la verifica delle firme T0 sono disponibili via endpoint API e, in roadmap, via `/.well-known/certisigma-keys.json` (non shipped cut 1; consulta `/trust/key-management` per stato corrente).

Ogni chiave include `kid` (key ID), `alg` (ECDSA-P256), `created_at` e politica di rotazione. La verifica delle firme può essere fatta offline con qualsiasi libreria crypto compatibile.

Test vector e verifica indipendente

Quando integri CertiSigma, conserva test vector locali: payload canonico, digest SHA-256, attestation id, firma T0, chiave pubblica usata e, quando disponibili, materiali T1/T2.

Il percorso consigliato e riprodurre la verifica in CI o in un job periodico: ricalcolo digest, verifica firma ECDSA, verifica Merkle inclusion/TSA token quando presenti e verifica OpenTimestamps quando T2 e disponibile.

Developer experience

SDK Python (`certisigma`) e JavaScript/TypeScript (`@certisigma/sdk`) con typing, error handling esplicito e convenzione env var `CERTISIGMA_API_KEY` per credenziali.

Esempi di hashing locale, attestazione singola, batch, evidence retrieval, verifica locale e metadata cifrati lato client sono disponibili nella documentazione completa.

Pattern di produzione

Per workflow di produzione: usa il prefisso stabile `/v1`, scoped API key con permessi minimi, ambienti dev/test/prod separati via chiavi distinte e webhook endpoint con HTTPS + signature verification.

Per high-throughput, raggruppa attestazioni in batch e consuma eventi asincroni T1/T2. Per audit trail, conserva `attestation_id`, digest, timestamp e riferimenti all'evidence bundle nel sistema di record del cliente.

RBAC e scoped keys

Le API key supportano scope granulari per attestazione, batch, metadata, tag, share, scan, Census e webhook. Crea chiavi separate per ogni servizio o microservizio.

La rotazione delle chiavi è supportata via console e via API. Le chiavi compromesse possono essere revocate immediatamente; le attestazioni emesse rimangono valide e verificabili.

Security e privacy model

Il pattern preferito e hash-first: file, dataset e dossier restano nel tuo ambiente; CertiSigma riceve il digest e i metadati operativi che decidi di associare al workflow.

Per metadata sensibili usa cifratura client-side o derived identifier HMAC. CertiSigma puo preservare riferimenti verificabili, ma non deve diventare un deposito di contenuti originali o segreti applicativi.

Metadata e tag

I metadati operativi (source, extra_data, tag strutturati) sono visibili solo al proprietario autenticato e ai soggetti con accesso esplicito (share token).

I tag sono coppie chiave-valore per filtering e query. Per dati sensibili, valuta cifratura client-side prima dell'invio: CertiSigma conserverà solo un blob opaco. Vedi anche /trust/privacy-security per dettagli su cosa è esposto.

Webhook e asincronia T1/T2

T0 (firma ECDSA) è sincrono e disponibile in risposta alla call di attestazione. T1 (timestamp TSA qualificata Sectigo, RFC 3161) è asincrono entro minuti, notificato via evento `attestation.t1_sealed`.

T2 (anchoring Bitcoin via OpenTimestamps) è asincrono entro ~6 ore mediamente, notificato via evento `attestation.t2_anchored`. L'evidence bundle viene aggiornato progressivamente con i materiali T1 e T2 quando disponibili.

Census per sviluppatori e operatori

Census è la CLI per inventario crittografico, baseline, compare, verify-manifest, integrity check, report/archive e SARIF. Permette anche derived list HMAC per matching controllato senza esporre l'inventario raw.

Use case tipici: baseline supply chain (SBOM + SLSA provenance), inventari attestati per controlli forensi, timeline/correlation locali, string attestation e federation multi-manifest. Vedi /products/census per dettagli prodotto.

Pattern consigliati

Tratta CertiSigma come evidence layer: il tuo sistema resta system of record, mentre CertiSigma aggiunge ricevute e materiali verificabili per datazione, integrita e audit trail.

Per workflow regolati, registra nel tuo sistema il mapping fra digest, attestation id, versione del documento, owner interno e motivo dell'attestazione. Mantieni anche una procedura di export evidence bundle per audit o incident review.