--- title: "Signing Your First Document" description: "A complete walkthrough of signing content with XI Objects, from setup to verification." published: 2026-02-18T18:06:28.761857+00:00 updated: 2026-02-18T18:06:28.761857+00:00 tags: ["getting-started", "guide", "tutorial"] url: https://xiobjects.com/docs/xio/guides/sign-first-image source: XI Objects --- # Signing Your First Document This guide walks you through the complete process of signing content with a trust block using XI Objects, embedding a cryptographic proof of authorship directly into a document. ## Prerequisites - .NET 10.0 or later - Access to an Orbital endpoint with the Control module active (for certificate issuance) - The **Xio.Trust** and **Xio.Crypto** libraries ## What Happens When You Sign When you sign content with XI Objects, the system: 1. Canonicalizes the document (strips existing trust blocks, normalizes whitespace/BOM) 2. Computes a BLAKE3-256 hash over `[context || canonical_bytes]` 3. Signs the canonical bytes with your Ed25519 private key 4. Embeds a trust block containing the hash, signature, public key, and certificate chain The result is a **self-contained signed document**. Anyone with access to the Institute of Provenance Root CA public key can verify it independently. ## Step 1: Obtain a Leaf Certificate Request a short-lived leaf certificate from a certified Orbital. The Control module issues an Ed25519 leaf certificate signed by its intermediate CA. Leaf certificates are intentionally short-lived (hours to a day) to limit exposure from key compromise. ## Step 2: Set Up Trust Options ```csharp using Xio.Trust; using Xio.Crypto; // Your Ed25519 key pair (private key held securely) var publicKey = /* 32-byte Ed25519 public key */; // Configure signing: private key is passed as a delegate, never directly var trustOptions = new TrustOptions { PublicKey = publicKey, Signer = async (data) => { // Sign data with your Ed25519 private key // This delegate can wrap a Key Vault, HSM, or file-based key return await MyKeyStore.SignAsync(data); }, Context = "my-application.document-signing", X509ChainPem = new[] { leafCertificatePem, // Your leaf certificate intermediateCertificatePem // The intermediate CA certificate }, HashAlgorithm = HashAlgorithm.Blake3_256 }; ``` > **Security note:** The signing delegate pattern means the private key never leaves your secure storage. The trust library only sees the signature output. ## Step 3: Sign the Document ```csharp // Create the trust signer var trustSigner = new Ed25519XionTrustSigner(cryptoServices); // Sign the document content var signedDocument = await trustSigner.SignAsync(documentContent, trustOptions); ``` The signed document now contains an embedded trust block with: - BLAKE3 content hash - Ed25519 signature - Your public key and key ID - The full X.509 certificate chain (leaf → intermediate) - A timestamp ## Step 4: Verify the Signed Document ```csharp // Verification checks: // 1. BLAKE3 hash matches the canonical content // 2. Ed25519 signature is valid against the embedded public key // 3. Certificate chain traces to Institute of Provenance Root CA // 4. No certificate in the chain has been revoked // 5. Leaf certificate was valid at signing time var verificationResult = await trustSigner.VerifyAsync(signedDocument); ``` ## Step 5: Register on the Orbital Network (Optional) To make the signing record globally discoverable, publish the signing metadata and fingerprint to the Orbital network. This stores an `XSIGN` record (signing metadata) and optionally an `XFPR` record (spectral fingerprint), making the content's provenance queryable. ## What's in the Trust Block? ```mermaid graph LR T[Trust Block] --> S[Ed25519 Signature] T --> H[BLAKE3 Hash] T --> K[Public Key + Key ID] T --> C[Certificate Chain] T --> M[Metadata] C --> C1[Leaf Certificate] C --> C2[Intermediate CA] M --> M1[Context] M --> M2[Timestamp] M --> M3[Version] style T fill:#582c7e,stroke:#7a4a9e,color:#fff style S fill:#0a0e1a,stroke:#ff3a00,color:#e1d5b9 style H fill:#1a1a2e,stroke:#7a4a9e,color:#e1d5b9 style K fill:#1a1a2e,stroke:#7a4a9e,color:#e1d5b9 style C fill:#1a1a2e,stroke:#7a4a9e,color:#e1d5b9 style M fill:#1a1a2e,stroke:#7a4a9e,color:#e1d5b9 ``` ## Next Steps - Learn about [Content Fingerprinting](/docs/xio/concepts/fingerprinting) for tracking content across transformations - Explore the [Signing & Trust Blocks API](/docs/xio/api/signing) for detailed trust block format documentation - Set up [CI/CD Integration](/docs/xio/guides/cicd-integration) for automated signing in pipelines