From 510a3a66e5e7d005eb1f30a3fec2ca54c679ec24 Mon Sep 17 00:00:00 2001
From: Michael <sp1ff@pobox.com>
Date: Fri, 14 Feb 2025 07:50:17 -0800
Subject: [PATCH] argon2: add a peppering example to the docs (#559)

---
 argon2/src/lib.rs | 52 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/argon2/src/lib.rs b/argon2/src/lib.rs
index 82301173..b3e8468d 100644
--- a/argon2/src/lib.rs
+++ b/argon2/src/lib.rs
@@ -64,6 +64,58 @@
 //! # }
 //! ```
 //!
+//! To [pepper] as well as salt your passwords:
+//!
+//! [pepper]: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#peppering
+//!
+#![cfg_attr(all(feature = "password-hash", feature = "std"), doc = "```")]
+#![cfg_attr(
+    not(all(feature = "password-hash", feature = "std")),
+    doc = "```ignore"
+)]
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! use argon2::{
+//!     password_hash::{
+//!         // `OsRng` requires enabled `std` crate feature
+//!         rand_core::OsRng,
+//!         PasswordHash, PasswordHasher, PasswordVerifier, SaltString
+//!     },
+//!     Algorithm, Argon2, Params, Version
+//! };
+//!
+//! let password = b"hunter42"; // Bad password; don't actually use!
+//! let salt = SaltString::generate(&mut OsRng);
+//!
+//! // Argon2 with default params (Argon2id v19) and pepper
+//! let argon2 = Argon2::new_with_secret(
+//!     b"secret pepper",
+//!     Algorithm::default(),
+//!     Version::default(),
+//!     Params::default()
+//! )
+//! .unwrap();
+//!
+//! // Hash password to PHC string ($argon2id$v=19$...)
+//! let password_hash = argon2.hash_password(password, &salt)?.to_string();
+//!
+//! // Verify password against PHC string.
+//! //
+//! // NOTE: hash params from `parsed_hash` are used instead of what is configured in the
+//! // `Argon2` instance.
+//! let parsed_hash = PasswordHash::new(&password_hash)?;
+//! let argon2 = Argon2::new_with_secret(
+//!     b"secret pepper",
+//!     Algorithm::default(),
+//!     Version::default(),
+//!     Params::default(),
+//! )
+//! .unwrap();
+//! let res = argon2.verify_password(password, &parsed_hash);
+//! assert!(res.is_ok());
+//! # Ok(())
+//! # }
+//! ```
+//!
 //! ### Key Derivation
 //!
 //! This API is useful for transforming a password into cryptographic keys for