sha.h@ 60547

Last change on this file since 60547 was 57926, checked in by vboxsync, 9 years ago
IPRT: Doxygen clenaups (mostly).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 18.2 KB

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

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

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

Download in other formats: