Skip to content

Getting Started

This guide walks you through installing Diogenes, registering a key, and creating your first attestation.

Prerequisites

  • Python 3.12 or later
  • PostgreSQL (for the transparency log database)
  • A terminal with pip available

Installation

Install Diogenes from source:

git clone https://github.com/ubiquitousthey/diogenes.git
cd diogenes
pip install -e ".[dev]"

Start the Server

Diogenes runs as a FastAPI application. Start the development server:

./start.sh

By default, the server listens on http://localhost:8000. You can verify it is running:

curl http://localhost:8000/api/v1/health

Expected response:

{
  "status": "ok",
  "version": "0.1.0"
}

Step 1: Generate a Key Pair

Diogenes uses client-side key generation. The private key never leaves your machine. You can generate a key pair using any cryptographic library. Here is an example using Python:

from cryptography.hazmat.primitives.asymmetric import ed25519
from cryptography.hazmat.primitives.serialization import (
    Encoding,
    NoEncryption,
    PrivateFormat,
    PublicFormat,
)

# Generate an Ed25519 key pair
private_key = ed25519.Ed25519PrivateKey.generate()
public_key = private_key.public_key()

# Export the public key in PEM format (this gets registered)
public_key_pem = public_key.public_bytes(
    Encoding.PEM, PublicFormat.SubjectPublicKeyInfo
).decode()

# Export the private key (keep this secret!)
private_key_pem = private_key.private_bytes(
    Encoding.PEM, PrivateFormat.PKCS8, NoEncryption()
).decode()

print("Public key (register this):")
print(public_key_pem)

Diogenes supports three key algorithms:

Algorithm Use Case
Ed25519 Recommended. Fast, small keys and signatures.
ECDSA P-256 Good interoperability with Web Crypto API (browser signing).
RSA-2048 Legacy compatibility.

Step 2: Register Your Key

Register your public key on the transparency log:

curl -X POST http://localhost:8000/api/v1/keys/register \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
      "pseudonym": "Alice Scholar",
      "key_algorithm": "ed25519"
    }
  }'

Response:

{
  "fingerprint": "sha256:a1b2c3d4...",
  "pseudonym": "Alice Scholar",
  "algorithm": "ed25519",
  "log_entry_id": 1,
  "entry_hash": "sha256:e5f6a7b8..."
}

Save the fingerprint -- this is your key's unique identifier throughout the system.

Step 3: Create an Attestation

To sign a document, compute its SHA-256 hash locally (the document content is never sent to the server), create a manifest, sign the manifest payload, and submit the attestation.

Compute the Document Hash

import hashlib

with open("my-document.pdf", "rb") as f:
    content_hash = hashlib.sha256(f.read()).hexdigest()

print(f"Document hash: {content_hash}")

Sign and Submit

import json
import base64
import httpx

# Build the manifest
manifest = {
    "document": {
        "title": "My Important Document",
        "content_hash": content_hash,
    },
    "attestations": []
}

# Compute the signing payload (deterministic JSON)
signing_payload = json.dumps(manifest, sort_keys=True, separators=(",", ":"))

# Sign with your private key
signature = private_key.sign(signing_payload.encode())
signature_b64 = base64.b64encode(signature).decode()

# Submit to the server
response = httpx.post(
    "http://localhost:8000/api/v1/attestations",
    json={
        "manifest": manifest,
        "public_key_pem": public_key_pem,
        "signature": signature_b64,
        "attestation_type": "authorship",
        "pseudonym": "Alice Scholar",
    },
)

print(response.json())

Response:

{
  "attestation": {
    "id": "a1b2c3d4e5f6...",
    "type": "authorship",
    "signer_key_fingerprint": "sha256:a1b2c3d4...",
    "signature": "...",
    "timestamp": "2026-01-15T10:30:00Z"
  },
  "fingerprint": "sha256:a1b2c3d4...",
  "pseudonym": "Alice Scholar",
  "log_entry_id": 2
}

Step 4: Verify a Document

To verify a document, you need its manifest and the source file hash:

curl -X POST http://localhost:8000/api/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "manifest": {
      "document": {
        "title": "My Important Document",
        "content_hash": "sha256:..."
      },
      "attestations": [...]
    },
    "source_hash": "sha256:..."
  }'

The response includes a VerificationResult with Layer 1 (cryptographic) and Layer 2 (key status) results, an overall status, and an attestation graph showing the provenance chain.

Next Steps