-
Notifications
You must be signed in to change notification settings - Fork 47
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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]>
- Loading branch information
Showing
4 changed files
with
136 additions
and
27 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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` | ||
|
|
||