password-auth: improve documentation (#419)

password-auth/Cargo.toml

@@ -30,3 +30,7 @@ std = []
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 getrandom = { version = "0.2", features = ["js"] }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

password-auth/README.md

@@ -1,4 +1,4 @@
-# RustCrypto: Password Authentication
+# [RustCrypto]: Password Authentication
 
 [![crate][crate-image]][crate-link]
 [![Docs][docs-image]][docs-link]
@@ -12,6 +12,26 @@ with support for [Argon2], [PBKDF2], and [scrypt] password hashing algorithms.
 
 [Documentation][docs-link]
 
+## About
+
+`password-auth` is a high-level password authentication library with a simple
+API which eliminates as much complexity and user choice as possible. It only
+has two functions:
+
+- [`generate_hash`]: generates a password hash from the provided password. The
+- [`verify_password`]: verifies the provided password against a password hash,
+  returning an error if the password is incorrect.
+
+Behind the scenes the crate uses the multi-algorithm support in the
+[`password-hash`] crate to support multiple password hashing algorithms
+simultaneously. By default it supports Argon2 (using the latest OWASP
+recommended parameters 8), but it can also optionally support PBKDF2 and scrypt
+by enabling crate features.
+
+When multiple algorithms are enabled, it will still default to Argon2 for
+generate_hash, but will be able to verify password hashes from PBKDF2 and
+scrypt as well, if you have them in your password database.
+
 ## Minimum Supported Rust Version
 
 Rust **1.65** or higher.
@@ -54,6 +74,10 @@ dual licensed as above, without any additional terms or conditions.
 
 [//]: # (general links)
 
+[RustCrypto]: https://github.com/RustCrypto/
 [Argon2]: https://en.wikipedia.org/wiki/Argon2
 [PBKDF2]: https://en.wikipedia.org/wiki/PBKDF2
 [scrypt]: https://en.wikipedia.org/wiki/Scrypt
+[`generate_hash`]: https://docs.rs/password-auth/latest/password_auth/fn.generate_hash.html
+[`verify_password`]: https://docs.rs/password-auth/latest/password_auth/fn.verify_password.html
+[`password-hash`]: https://docs.rs/password-hash/latest/password_hash/

password-auth/src/lib.rs

@@ -1,4 +1,5 @@
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc = include_str!("../README.md")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
@@ -48,10 +49,12 @@ impl fmt::Display for VerifyError {
 }
 
 #[cfg(feature = "std")]
-#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 impl std::error::Error for VerifyError {}
 
 /// Generate a password hash for the given password.
+///
+/// Uses the best available password hashing algorithm given the enabled
+/// crate features (typically Argon2 unless explicitly disabled).
 pub fn generate_hash(password: impl AsRef<[u8]>) -> String {
     let salt = SaltString::generate(OsRng);
     generate_phc_hash(password.as_ref(), &salt)
@@ -79,6 +82,12 @@ fn generate_phc_hash<'a>(
 }
 
 /// Verify the provided password against the provided password hash.
+///
+/// # Returns
+///
+/// - `Ok(())` if the password hash verified successfully
+/// - `Err(VerifyError)` if the hash didn't parse successfully or the password
+///   failed to verify against the hash.
 pub fn verify_password(password: impl AsRef<[u8]>, hash: &str) -> Result<(), VerifyError> {
     let hash = PasswordHash::new(hash).map_err(|_| VerifyError)?;