Racket

Web Push🔗ℹ

This library provides implementations of RFC 8188 and RFC 8291.

1 Reference🔗ℹ

1.1 Encrypted Content-Encoding for HTTP🔗ℹ

procedure
(http-ece-decrypt in
out
secret
[ #:factories factories]) → void?
  in : input-port?
  out : output-port?
  secret : (or/c bytes? (-> bytes? bytes?))
   factories : (or/c crypto-factory? (listof crypto-factory?))
= (crypto-factories)

Decrypts the contents of in to out using secret and the provided factories. When secret is a procedure, it receives the key id read from the input header. It must then provide a secret based on that key id.

procedure
(http-ece-encrypt in
out
secret
[ #:salt salt
#:key-id key-id
#:record-size record-size
#:factories factories]) → void?
  in : input-port?
  out : input-port?
  secret : bytes?
  salt : bytes? = (crypto-random-bytes 16)
  key-id : bytes? = #""
  record-size : (integer-in 18 (sub1 (expt 2 31))) = 4096
   factories : (or/c crypto-factory? (listof crypto-factory?))
= (crypto-factories)

Encrypts the contents of in and writes the output to out using secret and the provided factories. The content is split into #:record-size chunks. The #:key-id argument can be used to signal to the recipient what key they should use to decrypt the data. The key id may be at most 255 bytes long.

1.2 Message Encryption for Web Push🔗ℹ

(require crypto/web-push)

package: web-push-lib

procedure
(web-push-decrypt in
out
#:auth-secret auth-secret
#:private-key ua-private
[ #:factories factores]) → void?
  in : input-port?
  out : output-port?
  auth-secret : bytes?
  ua-private : pk-key?
   factores : (or/c crypto-factory? (listof crypto-factory?))
= (crypto-factories)

Decrypts the contents of in and writes the output to out after exchanging the ua-private key with the as-private key located in the keyid field in the HTTP ECE header of in, using auth-secret as a salt.

procedure
(web-push-encrypt in
out
[ #:salt salt]
#:auth-secret auth-secret
[ #:private-key as-private]
#:user-agent-key ua-public
[ #:factories factories]) → void?
  in : input-port?
  out : output-port?
  salt : bytes? = (crypto-random-bytes 16)
  auth-secret : bytes?
  as-private : pk-key? = (generate-ecdh-private-key)
  ua-public : bytes?
   factories : (or/c crypto-factory? (listof crypto-factory?))
= (crypto-factories)

Encrypts the contents of in and writes the output to out after exchanging the as-private and ua-public keys, using auth-secret as a salt. When #:private-key is not provided, a key is generated automatically on every invocation. This is the normal use case. Do not reuse keys outside of testing scenarios.

1.3 Voluntary Application Server Identification (VAPID) for Web Push🔗ℹ

(require crypto/vapid)

package: web-push-lib

procedure
(generate-ecdh-private-key [factories]) → pk-key?
factories : (or/c crypto-factory? (listof crypto-factory?))
= (crypto-factories)

Generates an ECDH private key over the P-256 curve using factories for use in VAPID.

procedure
(pk->vapid-key-data pk) →
bytes? bytes?
pk : pk-key?

Returns a pair of bytes? values representing the public and private key components of pk, respectively. The pk argument must be a key in ECDH format over the P-256 curve (eg. one generated by generate-ecdh-private-key).

The public key value can be converted to urlsafe base64 and shared.

procedure
(vapid-key-data->pk public-bs private-bs) → pk-key?
public-bs : bytes?
private-bs : bytes?

Returns the ECDH private key represented by public-bs and private-bs.

procedure
(make-vapid-token pk
url
[ #:aud audience
#:exp expiry]
#:sub subject) → string?
  pk : pk-key?
  url : url?
  audience : string? = (url->audience url)
  expiry : integer? = (+ (current-seconds) 3600)
  subject : string?

Encodes audience, expiry and subject into a JWT for use with VAPID and signs the headers and payload using pk.