Component bdlde_sha1 [Package bdlde]

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

Namespaces
namespace	bdlde

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Security
  • 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:

Component bdlde_md5, Component 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. 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.

  bool validatePassword(const bsl::string_view&  password,
                        const bsl::string_view&  salt,
                        const unsigned char     *expected)
      // Return 'true' if the specified 'password' concatenated with the
      // specified 'salt' has a SHA-1 hash equal to the specified 'expected',
      // and 'false' otherwise.
  {
      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);
  }

  void assertPasswordIsExpected()
      // 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.
  {
      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));
  }