bdlde_sha1

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Security
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a value-semantic type encoding a message in a SHA-1 digest.

Classes

• bdlde::Sha1: value-semantic type representing a SHA-1 digest

See also

bdlde_md5, bdlde_sha2

Description

This component provides the class bdlde::Sha1, which implements a mechanism for computing and updating a SHA-1 digest (a cryptographic hash). The specification for this is based on FIPS-180, which can be found at

https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf

Note that a SHA-1 digest does not aid in error correction.

Security

Practical collision and chosen-prefix collision attacks are known against SHA-1. Do not use SHA-1 to generate digital signatures under any circumstances, and do not use SHA-1 at all except when it is required for interoperation with legacy systems that use SHA-1. SHA-2 (available in the bdlde_sha2 component) and SHA-3 are more secure alternatives to SHA-1.

You might think that your application doesn't require collision resistance. However, (1) you might be mistaken, (2) once you start using SHA-1, you prevent future versions of your application from being able to rely on collision resistance unless they break backward compatibility, (3) a maintainer of your application might accidentally make a change that implicitly assumes collision resistance, and (4) if you expose SHA-1 hashes to your users, they might assume that they are secure digital signatures, which will make their applications insecure. In light of the foregoing considerations, and the availability of SHA-2 and SHA-3 as alternatives, there is no justification for using SHA-1 unless you absolutely have to.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

The validatePassword function below returns whether a specified password has a specified hash value. The assertPasswordIsExpected function below has a sample password to hash and a hash value that matches it. Note that the output of loadDigest is a binary representation. When hashes are displayed for human consumption, they are typically converted to hex, but that would create unnecessary overhead here. Also note that because SHA-1 digests are inexpensive to compute, they are vulnerable to brute force attacks and should not be used for password hashing in real-world applications. A function like validatePassword must only be used to validate passwords against previously computed SHA-1 hashes, and only during a transition period to a more secure password hashing function.

/// Return `true` if the specified `password` concatenated with the
/// specified `salt` has a SHA-1 hash equal to the specified `expected`,
/// and `false` otherwise.
bool validatePassword(const bsl::string_view&  password,
                      const bsl::string_view&  salt,
                      const unsigned char     *expected)
{
    bdlde::Sha1 hasher;
    hasher.update(password.data(), password.length());
    hasher.update(salt.data(), salt.length());
 
    unsigned char digest[bdlde::Sha1::k_DIGEST_SIZE];
    hasher.loadDigest(digest);
    return bsl::equal(bsl::begin(digest), bsl::end(digest), expected);
}
 
/// Asserts that the constant string `pass` salted with `word` has the
/// expected hash value.  In a real application, the expected hash would
/// likely come from some sort of database.
void assertPasswordIsExpected()
{
    const bsl::string   password = "pass";
    const bsl::string   salt     = "word";
    const unsigned char expected[bdlde::Sha1::k_DIGEST_SIZE] = {
        0x5B, 0xAA, 0x61, 0xE4, 0xC9, 0xB9, 0x3F, 0x3F, 0x06, 0x82,
        0x25, 0x0B, 0x6C, 0xF8, 0x33, 0x1B, 0x7E, 0xE6, 0x8F, 0xD8
    };
 
    ASSERT(validatePassword(password, salt, expected));
}