BCrypt.Net: a C# port of jBCrypt with an adjustable work factor

A direct port, and how its parity is checked

BCrypt.Net is a.NET port of jBCrypt, written by Damien Miller, and the README is precise about the relationship. For all intents and purposes it is a direct port, with the addition of some convenience methods and some mild re-factoring. That is a useful thing to know, because it tells you what to expect from the library and how to test it. The recommended way to confirm that the port behaves like the original is to compare the unit tests, which is a stronger statement than a claim of compatibility because it is a checkable one. The package is published on NuGet under the name BCrypt.Net-Next, and the project keeps a separate test harness folder alongside the unit tests, which suggests the library is exercised from other language stacks as well as from C#.

Why the work factor is the whole point

The description calls bcrypt a variant of the Blowfish encryption algorithm's keying schedule with the addition of a work factor, and that work factor is what makes the algorithm usable for passwords rather than merely slow. The argument in the README is about Moore's law. A hash algorithm that is fast today will be trivially broken by hardware that arrives later, so bcrypt lets you decide how expensive a hash is to compute, and the cost is embedded in the resulting hash itself. That last detail is what makes the approach work in practice: because the work factor travels inside the hash, a hash made with an old cost stays verifiable after you raise the cost for new hashes, and the library can tell the two apart. So the hashes are forward and backward compatible, and raising the cost later does not invalidate the passwords already stored.

Hashing and verifying a password

The quick start is two calls, and the README shows them in a file scoped namespace with the BCryptNet namespace imported. Hashing a password looks like this:

string passwordHash =  BCrypt.HashPassword("my password");

and verification compares a candidate against the stored value:

if(BCrypt.Verify("my password", passwordHash))
{
    // Password is correct
}

The note under the example is the part worth remembering. The library does let you supply your own salt, but the README calls it highly advisable to let the library generate the salt, and it says those methods exist to maintain compatibility and for more advanced cross-platform requirements that may need them. The default work factor is 11, which is 2 to the power of the number of rounds, and the README notes that this matches the default in most implementations and is currently regarded as a good level of security and risk.

The repository layout and how it is built

The tree is that of a library that is built, tested, benchmarked and packaged in several ways. The source lives in src/, with the project file the Makefile packs, the tests in tests/ and the benchmark project in src/benchmarks, and there is a separate benchmarks/ directory at the root as well. The examples directory holds an Android test project, an API example and a console application, which are the three ways people tend to try a hashing library. The build is centralised, with Directory.Build.props and Directory.Packages.props for shared properties and centrally managed package versions, a global.json pinning the SDK, and a nuget.config for feeds. Two files stand out for what they imply about the project quality: a strong naming key, which lets the assembly be signed and referenced with a public key, and a Stryker configuration, which is mutation testing, a technique where the tests are checked by deliberately breaking the code to see whether they notice.

Running the tests and the benchmarks

The Makefile wraps the dotnet commands that CI runs, and the targets are the quickest way to see what the project does on a build server. The test target runs the test suite in Release configuration with coverage collected in the Cobertura format and reported to GitHub, which is a slightly unusual choice and means the coverage lands in the pull request rather than in a separate service. There are two packaging targets, one that packs with the version taken from the project file and one that packs a pre-release with an explicit 5.0.0-alpha suffix, which is the mechanism the V5 line will travel on. A separate target delegates to the benchmark project. The Dockerfile does the same thing in a container, starting from the .NET 10 SDK image, building the whole solution in the Benchmark configuration and running the benchmark project, so the performance numbers are produced in the same environment the container defines.

Which version you actually get

There is a gap here that a reader has to notice, and the README flags it in a note at the very top. The main code, the documentation and the website all refer to V5, which is being prepared for release, while the package people install today is the 4.x line. The published releases are v4.2.0 on 2026-05-11, described as a maintenance release, v4.1.0 on 2026-02-16, which is a maintenance release on the.NET 10 target on the 4x branch, and 4.0.3 from 2022-03-03, which is the.NET 6 version. The last push was on 2026-07-09. So there are two questions an adopter has to answer separately, which version to install now, and what the rewrite in the branch is going to change, and the second one is left open. The sensible reading of the version numbers is that 4.x is a maintained line for existing users while the branch carries the next major version.

What BCrypt.Net does not cover, and the alternatives

The library is a hashing function and nothing more. It does not store a user record, it does not decide a password policy, it does not tell you when a hash was made with an outdated cost, and it does not rehash on a successful login, all of which are application concerns that a service using it has to implement. The alternative worth comparing is the hasher already in the platform. .NET has a built-in password hasher, and the reason to prefer bcrypt over it is the reason the README gives, an adjustable cost that can be raised over the life of a deployment and a format that other implementations understand, including the original jBCrypt and the widely used command line tools. The reason to prefer the platform hasher is that it is already there, tuned to the runtime and supported by the framework. The README does not document a maximum input length or any support for a pepper, and both of those matter when you are migrating an existing credential store, so they are worth checking in the source.

Editorial conclusion

BCrypt.Net fits a .NET application that needs to verify bcrypt hashes it did not create, that is migrating from another stack, or that simply wants a password hash with a cost parameter it can raise over time. It does not fit a team that wants the platform defaults, since the built-in .NET hasher is already there, and it does not fit a project that has decided on a memory-hard algorithm, because bcrypt is not one. Before adopting it, read the version notes carefully, since the NuGet package and the branch are on different major versions, and check the two things the README does not document, a maximum input length and any support for a pepper, because both affect how you integrate it with an existing credential store.

Frequently asked questions

Official sources

1. BcryptNet/bcrypt.net on GitHub
2. License: MIT
3. Project website
4. README
5. Releases