Pular para o conteúdo
Alexandre Freire
GitHub

MD5 for .NET: Hash Strings, Objects, Streams, and More

Abstract illustration of data flowing through a cryptographic hashing core into a hexadecimal digest

Hashing is one of those small engineering tasks that appears everywhere: validating file integrity, comparing payloads, creating cache keys, and detecting whether data has changed. In .NET, the platform already provides the cryptographic primitives you need, but applying them consistently across strings, byte arrays, objects, and streams can still lead to repetitive code.

That is the problem the MD5 NuGet package was created to simplify. Published by Alexandre Freire, the library provides convenient extension methods for MD5, SHA-256, and HMAC-SHA-256 hashing while preserving the historical MD5 behavior that existing applications may depend on.

What is the MD5 .NET library?

MD5 is a lightweight .NET library for generating hash values from common input types, including:

  • Strings
  • Byte arrays
  • Objects
  • Streams

The package builds on .NET’s System.Security.Cryptography APIs and exposes a concise extension-method experience. Instead of repeating hashing setup and byte-to-hex conversion throughout an application, you can call a method directly on the value you want to process.

The library also provides SHA-256 and HMAC-SHA-256 APIs without changing the existing MD5 method signatures or their historical behavior. This makes the package useful both for legacy compatibility and for newer integrity scenarios.

Installing the MD5 .NET library

You can install the package from NuGet using the .NET CLI:

dotnet add package MD5

With the Visual Studio Package Manager Console:

Install-Package MD5

Or add it directly to a project file:

<PackageReference Include="MD5" />

The package targets .NET Standard 2.0. Its NuGet metadata lists Newtonsoft.Json 13.0.4 as the dependency for that target, which is used to support object-based hashing.

Hashing a string

The simplest use case is generating an MD5 hash from a string:

string hash = "hello world".GetMD5();

When encoding matters, you can select the encoding explicitly:

string hash = "hello world".GetMD5(EncodingType.UTF8);

Being explicit about encoding is helpful when the same data is processed by different systems. It makes the input representation clear and helps avoid unexpected differences between environments.

Hashing byte arrays

Byte arrays are useful when the data has already been serialized, received over the network, or read from another API:

byte[] payload = Encoding.UTF8.GetBytes("Hello, World!");
string hash = payload.GetMD5();

The same pattern can be used with the newer SHA-256 API:

string sha256 = payload.GetSHA256();
Digital document flowing through a secure processing pipeline into a compact hash fingerprint
Stream-based hashing lets .NET applications process large files while keeping memory usage predictable.

Hashing files and streams

For files and large content, streams avoid loading the entire payload into memory at once:

using var stream = File.OpenRead("Rondonia.pdf");
string hash = stream.GetMD5();

Streams are particularly useful for document uploads, backups, downloads, and other operations where memory usage matters. The same input style is also available for SHA-256:

using var stream = File.OpenRead("report.pdf");
string sha256 = stream.GetSHA256();

Hashing objects

The library can also hash an object, which is convenient when you need a stable fingerprint for a model or serialized data structure:

var customer = new Customer
{
    Id = 42,
    Name = "Alexandre"
};

string hash = customer.GetMD5();

Object hashing is useful for change detection, cache invalidation, synchronization checks, and comparing serialized representations. If object properties or values change, the resulting hash should change as well.

Hashing numbers

Numbers can be converted to strings before hashing:

int orderId = 2026;
string hash = orderId.ToString().GetMD5();

For reproducible results across systems, use a consistent culture and formatting strategy when converting numeric values to text.

Abstract comparison between a compact checksum pattern and a layered cryptographic fingerprint
MD5 is useful for compatibility and non-adversarial checksums; SHA-256 is the stronger default for new integrity features.

SHA-256 for new integrity scenarios

MD5 remains useful for compatibility and non-adversarial checksums, but it is no longer considered collision-resistant. For new integrity features, the package includes GetSHA256:

string checksum = "hello world".GetSHA256();

SHA-256 is a better choice for public checksums, file fingerprints, content-addressed storage, and integrity validation where you are designing a new format.

The package keeps the API straightforward across the same supported input types:

var document = File.OpenRead("document.pdf");
string checksum = document.GetSHA256();
Two secure endpoints exchanging a message through a glowing cryptographic lock and shared key
HMAC-SHA-256 combines a message with a shared secret so the receiver can verify integrity and authenticity.

HMAC-SHA-256 for authenticity

When integrity also depends on a shared secret, use HMAC-SHA-256. The package exposes this through GetHMACSHA256:

string secretKey = "a-secret-key";
string signature = "important payload".GetHMACSHA256(secretKey);

HMAC helps a receiver verify that a message was created with knowledge of the shared key and was not modified afterward. For binary data, both the payload and key can be represented as byte arrays:

byte[] payload = Encoding.UTF8.GetBytes("Important payload");
byte[] key = Encoding.UTF8.GetBytes("a-secret-key");

string signature = payload.GetHMACSHA256(key);

Keep secret keys out of source control. Store them using the secret-management facilities appropriate for your deployment environment.

Legacy salted MD5 support

The library also supports the historical GetMD5WithSalt methods for strings, byte arrays, objects, and streams:

string salt = "randomSalt";
string hash = "hello world".GetMD5WithSalt(salt);

The library intentionally preserves the legacy behavior of these overloads for compatibility. Strings and objects hash salt + content, while byte arrays and streams hash content + salt. That order matters when reproducing values generated by older versions.

Security note: adding a salt does not make MD5 suitable for password storage or authentication. For passwords, use a password-specific key derivation function such as PBKDF2, bcrypt, or Argon2.

Which hashing method should you choose?

  • MD5: use when you need compatibility with an existing system or a non-security checksum where collision resistance is not a requirement.
  • SHA-256: use for new checksums, fingerprints, and content-integrity features.
  • HMAC-SHA-256: use when you need integrity and authenticity based on a shared secret.
  • Password hashing: use a dedicated password KDF such as PBKDF2, bcrypt, or Argon2 instead of any of the methods above.

This distinction is important: a hash is not encryption. Hash functions are one-way transformations, and the package does not provide encryption or password hashing.

Practical use cases

The MD5 library can help reduce repetitive hashing code in a wide range of .NET applications:

  • Checking whether a downloaded file changed
  • Comparing document or image content
  • Building cache keys from request data
  • Detecting changes in serialized objects
  • Creating compatibility checksums for legacy integrations
  • Generating SHA-256 fingerprints for new APIs
  • Signing payloads with HMAC-SHA-256

For security-sensitive workflows, choose the algorithm based on the threat model rather than convenience alone.

Why use the MD5 NuGet package?

The package combines a small, expressive API with broad input support. Its extension methods make common operations easy to read, while its support for streams helps applications process files without unnecessary memory pressure.

Another benefit is gradual modernization. Existing projects can continue using GetMD5 where compatibility is required, while newer code can adopt GetSHA256 and GetHMACSHA256 without introducing a separate library or rewriting every call site.

Source code, license, and package details

MD5 is open source and available under the MIT License. The source code and issue tracker are available on GitHub.

Final thoughts

The MD5 .NET library is a practical way to centralize hashing for strings, byte arrays, objects, and streams. The library goes beyond its original compatibility focus by providing SHA-256 and HMAC-SHA-256, giving developers a clear path toward stronger integrity and authenticity checks.

If you maintain a .NET application that needs predictable hashing with a compact API, install MD5 from NuGet, review the security requirements of your use case, and choose the algorithm that matches the job.

Load WordPress Sites in as fast as 37ms!