Signify is not a complete KERI implementation but rather a specialized client library that implements a specific subset of KERI agent functions. Traditional KERI agents perform five core functions:

1. Key generation - Creating cryptographic key pairs
2. Encrypted key storage - Securely storing private keys
3. Event generation - Creating KERI event messages
4. Event signing - Applying digital signatures to events
5. Event validation - Verifying signatures and event integrity

Signify specifically implements key generation and event signing on the client side, while delegating event generation, encrypted storage coordination, and validation to remote KERIA agents. This separation ensures that private keys never need to be transmitted to or accessed by cloud infrastructure, maintaining the non-repudiable property essential to KERI's security model.

Key Features & Capabilities

Edge-Based Cryptographic Operations

The fundamental capability of Signify is performing cryptographic operations at the edge - on the user's device rather than on remote servers. This includes:

Key Pair Generation: Signify uses libsodium as its cryptographic foundation, generating two types of asymmetric key pairs:

• Ed25519 key pairs for digital signature operations
• X25519 key pairs for encrypting private keys, next public keys, and salts used in key generation

For both inception events (identifier creation) and rotation events (key updates), Signify generates new key pair sets containing current keys and next keys (for pre-rotation). Critically, only the public keys and blake3 hashes of the next keys are transmitted to the agent, maintaining the security boundary.

Event Signing: All key events and other KERI protocol messages requiring signatures are signed client-side using the controller's private keys. The signed events are then transmitted to the KERIA agent for dissemination to witnesses and storage in the KEL.

Encrypted Remote Storage

While private keys never leave the client in unencrypted form, Signify supports encrypted key storage on remote KERIA agents. The encryption uses X25519 key pairs, and the critical security property is that the cloud agent never has access to the decryption keys. This enables:

• Multi-device access: Users can access their identifiers from different devices by retrieving encrypted key material
• Backup and recovery: Encrypted keys stored remotely provide disaster recovery capabilities
• Convenience: Users don't need to manage raw key material across devices

The encrypted storage includes:

• Private keys
• Next public keys (for pre-rotation)
• Salts used to generate private keys

CESR Protocol Communication

Signify communicates with KERIA agents using CESR (Composable Event Streaming Representation) encoding. The initial implementations encode all cryptographic primitives as CESR base64 encoded strings in the text domain, though the architecture supports future binary CESR encoding for improved efficiency.

This protocol choice ensures:

• Interoperability: All KERI implementations can parse Signify-generated messages
• Composability: Multiple primitives can be concatenated and processed as streams
• Verifiability: All messages maintain cryptographic integrity through CESR's self-framing properties

Client-Agent Delegation Model

Signify operates within a cooperative delegation architecture where:

1. The Client AID (controlled by Signify) acts as the delegator
2. The Agent AID (managed by KERIA) acts as the delegate
3. Both parties must participate in all establishment events

This delegation enables:

• Scalable operations: The agent handles witness coordination and message routing
• Retained control: The client maintains ultimate authority through rotation authority
• Security boundaries: Signing authority remains with the client while operational management occurs in the cloud

Passcode-Based Key Derivation

Signify uses a passcode (called bran in KERI terminology) as the entropy source for deterministic key generation. The key generation algorithm:

1. Prepends a 128-bit random salt derivation code to the passcode
2. Uses Argon2 key stretching to derive Ed25519 private keys
3. Generates keys from specific derivation paths (e.g., signify:controller00 for signing keys)
4. Creates both current and next (pre-rotated) key pairs

This approach enables:

• Deterministic recovery: The same passcode always generates the same keys
• Multi-device consistency: Different devices can derive identical keys from the same passcode
• User-friendly security: Users only need to remember a single passcode rather than managing raw key material

Installation & Setup

TypeScript Implementation (signify-ts)

Prerequisites:

• Node.js runtime environment
• npm package manager

Installation:

npm install signify-ts

Basic Setup:

import { randomPasscode, ready, SignifyClient, Tier } from 'signify-ts';

// Initialize libsodium (required before any operations)
await ready();

// Generate a random passcode
const bran = randomPasscode();

// Create client instance
const client = new SignifyClient(
    'http://127.0.0.1:3901',  // KERIA admin URL
    bran,                      // passcode for key derivation
    Tier.low,                  // security tier
    'http://127.0.0.1:3903'    // KERIA boot URL
);

The ready() function must be called at application initialization because the dependency libsodium must be initialized before any signify-ts functionalities can work.

Python Implementation (signifypy)

Prerequisites:

• Python 3.x
• pip package manager

Installation:

pip install signifypy

Basic Setup: The Python implementation follows similar patterns to the TypeScript version, using the same underlying cryptographic libraries and CESR encoding.

Java Implementation (cf-signify-java)

Prerequisites:

• Java 21
• Gradle build tool

Installation:

./gradlew build

The Java implementation provides equivalent functionality for JVM-based applications, using libsodium through native bindings.

KERIA Agent Configuration

All Signify implementations require a running KERIA agent. The agent exposes three HTTP interfaces:

1. Boot Interface (default port 3903): For initial agent worker provisioning
2. Admin Interface (default port 3901): For command and control operations
3. KERI Protocol Interface (default port 3902): For KERI protocol messages

Signify clients connect to the Admin and Boot interfaces, while the Protocol interface handles external KERI communications.

Usage & API

Client Initialization and Agent Bootstrapping

The Signify client initialization follows a multi-step process:

Step 1: Create SignifyClient Instance

const client = new SignifyClient(
    adminUrl,   // KERIA admin interface URL
    bran,       // passcode for key derivation
    tier,       // security tier (low, med, high)
    bootUrl     // KERIA boot interface URL
);

Step 2: Boot the Agent

await client.boot();

This initializes the KERIA agent connection and prepares for AID operations.

Step 3: Connect and Establish Delegation

await client.connect();

This establishes the Client AID to Agent AID delegation relationship through a three-step handshake:

1. Client generates its AID with signing and rotation keys
2. Client provides signed inception event to KERIA via Boot interface
3. KERIA creates delegated Agent AID and returns it to the client

AID Creation and Management

Creating a New AID:

const result = await client.identifiers().create(
    'my-identifier',  // alias for the AID
    {
        toad: 3,      // threshold of accountable duplicity
        wits: [       // witness AIDs
            'witness1-aid',
            'witness2-aid',
            'witness3-aid'
        ]
    }
);

// Wait for operation completion
const op = await client.operations().wait(result.op);

The creation process:

1. Signify generates key pairs client-side
2. Constructs inception event with public keys and witness configuration
3. Signs the event with the newly generated private key
4. Sends signed event to KERIA for witness coordination
5. KERIA disseminates to witnesses and collects receipts

Key Rotation:

const rotateResult = await client.identifiers().rotate(
    'my-identifier'  // alias of AID to rotate
);

await client.operations().wait(rotateResult.op);

Rotation demonstrates Signify's security model:

1. Client generates new current and next key pairs
2. Creates rotation event referencing previous event
3. Signs with current private key (proving control)
4. Includes commitment to next keys (pre-rotation)
5. KERIA coordinates witness agreement on the rotation

OOBI Resolution

Out-of-Band Introductions enable discovery and trust establishment:

Generating an OOBI:

const oobi = await client.oobis().get(
    'my-identifier',  // AID alias
    'agent'           // role (typically 'agent' for KERIA)
);
// Returns URL like: http://keria:3902/oobi/{aid}/agent/{agent-aid}

Resolving an OOBI:

const resolveResult = await client.oobis().resolve(
    oobiUrl,          // OOBI URL to resolve
    'remote-alias'    // local alias for the discovered AID
);

await client.operations().wait(resolveResult.op);

OOBI resolution:

1. Fetches the KEL from the OOBI endpoint
2. Verifies signatures and event chain integrity
3. Stores the KEL locally for future verification
4. Establishes trust basis for subsequent interactions

Credential Operations

Signify supports ACDC credential operations through IPEX protocol:

Issuing a Credential:

const issueResult = await client.credentials().issue(
    'issuer-aid',     // issuing AID alias
    registryId,       // credential registry SAID
    schemaId,         // schema SAID
    recipientAid,     // issuee AID
    attributes        // credential attributes
);

await client.operations().wait(issueResult.op);

Presenting a Credential:

const presentResult = await client.ipex().grant(
    'holder-aid',     // presenting AID alias
    'verifier-aid',   // recipient AID
    credentialSaid,   // credential to present
    includeChain      // include chained credentials
);

Credential operations demonstrate the edge signing model:

• All credential signatures are created client-side
• KERIA handles IPEX message routing and storage
• Verifiers can independently verify signatures against the KEL

Challenge-Response Authentication

Signify supports challenge-response protocols for proving control:

Generating a Challenge:

const challenge = await client.challenges().generate(
    'my-aid',         // AID to challenge
    recipientAid      // who should respond
);

Responding to a Challenge:

const response = await client.challenges().respond(
    'my-aid',         // responding AID
    challengeData     // challenge to respond to
);

The challenge-response flow:

1. Challenger generates random data and sends to respondent
2. Respondent signs the challenge with their private key
3. Challenger verifies signature against respondent's KEL
4. Successful verification proves control of the AID

Related Implementations

KERIA (KERI Agent)

KERIA is the complementary server-side component that Signify clients connect to. While Signify handles edge signing, KERIA provides:

• Agent AID management: Creating and managing delegated Agent AIDs
• Witness coordination: Collecting receipts from witness networks
• Message routing: Handling asynchronous KERI protocol messages
• Mailbox services: Store-and-forward for offline participants
• Credential storage: Managing issued and received ACDCs

KERIA exposes REST APIs that Signify clients use for all non-signing operations.

KERIpy (Full KERI Implementation)

KERIpy is the reference Python implementation of the complete KERI protocol. Unlike Signify, KERIpy:

• Implements all five KERI agent functions
• Provides the KLI command-line interface
• Can run witnesses and watchers
• Supports both direct and indirect modes

Signifypy is built on KERIpy's cryptographic primitives but provides a simplified client-focused API.

Browser Extension Integration

The signify-browser-extension provides a browser-based wallet using Signify:

• Manages AIDs directly in the browser
• Provides user approval workflows for signing operations
• Integrates with web applications for authentication
• Maintains the edge signing security model in browser contexts

This enables MetaMask-like functionality for KERI-based identity management.

Alternative Language Implementations

Rust: While there is no direct Signify implementation in Rust, cesride provides CESR primitives that could support a Rust Signify client.

Go: No official Signify implementation exists, though the CESR specification enables implementation in any language.

Swift: KERIml provides Swift KERI primitives that could support iOS Signify clients.

Implementation Notes

Security Considerations

Private Key Isolation: The fundamental security property of Signify is that private keys exist only in client memory during signing operations. Implementations must ensure:

• Keys are never serialized to disk in unencrypted form
• Keys are cleared from memory after use
• Encrypted keys sent to KERIA use strong encryption (X25519)
• The client never sends decryption keys to the server

Passcode Strength: The security of the entire system depends on the passcode (bran) strength. Implementations should:

• Generate random passcodes with sufficient entropy (21+ characters)
• Use Argon2 or equivalent key stretching
• Never transmit passcodes over the network
• Implement secure passcode entry mechanisms

Replay Attack Protection: All requests to KERIA must include KRAM (KERI Request Authentication Method) headers:

• Include ISO-8601 timestamp in request body
• Timestamp must be within acceptable window of server time
• Sign the entire request body including timestamp
• Server validates signature and timestamp freshness

Performance Optimization

Asynchronous Operations: Most Signify operations are asynchronous because they involve:

• Network communication with KERIA
• Witness coordination (may take seconds)
• Cryptographic operations (key generation, signing)

Implementations should:

• Use async/await patterns consistently
• Provide operation polling mechanisms
• Implement timeout handling
• Support operation cancellation

Caching: To reduce network overhead:

• Cache resolved KELs locally
• Cache key state for frequently accessed AIDs
• Implement cache invalidation on rotation events
• Use OOBI resolution results for subsequent verifications

Multi-Signature Support

Signify supports multi-signature identifiers where multiple parties must coordinate:

Partial Signing: When a multi-sig event is created:

1. Each participant signs with their portion of keys
2. Signatures are collected asynchronously
3. Event is only valid when threshold is met
4. KERIA coordinates signature collection

Threshold Configuration: Multi-sig AIDs specify:

• Current threshold: Number of signatures required for current operations
• Next threshold: Number of signatures required for rotation
• Weights: Optional weighted thresholds for complex governance

Error Handling

Operation Failures: Signify operations can fail at multiple points:

• Client-side: Key generation, signing, validation
• Network: Connection failures, timeouts
• KERIA: Agent errors, witness failures
• Protocol: Invalid events, threshold not met

Implementations should:

• Distinguish between retryable and permanent failures
• Provide detailed error messages
• Support operation retry with exponential backoff
• Clean up partial state on failures

Witness Agreement: Operations requiring witness agreement may fail if:

• Insufficient witnesses are available
• Witnesses detect duplicity
• Network partitions prevent communication

Clients should implement timeout and retry logic appropriate for their use case.

Testing Strategies

Unit Tests: Test cryptographic operations in isolation:

• Key generation produces valid key pairs
• Signing produces verifiable signatures
• CESR encoding/decoding round-trips correctly

Integration Tests: Test client-agent interactions:

• Boot and connect sequences complete successfully
• AID creation and rotation work end-to-end
• OOBI resolution discovers and verifies KELs
• Credential issuance and presentation flows work

End-to-End Tests: Test complete workflows:

• Multi-party credential exchanges
• Challenge-response authentication
• Multi-signature coordination
• Error recovery scenarios

Deployment Patterns

Web Applications: Signify-ts can run in browsers:

• Use WebAssembly for libsodium
• Store encrypted keys in IndexedDB
• Use Service Workers for background operations
• Implement secure passcode entry

Mobile Applications: Signify can integrate with mobile apps:

• Use platform secure storage (Keychain, Keystore)
• Implement biometric authentication
• Handle background/foreground transitions
• Manage network connectivity changes

Desktop Applications: Signify works in Electron or native apps:

• Use OS credential storage
• Implement auto-lock mechanisms
• Support hardware security modules
• Provide backup/restore functionality

Server-Side: While Signify is designed for edge signing, server-side use cases exist:

• Automated credential issuance
• Service-to-service authentication
• Batch operations
• Testing and development

Server deployments must carefully manage key security and access control.

End-to-End Tests: Test complete workflows - multi-party credential exchanges, challenge-response authentication, multi-signature coordination, error recovery scenarios.

Deployment Considerations

Web Applications: Use WebAssembly for libsodium, store encrypted keys in IndexedDB, use Service Workers for background operations, implement secure passcode entry.

Mobile Applications: Use platform secure storage (Keychain, Keystore), implement biometric authentication, handle background/foreground transitions, manage network connectivity changes.

Desktop Applications: Use OS credential storage, implement auto-lock mechanisms, support hardware security modules, provide backup/restore functionality.

Server-Side: While designed for edge signing, server-side use cases exist for automated credential issuance, service-to-service authentication, batch operations, and testing. Server deployments must carefully manage key security and access control.