Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

hpke-js

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

hpke-js

A Hybrid Public Key Encryption (HPKE) library

0.11.0
Source
npm

Version published: 2 years ago

Maintainers: 1

Created: 3 years ago

Source

hpke-js

A TypeScript Hybrid Public Key Encryption (HPKE) implementation build on top of Web Cryptography API. This library works both on web browsers, Node.js and Deno.

API Documentation

Index

Supported Features
Supported Environments
Warnings and Restrictions
Installation
Usage
- Base mode - for browsers, Node.js and Deno.
- Base mode with Single-Shot APIs
- Base mode with bidirectional encryption
- Base mode with export-only AEAD
- PSK mode
- Auth mode
- AuthPSK mode
Contributing
References

Supported Features

HPKE Modes

Base	PSK	Auth	AuthPSK
✅	✅	✅	✅

Key Encapsulation Machanisms (KEMs)

KEMs	Browser	Node.js	Deno
DHKEM (P-256, HKDF-SHA256)	✅	✅
DHKEM (P-384, HKDF-SHA384)	✅	✅
DHKEM (P-521, HKDF-SHA512)	✅	✅
DHKEM (X25519, HKDF-SHA256)	✅	✅	✅	@stablelib/x25519 is used until Secure Curves is implemented on browsers.
DHKEM (X448, HKDF-SHA512)	✅	✅	✅	x449-js is used until Secure Curves is implemented on browsers.

Key Derivation Functions (KDFs)

KDFs	Browser	Node.js	Deno
HKDF-SHA256	✅	✅	✅
HKDF-SHA384	✅	✅	✅
HKDF-SHA512	✅	✅	✅

Authenticated Encryption with Associated Data (AEAD) Functions

AEADs	Browser	Node.js	Deno
AES-128-GCM	✅	✅	✅
AES-256-GCM	✅	✅	✅
ChaCha20Poly1305	✅	✅	✅	@stablelib/chacha20poly1305 is used.
Export Only	✅	✅	✅

Supported Environments

Web Browser: Web Cryptography API supported browsers
- Confirmed: Chrome, Firefox, Edge, Safari, Opera, Vivaldi, Brave
Node.js: 16.x, 17.x, 18.x
Deno: 1.x

Warnings and Restrictions

Although this library has been passed the following test vectors, it has not been formally audited.
- RFC9180 official test vectors provided on github.com/cfrg/draft-irtf-cfrg-hpke
- ECDH/X25519/X449 test vectors provided on Project Wycheproof
The upper limit of the AEAD sequence number is further rounded to JavaScript's MAX_SAFE_INTEGER (2^53-1).

Installation

Using unpkg CDN:

<!-- use the latest stable version -->
<script type="module">
  import * as hpke from "https://unpkg.com/hpke-js/esm/mod.js";
  // ...
</script>

<!-- use a specific version -->
<script type="module">
  import * as hpke from "https://unpkg.com/hpke-js@0.11.0/esm/mod.js";
  // ...
</script>

Using jsDelivr CDN:

<!-- use the latest stable version -->
<script type="module">
  import * as hpke from "https://cdn.jsdelivr.net/npm/hpke-js/esm/mod.js";
  // ...
</script>

<!-- use a specific version -->
<script type="module">
  import * as hpke from "https://cdn.jsdelivr.net/npm/hpke-js@0.11.0/esm/mod.js";
  // ...
</script>

Using npm:

npm install hpke-js

Using yarn:

yarn add hpke-js

Using deno.land:

import * as hpke from "https://deno.land/x/hpke@v0.11.0/mod.ts";

Usage

This section shows some typical usage examples.

Base mode

Browsers:

<html>
  <head></head>
  <body>
    <script type="module">
      // import * as hpke from "https://cdn.jsdelivr.net/npm/hpke-js/esm/mod.js";
      import { Kem, Kdf, Aead, CipherSuite } from "https://cdn.jsdelivr.net/npm/hpke-js/esm/mod.js";

      globalThis.doHpke = async () => {

        const suite = new CipherSuite({
          kem: Kem.DhkemP256HkdfSha256,
          kdf: Kdf.HkdfSha256,
          aead: Aead.Aes128Gcm
        });
 
        const rkp = await suite.generateKeyPair();
      
        const sender = await suite.createSenderContext({
          recipientPublicKey: rkp.publicKey
        });
      
        const recipient = await suite.createRecipientContext({
          recipientKey: rkp,
          enc: sender.enc,
        });
      
        // encrypt
        const ct = await sender.seal(new TextEncoder().encode('hello world!'));
      
        // decrypt
        const pt = await recipient.open(ct);

        // hello world!
        alert(new TextDecoder().decode(pt));
      }
      
    </script>
    <button type="button" onclick="doHpke()">do HPKE</button>
  </body>
</html>

Node.js:

const { Kem, Kdf, Aead, CipherSuite } = require("hpke-js");

async function doHpke() {
  // setup
  const suite = new CipherSuite({
    kem: Kem.DhkemP256HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.Aes128Gcm,
  });

  const rkp = await suite.generateKeyPair();

  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
  });

  const recipient = await suite.createRecipientContext({
    recipientKey: rkp,
    enc: sender.enc,
  });

  // encrypt
  const ct = await sender.seal(new TextEncoder().encode("my-secret-message"));

  // decrypt
  const pt = await recipient.open(ct);

  console.log("decrypted: ", new TextDecoder().decode(pt));
  // decrypted: my-secret-message
}

doHpke();

Deno:

import { Kem, Kdf, Aead, CipherSuite } from "https://deno.land/x/hpke@v0.11.0/mod.ts";

async function doHpke() {
  // setup
  const suite = new CipherSuite({
    kem: Kem.DhkemX25519HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.Aes128Gcm,
  });

  const rkp = await suite.generateKeyPair();

  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
  });

  const recipient = await suite.createRecipientContext({
    recipientKey: rkp,
    enc: sender.enc,
  });

  // encrypt
  const ct = await sender.seal(new TextEncoder().encode("my-secret-message"));

  // decrypt
  const pt = await recipient.open(ct);

  console.log("decrypted: ", new TextDecoder().decode(pt));
  // decrypted: my-secret-message
}

doHpke();

Base mode with Single-Shot APIs

Node.js:

const { Kem, Kdf, Aead, CipherSuite } = require('hpke-js');

async function doHpke() {

  // setup
  const suite = new CipherSuite({
    kem: Kem.DhkemP256HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.Aes128Gcm
  });

  const rkp = await suite.generateKeyPair();
  const pt = new TextEncoder().encode('my-secret-message'),

  // encrypt
  const { ct, enc } = await suite.seal({ recipientPublicKey: rkp.publicKey }, pt);

  // decrypt
  const pt = await suite.open({ recipientKey: rkp, enc: enc }, ct);

  console.log('decrypted: ', new TextDecoder().decode(pt));
  // decrypted: my-secret-message
}

doHpke();

Base mode with bidirectional encryption

Node.js:

const { Kem, Kdf, Aead, CipherSuite } = require("hpke-js");

const te = new TextEncoder();
const td = new TextDecoder();

async function doHpke() {
  // setup
  const suite = new CipherSuite({
    kem: Kem.DhkemP256HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.Aes128Gcm,
  });
  const rkp = await suite.generateKeyPair();

  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
  });

  const recipient = await suite.createRecipientContext({
    recipientKey: rkp,
    enc: sender.enc,
  });

  // setup bidirectional encryption
  await sender.setupBidirectional(
    te.encode("seed-for-key"),
    te.encode("seed-for-nonce"),
  );
  await recipient.setupBidirectional(
    te.encode("seed-for-key"),
    te.encode("seed-for-nonce"),
  );

  // encrypt
  const ct = await sender.seal(te.encode("my-secret-message-s"));

  // decrypt
  const pt = await recipient.open(ct);

  console.log("recipient decrypted: ", td.decode(pt));
  // decrypted: my-secret-message-s

  // encrypt reversely
  const rct = await recipient.seal(te.encode("my-secret-message-r"));

  // decrypt reversely
  const rpt = await sender.open(rct);

  console.log("sender decrypted: ", td.decode(rpt));
  // decrypted: my-secret-message-r
}

doHpke();

Base mode with export-only AEAD

Node.js:

  const suite = new CipherSuite({
    kem: Kem.DhkemP256HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.ExportOnly,
  });

  const rkp = await suite.generateKeyPair();

  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
  });

  const recipient = await suite.createRecipientContext({
    recipientKey: rkp,
    enc: sender.enc,
  });

  const te = new TextEncoder();

  // export
  const pskS = sender.export(te.encode('jugemujugemu'), 32);
  const pskR = recipient.export(te.encode('jugemujugemu'), 32);
  // pskR === pskS
}

doHpke();

PSK mode

Node.js:

const { Kem, Kdf, Aead, CipherSuite } = require("hpke-js");

async function doHpke() {
  // setup
  const suite = new CipherSuite({
    kem: Kem.DhkemP256HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.Aes128Gcm,
  });

  const rkp = await suite.generateKeyPair();

  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
    psk: {
      id: new TextEncoder().encode("our-pre-shared-key-id"),
      // a PSK MUST have at least 32 bytes.
      key: new TextEncoder().encode("jugemujugemugokounosurikirekaija"),
    },
  });

  const recipient = await suite.createRecipientContext({
    recipientKey: rkp,
    enc: sender.enc,
    psk: {
      id: new TextEncoder().encode("our-pre-shared-key-id"),
      // a PSK MUST have at least 32 bytes.
      key: new TextEncoder().encode("jugemujugemugokounosurikirekaija"),
    },
  });

  // encrypt
  const ct = await sender.seal(new TextEncoder().encode("my-secret-message"));

  // decrypt
  const pt = await recipient.open(ct);

  console.log("decrypted: ", new TextDecoder().decode(pt));
  // decrypted: my-secret-message
}

doHpke();

Auth mode

Node.js:

const { Kem, Kdf, Aead, CipherSuite } = require("hpke-js");

async function doHpke() {
  // setup
  const suite = new CipherSuite({
    kem: Kem.DhkemP256HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.Aes128Gcm,
  });

  const rkp = await suite.generateKeyPair();
  const skp = await suite.generateKeyPair();

  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
    senderKey: skp,
  });

  const recipient = await suite.createRecipientContext({
    recipientKey: rkp,
    enc: sender.enc,
    senderPublicKey: skp.publicKey,
  });

  // encrypt
  const ct = await sender.seal(new TextEncoder().encode("my-secret-message"));

  // decrypt
  const pt = await recipient.open(ct);

  console.log("decrypted: ", new TextDecoder().decode(pt));
  // decrypted: my-secret-message
}

doHpke();

AuthPSK mode

Node.js:

const { Kem, Kdf, Aead, CipherSuite } = require("hpke-js");

async function doHpke() {
  // setup
  const suite = new CipherSuite({
    kem: Kem.DhkemP256HkdfSha256,
    kdf: Kdf.HkdfSha256,
    aead: Aead.Aes128Gcm,
  });

  const rkp = await suite.generateKeyPair();
  const skp = await suite.generateKeyPair();

  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
    senderKey: skp,
    psk: {
      id: new TextEncoder().encode("our-pre-shared-key-id"),
      // a PSK MUST have at least 32 bytes.
      key: new TextEncoder().encode("jugemujugemugokounosurikirekaija"),
    },
  });

  const recipient = await suite.createRecipientContext({
    recipientKey: rkp,
    enc: sender.enc,
    senderPublicKey: skp.publicKey,
    psk: {
      id: new TextEncoder().encode("our-pre-shared-key-id"),
      // a PSK MUST have at least 32 bytes.
      key: new TextEncoder().encode("jugemujugemugokounosurikirekaija"),
    },
  });

  // encrypt
  const ct = await sender.seal(new TextEncoder().encode("my-secret-message"));

  // decrypt
  const pt = await recipient.open(ct);

  console.log("decrypted: ", new TextDecoder().decode(pt));
  // decrypted: my-secret-message
}

doHpke();

Contributing

We welcome all kind of contributions, filing issues, suggesting new features or sending PRs.

References

Keywords

FAQs

What is hpke-js?

Is hpke-js well maintained?

Package last updated on 05 Jun 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

hpke-js

hpke-js

Index

Supported Features

HPKE Modes

Key Encapsulation Machanisms (KEMs)

Key Derivation Functions (KDFs)

Authenticated Encryption with Associated Data (AEAD) Functions

Supported Environments

Warnings and Restrictions

Installation

Usage

Base mode

Base mode with Single-Shot APIs

Base mode with bidirectional encryption

Base mode with export-only AEAD

PSK mode

Auth mode

AuthPSK mode

Contributing

References

Keywords

Related posts

Massive npm Malware Campaign Leverages Ethereum Smart Contracts To Evade Detection and Maintain Control

Author Typosquatting on npm: Attackers Impersonate Sindre Sorhus with Malicious ‘chalk-node’ Package