diff --git a/README.md b/README.md index 576b2ad..836836e 100644 --- a/README.md +++ b/README.md @@ -225,6 +225,93 @@ pnpm example:client-with-password-reset:dev ## Advanced usage +### Key Stretching Function Config + +The password input is passed through a key stretching function before being used in the OPRF. The key stretching function is [`argon2id`](https://www.rfc-editor.org/rfc/rfc9106.html). The [OPAQUE protocol](https://www.ietf.org/archive/id/draft-irtf-cfrg-opaque-17.html) defines recommended parameters, but depending on the application these parameters can be adjusted using param `keyStretchingFunctionConfig` in the `opaque.client.startRegistration` and `opaque.client.startLogin` functions. + +Available options are: + +#### Recommended (default) + +This is the default in case the option is omitted. It is based on the recommendation in the [Configurations section in the OPAQUE protocol](https://www.ietf.org/archive/id/draft-irtf-cfrg-opaque-17.html#name-configurations) with the exception that the memory is set to (2^21)-1 instead of (2^21) since we noticed (2^21) caused it to crash when running the registration in a browser environment. + +Parameters: + +- Memory: 2^21-1 +- Iterations: 1 +- Parallelism: 4 + +```ts +{ + keyStretchingFunctionConfig: "recommended"; +} +``` + +**Note**: The recommended configuration is the most secure but also the slowest. `client.finishRegistration` and `client.finishLogin` each take around 13 seconds to complete on a MacBook Pro M1, 2020, 16 GB Memory. + +#### Memory constrained + +This option is based on the recommendation for memory-constrained environments in the [Argon2 RFC](https://www.rfc-editor.org/rfc/rfc9106.html#name-recommendations). + +Parameters: + +- Memory: 2^16 +- Iterations: 3 +- Parallelism: 1 + +```ts +{ + keyStretchingFunctionConfig: "memory-constrained"; +} +``` + +**Note**: This configuration is faster, but less secure. `client.finishRegistration` and `client.finishLogin` each take around 1 seconds to complete on a MacBook Pro M1, 2020, 16 GB Memory. + +#### Custom + +You can also provide custom parameters for the key stretching function. The parameters are passed directly to the `argon2id` function. In case you provide an invalid configuration, the function will throw an error. + +```ts +const memory = 65536; +const iterations = 3; +const parallelism = 1; +{ + keyStretchingFunctionConfig: { + "argon2id-custom": { + memory, + iterations, + parallelism, + }, + }; +} +``` + +#### Example usage + +**Registration** + +```ts +// client +opaque.client.finishRegistration({ + clientRegistrationState, + registrationResponse, + password, + keyStretchingFunctionConfig: "memory-constrained", +}); +``` + +**Login** + +```ts +// client +opaque.client.finishLogin({ + clientLoginState, + loginResponse, + password, + keyStretchingFunctionConfig: "memory-constrained", +}); +``` + ### ExportKey After the initial registration flow as well as ever login flow, the client has access to a private key only available to the client. This is the `exportKey`. The key is not available to the server and it is stable. Meaning if you log in multiple times your `exportKey` will stay the same.