Skip to content

API_ASYMMETRIC.md

Latest commit

 

History

History
184 lines (116 loc) · 4.95 KB

API_ASYMMETRIC.md

File metadata and controls

184 lines (116 loc) · 4.95 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);