The underlying library uses the following OPAQUE configuration, based on the recommendations of the OPAQUE draft:
OPRF: ristretto255-SHA512
KDF: HKDF-SHA-512
MAC: HMAC-SHA-512
Hash: SHA-512
Group: ristretto255
Make sure to match this configuration in your clients, otherwise the protocol will not be able to execute. For
browser clients, we recommend @squirrelchat/opaque-wasm-client.
Totally unbiased recommendation, of course :whistle:
Once registered, you have the OPAQUE server instance accessible via fastify.opaque. However, you shouldn't need to
use it as more convenient methods are added to the FastifyRequest object.
These methods will handle temporary state holding for you (by forwarding the work to @fastify/session, itself capable
of dealing with scaled environments by using a Redis-backed store for example).
The examples below are absolutely NOT production ready. They show off the API of the plugin, but lack error handling.
Every call to *Opaque* should be wrapped in a try/catch block, body should be validated (at least make sure it's
an array of numbers, the rest will be handled by the lib)!
fastify.post('/auth/register/init', (request, reply) => { const reqBytes = new Uint8Array(request.body.request) const resBytes = request.startOpaqueRegistration(request.body.username, reqBytes) return { response: Array.from(resBytes) }})fastify.post('/auth/register/finalize', (request, reply) => { const recordBytes = new Uint8Array(request.body.record) const credentials = request.finishOpaqueRegistration() // store credentials to database reply.code(204).send()})fastify.
Configuring state
The state holds the salt and the keypair used by the server. This keypair must not change, and must be the same across
all instances if you have multiple instances of your app. There are 3 ways of providing the state to the plugin: using
a static one, using a provider, or pointing to a file.
With a static state, you are responsible for loading/saving the state.
const state = loadState()fastify.register(import('fastify-opaque-apake'), { state: state }) .after() .then(() => saveState(fastify.opaque.getState()))
With a provider, the library uses functions you've provided to load/save the state. Your functions can return promises
and the library will await them accordingly.
When pointing to a file, the plugin will read/write the file by itself. Please note that the OPAQUE keys are extremely
sensitive, and storing them to a file isn't the best for security.
In case you need to handle the OPAQUE state in a specific way, and don't want to register a session plugin for this
reason, you can use fastify-opaque-apake/core.
When registered like this, you only get the fastify.opaque decorator. The helpers on FastifyRequest are not
registered, and you must handle the state management by yourself during login.