sha.h@ 76585

Last change on this file since 76585 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
34	RT_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	*/
49	typedef 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. */
61	typedef 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	*/
71	RTDECL(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	*/
82	RTDECL(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	*/
89	RTDECL(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	*/
98	RTDECL(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	*/
107	RTDECL(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	*/
119	RTDECL(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	*/
131	RTDECL(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	*/
144	RTR3DECL(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	*/
156	RTR3DECL(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	*/
168	typedef 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. */
180	typedef 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	*/
190	RTDECL(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	*/
201	RTDECL(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	*/
208	RTDECL(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	*/
217	RTDECL(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	*/
226	RTDECL(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	*/
238	RTDECL(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	*/
250	RTDECL(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	*/
264	RTR3DECL(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	*/
277	RTR3DECL(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). */
287	typedef RTSHA256CONTEXT RTSHA224CONTEXT;
288	/** Pointer to an SHA-224 context. */
289	typedef 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	*/
299	RTDECL(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	*/
310	RTDECL(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	*/
317	RTDECL(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	*/
326	RTDECL(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	*/
335	RTDECL(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	*/
347	RTDECL(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	*/
359	RTDECL(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	*/
372	RTR3DECL(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	*/
384	RTR3DECL(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	*/
396	typedef 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. */
408	typedef 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	*/
418	RTDECL(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	*/
429	RTDECL(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	*/
436	RTDECL(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	*/
445	RTDECL(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	*/
454	RTDECL(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	*/
466	RTDECL(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	*/
478	RTDECL(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
499	RTSHA512_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
506	RTSHA512_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
513	RTSHA512_DECLARE_VARIANT(512t256,512T256);
514
515
516	/** @} */
517
518	RT_C_DECLS_END
519
520	#endif /* !IPRT_INCLUDED_sha_h */
521

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: