Skip to content

API_ASYMMETRIC.md

Latest commit

 

History

History
185 lines (117 loc) · 5.03 KB

API_ASYMMETRIC.md

File metadata and controls

185 lines (117 loc) · 5.03 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, recipientPublicKey) / decryptWithECDH(b64, recipientPrivateKey, senderPublicKey)

One-step ECDH public-key encryption and decryption.

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

Digital Signatures

generateSigningKeyPair(algorithm, curveOrModulus)

Generates digital signing key pair (ECDSA P-256/P-384 or RSA-PSS 4096).

const ecdsaKeys = await wca.generateSigningKeyPair("ECDSA", "P-256");
const rsaKeys = await wca.generateSigningKeyPair("RSA-PSS", 4096);

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)

deriveKeyHKDF(secret, salt, info, keyLength)

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

const hkdfKey = await wca.deriveKeyHKDF(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");

PEM & JWK Key Export / Import

exportPublicKeyToPEM(publicKey) / importPublicKeyFromPEM(pem)

Exports and imports public keys in standard PKCS#8 / SPKI PEM format.

const pemString = await wca.exportPublicKeyToPEM(keys.publicKey);
const importedKey = await wca.importPublicKeyFromPEM(pemString);

exportKeyToJWK(key) / importKeyFromJWK(jwk, algorithm)

Exports and imports keys in JSON Web Key (JWK, RFC 7517) format.

const jwk = await wca.exportKeyToJWK(keys.publicKey);
const key = await wca.importKeyFromJWK(jwk, { name: "RSA-OAEP", hash: "SHA-256" });