Argon2 Example (#282)

* add argon2 example to simple_login.rs

* rename Default to DefaultCipherSuite in examples to avoid conflicts with core::default::Default

* put the custom KSF example in the documentation

* add links in documentation

Co-authored-by: daxpedda <[email protected]>

* remove no_run on argon2 doctest

* hide argon2 cfg attribute in docs

Co-authored-by: daxpedda <[email protected]>

Co-authored-by: daxpedda <[email protected]>

src/lib.rs

@@ -986,6 +986,103 @@
 //! let server_setup = ServerSetup::<Default, YourRemoteKey>::new_with_key(&mut OsRng, keypair);
 //! ```
 //!
+//! ## Custom KSF and Parameters
+//!
+//! An application might want to use a custom KSF (Key Stretching Function)
+//! that's not supported directly by this crate. The maintainer of the said KSF
+//! or of the application itself can implement the [`Ksf`](ksf::Ksf) trait to
+//! use it with `opaque-ke`. `scrypt` is used for this example, but any KSF
+//! can be used.
+//! ```
+//! # use generic_array::GenericArray;
+//! #[derive(Default)]
+//! struct CustomKsf(scrypt::Params);
+//!
+//! // The Ksf trait must be implemented to be used in the ciphersuite.
+//! impl opaque_ke::ksf::Ksf for CustomKsf {
+//!     fn hash<L: generic_array::ArrayLength<u8>>(
+//!         &self,
+//!         input: GenericArray<u8, L>,
+//!     ) -> Result<GenericArray<u8, L>, opaque_ke::errors::InternalError> {
+//!         let mut output = GenericArray::<u8, L>::default();
+//!         scrypt::scrypt(&input, &[], &self.0, &mut output)
+//!             .map_err(|_| opaque_ke::errors::InternalError::KsfError)?;
+//!
+//!         Ok(output)
+//!     }
+//! }
+//! ```
+//!
+//! It is also possible to override the default derivation parameters that are
+//! used by the KSF during registration and login. This can be especially
+//! helpful if the `Ksf` trait is already implemented.
+//! ```
+//! # use opaque_ke::CipherSuite;
+//! # use opaque_ke::ClientRegistration;
+//! # use opaque_ke::ClientRegistrationFinishParameters;
+//! # use opaque_ke::ServerSetup;
+//! # use opaque_ke::errors::ProtocolError;
+//! # use rand::rngs::OsRng;
+//! # use rand::RngCore;
+//! # use std::default::Default;
+//! # #[cfg(feature = "argon2")]
+//! # {
+//! # struct DefaultCipherSuite;
+//! # #[cfg(feature = "ristretto255")]
+//! # impl CipherSuite for DefaultCipherSuite {
+//! #     type OprfCs = opaque_ke::Ristretto255;
+//! #     type KeGroup = opaque_ke::Ristretto255;
+//! #     type KeyExchange = opaque_ke::key_exchange::tripledh::TripleDh;
+//! #     type Ksf = argon2::Argon2<'static>;
+//! # }
+//! # #[cfg(not(feature = "ristretto255"))]
+//! # impl CipherSuite for DefaultCipherSuite {
+//! #     type OprfCs = p256::NistP256;
+//! #     type KeGroup = p256::NistP256;
+//! #     type KeyExchange = opaque_ke::key_exchange::tripledh::TripleDh;
+//! #     type Ksf = argon2::Argon2<'static>;
+//! # }
+//! #
+//! # let password = b"password";
+//! # let mut rng = OsRng;
+//! # let server_setup = ServerSetup::<DefaultCipherSuite>::new(&mut rng);
+//! # let mut client_rng = OsRng;
+//! # let client_registration_start_result =
+//! #     ClientRegistration::<DefaultCipherSuite>::start(&mut client_rng, password)?;
+//! # use opaque_ke::ServerRegistration;
+//! # let server_registration_start_result = ServerRegistration::<DefaultCipherSuite>::start(
+//! #     &server_setup,
+//! #     client_registration_start_result.message,
+//! #     b"[email protected]",
+//! # )?;
+//! #
+//! // Create an Argon2 instance with the specified parameters
+//! let argon2_params = argon2::Params::new(131072, 2, 4, None).unwrap();
+//! let argon2_params = argon2::Argon2::new(
+//!     argon2::Algorithm::Argon2id,
+//!     argon2::Version::V0x13,
+//!     argon2_params,
+//! );
+//!
+//! // Override the default parameters with the custom ones
+//! let hash_params = ClientRegistrationFinishParameters {
+//!     ksf: Some(&argon2_params),
+//!     ..Default::default()
+//! };
+//!
+//! let client_registration_finish_result = client_registration_start_result
+//!     .state
+//!     .finish(
+//!         &mut rng,
+//!         password,
+//!         server_registration_start_result.message,
+//!         hash_params,
+//!     )
+//!     .unwrap();
+//! # }
+//! # Ok::<(), ProtocolError>(())
+//! ```
+//!
 //! # Features
 //!
 //! - The `argon2` feature, when enabled, introduces a dependency on `argon2`