add ksf config docs

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.