@peculiar/webcrypto

What is @peculiar/webcrypto?

The @peculiar/webcrypto package is an implementation of the Web Cryptography API for Node.js. It provides cryptographic operations in web applications, including hashing, signature generation and verification, encryption and decryption, and key generation and management. This package is particularly useful for server-side applications that require cryptographic operations consistent with those available in the browser.

What are @peculiar/webcrypto's main functionalities?

Generating cryptographic keys

This code sample demonstrates how to generate a cryptographic key pair using RSA-PSS algorithm. The generated keys can be used for signing and verification purposes.

const { Crypto } = require('@peculiar/webcrypto');
const crypto = new Crypto();

async function generateKey() {
  const key = await crypto.subtle.generateKey(
    {
      name: 'RSA-PSS',
      modulusLength: 2048,
      publicExponent: new Uint8Array([1, 0, 1]),
      hash: 'SHA-256',
    },
    true,
    ['sign', 'verify']
  );
  return key;
}

Encrypting and decrypting data

This code sample shows how to encrypt data using a public key and decrypt it using a private key with the RSA-OAEP algorithm. It's useful for secure data transmission.

const { Crypto } = require('@peculiar/webcrypto');
const crypto = new Crypto();

async function encryptData(publicKey, data) {
  const encryptedData = await crypto.subtle.encrypt(
    {
      name: 'RSA-OAEP'
    },
    publicKey,
    data
  );
  return encryptedData;
}

async function decryptData(privateKey, encryptedData) {
  const decryptedData = await crypto.subtle.decrypt(
    {
      name: 'RSA-OAEP'
    },
    privateKey,
    encryptedData
  );
  return decryptedData;
}

Signing and verifying data

This example demonstrates signing data with a private key and verifying the signature with the corresponding public key using the RSA-PSS algorithm. It's essential for ensuring data integrity and authenticity.

const { Crypto } = require('@peculiar/webcrypto');
const crypto = new Crypto();

async function signData(privateKey, data) {
  const signature = await crypto.subtle.sign(
    {
      name: 'RSA-PSS',
      saltLength: 32,
    },
    privateKey,
    data
  );
  return signature;
}

async function verifySignature(publicKey, signature, data) {
  const isVerified = await crypto.subtle.verify(
    {
      name: 'RSA-PSS',
      saltLength: 32,
    },
    publicKey,
    signature,
    data
  );
  return isVerified;
}

Other packages similar to @peculiar/webcrypto

node-forge

node-forge is a native JavaScript implementation of networking protocols and cryptographic operations. Compared to @peculiar/webcrypto, node-forge offers a broader range of cryptographic algorithms and utilities, but it does not follow the Web Cryptography API standard, making it less suitable for projects aiming for consistency with web crypto operations.

crypto-browserify

crypto-browserify is a package that attempts to mimic the Node.js crypto module for use in the browser, using native browser implementations where possible. While it provides similar functionalities to @peculiar/webcrypto, its primary focus is on bridging Node.js crypto capabilities to the browser rather than offering a consistent Web Cryptography API experience across platforms.

README

@peculiar/webcrypto

We wanted to be able to write Javascript that used crypto on both the client and the server but we did not want to rely on Javascript implementations of crypto. The only native cryptography available in browser is Web Crypto, this resulted in us creating a @peculiar/webcrypto.

Table Of Contents

• WARNING
• Installing
• Using
• Examples
• Bug Reporting
• Related

WARNING

At this time this solution should be considered suitable for research and experimentation, further code and security review is needed before utilization in a production application.

Module is based on NodeJS v10 Crypto API. It would work only with Node v10 and higher.

Installing

npm install @peculiar/webcrypto

Supported algorithms

Algorithm name	generateKey	digest	export/import	sign/verify	encrypt/decrypt	wrapKey/unwrapKey	derive
SHA-1		X
SHA-256		X
SHA-384		X
SHA-512		X
HMAC	X		X	X
RSASSA-PKCS1-v1_5	X		X	X
RSAES-PKCS1-v1_52	X		X		X	X
RSA-PSS	X		X	X
RSA-OAEP	X		X		X	X
AES-CMAC	X		X	X
AES-CBC	X		X		X	X
AES-CTR	X		X		X	X
AES-ECB	X		X		X	X
AES-GCM	X		X		X	X
AES-KW	X		X			X
ECDSA1	X		X	X
ECDH1	X		X				X
EdDSA2,3	X		X	X
ECDH-ES2,4	X		X				X
HKDF			X				X
PBKDF2			X				X
DES-CBC2	X		X		X	X
DES-EDE3-CBC2	X		X		X	X
shake1282		X
shake2562		X

¹ Mechanism supports extended list of named curves P-256, P-384, P-521, K-256, brainpoolP160r1, brainpoolP160t1, brainpoolP192r1, brainpoolP192t1, brainpoolP224r1, brainpoolP224t1, brainpoolP256r1, brainpoolP256t1, brainpoolP320r1, brainpoolP320t1, brainpoolP384r1, brainpoolP384t1, brainpoolP512r1, and brainpoolP512t1

² Mechanism is not defined by the WebCrypto specifications. Use of mechanism in a safe way is hard, it was added for the purpose of enabling interoperability with an existing system. We recommend against its use unless needed for interoperability.

³ Mechanism supports extended list of named curves Ed25519, and Ed448

⁴ Mechanism supports extended list of named curves X25519, and X448

Using

const { Crypto } = require("@peculiar/webcrypto");

const crypto = new Crypto();

Examples

See WebCrypto Docs for examples

Bug Reporting

Please report bugs either as pull requests or as issues in the issue tracker. @peculiar/webcrypto has a full disclosure vulnerability policy. Please do NOT attempt to report any security vulnerability in this code privately to anybody.

Related

• node-webcrypto-ossl
• node-webcrypto-p11
• webcrypto-liner

Changelog

1.5.0 (2024-05-28)

Features

• Add support for Ed25519 and X25519 algorithms (a0cf289)