Add more docs + bump version

Keats · Nov 18, 2024 · 378f356 · 378f356
1 parent 1cdfc22
commit 378f356
Show file tree

Hide file tree

Showing 4 changed files with 11 additions and 3 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bcrypt"
-version = "0.15.1"
+version = "0.16.0"
 authors = ["Vincent Prouillet <[email protected]>"]
 license = "MIT"
 readme = "README.md"

diff --git a/README.md b/README.md
@@ -28,7 +28,11 @@ let valid = verify("hunter2", &hashed)?;
 The cost needs to be an integer between 4 and 31 (see benchmarks to have an idea of the speed for each), the `DEFAULT_COST` is 12.
 
 ## Error on truncation
-Most if not all bcrypt implementation truncates the password after 72 bytes. In specific use cases this can break 2nd pre-image resistance. One can enforce the 72-bytes limit on input by using `non_truncating_hash`, `non_truncating_hash_with_result`, `non_truncating_hash_with_salt`, and `non_truncating_verify`. The `non_truncating_*` functions behave identically to their truncating counterparts unless the input is longer than 72 bytes, in which case they will return `BcryptError::Truncation`.
+Most if not all bcrypt implementation truncates the password after 72 bytes. In specific use cases this can break 2nd pre-image resistance. 
+One can enforce the 72-bytes limit on input by using `non_truncating_hash`, `non_truncating_hash_with_result`, `non_truncating_hash_with_salt`, and `non_truncating_verify`. 
+The `non_truncating_*` functions behave identically to their truncating counterparts unless the input is longer than 72 bytes, in which case they will return `BcryptError::Truncation`.
+
+If you are generating hashes from other libraries/languages, do not use the `non_truncating_verify` function.
 
 ## `no_std`
 
@@ -57,6 +61,7 @@ for new projects.
 
 ## Changelog
 
+* 0.16.0: add `non_truncating_*` functions
 * 0.15.1: update base64 dependency
 * 0.15.0: add an `alloc` feature that can be disabled.
 * 0.14.0: use `subtle` crate for constant time comparison, update base64 and bump to 2021 edition

diff --git a/src/errors.rs b/src/errors.rs
@@ -29,6 +29,7 @@ pub enum BcryptError {
     Rand(getrandom::Error),
     /// Return this error if the input contains more than 72 bytes. This variant contains the
     /// length of the input in bytes.
+    /// Only returned when calling `non_truncating_*` functions
     Truncation(usize),
 }
 

diff --git a/src/lib.rs b/src/lib.rs
@@ -278,7 +278,9 @@ pub fn verify<P: AsRef<[u8]>>(password: P, hash: &str) -> BcryptResult<bool> {
     _verify(password, hash, false)
 }
 
-/// Verify that a password is equivalent to the hash provided
+/// Verify that a password is equivalent to the hash provided.
+/// Only use this if you are only using `non_truncating_hash` to generate the hash.
+/// It will return an error for inputs that will work if generated from other sources.
 #[cfg(any(feature = "alloc", feature = "std"))]
 pub fn non_truncating_verify<P: AsRef<[u8]>>(password: P, hash: &str) -> BcryptResult<bool> {
     _verify(password, hash, true)