1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
/** @file
* IPRT - Crypto - SHA-crypt.
*/
/*
* Copyright (C) 2023-2025 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#ifndef IPRT_INCLUDED_crypto_shacrypt_h
#define IPRT_INCLUDED_crypto_shacrypt_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/sha.h>
RT_C_DECLS_BEGIN
/** @defgroup grp_rt_crshacrypt RTCrShaCrypt - SHA-crypt
* @ingroup grp_rt_crypto
*
* This implements SHA-crypt.txt v0.6 (2016-08-31), which is a scheme to encrypt
* passwords using SHA-256 and SHA-512.
*
* @{
*/
/** Minimum salt string length for SHA-crypt (inclusive). */
#define RT_SHACRYPT_SALT_MIN_LEN 8
/** Maximum salt string length for SHA-crypt (inclusive). */
#define RT_SHACRYPT_SALT_MAX_LEN 16
/** Minimum number of rounds for SHA-crypt (inclusive). */
#define RT_SHACRYPT_ROUNDS_MIN 1000
/** Default number of rounds for SHA-crypt. */
#define RT_SHACRYPT_ROUNDS_DEFAULT 5000
/** Maximum number of rounds for SHA-crypt (inclusive). */
#define RT_SHACRYPT_ROUNDS_MAX 999999999
/** The maximum string length of a password encrypted with SHA-256
* (including the terminator). */
#define RT_SHACRYPT_256_MAX_SIZE 80
/** The maximum string length of a password encrypted with SHA-512.
* (including the terminator). */
#define RT_SHACRYPT_512_MAX_SIZE 123
/** The extended password '$ID$' part for SHA-256 encrypted passwords. */
#define RT_SHACRYPT_ID_STR_256 "$5$"
/** The extended password '$ID$' part for SHA-512 encrypted passwords. */
#define RT_SHACRYPT_ID_STR_512 "$6$"
/**
* Creates a randomized salt for the RTCrShaCryptXXX functions.
*
* @returns IPRT status code.
* @param pszSalt Where to return the generated salt string.
* @param cchSalt The length of the salt to generate. The buffer size is
* this value plus 1 (for the terminator character)!
*
* Must be in the range RT_SHACRYPT_MIN_SALT_LEN to
* RT_SHACRYPT_MAX_SALT_LEN (both inclusive).
*
* @warning Be very careful with the @a cchSalt parameter, as it must be at
* least one less than the actual buffer size!
*/
RTDECL(int) RTCrShaCryptGenerateSalt(char *pszSalt, size_t cchSalt);
/**
* Encrypts @a pszPhrase using SHA-256, @a pszSalt and @a cRounds.
*
* @returns IPRT status code.
* @param pszPhrase The passphrase (password) to encrypt.
* @param pszSalt Salt to use. This can either be a pure salt, like from
* RTCrShaCryptGenerateSalt(), or a 'password' string as
* generated by RTCrShaCrypt256ToString().
*
* The latter allows for easy password validation by
* comparing the encrypted string with the one stored in
* the passwd file.
*
* The length of the actual salt portion of the string must
* be within RT_SHACRYPT_MIN_SALT_LEN to
* RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
*
* @param cRounds Number of rounds to use, must be in the range
* RT_SHACRYPT_ROUNDS_MIN thru RT_SHACRYPT_ROUNDS_MAX.
* If unsure, use RT_SHACRYPT_ROUNDS_DEFAULT. This is
* ignored if the salt includes a 'rounds=xxx$' part.
* @param pszString Where to store the string on success.
* @param cbString The size of the buffer pointed to by @a pszString.
*
* The minimum length is 3 + salt + 1 + 43 + zero
* terminator. If a non-default @a cRounds value is used,
* add 8 + strlen(cRounds as decimal). The max buffer
* needed is 80 bytes (RT_SHACRYPT_256_MAX_SIZE).
*/
RTDECL(int) RTCrShaCrypt256(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
/**
* Encrypts @a pszPhrase using SHA-512, @a pszSalt and @a cRounds.
*
* @returns IPRT status code.
* @param pszPhrase The passphrase (password) to encrypt.
* @param pszSalt Salt to use. This can either be a pure salt, like from
* RTCrShaCryptGenerateSalt(), or a 'password' string as
* generated by RTCrShaCrypt512ToString().
*
* The latter allows for easy password validation by
* comparing the encrypted string with the one stored in
* the passwd file.
*
* The length of the actual salt portion of the string must
* be within RT_SHACRYPT_MIN_SALT_LEN to
* RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
*
* @param cRounds Number of rounds to use, must be in the range
* RT_SHACRYPT_ROUNDS_MIN thru RT_SHACRYPT_ROUNDS_MAX.
* If unsure, use RT_SHACRYPT_ROUNDS_DEFAULT. This is
* ignored if the salt includes a 'rounds=xxx$' part.
* @param pszString Where to store the string on success.
* @param cbString The size of the buffer pointed to by @a pszString.
*
* The minimum length is 3 + salt + 1 + 86 + zero
* terminator. If a non-default @a cRounds value is used,
* add 8 + strlen(cRounds as decimal). The max buffer
* needed is 123 bytes (RT_SHACRYPT_512_MAX_SIZE).
*/
RTDECL(int) RTCrShaCrypt512(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, char *pszString, size_t cbString);
/**
* Encrypts @a pszPhrase using SHA-256, @a pszSalt and @a cRounds, returning raw
* bytes.
*
* @returns IPRT status code.
* @param pszPhrase The passphrase (password) to encrypt.
* @param pszSalt Salt to use. This can either be a pure salt, like from
* RTCrShaCryptGenerateSalt(), or a 'password' string as
* generated by RTCrShaCrypt256ToString().
*
* The latter allows for easy password validation by
* comparing the encrypted string with the one stored in
* the passwd file.
*
* The length of the actual salt portion of the string must
* be within RT_SHACRYPT_MIN_SALT_LEN to
* RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
*
* @param cRounds Number of rounds to use, must be in the range
* RT_SHACRYPT_ROUNDS_MIN thru RT_SHACRYPT_ROUNDS_MAX.
* If unsure, use RT_SHACRYPT_ROUNDS_DEFAULT. This is
* ignored if the salt includes a 'rounds=xxx$' part.
* @param pabHash Where to return the hash on success.
* @see RTCrShaCrypt256, RTCrShaCrypt256ToString
*/
RTDECL(int) RTCrShaCrypt256Ex(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, uint8_t pabHash[RTSHA256_HASH_SIZE]);
/**
* Encrypts @a pszPhrase using SHA-512, @a pszSalt and @a cRounds, returning raw
* bytes.
*
* @returns IPRT status code.
* @param pszPhrase The passphrase (password) to encrypt.
* @param pszSalt Salt to use. This can either be a pure salt, like from
* RTCrShaCryptGenerateSalt(), or a 'password' string as
* generated by RTCrShaCrypt512ToString().
*
* The latter allows for easy password validation by
* comparing the encrypted string with the one stored in
* the passwd file.
*
* The length of the actual salt portion of the string must
* be within RT_SHACRYPT_MIN_SALT_LEN to
* RT_SHACRYPT_MAX_SALT_LEN, both inclusive.
*
* @param cRounds Number of rounds to use, must be in the range
* RT_SHACRYPT_ROUNDS_MIN thru RT_SHACRYPT_ROUNDS_MAX.
* If unsure, use RT_SHACRYPT_ROUNDS_DEFAULT. This is
* ignored if the salt includes a 'rounds=xxx$' part.
* @param pabHash Where to return the hash on success.
* @see RTCrShaCrypt512, RTCrShaCrypt512ToString
*/
RTDECL(int) RTCrShaCrypt512Ex(const char *pszPhrase, const char *pszSalt, uint32_t cRounds, uint8_t pabHash[RTSHA512_HASH_SIZE]);
/**
* Formats the RTCrShaCrypt256Ex() result and non-secret inputs using the
* extended password format.
*
* @returns IPRT status code.
* @param pabHash The result from RTCrShaCrypt256().
* @param pszSalt The salt used when producing @a pabHash.
* @param cRounds Number of rounds used for producing @a pabHash.
* @param pszString Where to store the string on success.
* @param cbString The size of the buffer pointed to by @a pszString.
*
* The minimum length is 3 + salt + 1 + 43 + zero
* terminator. If a non-default @a cRounds value is used,
* add 8 + strlen(cRounds as decimal). The max buffer
* needed is 80 bytes (RT_SHACRYPT_256_MAX_SIZE).
*
* @note This implements step 22 of SHA-crypt.txt v0.6.
* @see RTCrShaCrypt256Ex
*/
RTDECL(int) RTCrShaCrypt256ToString(uint8_t const pabHash[RTSHA256_HASH_SIZE], const char *pszSalt, uint32_t cRounds,
char *pszString, size_t cbString);
/**
* Formats the RTCrShaCrypt512Ex() result and non-secret inputs using the
* extended password format.
*
* @returns IPRT status code.
* @param pabHash The result from RTCrShaCrypt512().
* @param pszSalt The salt used when producing @a pabHash.
* @param cRounds Number of rounds used for producing @a pabHash.
* @param pszString Where to store the string on success.
* @param cbString The size of the buffer pointed to by @a pszString.
*
* The minimum length is 3 + salt + 1 + 86 + zero
* terminator. If a non-default @a cRounds value is used,
* add 8 + strlen(cRounds as decimal). The max buffer
* needed is 123 bytes (RT_SHACRYPT_512_MAX_SIZE).
*
* @note This implements step 22 of SHA-crypt.txt v0.6.
* @see RTCrShaCrypt512Ex
*/
RTDECL(int) RTCrShaCrypt512ToString(uint8_t const pabHash[RTSHA512_HASH_SIZE], const char *pszSalt, uint32_t cRounds,
char *pszString, size_t cbString);
/** @} */
RT_C_DECLS_END
#endif /* !IPRT_INCLUDED_crypto_shacrypt_h */
|
