Skip to content

API_ASYMMETRIC.md

Latest commit

 

History

History
198 lines (125 loc) · 5.8 KB

API_ASYMMETRIC.md

File metadata and controls

198 lines (125 loc) · 5.8 KB
Raw

WebCryptAsym API Reference (Asymmetric & Public-Key Cryptography)

The WebCryptAsym class provides zero-dependency asymmetric cryptography including RSA-4096 Hybrid Encryption, ECDH Key Agreement, Digital Signatures (ECDSA P-256 / RSA-PSS), JWE Compact Serialization (RFC 7516), HKDF/PBKDF2 Key Derivation, and Hierarchical Key Derivation.

Table of Contents

Instantiation

import { WebCryptAsym } from "webcrypt";

const wca = new WebCryptAsym();

RSA Key Pairs & Hybrid Encryption

generateKeyPair(modulusLength)

Generates an RSA-OAEP key pair (default: 4096-bit).

  • Parameters: modulusLength (number, default: 4096)
  • Returns: Promise<{ publicKey: CryptoKey, privateKey: CryptoKey }>
const keys = await wca.generateKeyPair(4096);

encryptText(text, publicKey) / decryptText(b64, privateKey)

Hybrid encryption using RSA-OAEP to encrypt an ephemeral AES-256-GCM session key.

const encrypted = await wca.encryptText("Confidential message", keys.publicKey);
const decrypted = await wca.decryptText(encrypted, keys.privateKey);

encryptData(data, publicKey) / decryptData(b64, privateKey)

Serializes JavaScript objects to JSON and encrypts via RSA hybrid encryption.

const b64 = await wca.encryptData({ secret: "data" }, keys.publicKey);
const obj = await wca.decryptData(b64, keys.privateKey);

ECDH Key Agreement

generateECDHKeyPair(namedCurve)

Generates an Elliptic Curve Diffie-Hellman key pair (P-256 or P-384).

const aliceKeys = await wca.generateECDHKeyPair("P-256");
const bobKeys = await wca.generateECDHKeyPair("P-256");

deriveECDHSharedSecret(privateKey, peerPublicKey)

Derives an AES-GCM 256-bit shared key via ECDH key agreement.

const sharedKey = await wca.deriveECDHSharedSecret(aliceKeys.privateKey, bobKeys.publicKey);

encryptWithECDH(payload, senderPrivateKey, recipientPublicKey) / decryptWithECDH(b64, recipientPrivateKey, senderPublicKey)

One-step ECDH public-key encryption and decryption.

const encrypted = await wca.encryptWithECDH("ECDH Secret", aliceKeys.privateKey, bobKeys.publicKey);
const decrypted = await wca.decryptWithECDH(encrypted, bobKeys.privateKey, aliceKeys.publicKey);

Digital Signatures

generateSigningKeyPair(curve = "P-256")

Generates ECDSA digital signing key pair (P-256 or P-384).

const ecdsaKeys = await wca.generateSigningKeyPair("P-256");

signText(text, privateKey) / verifyText(text, signatureB64, publicKey)

Computes and verifies digital signatures over text messages.

const sig = await wca.signText("Message", ecdsaKeys.privateKey);
const isValid = await wca.verifyText("Message", sig, ecdsaKeys.publicKey);

JWE Compact Serialization (RFC 7516)

encryptJWE(payload, publicKey, customHeaders)

Encrypts payload into a RFC 7516 compliant 5-part JWE Compact Serialization string (header.encryptedKey.iv.ciphertext.tag).

const jweToken = await wca.encryptJWE({ user: "Alice" }, rsaKeys.publicKey);

decryptJWE(jweToken, privateKey)

Decrypts a 5-part JWE Compact string.

const payload = await wca.decryptJWE(jweToken, rsaKeys.privateKey);

Key Derivation (HKDF / PBKDF2 / SHA-3)

deriveKeyHKDFSHA2(secret, salt, info, keyLength)

Derives a key using HKDF-SHA256 (RFC 5869).

const hkdfKey = await wca.deriveKeyHKDFSHA2(masterSecret, salt, "app-context", 256);

deriveKeyHKDFSHA3(secret, salt, info, keyLength)

Derives key via HKDF with SHA-3 digest.

const hkdfSha3Key = await wca.deriveKeyHKDFSHA3(masterSecret, salt, "context", 256);

Hierarchical Key Derivation

deriveChildKeyHierarchical(parentKey, childSalt, purpose)

Derives a child AES key from an existing parent AES key for context-specific operations.

const childKey = await wca.deriveChildKeyHierarchical(parentKey, salt, "file-encryption");

Key Export / Import (SPKI / PKCS#8 Base64)

exportPublicKey(publicKey) / importPublicKey(b64Key)

Exports and imports RSA/ECDH public keys in Base64 SPKI format.

const pubB64 = await wca.exportPublicKey(rsaKeys.publicKey);
const importedPub = await wca.importPublicKey(pubB64);

exportPrivateKey(privateKey) / importPrivateKey(b64Key)

Exports and imports RSA/ECDH private keys in Base64 PKCS#8 format.

const privB64 = await wca.exportPrivateKey(rsaKeys.privateKey);
const importedPriv = await wca.importPrivateKey(privB64);

AI Agent MCP Tooling

WebCrypt includes native Model Context Protocol (MCP) tooling exposing asymmetric cryptography to AI agents:

  • manage_keys(action: "generate", type: "rsa" | "ecdh" | "hmac" | "password", modulusLength?: 2048 | 4096, namedCurve?: "P-256" | "P-384")
  • encrypt_payload(mode: "asymmetric", data: string | object, public_key_jwk: object)
  • decrypt_payload(mode: "asymmetric", ciphertext: string, private_key_jwk: object)
  • sign_verify(action: "sign" | "verify", algorithm: "ECDSA" | "RSA-PSS", data: string, key_jwk: object, signature?: string)
  • pqc_kem_sign(action: "hybrid_encapsulate" | "hybrid_decapsulate", rsa_public_key_jwk?: object, rsa_private_key_jwk?: object, public_key_b64?: string, private_key_b64?: string)

For full agent setup instructions, see docs/MCP_IDE_SETUP.md.