Skip to content

web.md

Latest commit

 

History

History
69 lines (51 loc) · 2.97 KB

web.md

File metadata and controls

69 lines (51 loc) · 2.97 KB
Raw

HardKey Web Binding

The Web binding provides browser-based signing using WebCrypto and WebAuthn.

Important: Trust Assumptions

HardKey provides a proof-of-possession primitive only. It does not establish identity, perform enrollment, or create trust from scratch.

Verification assumes an existing trust binding to the expected public key. The verifier is responsible for knowing and trusting the expected public key via prior enrollment or out-of-band exchange.

Features

  • WebCrypto: Uses ECDSA P-256 keys generated as non-exportable (in memory for the session). The keyOrigin is software.
  • WebAuthn: (Planned) Uses platform authenticators (TouchID, FaceID, Windows Hello). The keyOrigin would be webauthn.

Usage (WebCrypto)

// For bundled/npm usage:
import { WebDeviceKeyProvider, createTrustToken, verifyTrustToken } from 'hardkey-sdk/web';

// 1. Initialize Provider
const provider = new WebDeviceKeyProvider();
await provider.getOrCreateDeviceKey();

// 2. Create signed assertion
const assertion = await createTrustToken(provider, {
  issuerId: 'browser_session_1',
  subjectId: 'server_1',
  purpose: 'session_auth',
  expiresInSeconds: 300, // 5 minutes
  keyOrigin: provider.keyOrigin // 'software'
});

// 3. Verify assertion
// NOTE: Verification only proves possession of the private key.
// The verifier must independently verify the public key matches an expected,
// previously-enrolled key.
const result = await verifyTrustToken(assertion, 'session_auth', {
  verifySignature: async (pub, data, sig) => {
    const key = await crypto.subtle.importKey(
      "spki", pub,
      { name: "ECDSA", namedCurve: "P-256" },
      false, ["verify"]
    );
    return crypto.subtle.verify(
      { name: "ECDSA", hash: { name: "SHA-256" } },
      key, sig, data
    );
  }
});

Key Origin

The WebDeviceKeyProvider reports keyOrigin: 'software' because WebCrypto P-256 keys are stored in browser memory (non-exportable but software-backed).

For hardware-backed keys in browsers, WebAuthn with a platform authenticator should be used. This would report keyOrigin: 'webauthn'.

Security Considerations

  • Software-Backed: WebCrypto keys in this implementation are software-backed (in memory for the session). They provide non-exportability but not hardware isolation.
  • Origin Bound: Keys are bound to the web origin (domain).
  • XSS Risk: If an attacker achieves XSS on your domain, they can use the key to sign messages during that session (though they cannot export the private key).
  • No Hardware Isolation: For higher security requirements, use WebAuthn with a platform authenticator that provides hardware backing.

Clock Skew

Assertions include iat (issued-at) and optional exp (expiration) timestamps. Verification allows a configurable clock skew tolerance (default: 60 seconds) to prevent false rejections due to minor clock differences. This is not a security mechanism and does not provide replay protection.