How Ed25519 key management actually works in OID — filesystem, environment variables, PKCS#11/HSM, and TPM2. VaultKeyProvider and KMSKeyProvider are not implemented.

KeyProvider API

This page previously documented a @abscore/identity package with a different API shape than what exists. The real package is @abs-core/identity (source at OID/src/). Function signatures, file names, env vars, and class names below have been corrected to match the code. VaultKeyProvider and KMSKeyProvider do not exist — the real enterprise path is HSM via PKCS#11 (OID/src/key-provider-hsm.ts) and TPM2 (OID/src/tpm2-key-provider.ts).

Every ABS Core agent proves its identity with an Ed25519 cryptographic keypair. The KeyProvider API abstracts where and how those keys are stored.

Architecture

              KeyProvider Interface
              |                   |
    +---------+--------+  +------+-------+
    | FileSystemKeyProvider |  | EnvKeyProvider |
    | (default)             |  | (CI/CD)        |
    +-----------------------+  +----------------+
              |
    +---------+--------+  +----------------------+
    | PKCS11KeyProvider  |  | TPM2KeyProvider      |
    | (HSM)              |  | (IL4/air-gap)        |
    +-------------------+  +-----------------------+

Auto-Detection

resolveKeyProvider() tries, in order: environment variables, then filesystem, then generates a new keypair on first run.

import { resolveKeyProvider } from '@abs-core/identity';

const { provider, keys } = await resolveKeyProvider('.abs-keys');
// 1. Checks ABS_SIGNING_KEY / ABS_SIGNING_KEY_PEM env vars -> EnvKeyProvider
// 2. Checks the given keyDir (default '.abs-keys')          -> FileSystemKeyProvider
// 3. Generates new keypair                                    -> FileSystemKeyProvider (auto-create)

Source: OID/src/key-provider.ts:323-344.

FileSystem Provider (Default)

Keys are stored as PEM files, not DER.

# Default location: .abs-keys/ (relative to process cwd)
.abs-keys/
  abs-signing-key.pem          # Ed25519 private key (PKCS8 PEM)
  abs-signing-key.pub.pem      # Ed25519 public key (SPKI PEM)
  abs-signing-key.fingerprint  # hex fingerprint

import { FileSystemKeyProvider } from '@abs-core/identity';

const provider = new FileSystemKeyProvider('/secure/path/to/keys'); // string, not an options object
const keys = await provider.loadKeys();       // throws if no keys exist yet
// or, to create keys on first run:
const keys = await provider.generateAndStore();

Security note: In production (ABS_ENV=production or NODE_ENV=production), the private key must be encrypted — storeKeys() throws if ABS_KEY_PASSWORD is unset. In development, an unencrypted key is written with a warning. Private key file permissions are 0600, public key and fingerprint are 0644.

Environment Provider (CI/CD)

For containerized environments where filesystem persistence is unavailable.

# PEM format
export ABS_SIGNING_KEY_PEM="-----BEGIN PRIVATE KEY-----..."
export ABS_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----..."

# or base64-encoded PKCS8/SPKI DER
export ABS_SIGNING_KEY="base64..."
export ABS_PUBLIC_KEY="base64..."

import { EnvKeyProvider } from '@abs-core/identity';

const provider = new EnvKeyProvider();
const keys = await provider.loadKeys();

HSM Provider (PKCS#11 — implemented today)

Unlike the previously-documented VaultKeyProvider/KMSKeyProvider (neither exists), real HSM support ships today via PKCS#11:

// See OID/src/key-provider-hsm.ts

This uses the graphene-pk11 library against any PKCS#11-compliant HSM (e.g. Thales Luna). See Key Management & HSM Integration — note that KMIP is not implemented, only PKCS#11.

TPM2 Provider (air-gapped / IL4)

OID/src/tpm2-key-provider.ts implements TPM2KeyProvider / resolveHardwareKeyProvider() for hardware-backed keys in air-gapped deployments — see IL4 Air-Gap Deployment.

Key Fingerprint

import { computeFingerprint } from '@abs-core/identity';

const fingerprint = computeFingerprint(publicKey); // SHA-256 hex digest

The fingerprint appears in:

Gateway startup logs
SovereignAuditRecord agent_oid_pubkey field
Compliance reports

Key Rotation

To rotate keys:

Generate a new keypair (generateAndStore() or a new HSM slot).
Register the new public key with the OID registry.
Revoke the old public key.
Update the KeyProvider configuration.

The hash chain records both the old and new key fingerprints, creating an auditable rotation trail.

ABS Core Engine Internals -- How the engine uses keys for signing
Sovereign Checklist -- Checkpoint: "Keys generated locally?"
Air-Gapped Operations -- Key management without internet

KeyProvider API

On this page