Signing Key Security Guide

1. Memory-Only Signing

The signing key should exist in application memory only for the duration of the signing operation. It should never be:

• Written to disk (log files, temp files, core dumps)
• Included in error messages or stack traces
• Sent over the network (only the signature travels, never the key)
• Retained in memory after the Witness is stopped

1.1 What the SDK does automatically

Both the Python and TypeScript SDKs implement these protections:

• The signing key is stored as a private field, not exposed via public API.
• Error messages from the buffer and flush pipeline never include the key value.
• The key is passed to HMAC-SHA256 as a byte buffer, used once per signature, and not cached.
• The .swt3.yaml loader uses _env suffix convention, so the key never appears in config files.

1.2 What the developer must do

• Do not log the signing key at application level (print(signing_key) or console.log(signingKey)).
• Do not include the signing key in application telemetry or APM metadata.
• If fetching from a secret store, do not cache the raw key beyond the Witness lifecycle.
• If the application crashes, ensure core dump settings exclude environment variables (ulimit -c 0 or systemd LimitCORE=0).

2. Language-Specific Considerations

2.1 Python

Python strings are immutable and garbage-collected non-deterministically. The signing key may persist in memory after the Witness is stopped until the garbage collector reclaims it. For most compliance scenarios, this is acceptable because:

• The key is in process memory, not on disk.
• An attacker who can read process memory already has full system access.
• Python's hmac module uses C-level memory for the HMAC computation.

2.2 TypeScript / Node.js

Node.js strings are immutable and managed by V8's garbage collector. Similar to Python, the key may persist in the V8 heap until GC. The crypto.createHmac() function operates on native buffers, not JavaScript strings.

For Node.js specifically:

• Do not use --inspect or --inspect-brk in production (exposes heap to debugger).
• Set NODE_OPTIONS="--max-old-space-size=512" to limit heap size and trigger GC more frequently.
• Use Buffer.alloc() instead of Buffer.from() if implementing custom key handling (allows explicit zeroing).

2.3 Rust (Recommended for High-Assurance)

The Rust SDK (swt3-ai crate) offers:

• Deterministic memory clearing. The signing key is stored in a Zeroize-implementing type that overwrites memory on drop. When the Witness goes out of scope, the key bytes are zeroed before deallocation.
• No garbage collector. Memory is freed at the exact point the owner goes out of scope. No key material lingers in heap.
• No runtime reflection. The key cannot be inspected via debugger protocols, serialization, or fmt::Debug (the Debug impl redacts the value).
• Compile-time safety. The borrow checker prevents accidental copies of the key. Only one owner exists at any time.

# Cargo.toml
[dependencies]
swt3-ai = "0.3.6"

# The crate uses zeroize internally for key material

use swt3_ai::{fingerprint, sign_payload};

let key = "your-signing-key";
let fp = fingerprint("TENANT", "AI-INF.1", 1, 1, 0, timestamp_ms);
let sig = sign_payload(key, &fp, Some("agent-id"));
// key is dropped when it goes out of scope; memory is zeroed

2.4 C# / .NET

The .NET SDK uses System.Security.Cryptography.HMACSHA256 which operates on byte arrays. The SecureString type is deprecated in .NET Core; use byte[] with explicit zeroing via Array.Clear() when done.

2.5 Ruby

Ruby strings are mutable. After signing, you can overwrite the key variable: signing_key.replace("\0" * signing_key.length). This is a best-effort mitigation since the GC may have copied the string internally.

3. Signing Security Tiers

Organizations can choose the appropriate signing security level based on their regulatory environment:

4. Server-Side Key Protection

When a tenant registers a signing key via POST /api/v1/signing-keys, the server never stores the raw key. Instead:

1. The key is encrypted with AES-256-GCM using a server-side envelope key (SIGNING_KEY_MASTER).
2. The ciphertext, IV, and authentication tag are stored separately in an encrypted key store.
3. Row-level security restricts access to the service role only (no anon or authenticated access).
4. The raw key is never returned by any API endpoint after registration.
5. The key is decrypted in memory only during signature validation, then discarded.

If the database is compromised, the attacker gets encrypted ciphertext that is useless without the SIGNING_KEY_MASTER environment variable from the server.

5. Key Generation Best Practices

Generate signing keys using cryptographically secure random number generators:

# Python
python3 -c "import secrets; print(secrets.token_hex(32))"

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# OpenSSL
openssl rand -hex 32

# Rust
use rand::Rng;
let key: String = rand::thread_rng()
    .sample_iter(&rand::distributions::Alphanumeric)
    .take(64)
    .map(char::from)
    .collect();

6. When to Use Rust

Use the Rust SDK when any of these apply:

• Your deployment handles classified or ITAR-controlled workloads.
• Your compliance framework requires deterministic memory clearing (FIPS 140-2, Common Criteria).
• You are building a long-running daemon or gateway that processes millions of inferences.
• Your threat model includes memory forensics or cold boot attacks.
• You need the smallest possible binary with zero runtime dependencies.

For all other cases, the Python and TypeScript SDKs provide equivalent cryptographic guarantees at the protocol level. The signing algorithm (HMAC-SHA256), fingerprint formula, and clearing engine are identical across all five language implementations.