Add bcrypt from Capy

Author: vinniefalco

CMakeLists.txt

@@ -172,6 +172,13 @@ add_library(boost_http include/boost/http.hpp build/Jamfile ${BOOST_HTTP_HEADERS
 add_library(Boost::http ALIAS boost_http)
 boost_http_setup_properties(boost_http)
 
+# bcrypt requires platform-specific libraries
+if (WIN32)
+    target_link_libraries(boost_http PRIVATE bcrypt)
+elseif (APPLE)
+    target_link_libraries(boost_http PRIVATE "-framework Security")
+endif ()
+
 #-------------------------------------------------
 #
 # Tests

build/Jamfile

@@ -36,6 +36,9 @@ alias http_sources : [ glob-tree-ex ./src : *.cpp ] ;
 
 explicit http_sources ;
 
+# Windows CNG library for bcrypt random number generation.
+lib bcrypt_sys : : <name>bcrypt ;
+
 lib boost_http
    : http_sources
    : requirements
@@ -44,10 +47,14 @@ lib boost_http
      <library>/boost//url
      <include>../
      <define>BOOST_HTTP_SOURCE
+     <target-os>windows:<library>bcrypt_sys
+     <target-os>darwin:<linkflags>"-framework Security"
    : usage-requirements
      <library>/boost//capy
      <library>/boost/json//boost_json/<warnings-as-errors>off
      <library>/boost//url
+     <target-os>windows:<library>bcrypt_sys
+     <target-os>darwin:<linkflags>"-framework Security"
    ;
 
 boost-install boost_http ;

doc/modules/ROOT/nav.adoc

@@ -9,6 +9,8 @@
 * xref:Message.adoc[]
 * Server
 ** xref:server/router.adoc[Router]
+* Cryptography
+** xref:bcrypt.adoc[BCrypt Password Hashing]
 // ** xref:server/middleware.adoc[Middleware]
 // ** xref:server/errors.adoc[Error Handling]
 // ** xref:server/params.adoc[Route Parameters]

doc/modules/ROOT/pages/bcrypt.adoc

@@ -0,0 +1,290 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http
+//
+
+= BCrypt Password Hashing
+
+This page explains how to securely hash and verify passwords using bcrypt.
+
+NOTE: Code snippets assume `using namespace boost::http;` is in effect.
+
+== What is BCrypt?
+
+BCrypt is a password-hashing function designed by Niels Provos and David
+Mazières. It incorporates:
+
+* A **salt** to protect against rainbow table attacks
+* An **adaptive cost factor** that can be increased as hardware improves
+* Built-in work factor that makes brute-force attacks expensive
+
+BCrypt is the recommended algorithm for password storage.
+
+== Quick Start
+
+[source,cpp]
+----
+#include <boost/http/bcrypt.hpp>
+
+// Hash a password
+bcrypt::result hash = bcrypt::hash("my_password", 12);
+
+// Store hash.str() in database...
+
+// Later, verify the password
+system::error_code ec;
+bool valid = bcrypt::compare("my_password", stored_hash, ec);
+
+if (ec)
+    // Hash was malformed
+else if (valid)
+    // Password matches
+else
+    // Password does not match
+----
+
+== Hashing Passwords
+
+The `hash` function generates a salted hash:
+
+[source,cpp]
+----
+// Default cost factor (10)
+bcrypt::result r1 = bcrypt::hash("password");
+
+// Custom cost factor
+bcrypt::result r2 = bcrypt::hash("password", 12);
+
+// Custom cost factor and version
+bcrypt::result r3 = bcrypt::hash("password", 12, bcrypt::version::v2b);
+----
+
+=== Cost Factor
+
+The cost factor (rounds) determines how expensive hashing is. Each increment
+doubles the work:
+
+[cols="1,2"]
+|===
+| Cost | Approximate Time (modern CPU)
+
+| 10
+| ~100ms
+
+| 12
+| ~400ms
+
+| 14
+| ~1.6s
+
+| 16
+| ~6.4s
+|===
+
+**Guidelines:**
+
+* Minimum: 10 for new applications
+* Recommended: 12 for most applications
+* Maximum: 31 (impractically slow)
+* Adjust based on your hardware and latency requirements
+
+=== Password Length Limit
+
+BCrypt only uses the first 72 bytes of a password. Longer passwords are
+silently truncated. If you need to support longer passwords, pre-hash
+with SHA-256:
+
+[source,cpp]
+----
+// For passwords > 72 bytes
+std::string pre_hash = sha256(long_password);
+bcrypt::result r = bcrypt::hash(pre_hash, 12);
+----
+
+== Verifying Passwords
+
+The `compare` function extracts the salt from a stored hash, re-hashes
+the input password, and compares:
+
+[source,cpp]
+----
+system::error_code ec;
+bool valid = bcrypt::compare(user_input, stored_hash, ec);
+
+if (ec == bcrypt::error::invalid_hash)
+{
+    // Hash string is malformed - data corruption or tampering
+    log_security_event("invalid hash format");
+    return false;
+}
+
+if (valid)
+    grant_access();
+else
+    reject_login();
+----
+
+WARNING: Always check the error code. A false return value alone does not
+distinguish between "wrong password" and "malformed hash".
+
+== Working with Salts
+
+You can generate and use salts separately:
+
+[source,cpp]
+----
+// Generate a salt
+bcrypt::result salt = bcrypt::gen_salt(12);
+
+// Hash with explicit salt
+system::error_code ec;
+bcrypt::result hash = bcrypt::hash("password", salt.str(), ec);
+----
+
+This is rarely needed since `hash()` generates a salt automatically.
+
+== The result Type
+
+`bcrypt::result` is a fixed-size buffer (no heap allocation):
+
+[source,cpp]
+----
+bcrypt::result r = bcrypt::hash("password", 12);
+
+// Access the hash string
+core::string_view sv = r.str();  // Or just use r (implicit conversion)
+char const* cstr = r.c_str();    // Null-terminated
+
+// Check for valid result
+if (r)
+    store(r.str());
+----
+
+== Hash String Format
+
+A bcrypt hash string has this format:
+
+----
+$2b$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy
+│  │  │                                                    │
+│  │  │                                                    └─ hash (31 chars)
+│  │  └─ salt (22 chars)
+│  └─ cost factor
+└─ version
+----
+
+Total length: 60 characters.
+
+== Extracting the Cost Factor
+
+To check the cost factor of an existing hash:
+
+[source,cpp]
+----
+system::error_code ec;
+unsigned rounds = bcrypt::get_rounds(stored_hash, ec);
+
+if (ec)
+    // Invalid hash format
+else if (rounds < 12)
+    // Consider re-hashing with higher cost
+----
+
+== Upgrading Cost Factor
+
+When a user logs in successfully, you can check if their hash needs upgrading:
+
+[source,cpp]
+----
+system::error_code ec;
+bool valid = bcrypt::compare(password, stored_hash, ec);
+
+if (valid && !ec)
+{
+    unsigned current_cost = bcrypt::get_rounds(stored_hash, ec);
+    
+    if (!ec && current_cost < 12)
+    {
+        // Re-hash with higher cost
+        bcrypt::result new_hash = bcrypt::hash(password, 12);
+        update_stored_hash(user_id, new_hash.str());
+    }
+}
+----
+
+== Error Handling
+
+BCrypt defines two error codes:
+
+[cols="1,3"]
+|===
+| Error | Meaning
+
+| `bcrypt::error::invalid_salt`
+| Salt string is malformed
+
+| `bcrypt::error::invalid_hash`
+| Hash string is malformed
+|===
+
+These errors indicate either data corruption or malicious input. Log them
+as security events.
+
+== Version Selection
+
+BCrypt has multiple version prefixes:
+
+[cols="1,3"]
+|===
+| Version | Description
+
+| `version::v2a`
+| Original specification
+
+| `version::v2b`
+| Fixed handling of passwords > 255 chars (recommended)
+|===
+
+Use `v2b` for new hashes. All versions produce compatible hashes that can
+be verified by any version.
+
+== Security Considerations
+
+**Do:**
+
+* Use cost factor 12 or higher
+* Store the complete hash string (includes salt and cost)
+* Compare in constant time (handled by `compare`)
+* Log invalid hash errors as security events
+
+**Do Not:**
+
+* Store salts separately (they are embedded in the hash)
+* Use bcrypt for general-purpose hashing (use SHA-256)
+* Compare hashes with `==` (timing attacks)
+
+== Summary
+
+[cols="1,3"]
+|===
+| Function | Purpose
+
+| `bcrypt::hash(password, rounds)`
+| Hash a password with auto-generated salt
+
+| `bcrypt::hash(password, salt, ec)`
+| Hash with explicit salt
+
+| `bcrypt::compare(password, hash, ec)`
+| Verify a password against a hash
+
+| `bcrypt::gen_salt(rounds)`
+| Generate a random salt
+
+| `bcrypt::get_rounds(hash, ec)`
+| Extract cost factor from hash
+|===

include/boost/http.hpp

@@ -10,6 +10,7 @@
 #ifndef BOOST_HTTP_HPP
 #define BOOST_HTTP_HPP
 
+#include <boost/http/bcrypt.hpp>
 #include <boost/http/error.hpp>
 #include <boost/http/field.hpp>
 #include <boost/http/fields.hpp>

include/boost/http/bcrypt.hpp

@@ -0,0 +1,49 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http
+//
+
+/** @file
+    bcrypt password hashing library.
+
+    This header includes all bcrypt-related functionality including
+    password hashing, verification, and salt generation.
+
+    bcrypt is a password-hashing function designed by Niels Provos
+    and David Mazières based on the Blowfish cipher. It incorporates
+    a salt to protect against rainbow table attacks and an adaptive
+    cost parameter that can be increased as hardware improves.
+
+    @code
+    #include <boost/http/bcrypt.hpp>
+
+    // Hash a password
+    http::bcrypt::result r;
+    http::bcrypt::hash(r, "my_password", 12);
+    
+    // Store r.str() in database...
+    
+    // Verify later
+    system::error_code ec;
+    bool ok = boost::http::bcrypt::compare("my_password", stored_hash, ec);
+    if (ec)
+        handle_malformed_hash();
+    else if (ok)
+        grant_access();
+    @endcode
+*/
+
+#ifndef BOOST_HTTP_BCRYPT_HPP
+#define BOOST_HTTP_BCRYPT_HPP
+
+#include <boost/http/detail/config.hpp>
+#include <boost/http/bcrypt/error.hpp>
+#include <boost/http/bcrypt/hash.hpp>
+#include <boost/http/bcrypt/result.hpp>
+#include <boost/http/bcrypt/version.hpp>
+
+#endif