Skip to content

README.md

Latest commit

 

History

History
65 lines (39 loc) · 4.25 KB

README.md

File metadata and controls

65 lines (39 loc) · 4.25 KB
Raw

pg-manual: PostGuard low-level WASM example

Browser example that drives PostGuard encryption and decryption directly through the low-level @e4a/pg-wasm library. Where pg-sveltekit and pg-node use the high-level @e4a/pg-js SDK, pg-manual calls seal, Unsealer, sealStream, and StreamUnsealer itself and builds the policies, signing requests, and key fetches by hand. It is the only sub-project that talks to the WASM module and the PKG directly, so it is the one to read when you need policy-level control that the SDK does not expose.

What it demonstrates

Two entry points, each a separate page:

Page Source What it does
string.html examples/string.js Encrypts a text field in memory with seal, then decrypts it back with Unsealer.
file.html examples/file.js Encrypts and decrypts a file as a stream with sealStream / StreamUnsealer, writing the result to disk via streamsaver.

Both flows sign the ciphertext with a public policy (visible to everyone) and a private policy (visible only to recipients), encrypt for a recipient identified by an email attribute, and then fetch a user decryption key to read it back.

How the key flow works

The example talks to a PostGuard Key Generator (PKG) and uses Yivi for authentication:

  1. The master public key and signing verification key are fetched from the PKG (/v2/parameters and /v2/sign/parameters).
  2. Retrieving a signing or decryption key starts a Yivi session. A popup appears with a QR code, and you disclose the requested attributes with the Yivi app on your phone.
  3. The PKG returns the key once the disclosure is valid, and the WASM module seals or unseals the payload.

The session and key-request shapes live in examples/utils.js. That file also holds the PKG_URL constant that every fetch derives from.

IRMA demo credentials

The example uses IRMA demo credentials, so no real personal data is involved. The policies reference demo attributes:

  • irma-demo.sidn-pbdf.email.email for the recipient (bob@example.com)
  • irma-demo.gemeente.personalData.fullname and irma-demo.gemeente.personalData.bsn for the sender's signature

Before running, load these demo credentials into your Yivi app. Anyone can issue an instance with custom data from the attribute index:

Because these are demo credentials, the Yivi popup issues them on the spot if you do not already hold them.

Prerequisites

  • Node.js and a browser.
  • The Yivi app on your phone, with the demo credentials above.

Run

cd pg-manual
npm install
npm run dev

Webpack Dev Server serves the example at http://localhost:9000. The landing page links to string.html and file.html. Open one, encrypt, and follow the Yivi popup to fetch the key needed to decrypt.

Configuration

PKG_URL in examples/utils.js selects the PKG deployment. It currently points at the legacy Radboud iHub deployment (https://main.postguard.ihub.ru.nl/pkg) rather than the modern staging host used by the other sub-projects (see issue #54). Change that one constant to target a different PKG; the encryption, signing, and key-fetch calls all derive from it.

When to use pg-manual

Reach for @e4a/pg-wasm directly when you need control the @e4a/pg-js SDK does not surface, such as custom policy construction, separate public and private signing policies, or direct access to the unsealer header. For most integrations the SDK used by pg-sveltekit and pg-node is the simpler starting point.

License

MIT