Would it not be great if we as developer of a site could warn our users when their passwords are part of a data breach? There is a simple API we can use thanks to Troy Hunt’s “Have I been pwned?” site.
This post is part of the Protecting Passwords series. You can find the other parts here:
- Part 1: Do Something Good for You: Use a Password Manager
- Part 2: KeePass – the Cloud-Free Solution to Manage Your Passwords
- Part 3: Use BCrypt to Save Password (Hashes)
- Part 4: How to Find out If Your User’s Password Is in a Data Breach
Attention
This post uses SHA1 to create hashes to check passwords against the ones in known data breaches. Do not use SHA1 to store passwords! Use BCrypt instead.
The idea of this API is to integrate it into your login or password change process. Only in this two use cases should you know the password of your users. In all other places, there should always be only a hash.
Before you scream: we will not send the password or the hash to an API. Instead, we will only use the first 5 characters of the hash. The pwned passwords API uses a concept called k-anonymity to ensure the safety of your data. By providing only the first 5 characters of a 40 characters long hash, no one who could get their hands on your request could figure out what the password hash was – there are simply too many possibilities.
Documentation
You find a long post on all features of the API in this blog post by Troy Hunt. The documentation of the API including all things you need to know and clickable test cases is here.
A little trap
The API documentation explains it, but I guess you may overlook it as I did. You send a 5 character long prefix to the API and get back the suffixes. Meaning, what you get is only a part of the hash. To turn the result into a complete hash, you need to add the prefix you send to the API (in this example in bold)
21BD12D8D1B3FAACCA6A3C6A91617B2FA32E2F57:1
21BD12DC183F740EE76F27B78EB39C8AD972A757:49938
21BD130151E8272224C96B799A0FFF4D8980CBF2:2
21BD1308E814601245EB388B9547B0B09E9632A1:23
Code example
You do not need a special NuGet package to call the API. All it needs is an HttpClient instance and a little bit of setup code.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
private static async Task<int> CheckPassword(string hash) { var first5 = hash.Substring(0, 5); var restOfHash = hash.Substring(5); var req = $"https://api.pwnedpasswords.com/range/{first5}"; HttpResponseMessage response = await client.GetAsync(req); if (response.IsSuccessStatusCode) { var range = await response.Content.ReadAsStringAsync(); var lines = range.Split(new[] { Environment.NewLine }, StringSplitOptions.None); foreach (var line in lines) { var parts = line.Split(':'); if (restOfHash.Equals(parts[0])) { return int.Parse(parts[1]); } } } return 0; } |
To create a SHA1 hash you can use this code from an answer by Mitch on Stack Overflow:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
private static string Hash(string input) { using (SHA1Managed sha1 = new SHA1Managed()) { var hash = sha1.ComputeHash(Encoding.UTF8.GetBytes(input)); var sb = new StringBuilder(hash.Length * 2); foreach (byte b in hash) { // can be "x2" if you want lowercase sb.Append(b.ToString("X2")); } return sb.ToString(); } } |
All you need now is a little bit of boilerplate code for a command line application to call those methods. Be aware that you have to set the User-Agent field:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
public class Program { static HttpClient client = new HttpClient(); public static void Main(string[] args) { RunAsync().GetAwaiter().GetResult(); } static async Task RunAsync() { client.DefaultRequestHeaders.Accept.Clear(); client.DefaultRequestHeaders.Accept.Add( new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Add( "User-Agent", "C# App ImproveAndRepeat.com"); var hash = Hash("test"); var numberOfPawnedAccounts = await CheckPassword(hash); if (numberOfPawnedAccounts > 0) { Console.WriteLine( $"Your password is used in {numberOfPawnedAccounts}" + " pwned accounts"); } else { Console.WriteLine( "Your password was not used by any pwned accounts"); } Console.ReadLine(); } } |
If you run this tool, you make a call to the API and should get an output like this one:
Your password is used in 73557 pwned accounts
You like the idea but cannot use this service?
In this case, you can download the whole list of pwned passwords. It contains 517 million hashes and has the size of 10 GB. You can extract the file and load it into a SQL Server database. Instead of a call to the API you then query your database.
Conclusion
If you add this little API call to your login or password change form, you can increase the security of your users. Only when they know that they use an insecure password, can they change it. That additional check concludes my series on passwords. I hope you have enjoyed it.
1 thought on “How to Find out If Your User’s Password Is in a Data Breach”