Changeset 102292 in vbox for trunk/include

Timestamp:

Nov 24, 2023 1:01:41 PM (14 months ago)

Author:

vboxsync

Message:

IPRT: Implemented SHA-crypt 256 / 512 variants, along with testcases. Needed for password hashing in cloud-init-based Linux installers [build fix, moved docs]. bugref:10551

File:

• trunk/include/iprt/crypto/shacrypt.h (modified) (1 diff)

trunk/include/iprt/crypto/shacrypt.h

@@ -52 +52 @@
 RT_C_DECLS_BEGIN
 
-RTDECL(int) RTShaCrypt256(const char *pszKey, const char *pszSalt, uint32_t cRounds, uint8_t pabHash[RTSHA256_HASH_SIZE]);
-RTDECL(int) RTShaCrypt256ToString(uint8_t abHash[RTSHA256_HASH_SIZE], const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
-RTDECL(int) RTShaCrypt512(const char *pszKey, const char *szSalt, uint32_t cRounds, uint8_t pabHash[RTSHA512_HASH_SIZE]);
-RTDECL(int) RTShaCrypt512ToString(uint8_t abHash[RTSHA512_HASH_SIZE], const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
+/**
+ * Calculates a SHAcrypt (SHA-256) digest.
+ *
+ * @returns VBox status code.
+ * @param   pszKey              Key (password) to use.
+ * @param   pszSalt             Salt to use.
+ *                              Must be >= RT_SHACRYPT_MIN_SALT_LEN and <= RT_SHACRYPT_MAX_SALT_LEN.
+ * @param   cRounds             Number of rounds to use.
+ * @param   pabHash             Where to return the hash on success.
+ *
+ * @note    This implements SHA-crypt.txt Version: 0.6 2016-8-31.
+ */
+RTR3DECL(int) RTShaCrypt256(const char *pszKey, const char *pszSalt, uint32_t cRounds, uint8_t pabHash[RTSHA256_HASH_SIZE]);
+
+/**
+ * Returns a SHAcrypt (SHA-256) digest as a printable scheme.
+ *
+ * @returns VBox status code.
+ * @param   pabHash             SHAcrypt (SHA-256) digest to return printable scheme for.
+ * @param   pszSalt             Salt to use. Must match the salt used when generating \a pabHash via RTSha256Crypt().
+ * @param   cRounds             Number of rounds used for generating \a pabHash.
+ * @param   pszString           Where to store the printable string on success.
+ * @param   cbString            Size (in bytes) of \a pszString.
+ *
+ * @note    This implements step 22 of SHA-crypt.txt Version: 0.6 2016-8-31.
+ */
+RTR3DECL(int) RTShaCrypt256ToString(uint8_t abHash[RTSHA256_HASH_SIZE], const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
+
+
+/**
+ * Calculates a SHAcrypt (SHA-512) digest.
+ *
+ * @returns VBox status code.
+ * @param   pszKey              Key (password) to use.
+ * @param   pszSalt             Salt to use.
+ *                              Must be >= RT_SHACRYPT_MIN_SALT_LEN and <= RT_SHACRYPT_MAX_SALT_LEN.
+ * @param   cRounds             Number of rounds to use.
+ * @param   pabHash             Where to return the hash on success.
+ *
+ * @note    This implements SHA-crypt.txt Version: 0.6 2016-8-31.
+ */
+RTR3DECL(int) RTShaCrypt512(const char *pszKey, const char *szSalt, uint32_t cRounds, uint8_t pabHash[RTSHA512_HASH_SIZE]);
+
+
+/**
+ * Returns a SHAcrypt (SHA-512) digest as a printable scheme.
+ *
+ * @returns VBox status code.
+ * @param   pabHash             SHAcrypt (SHA-512) digest to return printable scheme for.
+ * @param   pszSalt             Salt to use. Must match the salt used when generating \a pabHash via RTSha512Crypt().
+ * @param   cRounds             Number of rounds used for generating \a pabHash.
+ * @param   pszString           Where to store the printable string on success.
+ * @param   cbString            Size (in bytes) of \a pszString.
+ *
+ * @note    This implements step 22 of SHA-crypt.txt Version: 0.6 2016-8-31.
+ */
+RTR3DECL(int) RTShaCrypt512ToString(uint8_t abHash[RTSHA512_HASH_SIZE], const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
 
 RT_C_DECLS_END