MD5 2.4.0

MD5

Overview

MD5 is a .NET library that provides methods to generate MD5 hash from string, byteArray, object or stream content. It uses the System.Security.Cryptography.MD5 class to generate the hash.

Usage

To use the library, you can call the GetMD5 method on a string, byteArray, object or stream to get the MD5 hash. Examples:

string hash1 = "hello world".GetMD5();
// or specific encoding type
string hash2 = "hello world".GetMD5(EncodingType.UTF8);

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

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

BrasilModel obj = new BrasilModel() { Id = 1, Details = "Maior país da América do Sul" };
string hash = obj.GetMD5();

For a number, you can use:

string hash = myNumber.ToString().GetMD5();

SHA-256 and HMAC-SHA-256

For new integrity scenarios, use the new GetSHA256 and GetHMACSHA256 methods. They are additional APIs and do not change the existing MD5 method signatures or their historical behavior.

SHA-256 is appropriate for public checksums, fingerprints and content integrity. HMAC-SHA-256 is appropriate when integrity and authenticity depend on a shared secret key. HMAC is not a password-hashing function; use the password-specific APIs below for passwords.

The new methods support strings, byte arrays, objects and streams, just like the existing MD5 methods. String and object inputs use UTF-8 by default.

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

string secretKey = "a-secret-key";
string hmac = "hello world".GetHMACSHA256(secretKey);

For binary data and keys:

byte[] payload = Encoding.UTF8.GetBytes("Hello, World!");
byte[] key = Encoding.UTF8.GetBytes("a-secret-key");

string sha256 = payload.GetSHA256();
string hmac = payload.GetHMACSHA256(key);

Password hashing: PBKDF2, bcrypt and Argon2id

For password storage and authentication, use PasswordHash. These algorithms are deliberately separate from the legacy MD5 and salted-MD5 methods. Each Hash... method generates a random salt and returns a self-contained encoded value with the parameters required by its matching Verify... method.

Argon2id is the preferred choice for new password storage when the deployment environment supports it. PBKDF2-HMAC-SHA256 is a broadly compatible alternative, and bcrypt is useful when compatibility with existing bcrypt hashes is required.

string pbkdf2 = PasswordHash.HashPBKDF2("my password");
bool pbkdf2Matches = PasswordHash.VerifyPBKDF2("my password", pbkdf2);

string bcrypt = PasswordHash.HashBCrypt("my password");
bool bcryptMatches = PasswordHash.VerifyBCrypt("my password", bcrypt);

string argon2 = PasswordHash.HashArgon2("my password");
bool argon2Matches = PasswordHash.VerifyArgon2("my password", argon2);

Store the returned encoded value and verify the supplied password against it; never store the plaintext password. Password hashing is intentionally slower than a checksum, so tune the parameters for the production hardware and periodically review them. The existing GetMD5, GetMD5WithSalt, GetSHA256 and GetHMACSHA256 contracts and behavior are unchanged.

New Feature: MD5 with Salt

This feature generates the legacy salted MD5 variants supported by the package. A salt does not make MD5 suitable for password storage or authentication.

Usage

To use the salted hash functionality, you can call the GetMD5WithSalt method on a string, byte array, object or stream to get the legacy salted MD5 result.

The existing overloads intentionally retain their historical behavior for compatibility: string and object values hash salt + content, while byte arrays and streams hash content + salt. Do not change the order when reproducing hashes generated by older versions. Examples:

string salt = "randomSalt";
string hash1 = "hello world".GetMD5WithSalt(salt);
// or specific encoding type
string hash2 = "hello world".GetMD5WithSalt(salt, EncodingType.UTF8);

byte[] byteArray = Encoding.UTF8.GetBytes("Hello, World!");
byte[] saltBytes = Encoding.UTF8.GetBytes("randomSalt");
string hash = byteArray.GetMD5WithSalt(saltBytes);

BrasilModel obj = new BrasilModel() { Id = 1, Details = "Maior país da América do Sul" };
string salt = "randomSalt";
string hash = obj.GetMD5WithSalt(salt);

For a number, you can use:

string salt = "randomSalt";
string hash = myNumber.ToString().GetMD5WithSalt(salt);

Installation

You can install the library via NuGet package manager by searching for MD5 or by executing the following command in the Package Manager Console:

PM> Install-Package MD5

License

This library is licensed under the MIT License. See the LICENSE file for more details.

Contributions

Contributions to this library are welcome. Please open an issue or submit a pull request with your changes.