VirtualBox

Changeset 102488 in vbox for trunk/include


Ignore:
Timestamp:
Dec 5, 2023 11:53:09 PM (16 months ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
160631
Message:

IPRT,Main/Unattended: Added a simplified API for the SHAcrypt functionality (the two step approach isn't really something we'll be needing). Corrected documentation, added constant for max output size (RTSHA512_HASH_SIZE*4 isn't a good choice) and whatnot. Added missing round count range checks. Fixed rounding error in output string buffer requirements; actually replacing the whole stuff by just calculating the size upfront before formatting anything. bugref:10551

Location:
trunk/include/iprt
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/crypto/shacrypt.h

    r102375 r102488  
    4545RT_C_DECLS_BEGIN
    4646
    47 /** @defgroup grp_rt_crshacrypt   RTCrShaCrypt - SHAcrypt functions
    48  * @ingroup grp_rt
     47/** @defgroup grp_rt_crshacrypt   RTCrShaCrypt - SHA-crypt
     48 * @ingroup grp_rt_crypto
     49 *
     50 * This implements SHA-crypt.txt v0.6 (2016-08-31), which is a scheme to encrypt
     51 * passwords using SHA-256 and SHA-512.
     52 *
    4953 * @{
    5054 */
    5155
    52 /** Default number of rounds for SHA-crypt 256/512. */
    53 #define RT_SHACRYPT_DEFAULT_ROUNDS 5000
    54 /** Minimum salt length (in bytes) for SHA-crypt 256/512. */
    55 #define RT_SHACRYPT_MIN_SALT_LEN   8
    56 /** Maximum salt length (in bytes) for SHA-crypt 256/512. */
    57 #define RT_SHACRYPT_MAX_SALT_LEN   16
     56/** Minimum salt string length for SHA-crypt (inclusive). */
     57#define RT_SHACRYPT_SALT_MIN_LEN        8
     58/** Maximum salt string length for SHA-crypt (inclusive). */
     59#define RT_SHACRYPT_SALT_MAX_LEN        16
     60
     61
     62/** Minimum number of rounds for SHA-crypt (inclusive). */
     63#define RT_SHACRYPT_ROUNDS_MIN          1000
     64/** Default number of rounds for SHA-crypt. */
     65#define RT_SHACRYPT_ROUNDS_DEFAULT      5000
     66/** Maximum number of rounds for SHA-crypt (inclusive). */
     67#define RT_SHACRYPT_ROUNDS_MAX          999999999
     68
     69
     70/** The maximum string length of a password encrypted with SHA-256
     71 * (including the terminator). */
     72#define RT_SHACRYPT_256_MAX_SIZE        80
     73/** The maximum string length of a password encrypted with SHA-512.
     74 * (including the terminator). */
     75#define RT_SHACRYPT_512_MAX_SIZE        123
     76
     77
     78/** The extended password '$ID$' part for SHA-256 encrypted passwords. */
     79#define RT_SHACRYPT_ID_STR_256          "$5$"
     80/** The extended password '$ID$' part for SHA-512 encrypted passwords. */
     81#define RT_SHACRYPT_ID_STR_512          "$6$"
    5882
    5983
    … …  
    6286 *
    6387 * @returns IPRT status code.
    64  * @param   pszSalt     Where to store the generated salt.
    65  * @param   cchSalt     Size of \a pszSalt.
    66  *                      Also marks the number of characters the generated salt should use.
    67  *                      Must be >= RT_SHACRYPT_MIN_SALT_LEN and <= RT_SHACRYPT_MAX_SALT_LEN.
    68  */
    69 RTR3DECL(int) RTCrShaCryptGenerateSalt(char *pszSalt, size_t cchSalt);
    70 
    71 
    72 /**
    73  * Calculates a SHAcrypt (SHA-256) digest.
    74  *
    75  * @returns IPRT status code.
    76  * @param   pszKey              Key (password) to use.
    77  * @param   pszSalt             Salt to use.
    78  *                              Must be >= RT_SHACRYPT_MIN_SALT_LEN and <= RT_SHACRYPT_MAX_SALT_LEN.
    79  *
    80  *                              This parameter also accepts crypted password strings produced by RTCrShaCrypt256ToString().
    81  *
    82  *                              This approach is used by many *crypt implementations -- it allows feeding the user-provided
    83  *                              password and the crypted password from "the password file" to the function. If it returns the
    84  *                              same crypted password then the user-provided password must be the correct one.
    85  * @param   cRounds             Number of rounds to use. @sa RT_SHACRYPT_DEFAULT_ROUNDS
    86  * @param   abHash              Where to return the hash on success.
    87  *
    88  * @note    This implements SHA-crypt.txt Version: 0.6 2016-8-31.
    89  */
    90 RTR3DECL(int) RTCrShaCrypt256(const char *pszKey, const char *pszSalt, uint32_t cRounds, uint8_t abHash[RTSHA256_HASH_SIZE]);
    91 
    92 
    93 /**
    94  * Returns a SHAcrypt (SHA-256) digest as a printable scheme.
    95  *
    96  * @returns IPRT status code.
    97  * @param   abHash              SHAcrypt (SHA-256) digest to return printable scheme for.
    98  * @param   pszSalt             Salt to use. Must match the salt used when generating \a pabHash via RTSha256Crypt().
    99  * @param   cRounds             Number of rounds used for generating \a pabHash.
    100  * @param   pszString           Where to store the printable string on success.
    101  * @param   cchString           Size of \a pszString.
    102  *                              Should be at least RTSHA256_DIGEST_LEN + 1 bytes.
    103  *
    104  * @note    This implements step 22 of SHA-crypt.txt Version: 0.6 2016-8-31.
    105  */
    106 RTR3DECL(int) RTCrShaCrypt256ToString(uint8_t abHash[RTSHA256_HASH_SIZE], const char *pszSalt, uint32_t cRounds, char *pszString, size_t cchString);
    107 
    108 
    109 /**
    110  * Calculates a SHAcrypt (SHA-512) digest.
    111  *
    112  * @returns IPRT status code.
    113  * @param   pszKey              Key (password) to use.
    114  * @param   pszSalt             Salt to use.
    115  *                              Must be >= RT_SHACRYPT_MIN_SALT_LEN and <= RT_SHACRYPT_MAX_SALT_LEN.
    116  *
    117  *                              This parameter also accepts crypted password strings produced by RTCrShaCrypt512ToString().
    118  *
    119  *                              This approach is used by many *crypt implementations -- it allows feeding the user-provided
    120  *                              password and the crypted password from "the password file" to the function. If it returns the
    121  *                              same crypted password then the user-provided password must be the correct one.
    122  * @param   cRounds             Number of rounds to use. @sa RT_SHACRYPT_DEFAULT_ROUNDS
    123  * @param   abHash              Where to return the hash on success.
    124  *
    125  * @note    This implements SHA-crypt.txt Version: 0.6 2016-8-31.
    126  */
    127 RTR3DECL(int) RTCrShaCrypt512(const char *pszKey, const char *pszSalt, uint32_t cRounds, uint8_t abHash[RTSHA512_HASH_SIZE]);
    128 
    129 
    130 /**
    131  * Returns a SHAcrypt (SHA-512) digest as a printable scheme.
    132  *
    133  * @returns IPRT status code.
    134  * @param   abHash              SHAcrypt (SHA-512) digest to return printable scheme for.
    135  * @param   pszSalt             Salt to use. Must match the salt used when generating \a pabHash via RTSha512Crypt().
    136  * @param   cRounds             Number of rounds used for generating \a pabHash.
    137  * @param   pszString           Where to store the printable string on success.
    138  * @param   cchString           Size of \a pszString.
    139  *                              Should be at least RTSHA512_DIGEST_LEN + 1 bytes.
    140  *
    141  * @note    This implements step 22 of SHA-crypt.txt Version: 0.6 2016-8-31.
    142  */
    143 RTR3DECL(int) RTCrShaCrypt512ToString(uint8_t abHash[RTSHA512_HASH_SIZE], const char *pszSalt, uint32_t cRounds, char *pszString, size_t cchString);
     88 * @param   pszSalt     Where to return the generated salt string.
     89 * @param   cchSalt     The length of the salt to generate.  The buffer size is
     90 *                      this value plus 1 (for the terminator character)!
     91 *
     92 *                      Must be in the range RT_SHACRYPT_MIN_SALT_LEN to
     93 *                      RT_SHACRYPT_MAX_SALT_LEN (both inclusive).
     94 *
     95 * @warning Be very careful with the @a cchSalt parameter, as it must be at
     96 *          least one less than the actual buffer size!
     97 */
     98RTDECL(int) RTCrShaCryptGenerateSalt(char *pszSalt, size_t cchSalt);
     99
     100/**
     101 * Encrypts @a pszPhrase using SHA-256, @a pszSalt and @a cRounds.
     102 *
     103 * @returns IPRT status code.
     104 * @param   pszPhrase   The passphrase (password) to encrypt.
     105 * @param   pszSalt     Salt to use.  This can either be a pure salt, like from
     106 *                      RTCrShaCryptGenerateSalt(), or a 'password' string as
     107 *                      generated by RTCrShaCrypt256ToString().
     108 *
     109 *                      The latter allows for easy password validation by
     110 *                      comparing the encrypted string with the one stored in
     111 *                      the passwd file.
     112 *
     113 *                      The length of the actual salt portion of the string must
     114 *                      be within RT_SHACRYPT_MIN_SALT_LEN to
     115 *                      RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
     116 *
     117 * @param   cRounds     Number of rounds to use (@see
     118 *                      RT_SHACRYPT_ROUNDS_DEFAULT).  This is ignored if the
     119 *                      salt includes a 'rounds=xxx$' part.
     120 * @param   pszString   Where to store the string on success.
     121 * @param   cbString    The size of the buffer pointed to by @a pszString.
     122 *
     123 *                      The minimum length is 3 + salt + 1 + 43 + zero
     124 *                      terminator.  If a non-default @a cRounds value is used,
     125 *                      add 8 + strlen(cRounds as decimal). The max buffer
     126 *                      needed is 80 bytes (RT_SHACRYPT_256_MAX_SIZE).
     127 */
     128RTDECL(int) RTCrShaCrypt256(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
     129
     130/**
     131 * Encrypts @a pszPhrase using SHA-512, @a pszSalt and @a cRounds.
     132 *
     133 * @returns IPRT status code.
     134 * @param   pszPhrase   The passphrase (password) to encrypt.
     135 * @param   pszSalt     Salt to use.  This can either be a pure salt, like from
     136 *                      RTCrShaCryptGenerateSalt(), or a 'password' string as
     137 *                      generated by RTCrShaCrypt512ToString().
     138 *
     139 *                      The latter allows for easy password validation by
     140 *                      comparing the encrypted string with the one stored in
     141 *                      the passwd file.
     142 *
     143 *                      The length of the actual salt portion of the string must
     144 *                      be within RT_SHACRYPT_MIN_SALT_LEN to
     145 *                      RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
     146 *
     147 * @param   pszString   Where to store the string on success.
     148 * @param   cbString    The size of the buffer pointed to by @a pszString.
     149 *
     150 *                      The minimum length is 3 + salt + 1 + 86 + zero
     151 *                      terminator. If a non-default @a cRounds value is used,
     152 *                      add 8 + strlen(cRounds as decimal). The max buffer
     153 *                      needed is 123 bytes (RT_SHACRYPT_512_MAX_SIZE).
     154 */
     155RTDECL(int) RTCrShaCrypt512(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
     156
     157
     158
     159/**
     160 * Encrypts @a pszPhrase using SHA-256, @a pszSalt and @a cRounds, returning raw
     161 * bytes.
     162 *
     163 * @returns IPRT status code.
     164 * @param   pszPhrase   The passphrase (password) to encrypt.
     165 * @param   pszSalt     Salt to use.  This can either be a pure salt, like from
     166 *                      RTCrShaCryptGenerateSalt(), or a 'password' string as
     167 *                      generated by RTCrShaCrypt256ToString().
     168 *
     169 *                      The latter allows for easy password validation by
     170 *                      comparing the encrypted string with the one stored in
     171 *                      the passwd file.
     172 *
     173 *                      The length of the actual salt portion of the string must
     174 *                      be within RT_SHACRYPT_MIN_SALT_LEN to
     175 *                      RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
     176 *
     177 * @param   cRounds     Number of rounds to use (@see
     178 *                      RT_SHACRYPT_ROUNDS_DEFAULT).
     179 * @param   pabHash     Where to return the hash on success.
     180 * @see     RTCrShaCrypt256, RTCrShaCrypt256ToString
     181 */
     182RTDECL(int) RTCrShaCrypt256Ex(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, uint8_t pabHash[RTSHA256_HASH_SIZE]);
     183
     184
     185/**
     186 * Encrypts @a pszPhrase using SHA-512, @a pszSalt and @a cRounds, returning raw
     187 * bytes.
     188 *
     189 * @returns IPRT status code.
     190 * @param   pszPhrase   The passphrase (password) to encrypt.
     191 * @param   pszSalt     Salt to use.  This can either be a pure salt, like from
     192 *                      RTCrShaCryptGenerateSalt(), or a 'password' string as
     193 *                      generated by RTCrShaCrypt512ToString().
     194 *
     195 *                      The latter allows for easy password validation by
     196 *                      comparing the encrypted string with the one stored in
     197 *                      the passwd file.
     198 *
     199 *                      The length of the actual salt portion of the string must
     200 *                      be within RT_SHACRYPT_MIN_SALT_LEN to
     201 *                      RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
     202 *
     203 * @param   cRounds     Number of rounds to use (@see
     204 *                      RT_SHACRYPT_ROUNDS_DEFAULT).
     205 * @param   pabHash     Where to return the hash on success.
     206 * @see     RTCrShaCrypt512, RTCrShaCrypt512ToString
     207 */
     208RTDECL(int) RTCrShaCrypt512Ex(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, uint8_t pabHash[RTSHA512_HASH_SIZE]);
     209
     210/**
     211 * Formats the RTCrShaCrypt256Ex() result and non-secret inputs using the
     212 * extended password format.
     213 *
     214 * @returns IPRT status code.
     215 * @param   pabHash     The result from RTCrShaCrypt256().
     216 * @param   pszSalt     The salt used when producing @a pabHash.
     217 * @param   cRounds     Number of rounds used for producing @a pabHash.
     218 * @param   pszString   Where to store the string on success.
     219 * @param   cbString    The size of the buffer pointed to by @a pszString.
     220 *
     221 *                      The minimum length is 3 + salt + 1 + 43 + zero
     222 *                      terminator.  If a non-default @a cRounds value is used,
     223 *                      add 8 + strlen(cRounds as decimal). The max buffer
     224 *                      needed is 80 bytes (RT_SHACRYPT_256_MAX_SIZE).
     225 *
     226 * @note    This implements step 22 of SHA-crypt.txt v0.6.
     227 * @see     RTCrShaCrypt256Ex
     228 */
     229RTDECL(int) RTCrShaCrypt256ToString(uint8_t const pabHash[RTSHA256_HASH_SIZE], const char *pszSalt, uint32_t cRounds,
     230                                    char *pszString, size_t cbString);
     231
     232/**
     233 * Formats the RTCrShaCrypt512Ex() result and non-secret inputs using the
     234 * extended password format.
     235 *
     236 * @returns IPRT status code.
     237 * @param   pabHash     The result from RTCrShaCrypt512().
     238 * @param   pszSalt     The salt used when producing @a pabHash.
     239 * @param   cRounds     Number of rounds used for producing @a pabHash.
     240 * @param   pszString   Where to store the string on success.
     241 * @param   cbString    The size of the buffer pointed to by @a pszString.
     242 *
     243 *                      The minimum length is 3 + salt + 1 + 86 + zero
     244 *                      terminator. If a non-default @a cRounds value is used,
     245 *                      add 8 + strlen(cRounds as decimal). The max buffer
     246 *                      needed is 123 bytes (RT_SHACRYPT_512_MAX_SIZE).
     247 *
     248 * @note    This implements step 22 of SHA-crypt.txt v0.6.
     249 * @see     RTCrShaCrypt512Ex
     250 */
     251RTDECL(int) RTCrShaCrypt512ToString(uint8_t const pabHash[RTSHA512_HASH_SIZE], const char *pszSalt, uint32_t cRounds,
     252                                    char *pszString, size_t cbString);
    144253
    145254/** @} */

  • trunk/include/iprt/mangling.h

    r102360 r102488  
    37363736# define RTCrShaCryptGenerateSalt                       RT_MANGLER(RTCrShaCryptGenerateSalt)
    37373737# define RTCrShaCrypt256                                RT_MANGLER(RTCrShaCrypt256)
     3738# define RTCrShaCrypt256Ex                              RT_MANGLER(RTCrShaCrypt256Ex)
    37383739# define RTCrShaCrypt256ToString                        RT_MANGLER(RTCrShaCrypt256ToString)
    37393740# define RTCrShaCrypt512                                RT_MANGLER(RTCrShaCrypt512)
     3741# define RTCrShaCrypt512Ex                              RT_MANGLER(RTCrShaCrypt512Ex)
    37403742# define RTCrShaCrypt512ToString                        RT_MANGLER(RTCrShaCrypt512ToString)
    37413743# define RTCrSpcAttributeTypeAndOptionalValue_SetPeImage RT_MANGLER(RTCrSpcAttributeTypeAndOptionalValue_SetPeImage)
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette