HibpPasswordProvider.hpp

1. Overview

The HibpPasswordProvider.hpp header defines the HibpPasswordProvider class and the associated PasswordLeakResult structure, which implement secure password compromise checking using the Have I Been Pwned (HIBP) Pwned Passwords service.

This module allows BastionGuard to verify whether a password has appeared in known breach datasets without transmitting the full password in plaintext.

Functionally, HibpPasswordProvider provides:

  • Secure password breach detection via k-anonymity
  • Integration with the HIBP Pwned Passwords API
  • Privacy-preserving hash-based lookups
  • Quantitative exposure reporting
  • Support for password hygiene assessments

2. Dependencies and Includes

#include <string>
#include <cstdint>
  • <string> – password input handling
  • <cstdint> – fixed-width integer types for counters

3. Data Structures

3.1 PasswordLeakResult Structure

struct PasswordLeakResult {
    bool compromised = false;
    uint64_t count = 0;
};

Represents the outcome of a password breach lookup.

  • compromised – indicates whether the password was found in breach datasets
  • count – number of occurrences in known leaks

A high count value typically indicates widespread compromise.

4. Class Declaration and Scope

class HibpPasswordProvider

The class is implemented as a static utility container. All methods are static, and no instances are intended to be created.

5. Public Interface

5.1 Password Compromise Check

static PasswordLeakResult
checkPassword(const std::string& password);

Verifies whether the supplied password has appeared in known breach datasets using the HIBP API.

  • password – plaintext password to be checked (used only locally for hashing)
  • Return value – populated PasswordLeakResult structure

The password is never transmitted in full to external services. Instead, a cryptographic hash prefix is used.

6. Privacy-Preserving Lookup Model

HibpPasswordProvider uses the HIBP k-anonymity protocol:

  • The password is hashed locally (typically SHA-1)
  • Only the first 5 characters of the hash are transmitted
  • The server returns matching suffixes
  • The client performs local comparison

This ensures that the full password or full hash is never exposed to third parties.

7. Internal Logic

A typical lookup workflow includes:

  • Computing the cryptographic hash of the password
  • Splitting the hash into prefix and suffix
  • Querying the HIBP range API endpoint
  • Parsing response entries
  • Comparing suffixes locally
  • Extracting exposure count

8. Integration with Password Security Features

HibpPasswordProvider is typically integrated with:

  • Password strength validation workflows
  • Account setup and change-password dialogs
  • Security audit modules
  • User education and recommendations systems

9. Auto-Update (Scheduled Refresh)

This component does not implement scheduling. Password checks are executed on demand.

10. Settings and Configuration

API endpoints, rate limits, and user-agent identifiers are managed by shared HTTP client infrastructure and global configuration modules.

11. Compliance and Legal Considerations

  • HIBP Terms of Service: usage must comply with service policies and attribution requirements.
  • Data protection: passwords must never be stored or logged in plaintext.
  • Consent: users should be informed when external services are queried.

12. Runtime and Security Considerations

  • Memory hygiene: plaintext passwords should be cleared from memory as soon as possible.
  • TLS enforcement: API requests must use HTTPS with strict certificate validation.
  • Rate limiting: excessive queries may result in service throttling.
  • Error handling: network failures should result in conservative responses (assume unknown rather than safe).
  • Side-channel resistance: comparisons should be implemented in constant time where feasible.
Published on:
Last updated on: