From 5b73ac77989523e8e40013d8c9aedde6122ab1d3 Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Wed, 4 Jan 2023 13:29:01 -0700
Subject: [PATCH] argon2: add key derivation usage example

---
 .readme/Cargo.lock | 16 ++++++++--------
 argon2/src/lib.rs  | 41 +++++++++++++++++++++++++----------------
 2 files changed, 33 insertions(+), 24 deletions(-)

diff --git a/.readme/Cargo.lock b/.readme/Cargo.lock
index b06a1a99..0c202a7f 100644
--- a/.readme/Cargo.lock
+++ b/.readme/Cargo.lock
@@ -19,9 +19,9 @@ checksum = "b645a089122eccb6111b4f81cbc1a49f5900ac4666bb93ac027feaecf15607bf"
 
 [[package]]
 name = "blake2"
-version = "0.10.5"
+version = "0.10.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b12e5fd123190ce1c2e559308a94c9bacad77907d4c6005d9e58fe1a0689e55e"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
 dependencies = [
  "digest",
 ]
@@ -72,9 +72,9 @@ dependencies = [
 
 [[package]]
 name = "digest"
-version = "0.10.5"
+version = "0.10.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "adfbc57365a37acbd2ebf2b64d7e69bb766e2fea813521ed536f5d0520dcf86c"
+checksum = "8168378f4e5023e7218c89c891c0fd8ecdb5e5e4f18cb78f38cf245dd021e76f"
 dependencies = [
  "block-buffer",
  "crypto-common",
@@ -122,9 +122,9 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.137"
+version = "0.2.139"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc7fcc620a3bff7cdd7a365be3376c97191aeaccc2a603e600951e452615bf89"
+checksum = "201de327520df007757c1f0adce6e827fe8562fbc28bfd9c15571c66ca1f5f79"
 
 [[package]]
 name = "password-hash"
@@ -204,9 +204,9 @@ checksum = "6bdef32e8150c2a081110b42772ffe7d7c9032b606bc226c8260fd97e0976601"
 
 [[package]]
 name = "typenum"
-version = "1.15.0"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dcf81ac59edc17cc8697ff311e8f5ef2d99fcbd9817b34cec66f90b6c3dfd987"
+checksum = "497961ef93d974e23eb6f433eb5fe1b7930b659f06d12dec6fc44a8f554c0bba"
 
 [[package]]
 name = "version_check"
diff --git a/argon2/src/lib.rs b/argon2/src/lib.rs
index 1fb310a3..be74e2bc 100644
--- a/argon2/src/lib.rs
+++ b/argon2/src/lib.rs
@@ -22,26 +22,17 @@
     unused_qualifications
 )]
 
-//! ## Usage (simple with default params)
+//! ## Usage
 //!
-//! Note: this example requires the `rand_core` crate with the `std` feature
-//! enabled for `rand_core::OsRng` (embedded platforms can substitute their
-//! own RNG)
+//! ### Password Hashing
 //!
-//! Add the following to your crate's `Cargo.toml` to import it:
+//! This API hashes a password to a "PHC string" suitable for the purposes of
+//! password-based authentication. Do not use this API to derive cryptographic
+//! keys: see the "key derivation" usage example below.
 //!
-//! ```toml
-//! [dependencies]
-//! argon2 = "0.4"
-//! rand_core = { version = "0.6", features = ["std"] }
-//! ```
-//!
-//! The following example demonstrates the high-level password hashing API:
-//!
-//! ```
+#![cfg_attr(feature = "std", doc = "```")]
+#![cfg_attr(not(feature = "std"), doc = "```ignore")]
 //! # fn main() -> Result<(), Box<dyn std::error::Error>> {
-//! # #[cfg(all(feature = "password-hash", feature = "std"))]
-//! # {
 //! use argon2::{
 //!     password_hash::{
 //!         rand_core::OsRng,
@@ -65,7 +56,25 @@
 //! // `Argon2` instance.
 //! let parsed_hash = PasswordHash::new(&password_hash)?;
 //! assert!(Argon2::default().verify_password(password, &parsed_hash).is_ok());
+//! # Ok(())
 //! # }
+//! ```
+//!
+//! ### Key Derivation
+//!
+//! This API is useful for transforming a password into cryptographic keys for
+//! e.g. password-based encryption.
+//!
+#![cfg_attr(feature = "std", doc = "```")]
+#![cfg_attr(not(feature = "std"), doc = "```ignore")]
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! use argon2::Argon2;
+//!
+//! let password = b"hunter42"; // Bad password; don't actually use!
+//! let salt = b"example salt"; // Salt should be unique per password
+//!
+//! let mut output_key_material = [0u8; 32]; // Can be any desired size
+//! Argon2::default().hash_password_into(password, salt, &mut output_key_material)?;
 //! # Ok(())
 //! # }
 //! ```