HardKey SDK

Status: v0.1.0 (Beta)

HardKey is a cross-platform SDK for generating hardware-backed cryptographic keys and issuing short-lived, signed assertions that can be verified offline within an existing trust context. It provides a proof-of-possession primitive—not an authentication protocol, identity system, or standalone trust anchor. Verification of HardKey assertions requires a prior out-of-band trust binding, such as key enrollment, device pairing, or an application-level policy decision.

What HardKey Provides

• Hardware-protected key generation — Where platform support exists, private keys are generated and stored in hardware-isolated environments (Secure Enclave, Android Keystore, WebAuthn authenticators).
• Proof of continued key possession — Signed assertions demonstrate that the signing key remains under the control of the same device or authenticator that generated it.
• Portable, signed assertions — Assertions are self-contained, serializable, and can be transmitted or stored for later verification.
• Offline verification — Assertions can be verified without network access, provided the verifier already possesses the expected public key.

What HardKey Does NOT Provide

• Not an identity system — HardKey does not bind keys to real-world identities, user accounts, or external identity providers. Establishing who or what a key represents is the responsibility of the integrating application.
• Not a PKI replacement — HardKey does not issue certificates, manage certificate chains, or provide revocation mechanisms.
• Not a general authentication protocol — HardKey provides a cryptographic primitive. Building a secure authentication flow requires additional protocol design, including challenge-response, replay protection, and session management.
• Not protection against malicious local software — If trusted software on the device is compromised or acts maliciously, it may misuse keys that HardKey has generated. HardKey does not provide execution environment isolation or workload integrity guarantees.
• Not exclusive proof of execution environment — HardKey cannot prove that a specific application or code path invoked the signing operation, only that the key was used.

Threat Model

Assumptions

• A trust binding has been established out-of-band prior to verification (e.g., the verifier has enrolled or recorded the expected public key during a trusted setup phase).
• The hardware-backed keystore implementation on the device is functioning correctly and has not been compromised.
• The verifier possesses the correct public key corresponding to the signing device.

In-Scope Adversaries

• Adversaries who do not have access to the hardware-protected private key and cannot extract it from the device.
• Adversaries attempting to forge assertions without possession of the signing key.

Out-of-Scope Threats

• Key enrollment and initial trust establishment — HardKey does not secure the enrollment process; this must be handled by the application.
• Key revocation — HardKey provides no revocation mechanism. Applications must implement their own key lifecycle management.
• Malicious code on the device — If an attacker controls trusted software with access to the key, they can sign arbitrary payloads.
• Side-channel or physical attacks on hardware — HardKey relies on platform-provided hardware security; attacks against those mechanisms are out of scope.

Platform Differences

HardKey abstracts over platform-specific secure storage mechanisms to provide a portable API. However, these mechanisms offer different security properties:

Platform	Underlying Mechanism	Notes
iOS	Secure Enclave	Hardware-isolated key storage; keys are non-exportable.
Android	Android Keystore (TEE/StrongBox)	Hardware backing depends on device; some devices use software-only keystores.
Web	WebAuthn / WebCrypto	WebAuthn provides hardware backing via authenticators; WebCrypto P-256 keys are software-backed.
Node.js	Software keystore	No hardware protection; suitable for development and testing.

Applications with strict security requirements should verify the backing mechanism on each target platform and understand that HardKey intentionally abstracts over these differences for portability.

Key Origin Metadata

Assertions include an optional keyOrigin field indicating the class of key storage used:

• secure_enclave — iOS Secure Enclave (hardware-isolated)
• tee — Android TEE or StrongBox (hardware-isolated, device-dependent)
• webauthn — WebAuthn platform authenticator (may be hardware-backed)
• software — Software-only key storage (no hardware protection)

This field is informational only and does not affect verification logic. It is self-reported by the signer and should not be treated as authoritative by verifiers.

Platform Support

Platform	Status	Implementation
TypeScript / Node	✅ Available	Reference implementation (software keys)
Web (Browser)	✅ Available	WebCrypto (P-256) & WebAuthn
iOS	✅ Available	Swift / Secure Enclave (SPM)
Android	✅ Available	Kotlin / Android Keystore (Gradle)

Installation

Node.js / TypeScript

npm install hardkey-sdk

iOS (Swift Package Manager)

Add the package dependency in Xcode: https://github.com/LongevityManiac/HardKey.git

Android (Gradle)

implementation("com.hardkey.sdk:hardkey-android:0.1.0")

Example Usage

import * as crypto from 'crypto';
import { createTrustToken, verifyTrustToken, DeviceKeyProvider } from 'hardkey-sdk';

class NodeKeyProvider implements DeviceKeyProvider {
  private keys = crypto.generateKeyPairSync('ed25519');
  async getOrCreateDeviceKey() {}
  async getPublicKey() { 
    return new Uint8Array(this.keys.publicKey.export({ format: 'der', type: 'spki' })); 
  }
  async sign(data: Uint8Array) { 
    return new Uint8Array(crypto.sign(null, data, this.keys.privateKey)); 
  }
}

const provider = new NodeKeyProvider();

// Create a signed assertion
const assertion = await createTrustToken(provider, { 
  issuerId: 'device_1', 
  subjectId: 'session_1', 
  purpose: 'possession_proof',
  keyOrigin: 'software' // Indicates key storage class (informational)
});

// Verify the assertion (requires prior knowledge of expected public key)
const result = await verifyTrustToken(assertion, 'possession_proof', {
  verifySignature: async (pub, data, sig) => crypto.verify(
    null, 
    data, 
    crypto.createPublicKey({ key: Buffer.from(pub), format: 'der', type: 'spki' }), 
    sig
  )
});

See examples/simple_node_example.ts for a complete example.

Documentation

• Overview
• Signed Assertion Format
• API Reference
• Security Model
• Web Binding
• iOS Guide
• Android Guide

Licensing

HardKey is dual-licensed:

• Free for non-commercial, open-source, and academic use (MIT-style).
• Commercial License ($20) — One-time payment for commercial use.
• Enterprise License — Contact for custom terms.

See LICENSE.md for full terms.

Security Notice

HardKey is currently in Beta and has not undergone a formal external security audit. It relies on platform-native secure storage implementations. Evaluate suitability for your threat model before deployment.

Report security issues to hello@aifootprint.ai.