Key Management Guide

Overview

AgentKey uses public key cryptography to verify agent identities. You generate a key pair (public and private), register the public key with AgentKey, and use the private key to sign messages. Others can verify your signatures using your registered public key.

Supported Key Types

Ed25519 (Recommended)

Ed25519 is a modern elliptic curve signature scheme. It offers excellent security with small key and signature sizes.

# Generate Ed25519 key pair
openssl genpkey -algorithm ED25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

RSA

RSA is widely supported and well-understood. Use at least 2048-bit keys for security.

# Generate RSA key pair (4096-bit)
openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:4096
openssl pkey -in private.pem -pubout -out public.pem

ECDSA

ECDSA provides good security with smaller key sizes than RSA.

# Generate ECDSA key pair (P-256 curve)
openssl ecparam -genkey -name prime256v1 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

Registering Keys

After generating your key pair, register the public key through the Dashboard or via the API:

curl -X POST https://agentkey.example.com/api/v1/agents/{agent_id}/keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
    "keyType": "ed25519",
    "label": "Production Key 2024",
    "isPrimary": true
  }'

Key Labels

Use descriptive labels for your keys to help you identify them later:

• Production Key 2024 - For production environments
• Development - For testing and development
• CI/CD Pipeline - For automated systems
• Backup Key - Emergency backup key

Primary Keys

You can designate one key as your primary key. When someone verifies a signature without specifying a key fingerprint, the primary key is used first. Keep your primary key as your most trusted, production key.

Key Rotation

Regular key rotation improves security. We recommend:

1. Generate a new key pair
2. Register the new public key
3. Update your systems to use the new private key
4. Revoke the old key after a transition period

Revoking Keys

If a private key is compromised or no longer needed, revoke it immediately:

• Via Dashboard: Go to Keys and click "Revoke"
• Via API: DELETE /api/v1/agents/{id}/keys/{keyId}

Revoked keys are kept for audit purposes but will not be used for verification.

Signing Messages

Python Example

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
import base64

# Load private key
with open("private.pem", "rb") as f:
    private_key = serialization.load_pem_private_key(f.read(), password=None)

# Sign message
message = b"Hello, this is a signed message"
signature = private_key.sign(message)
signature_b64 = base64.b64encode(signature).decode()

print(f"Message: {message.decode()}")
print(f"Signature: {signature_b64}")

Node.js Example

const crypto = require('crypto');
const fs = require('fs');

// Load private key
const privateKey = fs.readFileSync('private.pem');

// Sign message
const message = 'Hello, this is a signed message';
const sign = crypto.createSign('SHA256');
sign.update(message);
const signature = sign.sign(privateKey, 'base64');

console.log('Message:', message);
console.log('Signature:', signature);

Go Example

package main

import (
    "crypto/ed25519"
    "encoding/base64"
    "encoding/pem"
    "fmt"
    "os"
)

func main() {
    // Load private key (simplified)
    keyPEM, _ := os.ReadFile("private.pem")
    block, _ := pem.Decode(keyPEM)
    privateKey := ed25519.PrivateKey(block.Bytes[len(block.Bytes)-64:])

    // Sign message
    message := []byte("Hello, this is a signed message")
    signature := ed25519.Sign(privateKey, message)
    signatureB64 := base64.StdEncoding.EncodeToString(signature)

    fmt.Println("Message:", string(message))
    fmt.Println("Signature:", signatureB64)
}

Verifying Signatures

Services can verify signatures using the AgentKey API:

curl -X POST https://agentkey.example.com/api/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "your-subject-id",
    "message": "Hello, this is a signed message",
    "signature": "<base64_signature>"
  }'

Security Best Practices

• Never share your private key - The private key should never leave your secure environment
• Use hardware security modules (HSMs) - For high-security applications
• Encrypt private keys at rest - Use password protection or encryption
• Limit access - Only authorized systems should access private keys
• Monitor for compromise - Watch for unauthorized signatures
• Have a revocation plan - Know how to quickly revoke compromised keys