End-to-end encryption client

Simple wrapper for the Web Crypto API to encrypt and decrypt text.

It can create a derived key (256 bits AES-GCM) from a public and private key, using an Elliptic Curve Diffie-Hellman key exchange. This key can then be used to encrypt and decrypt text.

It does not contain any logic to generate the public and private keys. Typically, you would want to do that in your backend and send the public key to the client. See the key generation example for a simple example using PHP.

Use cases

One-to-one communication

• Key exchange
  • Generate a public and private key pair on the server for both participants
    • If generated server-side; send each participant their own private key
  • Send the public key of participant A to participant B and vice versa
  • Participant A generates a derived key from his private key and the public key of participant B
  • Participant B generates a derived key from his private key and the public key of participant A
• Message exchange
  • Participant A encrypts a message with the derived key and sends it to participant B
  • Participant B decrypts the message with the derived key
  • Participant B encrypts a message with the derived key and sends it to participant A
  • Participant A decrypts the message with the derived key
• Done!

Group communication

• Key exchange
  • Generate a public and private key pair on the server for each participant
    • If generated server-side; send each participant their own public and private key
  • Generate a public and private key pair on the server for the group
  • Send each participant the group's public and private key
    • Recommended: Encrypt the private key for the group with the public key of each participant before sending it to them. They'll need to decrypt it with their private key before they can use it.
  • Each participant generates a derived key from the group's public and private key
• Message exchange
  • Each participant encrypts a message with the derived key and sends it to the backend, to be received by all other participants
  • Each participant decrypts the message with the derived key
• Done!

Installation

• Run npm i @endeavour/end-to-end-encryption-client
• Import the modules in your code:

import { CryptoKeyService, EndToEndEncryptionClient } from '@endeavour/end-to-end-encryption-client'

Documentation

CryptoKeyService

• A service for key management
• Sample usage:

const cryptoKeyService = new CryptoKeyService()

CryptoKeyService.importPemEncodedPrivateKey(privateKeyData: string): Promise<CryptoKey>

• Imports a PEM encoded private key
• Returns a promise that resolves to a CryptoKey
• Sample usage:

const myPrivateKeyData = `-----BEGIN PRIVATE KEY-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-----END PRIVATE KEY-----`
const myPrivateKey = await cryptoKeyService.importPemEncodedPrivateKey(myPrivateKeyData)

CryptoKeyService.importPemEncodedPublicKey(publicKeyData: string): Promise<CryptoKey>

• Imports a PEM encoded public key
• Returns a promise that resolves to a CryptoKey
• Sample usage:

const myPublicKeyData = `-----BEGIN PUBLIC KEY-----
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-----END PUBLIC KEY-----`
const myPublicKey = await cryptoKeyService.importPemEncodedPublicKey(myPublicKeyData)

CryptoKeyService.deriveKey(publicKey: CryptoKey, privateKey: CryptoKey): Promise<CryptoKey>

• Creates a derived key from a public and private key
• Sample usage:

const myEncryptionKey = await cryptoKeyService.deriveKey(myPublicKey, myPrivateKey)

EndToEndEncryptionClient

Used to encrypt and decrypt text

EndToEndEncryptionClient.encrypt(plaintextMessage: string, key: CryptoKey): Promise<string>

• Encrypts a message with a key
• Returns a promise that resolves to a base64 encoded string
• Sample usage:

const encryptedMessage = await endToEndEncryptionClient.encrypt(myEncryptionKey, 'Hello world!')

EndToEndEncryptionClient.decrypt(encryptedMessage: string, key: CryptoKey): Promise<string>

• Decrypts an encrypted message with a key
• Returns a promise that resolves to a string
• Sample usage:

const decryptedMessage = await endToEndEncryptionClient.decrypt(myEncryptionKey, encryptedMessage)

Examples

• See examples folder