VirtualBox

source: vbox/trunk/include/iprt/sha.h@ 77807

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 18.3 KB
Line 
1/** @file
2 * IPRT - SHA1 digest creation
3 */
4
5/*
6 * Copyright (C) 2009-2019 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef IPRT_INCLUDED_sha_h
27#define IPRT_INCLUDED_sha_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/types.h>
33
34RT_C_DECLS_BEGIN
35
36/** @defgroup grp_rt_sha RTSha - SHA Family of Hash Functions
37 * @ingroup grp_rt
38 * @{
39 */
40
41/** The size of a SHA-1 hash. */
42#define RTSHA1_HASH_SIZE 20
43/** The length of a SHA-1 digest string. The terminator is not included. */
44#define RTSHA1_DIGEST_LEN 40
45
46/**
47 * SHA-1 context.
48 */
49typedef union RTSHA1CONTEXT
50{
51 uint64_t u64BetterAlignment;
52 uint8_t abPadding[8 + (5 + 80) * 4 + 4];
53#ifdef RT_SHA1_PRIVATE_CONTEXT
54 SHA_CTX Private;
55#endif
56#ifdef RT_SHA1_PRIVATE_ALT_CONTEXT
57 RTSHA1ALTPRIVATECTX AltPrivate;
58#endif
59} RTSHA1CONTEXT;
60/** Pointer to an SHA-1 context. */
61typedef RTSHA1CONTEXT *PRTSHA1CONTEXT;
62
63/**
64 * Compute the SHA-1 hash of the data.
65 *
66 * @param pvBuf Pointer to the data.
67 * @param cbBuf The amount of data (in bytes).
68 * @param pabHash Where to store the hash. (What is passed is a pointer to
69 * the caller's buffer.)
70 */
71RTDECL(void) RTSha1(const void *pvBuf, size_t cbBuf, uint8_t pabHash[RTSHA1_HASH_SIZE]);
72
73/**
74 * Computes the SHA-1 hash for the given data comparing it with the one given.
75 *
76 * @returns true on match, false on mismatch.
77 * @param pvBuf Pointer to the data.
78 * @param cbBuf The amount of data (in bytes).
79 * @param pabHash The hash to verify. (What is passed is a pointer to the
80 * caller's buffer.)
81 */
82RTDECL(bool) RTSha1Check(const void *pvBuf, size_t cbBuf, uint8_t const pabHash[RTSHA1_HASH_SIZE]);
83
84/**
85 * Initializes the SHA-1 context.
86 *
87 * @param pCtx Pointer to the SHA-1 context.
88 */
89RTDECL(void) RTSha1Init(PRTSHA1CONTEXT pCtx);
90
91/**
92 * Feed data into the SHA-1 computation.
93 *
94 * @param pCtx Pointer to the SHA-1 context.
95 * @param pvBuf Pointer to the data.
96 * @param cbBuf The length of the data (in bytes).
97 */
98RTDECL(void) RTSha1Update(PRTSHA1CONTEXT pCtx, const void *pvBuf, size_t cbBuf);
99
100/**
101 * Compute the SHA-1 hash of the data.
102 *
103 * @param pCtx Pointer to the SHA-1 context.
104 * @param pabHash Where to store the hash. (What is passed is a pointer to
105 * the caller's buffer.)
106 */
107RTDECL(void) RTSha1Final(PRTSHA1CONTEXT pCtx, uint8_t pabHash[RTSHA1_HASH_SIZE]);
108
109/**
110 * Converts a SHA-1 hash to a digest string.
111 *
112 * @returns IPRT status code.
113 *
114 * @param pabHash The binary digest returned by RTSha1Final or RTSha1.
115 * @param pszDigest Where to return the stringified digest.
116 * @param cchDigest The size of the output buffer. Should be at least
117 * RTSHA1_DIGEST_LEN + 1 bytes.
118 */
119RTDECL(int) RTSha1ToString(uint8_t const pabHash[RTSHA1_HASH_SIZE], char *pszDigest, size_t cchDigest);
120
121/**
122 * Converts a SHA-1 hash to a digest string.
123 *
124 * @returns IPRT status code.
125 *
126 * @param pszDigest The stringified digest. Leading and trailing spaces are
127 * ignored.
128 * @param pabHash Where to store the hash. (What is passed is a pointer to
129 * the caller's buffer.)
130 */
131RTDECL(int) RTSha1FromString(char const *pszDigest, uint8_t pabHash[RTSHA1_HASH_SIZE]);
132
133/**
134 * Creates a SHA1 digest for the given memory buffer.
135 *
136 * @returns iprt status code.
137 *
138 * @param pvBuf Memory buffer to create a SHA1 digest for.
139 * @param cbBuf The amount of data (in bytes).
140 * @param ppszDigest On success the SHA1 digest.
141 * @param pfnProgressCallback optional callback for the progress indication
142 * @param pvUser user defined pointer for the callback
143 */
144RTR3DECL(int) RTSha1Digest(void* pvBuf, size_t cbBuf, char **ppszDigest, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
145
146/**
147 * Creates a SHA1 digest for the given file.
148 *
149 * @returns iprt status code.
150 *
151 * @param pszFile Filename to create a SHA1 digest for.
152 * @param ppszDigest On success the SHA1 digest.
153 * @param pfnProgressCallback optional callback for the progress indication
154 * @param pvUser user defined pointer for the callback
155 */
156RTR3DECL(int) RTSha1DigestFromFile(const char *pszFile, char **ppszDigest, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
157
158
159
160/** The size of a SHA-256 hash. */
161#define RTSHA256_HASH_SIZE 32
162/** The length of a SHA-256 digest string. The terminator is not included. */
163#define RTSHA256_DIGEST_LEN 64
164
165/**
166 * SHA-256 context.
167 */
168typedef union RTSHA256CONTEXT
169{
170 uint64_t u64BetterAlignment;
171 uint8_t abPadding[8 + (8 + 80) * 4];
172#ifdef RT_SHA256_PRIVATE_CONTEXT
173 SHA256_CTX Private;
174#endif
175#ifdef RT_SHA256_PRIVATE_ALT_CONTEXT
176 RTSHA256ALTPRIVATECTX AltPrivate;
177#endif
178} RTSHA256CONTEXT;
179/** Pointer to an SHA-256 context. */
180typedef RTSHA256CONTEXT *PRTSHA256CONTEXT;
181
182/**
183 * Compute the SHA-256 hash of the data.
184 *
185 * @param pvBuf Pointer to the data.
186 * @param cbBuf The amount of data (in bytes).
187 * @param pabHash Where to store the hash. (What is passed is a pointer to
188 * the caller's buffer.)
189 */
190RTDECL(void) RTSha256(const void *pvBuf, size_t cbBuf, uint8_t pabHash[RTSHA256_HASH_SIZE]);
191
192/**
193 * Computes the SHA-256 hash for the given data comparing it with the one given.
194 *
195 * @returns true on match, false on mismatch.
196 * @param pvBuf Pointer to the data.
197 * @param cbBuf The amount of data (in bytes).
198 * @param pabHash The hash to verify. (What is passed is a pointer to the
199 * caller's buffer.)
200 */
201RTDECL(bool) RTSha256Check(const void *pvBuf, size_t cbBuf, uint8_t const pabHash[RTSHA256_HASH_SIZE]);
202
203/**
204 * Initializes the SHA-256 context.
205 *
206 * @param pCtx Pointer to the SHA-256 context.
207 */
208RTDECL(void) RTSha256Init(PRTSHA256CONTEXT pCtx);
209
210/**
211 * Feed data into the SHA-256 computation.
212 *
213 * @param pCtx Pointer to the SHA-256 context.
214 * @param pvBuf Pointer to the data.
215 * @param cbBuf The length of the data (in bytes).
216 */
217RTDECL(void) RTSha256Update(PRTSHA256CONTEXT pCtx, const void *pvBuf, size_t cbBuf);
218
219/**
220 * Compute the SHA-256 hash of the data.
221 *
222 * @param pCtx Pointer to the SHA-256 context.
223 * @param pabHash Where to store the hash. (What is passed is a pointer to
224 * the caller's buffer.)
225 */
226RTDECL(void) RTSha256Final(PRTSHA256CONTEXT pCtx, uint8_t pabHash[RTSHA256_HASH_SIZE]);
227
228/**
229 * Converts a SHA-256 hash to a digest string.
230 *
231 * @returns IPRT status code.
232 *
233 * @param pabHash The binary digest returned by RTSha256Final or RTSha256.
234 * @param pszDigest Where to return the stringified digest.
235 * @param cchDigest The size of the output buffer. Should be at least
236 * RTSHA256_DIGEST_LEN + 1 bytes.
237 */
238RTDECL(int) RTSha256ToString(uint8_t const pabHash[RTSHA256_HASH_SIZE], char *pszDigest, size_t cchDigest);
239
240/**
241 * Converts a SHA-256 hash to a digest string.
242 *
243 * @returns IPRT status code.
244 *
245 * @param pszDigest The stringified digest. Leading and trailing spaces are
246 * ignored.
247 * @param pabHash Where to store the hash. (What is passed is a pointer to
248 * the caller's buffer.)
249 */
250RTDECL(int) RTSha256FromString(char const *pszDigest, uint8_t pabHash[RTSHA256_HASH_SIZE]);
251
252/**
253 * Creates a SHA256 digest for the given memory buffer.
254 *
255 * @returns iprt status code.
256 *
257 * @param pvBuf Memory buffer to create a
258 * SHA256 digest for.
259 * @param cbBuf The amount of data (in bytes).
260 * @param ppszDigest On success the SHA256 digest.
261 * @param pfnProgressCallback optional callback for the progress indication
262 * @param pvUser user defined pointer for the callback
263 */
264RTR3DECL(int) RTSha256Digest(void* pvBuf, size_t cbBuf, char **ppszDigest, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
265
266/**
267 * Creates a SHA256 digest for the given file.
268 *
269 * @returns iprt status code.
270 *
271 * @param pszFile Filename to create a SHA256
272 * digest for.
273 * @param ppszDigest On success the SHA256 digest.
274 * @param pfnProgressCallback optional callback for the progress indication
275 * @param pvUser user defined pointer for the callback
276 */
277RTR3DECL(int) RTSha256DigestFromFile(const char *pszFile, char **ppszDigest, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
278
279
280
281/** The size of a SHA-224 hash. */
282#define RTSHA224_HASH_SIZE 28
283/** The length of a SHA-224 digest string. The terminator is not included. */
284#define RTSHA224_DIGEST_LEN 56
285
286/** SHA-224 context (same as for SHA-256). */
287typedef RTSHA256CONTEXT RTSHA224CONTEXT;
288/** Pointer to an SHA-224 context. */
289typedef RTSHA256CONTEXT *PRTSHA224CONTEXT;
290
291/**
292 * Compute the SHA-224 hash of the data.
293 *
294 * @param pvBuf Pointer to the data.
295 * @param cbBuf The amount of data (in bytes).
296 * @param pabHash Where to store the hash. (What is passed is a pointer to
297 * the caller's buffer.)
298 */
299RTDECL(void) RTSha224(const void *pvBuf, size_t cbBuf, uint8_t pabHash[RTSHA224_HASH_SIZE]);
300
301/**
302 * Computes the SHA-224 hash for the given data comparing it with the one given.
303 *
304 * @returns true on match, false on mismatch.
305 * @param pvBuf Pointer to the data.
306 * @param cbBuf The amount of data (in bytes).
307 * @param pabHash The hash to verify. (What is passed is a pointer to the
308 * caller's buffer.)
309 */
310RTDECL(bool) RTSha224Check(const void *pvBuf, size_t cbBuf, uint8_t const pabHash[RTSHA224_HASH_SIZE]);
311
312/**
313 * Initializes the SHA-224 context.
314 *
315 * @param pCtx Pointer to the SHA-224 context.
316 */
317RTDECL(void) RTSha224Init(PRTSHA224CONTEXT pCtx);
318
319/**
320 * Feed data into the SHA-224 computation.
321 *
322 * @param pCtx Pointer to the SHA-224 context.
323 * @param pvBuf Pointer to the data.
324 * @param cbBuf The length of the data (in bytes).
325 */
326RTDECL(void) RTSha224Update(PRTSHA224CONTEXT pCtx, const void *pvBuf, size_t cbBuf);
327
328/**
329 * Compute the SHA-224 hash of the data.
330 *
331 * @param pCtx Pointer to the SHA-224 context.
332 * @param pabHash Where to store the hash. (What is passed is a pointer to
333 * the caller's buffer.)
334 */
335RTDECL(void) RTSha224Final(PRTSHA224CONTEXT pCtx, uint8_t pabHash[RTSHA224_HASH_SIZE]);
336
337/**
338 * Converts a SHA-224 hash to a digest string.
339 *
340 * @returns IPRT status code.
341 *
342 * @param pabHash The binary digest returned by RTSha224Final or RTSha224.
343 * @param pszDigest Where to return the stringified digest.
344 * @param cchDigest The size of the output buffer. Should be at least
345 * RTSHA224_DIGEST_LEN + 1 bytes.
346 */
347RTDECL(int) RTSha224ToString(uint8_t const pabHash[RTSHA224_HASH_SIZE], char *pszDigest, size_t cchDigest);
348
349/**
350 * Converts a SHA-224 hash to a digest string.
351 *
352 * @returns IPRT status code.
353 *
354 * @param pszDigest The stringified digest. Leading and trailing spaces are
355 * ignored.
356 * @param pabHash Where to store the hash. (What is passed is a pointer to
357 * the caller's buffer.)
358 */
359RTDECL(int) RTSha224FromString(char const *pszDigest, uint8_t pabHash[RTSHA224_HASH_SIZE]);
360
361/**
362 * Creates a SHA224 digest for the given memory buffer.
363 *
364 * @returns iprt status code.
365 *
366 * @param pvBuf Memory buffer to create a SHA224 digest for.
367 * @param cbBuf The amount of data (in bytes).
368 * @param ppszDigest On success the SHA224 digest.
369 * @param pfnProgressCallback optional callback for the progress indication
370 * @param pvUser user defined pointer for the callback
371 */
372RTR3DECL(int) RTSha224Digest(void* pvBuf, size_t cbBuf, char **ppszDigest, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
373
374/**
375 * Creates a SHA224 digest for the given file.
376 *
377 * @returns iprt status code.
378 *
379 * @param pszFile Filename to create a SHA224 digest for.
380 * @param ppszDigest On success the SHA224 digest.
381 * @param pfnProgressCallback optional callback for the progress indication
382 * @param pvUser user defined pointer for the callback
383 */
384RTR3DECL(int) RTSha224DigestFromFile(const char *pszFile, char **ppszDigest, PFNRTPROGRESS pfnProgressCallback, void *pvUser);
385
386
387
388/** The size of a SHA-512 hash. */
389#define RTSHA512_HASH_SIZE 64
390/** The length of a SHA-512 digest string. The terminator is not included. */
391#define RTSHA512_DIGEST_LEN 128
392
393/**
394 * SHA-512 context.
395 */
396typedef union RTSHA512CONTEXT
397{
398 uint64_t u64BetterAlignment;
399 uint8_t abPadding[16 + (80 + 8) * 8];
400#ifdef RT_SHA512_PRIVATE_CONTEXT
401 SHA512_CTX Private;
402#endif
403#ifdef RT_SHA512_PRIVATE_ALT_CONTEXT
404 RTSHA512ALTPRIVATECTX AltPrivate;
405#endif
406} RTSHA512CONTEXT;
407/** Pointer to an SHA-512 context. */
408typedef RTSHA512CONTEXT *PRTSHA512CONTEXT;
409
410/**
411 * Compute the SHA-512 hash of the data.
412 *
413 * @param pvBuf Pointer to the data.
414 * @param cbBuf The amount of data (in bytes).
415 * @param pabHash Where to store the hash. (What is passed is a pointer to
416 * the caller's buffer.)
417 */
418RTDECL(void) RTSha512(const void *pvBuf, size_t cbBuf, uint8_t pabHash[RTSHA512_HASH_SIZE]);
419
420/**
421 * Computes the SHA-512 hash for the given data comparing it with the one given.
422 *
423 * @returns true on match, false on mismatch.
424 * @param pvBuf Pointer to the data.
425 * @param cbBuf The amount of data (in bytes).
426 * @param pabHash The hash to verify. (What is passed is a pointer to the
427 * caller's buffer.)
428 */
429RTDECL(bool) RTSha512Check(const void *pvBuf, size_t cbBuf, uint8_t const pabHash[RTSHA512_HASH_SIZE]);
430
431/**
432 * Initializes the SHA-512 context.
433 *
434 * @param pCtx Pointer to the SHA-512 context.
435 */
436RTDECL(void) RTSha512Init(PRTSHA512CONTEXT pCtx);
437
438/**
439 * Feed data into the SHA-512 computation.
440 *
441 * @param pCtx Pointer to the SHA-512 context.
442 * @param pvBuf Pointer to the data.
443 * @param cbBuf The length of the data (in bytes).
444 */
445RTDECL(void) RTSha512Update(PRTSHA512CONTEXT pCtx, const void *pvBuf, size_t cbBuf);
446
447/**
448 * Compute the SHA-512 hash of the data.
449 *
450 * @param pCtx Pointer to the SHA-512 context.
451 * @param pabHash Where to store the hash. (What is passed is a pointer to
452 * the caller's buffer.)
453 */
454RTDECL(void) RTSha512Final(PRTSHA512CONTEXT pCtx, uint8_t pabHash[RTSHA512_HASH_SIZE]);
455
456/**
457 * Converts a SHA-512 hash to a digest string.
458 *
459 * @returns IPRT status code.
460 *
461 * @param pabHash The binary digest returned by RTSha512Final or RTSha512.
462 * @param pszDigest Where to return the stringified digest.
463 * @param cchDigest The size of the output buffer. Should be at least
464 * RTSHA512_DIGEST_LEN + 1 bytes.
465 */
466RTDECL(int) RTSha512ToString(uint8_t const pabHash[RTSHA512_HASH_SIZE], char *pszDigest, size_t cchDigest);
467
468/**
469 * Converts a SHA-512 hash to a digest string.
470 *
471 * @returns IPRT status code.
472 *
473 * @param pszDigest The stringified digest. Leading and trailing spaces are
474 * ignored.
475 * @param pabHash Where to store the hash. (What is passed is a pointer to
476 * the caller's buffer.)
477 */
478RTDECL(int) RTSha512FromString(char const *pszDigest, uint8_t pabHash[RTSHA512_HASH_SIZE]);
479
480
481/** Macro for declaring the interface for a SHA-512 variation.
482 * @internal */
483#define RTSHA512_DECLARE_VARIANT(a_Name, a_UName) \
484 typedef RTSHA512CONTEXT RT_CONCAT3(RTSHA,a_UName,CONTEXT); \
485 typedef RTSHA512CONTEXT *RT_CONCAT3(PRTSHA,a_UName,CONTEXT); \
486 RTDECL(void) RT_CONCAT(RTSha,a_Name)(const void *pvBuf, size_t cbBuf, uint8_t pabHash[RT_CONCAT3(RTSHA,a_UName,_HASH_SIZE)]); \
487 RTDECL(bool) RT_CONCAT3(RTSha,a_Name,Check)(const void *pvBuf, size_t cbBuf, uint8_t const pabHash[RT_CONCAT3(RTSHA,a_UName,_HASH_SIZE)]); \
488 RTDECL(void) RT_CONCAT3(RTSha,a_Name,Init)(RT_CONCAT3(PRTSHA,a_UName,CONTEXT) pCtx); \
489 RTDECL(void) RT_CONCAT3(RTSha,a_Name,Update)(RT_CONCAT3(PRTSHA,a_UName,CONTEXT) pCtx, const void *pvBuf, size_t cbBuf); \
490 RTDECL(void) RT_CONCAT3(RTSha,a_Name,Final)(RT_CONCAT3(PRTSHA,a_UName,CONTEXT) pCtx, uint8_t pabHash[RT_CONCAT3(RTSHA,a_UName,_HASH_SIZE)]); \
491 RTDECL(int) RT_CONCAT3(RTSha,a_Name,ToString)(uint8_t const pabHash[RT_CONCAT3(RTSHA,a_UName,_HASH_SIZE)], char *pszDigest, size_t cchDigest); \
492 RTDECL(int) RT_CONCAT3(RTSha,a_Name,FromString)(char const *pszDigest, uint8_t pabHash[RT_CONCAT3(RTSHA,a_UName,_HASH_SIZE)])
493
494
495/** The size of a SHA-384 hash. */
496#define RTSHA384_HASH_SIZE 48
497/** The length of a SHA-384 digest string. The terminator is not included. */
498#define RTSHA384_DIGEST_LEN 96
499RTSHA512_DECLARE_VARIANT(384,384);
500
501/** The size of a SHA-512/224 hash. */
502#define RTSHA512T224_HASH_SIZE 28
503/** The length of a SHA-512/224 digest string. The terminator is not
504 * included. */
505#define RTSHA512T224_DIGEST_LEN 56
506RTSHA512_DECLARE_VARIANT(512t224,512T224);
507
508/** The size of a SHA-512/256 hash. */
509#define RTSHA512T256_HASH_SIZE 32
510/** The length of a SHA-512/256 digest string. The terminator is not
511 * included. */
512#define RTSHA512T256_DIGEST_LEN 64
513RTSHA512_DECLARE_VARIANT(512t256,512T256);
514
515
516/** @} */
517
518RT_C_DECLS_END
519
520#endif /* !IPRT_INCLUDED_sha_h */
521
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle
Contact – Privacy/Do Not Sell My Info – Terms of Use