AtleX.HaveIBeenPwned 9.0.0

.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher. 
dotnet add package AtleX.HaveIBeenPwned --version 9.0.0                

                    
                

            
NuGet\Install-Package AtleX.HaveIBeenPwned -Version 9.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="AtleX.HaveIBeenPwned" Version="9.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add AtleX.HaveIBeenPwned --version 9.0.0                

                    
                

            
#r "nuget: AtleX.HaveIBeenPwned, 9.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install AtleX.HaveIBeenPwned as a Cake Addin
#addin nuget:?package=AtleX.HaveIBeenPwned&version=9.0.0

// Install AtleX.HaveIBeenPwned as a Cake Tool
#tool nuget:?package=AtleX.HaveIBeenPwned&version=9.0.0

AtleX.HaveIBeenPwned

AtleX.HaveIBeenPwned is a client library for HaveIBeenPwned.com. It supports finding breaches an account was in, which pastes contained the user's email address, getting the breaches a domain's mail addresses were in and to check whether a password was in a breach or not.

The AtleX.HaveIBeenPwned library is highly optimized for ease of use, great performance and low resource usage. It is thread safe, simple to plug into ASP.net Core(+)'s dependency injection system and usable on many platforms.

⚠️ For some actions, like getting the pastes and breaches for an account, the HaveIBeenPwned.com API requires a API key. These API keys are available on the HaveIBeenPwned.com website.

Trust

Leaked data can be a sensitive subject. Just like the HaveIBeenPwned.com website and API, this library is carefully designed to be trustworthy and require the least amount of data possible to work. There is no collection of data. All published packages have reproducible builds, meaning that a build from a certain source version will always result in the same binaries. Additionally, not a single part of the library is obfuscated. Anyone can easily inspect binaries in a tool like ILSpy or use a debugger to step through and inspect everything.

Examples


// Create the client
var settings = new HaveIBeenPwnedClientSettings()
{
    ApiKey = "APIKEY", // Get one from https://haveibeenpwned.com/API/Key. Necessary for getting the breaches and pastes an account is in.
    ApplicationName = "TheNameOfYourApplication",
};
using (var client = new HaveIBeenPwnedClient(settings))
{
    // Get all breaches in the system with their details
    var breaches = await client.GetAllBreachesAsync();

    // Get the latest breach in the system
    var latestBreach = await client.GetLatestBreachAsync();

    // Get the breaches for an account. This returns a collection of breaches with their 
    // name. Use the response from GetAllBreachesAsync() to find the corresponding details 
    // by name
    var breaches = await client.GetBreachesAsync("test@example.com"); // Requires an API key

    // Get the breached users of a domain.
    var breachedUsers = await client.GetBreachedDomainUsersAsync("example.com"); // Requires an API key

    // Get breaches for an account, excluding unverified breaches
    var breaches = await client.GetBreachesAsync("test@example.com", BreachMode.ExcludeUnverified); // Requires an API key

    // Get the subscribed domains for an API key
    var domains = await client.GetSubscribedDomainsAsync)(); // Requires an API key

    // Get breached users from a domain the API key is subscribed to
    var breachedUsersOfDomain = await client.GetBreachedDomainUsersAsync("example.com"); // Requires an API key

    // Get pastes for an email address
    var pastes = await client.GetPastesAsync("test@example.com"); // Requires an API key

    // Verify whether is password is in Pwned Passwords or not
    var isPwned = await client.IsPwnedPasswordAsync("1234");
}

All async methods have overrides with CancellationToken support.

Dependency injection

Usage with the dependency injection system of ASP.net Core/.NET Core or higher is fully supported.

builder.Services
  .AddSingleton(_ => new HaveIBeenPwnedClientSettings() 
    { 
      ApplicationName = "YourAppName", 
      ApiKey = "YourApiKey" // Only necessary for methods thar require an API key. Can be left blank otherwise
    })
  .AddScoped<IHaveIBeenPwnedClient, HaveIBeenPwnedClient>() // You can also use one of the more specialized interfaces
  .AddHttpClient<HaveIBeenPwnedClient>();
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
9.0.0 6,669 7/14/2024
8.1.1 8,191 2/22/2024
8.1.0 2,711 12/31/2023
8.0.0 1,394 8/11/2023
7.0.0 2,089 11/25/2022
6.0.1 881 10/27/2022
6.0.0 5,252 6/11/2022
5.0.3 4,111 7/11/2021
5.0.2 3,032 2/13/2021
5.0.1 2,203 9/8/2020
5.0.0 1,711 8/9/2020
5.0.0-beta3 462 6/27/2020
5.0.0-beta2 393 4/18/2020
5.0.0-beta1 388 2/2/2020
4.1.0 724 8/17/2019
4.0.0 628 7/27/2019
3.0.1 734 6/13/2019 3.0.1 is deprecated.
3.0.0 717 5/19/2019 3.0.0 is deprecated.
3.0.0-beta1 512 5/4/2019 3.0.0-beta1 is deprecated.
2.1.0 788 3/13/2019 2.1.0 is deprecated.
2.0.0 728 3/11/2019 2.0.0 is deprecated.
1.1.0 953 11/3/2018 1.1.0 is deprecated.
1.0.0 783 10/26/2018 1.0.0 is deprecated.

9.0.0:
- [Feature] Added support getting subscribed domains and their breached users (#104)
- [Feature] Added basic telemetry so users can observe the usage and performance of the library (#102)
- [Feature] Updated documentation (#97, #106)
- [Feature] Implemented '==' and '!=' operators on models (#100)
- [Feature] Add a package icon (#108)
- [Fix] Performance improvements (#96, #98, #99)

8.1.1:
- [Feature] Internal (performance) improvements. (#94 and other commits)

8.1.0:
- [Feature] Add .NET 8+ compatiblity
- [Feature] Add support for trimming and AOT on .NET 8 or higher (#85)

8.0.0
- [Feature][Breaking] Add support for domain searches (#86)
- [Feature][Breaking] Add support for retrieving only the latest breach in the system (#87)
- [Feature] Improved documentation
- [Feature] Internal improvements

7.0.0
- [Breaking] Throw exception when the CancellationToken is cancelled as soon as possible (#70)
- [Breaking] Wrap InvalidOperationException in HaveIBeenPwnedClientException (#71)
- [Breaking][Fix] GetPastesAsync() now returns an empty collection instead of throwing an exception when no pastes are found (#82)
- [Feature] Add .NET 6.0 target and use source generators for JSON (de)serialization (#72)
- [Feature] Add more properties to the SiteBreach model (#79)
- [Feature] Improved documentation
- [Feature] Many internal improvements to make this the best and most performant version ever (#75, #76, #77, #78, #79)

6.0.1:
- [Feature] Performance improvement when (de)serializing requests and responses (#74)
- [Fix] RateLimitExceededException no longer throws an exception when the retry-after value is 0 seconds or less (#73)
- [Fix] Internal improvements (#69)

6.0.0:
- [Breaking] Removed SerializeAttribute from exceptions (#50)
- [Breaking] Removed obsolete and no longer used settings from HaveIBeenPwnedClientSettings (#60)
- [Feature] Add support for padded pwned password checks (Enabled by default, #55)
- [Feature] Improved IntelliSense documentation (#61)
- [Feature] Internal improvements (#56, #57, #58)

5.0.3:
- Internal refactoring, build improvements and code simplification

5.0.2:
- [Fix] In RateLimitExceededException, only construct the message when it's needed (#49)
- [Fix] Standardize IEquatable<T> implementations (#52)

5.0.1:
- [Fix] Drastically reduced memory usage in HaveIBeenPwnedClient.IsPwnedPasswordAsync() (#47)

5.0.0:
- [Feature] Enabled deterministic builds (43)
- [Feature] Implement IEquatable<T> on Paste, Breach and SiteBreach (#46)
- [Feature] Performance optimizations (#36, #44)
- [Feature] Replace NewtonSoft.Json with System.Text.Json (#25)
- [Feature] Add C#8 Nullable Reference Types support (#31)
- [Feature] Calling ToString() on Breach now returns the value of the Name property instead of the type name (#41)
- [Feature] Calling ToString() on Paste now returns the value of the Title property instead of the type name (#41)
- [Feature] Calling ToString() on SiteBreach now returns the value of the Name property instead of the type name (#41)
- [Breaking] Mark HaveIBeenPwnedClientSettings.TimeOut as obsolete (#37)
- [Breaking] Throw InvalidApiKeyException instead of InvalidOperationException when no API key is supplied (#34)
- [Breaking] HaveIBeenPwnedClientSettings.ApplicationName should default to an empty string and an exception must be thrown when it's not set (#30)
- [Breaking] AtleX.HaveIBeenPwned is now strong named (#32)

4.1.0:
- [Feature] Introduce specialized API interfaces for specific functionality (#33)
- [Feature] Throw custom exception when an invalid or expired API key is used (#28)

4.0.0:
- [Breaking] Changed the HaveIBeenPwned.com API to V3. An API key is now mandatory for retrieving pastes and breaches (#27)
- [Breaking] Changed BreachMode.IncludeUnverified to BreachMode.ExcludeUnverified because the V3 API now returns unverifed breaches by default (#27)
- [Breaking] Fold HaveIBeenPwnedClient and HttpHaveIBeenPwnedClient into one (#26)
- [Breaking] Change RetryAfter property of RateLimitException from int to TimeSpan (#24)

3.0.1:
- [Fix] HttpHaveIBeenPwnedClient.GetAsync(Uri, CancellationToken) no longer resets the output stream when no data was loaded (#20)
- [Fix] HttpHaveIBeenPwnedClient.GetAsync(Uri, CancellationToken) no longer creates a new MemoryStream when no data was loaded (#21)
- [Fix] HttpHaveIBeenPwnedClient.GetBreachesInternalAsync(string, BreachMode, CancellationToken) no longer returns null instead of an empty enumerable when no data was loaded (#23)

3.0.0:
- [Feature] Moved from SourceLink with embedded PDB to a .snupkg on NuGet.org for debugging (#8)
- [Breaking] Removed the ClientSettings from the HaveIBeenPwnedClient (#12)
- [Breaking] Removed IDisposable from IHaveIBeenPwnedClient (#10)
- [Breaking] Renamed HttpServiceClient to HttpHaveIBeenPwnedClient (#13)
- [Breaking] Reorganised classes and namespaces (#16)
- [Breaking] Renamed BreachMode.None to BreachMode.Default (#15)
- [Breaking] Removed KAnonimityHelper from public API (#18)
- [Fix] HaveIBeenPwnedClient no longer disposes an injected IHaveIBeenPwnedClient (#11)

2.1.0
- [Fix] An injected HttpClient is no longer disposed by the HttpServiceClient (#6)
- [Fix] The initial HTTP requests is no longer performed outside of error-handling code in HttpServiceClient (#7)
- [Feature] When using the HttpServiceClient directly, it's no longer necessary to inject a HttpClient
- [Feature] General code cleanup

2.0.0
- [Feature] Added support for cancellation tokens (#4)
- [Feature] Add injecting a HttpClient in the HttpServiceClient (#2)
- [Breaking] Changed base interface name from IServiceClient to IHaveIBeenPwnedClient (#5)
- Various performance optimizations and reliability improvements

1.1.0
- [Fix] Marked built-in exceptions as serializable (fixes #1)

1.0.0
- [Feature] Added support for getting the breaches for an account
- [Feature] Added support for getting the pastes for an email address
- [Feature] Added support for checking a password against the Pwned Passwords API