xref: /trunk/main/sal/inc/rtl/digest.h (revision b9fd132d)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef _RTL_DIGEST_H_
25 #define _RTL_DIGEST_H_ "$Revision$"
26 
27 #include <sal/types.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /*========================================================================
34  *
35  * rtlDigest.
36  *
37  *======================================================================*/
38 /** Digest Handle opaque type.
39  */
40 typedef void* rtlDigest;
41 
42 
43 /** Digest Algorithm enumeration.
44     @see rtl_digest_create()
45  */
46 enum __rtl_DigestAlgorithm
47 {
48 	rtl_Digest_AlgorithmMD2,
49 	rtl_Digest_AlgorithmMD5,
50 	rtl_Digest_AlgorithmSHA,
51 	rtl_Digest_AlgorithmSHA1,
52 
53 	rtl_Digest_AlgorithmHMAC_MD5,
54 	rtl_Digest_AlgorithmHMAC_SHA1,
55 
56 	rtl_Digest_AlgorithmInvalid,
57 	rtl_Digest_Algorithm_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
58 };
59 
60 /** Digest Algorithm type.
61  */
62 typedef enum __rtl_DigestAlgorithm rtlDigestAlgorithm;
63 
64 
65 /** Error Code enumeration.
66  */
67 enum __rtl_DigestError
68 {
69 	rtl_Digest_E_None,
70 	rtl_Digest_E_Argument,
71 	rtl_Digest_E_Algorithm,
72 	rtl_Digest_E_BufferSize,
73 	rtl_Digest_E_Memory,
74 	rtl_Digest_E_Unknown,
75 	rtl_Digest_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
76 };
77 
78 /** Error Code type.
79  */
80 typedef enum __rtl_DigestError rtlDigestError;
81 
82 
83 /** Create a digest handle for the given algorithm.
84     @see rtlDigestAlgorithm
85 
86 	@param  Algorithm [in] digest algorithm.
87 	@return Digest handle, or 0 upon failure.
88  */
89 rtlDigest SAL_CALL rtl_digest_create  (
90 	rtlDigestAlgorithm Algorithm
91 ) SAL_THROW_EXTERN_C();
92 
93 
94 /** Destroy a digest handle.
95 	@postcond Digest handle destroyed and invalid.
96     @param    Digest [in] digest handle to be destroyed.
97 	@return   None.
98  */
99 void SAL_CALL rtl_digest_destroy (
100 	rtlDigest Digest
101 ) SAL_THROW_EXTERN_C();
102 
103 
104 /** Query the algorithm of a given digest.
105     @param  Digest [in] digest handle.
106 	@return digest algorithm, or rtl_Digest_AlgorithmInvalid upon failure.
107  */
108 rtlDigestAlgorithm SAL_CALL rtl_digest_queryAlgorithm (
109 	rtlDigest Digest
110 ) SAL_THROW_EXTERN_C();
111 
112 
113 /** Query the length of a given digest.
114     @param  Digest [in] digest handle.
115 	@return digest length, or 0 upon failure.
116  */
117 sal_uInt32 SAL_CALL rtl_digest_queryLength (
118 	rtlDigest Digest
119 ) SAL_THROW_EXTERN_C();
120 
121 
122 /** Initialize a digest with given data.
123     @param  Digest  [in] digest handle.
124 	@param  pData   [in] data buffer.
125 	@param  nDatLen [in] data length.
126 
127 	@return rtl_Digest_E_None upon success.
128  */
129 rtlDigestError SAL_CALL rtl_digest_init (
130 	rtlDigest Digest,
131 	const sal_uInt8 *pData, sal_uInt32 nDatLen
132 ) SAL_THROW_EXTERN_C();
133 
134 
135 /** Update a digest with given data.
136     @param  Digest  [in] digest handle.
137 	@param  pData   [in] data buffer.
138 	@param  nDatLen [in] data length.
139 
140 	@return rtl_Digest_E_None upon success.
141  */
142 rtlDigestError SAL_CALL rtl_digest_update (
143 	rtlDigest Digest,
144 	const void *pData, sal_uInt32 nDatLen
145 ) SAL_THROW_EXTERN_C();
146 
147 
148 /** Finalize a digest and retrieve the digest value.
149     @precond  Digest value length must not be less than digest length.
150 	@postcond Digest initialized to accept another update sequence.
151 	@see      rtl_digest_queryLength()
152 	@see      rtl_digest_update()
153 
154     @param  Digest  [in] digest handle.
155 	@param  pBuffer [in] digest value buffer.
156 	@param  nBufLen [in] digest value length.
157 
158 	@return rtl_Digest_E_None upon success.
159  */
160 rtlDigestError SAL_CALL rtl_digest_get (
161 	rtlDigest Digest,
162 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
163 ) SAL_THROW_EXTERN_C();
164 
165 /*========================================================================
166  *
167  * rtl_digest_MD2 interface.
168  *
169  *======================================================================*/
170 #define RTL_DIGEST_LENGTH_MD2 16
171 
172 /** Create a MD2 digest handle.
173     @descr The MD2 digest algorithm is specified in
174 
175     RFC 1319 (Informational)
176       The MD2 Message-Digest Algorithm
177 
178     @see rtl_digest_create()
179  */
180 rtlDigest SAL_CALL rtl_digest_createMD2 (void) SAL_THROW_EXTERN_C();
181 
182 
183 /** Destroy a MD2 digest handle.
184     @see rtl_digest_destroy()
185  */
186 void SAL_CALL rtl_digest_destroyMD2 (
187 	rtlDigest Digest
188 ) SAL_THROW_EXTERN_C();
189 
190 
191 /** Update a MD2 digest with given data.
192     @see rtl_digest_update()
193  */
194 rtlDigestError SAL_CALL rtl_digest_updateMD2 (
195 	rtlDigest Digest,
196 	const void *pData, sal_uInt32 nDatLen
197 ) SAL_THROW_EXTERN_C();
198 
199 
200 /** Finalize a MD2 digest and retrieve the digest value.
201     @see rtl_digest_get()
202  */
203 rtlDigestError SAL_CALL rtl_digest_getMD2 (
204 	rtlDigest Digest,
205 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
206 ) SAL_THROW_EXTERN_C();
207 
208 
209 /** Evaluate a MD2 digest value from given data.
210     @descr This function performs an optimized call sequence on a
211 	single data buffer, avoiding digest creation and destruction.
212 
213 	@see rtl_digest_updateMD2()
214 	@see rtl_digest_getMD2()
215 
216 	@param  pData   [in] data buffer.
217 	@param  nDatLen [in] data length.
218 	@param  pBuffer [in] digest value buffer.
219 	@param  nBufLen [in] digest value length.
220 
221 	@return rtl_Digest_E_None upon success.
222  */
223 rtlDigestError SAL_CALL rtl_digest_MD2 (
224 	const void *pData,   sal_uInt32 nDatLen,
225 	sal_uInt8  *pBuffer, sal_uInt32 nBufLen
226 ) SAL_THROW_EXTERN_C();
227 
228 /*========================================================================
229  *
230  * rtl_digest_MD5 interface.
231  *
232  *======================================================================*/
233 #define RTL_DIGEST_LENGTH_MD5 16
234 
235 /** Create a MD5 digest handle.
236     @descr The MD5 digest algorithm is specified in
237 
238     RFC 1321 (Informational)
239       The MD5 Message-Digest Algorithm
240 
241     @see rtl_digest_create()
242  */
243 rtlDigest SAL_CALL rtl_digest_createMD5 (void) SAL_THROW_EXTERN_C();
244 
245 
246 /** Destroy a MD5 digest handle.
247     @see rtl_digest_destroy()
248  */
249 void SAL_CALL rtl_digest_destroyMD5 (
250 	rtlDigest Digest
251 ) SAL_THROW_EXTERN_C();
252 
253 
254 /** Update a MD5 digest with given data.
255     @see rtl_digest_update()
256  */
257 rtlDigestError SAL_CALL rtl_digest_updateMD5 (
258 	rtlDigest Digest,
259 	const void *pData, sal_uInt32 nDatLen
260 ) SAL_THROW_EXTERN_C();
261 
262 
263 /** Finalize a MD5 digest and retrieve the digest value.
264     @see rtl_digest_get()
265  */
266 rtlDigestError SAL_CALL rtl_digest_getMD5 (
267 	rtlDigest Digest,
268 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
269 ) SAL_THROW_EXTERN_C();
270 
271 
272 /** Retrieve the raw (not finalized) MD5 digest value.
273 	@descr This function is a non-standard replacement for
274 	rtl_digest_getMD5() and must be used with caution.
275 
276 	@postcond Digest initialized to accept another update sequence.
277     @see      rtl_digest_get()
278  */
279 rtlDigestError SAL_CALL rtl_digest_rawMD5 (
280 	rtlDigest Digest,
281 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
282 ) SAL_THROW_EXTERN_C();
283 
284 
285 /** Evaluate a MD5 digest value from given data.
286     @descr This function performs an optimized call sequence on a
287 	single data buffer, avoiding digest creation and destruction.
288 
289 	@see rtl_digest_updateMD5()
290 	@see rtl_digest_getMD5()
291 
292 	@param  pData   [in] data buffer.
293 	@param  nDatLen [in] data length.
294 	@param  pBuffer [in] digest value buffer.
295 	@param  nBufLen [in] digest value length.
296 
297 	@return rtl_Digest_E_None upon success.
298  */
299 rtlDigestError SAL_CALL rtl_digest_MD5 (
300 	const void *pData,   sal_uInt32 nDatLen,
301 	sal_uInt8  *pBuffer, sal_uInt32 nBufLen
302 ) SAL_THROW_EXTERN_C();
303 
304 /*========================================================================
305  *
306  * rtl_digest_SHA interface.
307  *
308  *======================================================================*/
309 #define RTL_DIGEST_LENGTH_SHA 20
310 
311 /** Create a SHA digest handle.
312     @descr The SHA digest algorithm is specified in
313 
314     FIPS PUB 180 (Superseded by FIPS PUB 180-1)
315       Secure Hash Standard
316 
317     @see rtl_digest_create()
318  */
319 rtlDigest SAL_CALL rtl_digest_createSHA (void) SAL_THROW_EXTERN_C();
320 
321 
322 /** Destroy a SHA digest handle.
323     @see rtl_digest_destroy()
324  */
325 void SAL_CALL rtl_digest_destroySHA (
326 	rtlDigest Digest
327 ) SAL_THROW_EXTERN_C();
328 
329 
330 /** Update a SHA digest with given data.
331     @see rtl_digest_update()
332  */
333 rtlDigestError SAL_CALL rtl_digest_updateSHA (
334 	rtlDigest Digest,
335 	const void *pData, sal_uInt32 nDatLen
336 ) SAL_THROW_EXTERN_C();
337 
338 
339 /** Finalize a SHA digest and retrieve the digest value.
340     @see rtl_digest_get()
341  */
342 rtlDigestError SAL_CALL rtl_digest_getSHA (
343 	rtlDigest Digest,
344 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
345 ) SAL_THROW_EXTERN_C();
346 
347 
348 /** Evaluate a SHA digest value from given data.
349     @descr This function performs an optimized call sequence on a
350 	single data buffer, avoiding digest creation and destruction.
351 
352 	@see rtl_digest_updateSHA()
353 	@see rtl_digest_getSHA()
354 
355 	@param  pData   [in] data buffer.
356 	@param  nDatLen [in] data length.
357 	@param  pBuffer [in] digest value buffer.
358 	@param  nBufLen [in] digest value length.
359 
360 	@return rtl_Digest_E_None upon success.
361  */
362 rtlDigestError SAL_CALL rtl_digest_SHA (
363 	const void *pData,   sal_uInt32 nDatLen,
364 	sal_uInt8  *pBuffer, sal_uInt32 nBufLen
365 ) SAL_THROW_EXTERN_C();
366 
367 /*========================================================================
368  *
369  * rtl_digest_SHA1 interface.
370  *
371  *======================================================================*/
372 #define RTL_DIGEST_LENGTH_SHA1 20
373 
374 /** Create a SHA1 digest handle.
375     @descr The SHA1 digest algorithm is specified in
376 
377     FIPS PUB 180-1 (Supersedes FIPS PUB 180)
378       Secure Hash Standard
379 
380     @see rtl_digest_create()
381  */
382 rtlDigest SAL_CALL rtl_digest_createSHA1 (void) SAL_THROW_EXTERN_C();
383 
384 
385 /** Destroy a SHA1 digest handle.
386     @see rtl_digest_destroy()
387  */
388 void SAL_CALL rtl_digest_destroySHA1 (
389 	rtlDigest Digest
390 ) SAL_THROW_EXTERN_C();
391 
392 
393 /** Update a SHA1 digest with given data.
394     @see rtl_digest_update()
395  */
396 rtlDigestError SAL_CALL rtl_digest_updateSHA1 (
397 	rtlDigest Digest,
398 	const void *pData, sal_uInt32 nDatLen
399 ) SAL_THROW_EXTERN_C();
400 
401 
402 /** Finalize a SHA1 digest and retrieve the digest value.
403     @see rtl_digest_get()
404  */
405 rtlDigestError SAL_CALL rtl_digest_getSHA1 (
406 	rtlDigest Digest,
407 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
408 ) SAL_THROW_EXTERN_C();
409 
410 
411 /** Evaluate a SHA1 digest value from given data.
412     @descr This function performs an optimized call sequence on a
413 	single data buffer, avoiding digest creation and destruction.
414 
415 	@see rtl_digest_updateSHA1()
416 	@see rtl_digest_getSHA1()
417 
418 	@param  pData   [in] data buffer.
419 	@param  nDatLen [in] data length.
420 	@param  pBuffer [in] digest value buffer.
421 	@param  nBufLen [in] digest value length.
422 
423 	@return rtl_Digest_E_None upon success.
424  */
425 rtlDigestError SAL_CALL rtl_digest_SHA1 (
426 	const void *pData,   sal_uInt32 nDatLen,
427 	sal_uInt8  *pBuffer, sal_uInt32 nBufLen
428 ) SAL_THROW_EXTERN_C();
429 
430 /*========================================================================
431  *
432  * rtl_digest_HMAC_MD5 interface.
433  *
434  *======================================================================*/
435 #define RTL_DIGEST_LENGTH_HMAC_MD5 RTL_DIGEST_LENGTH_MD5
436 
437 /** Create a HMAC_MD5 digest handle.
438     @descr The HMAC_MD5 digest algorithm is specified in
439 
440     RFC 2104 (Informational)
441       HMAC: Keyed-Hashing for Message Authentication
442 
443     @see rtl_digest_create()
444  */
445 rtlDigest SAL_CALL rtl_digest_createHMAC_MD5 (void) SAL_THROW_EXTERN_C();
446 
447 
448 /** Destroy a HMAC_MD5 digest handle.
449     @see rtl_digest_destroy()
450  */
451 void SAL_CALL rtl_digest_destroyHMAC_MD5 (
452 	rtlDigest Digest
453 ) SAL_THROW_EXTERN_C();
454 
455 
456 /** Initialize a HMAC_MD5 digest.
457     @see rtl_digest_init()
458 
459     @param  Digest   [in] digest handle.
460 	@param  pKeyData [in] key material buffer.
461 	@param  nKeyLen  [in] key material length.
462 
463 	@return rtl_Digest_E_None upon success.
464  */
465 rtlDigestError SAL_CALL rtl_digest_initHMAC_MD5 (
466 	rtlDigest Digest,
467 	const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen
468 ) SAL_THROW_EXTERN_C();
469 
470 
471 /** Update a HMAC_MD5 digest with given data.
472     @see rtl_digest_update()
473  */
474 rtlDigestError SAL_CALL rtl_digest_updateHMAC_MD5 (
475 	rtlDigest Digest,
476 	const void *pData, sal_uInt32 nDatLen
477 ) SAL_THROW_EXTERN_C();
478 
479 
480 /** Finalize a HMAC_MD5 digest and retrieve the digest value.
481     @see rtl_digest_get()
482  */
483 rtlDigestError SAL_CALL rtl_digest_getHMAC_MD5 (
484 	rtlDigest Digest,
485 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
486 ) SAL_THROW_EXTERN_C();
487 
488 
489 /** Evaluate a HMAC_MD5 digest value from given data.
490     @descr This function performs an optimized call sequence on a
491 	single data buffer, avoiding digest creation and destruction.
492 
493 	@see rtl_digest_initHMAC_MD5()
494 	@see rtl_digest_updateHMAC_MD5()
495 	@see rtl_digest_getHMAC_MD5()
496 
497 	@param  pKeyData [in] key material buffer.
498 	@param  nKeyLen  [in] key material length.
499 	@param  pData    [in] data buffer.
500 	@param  nDatLen  [in] data length.
501 	@param  pBuffer  [in] digest value buffer.
502 	@param  nBufLen  [in] digest value length.
503 
504 	@return rtl_Digest_E_None upon success.
505  */
506 rtlDigestError SAL_CALL rtl_digest_HMAC_MD5 (
507 	const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen,
508 	const void      *pData,    sal_uInt32 nDatLen,
509 	sal_uInt8       *pBuffer,  sal_uInt32 nBufLen
510 ) SAL_THROW_EXTERN_C();
511 
512 /*========================================================================
513  *
514  * rtl_digest_HMAC_SHA1 interface.
515  *
516  *======================================================================*/
517 #define RTL_DIGEST_LENGTH_HMAC_SHA1 RTL_DIGEST_LENGTH_SHA1
518 
519 /** Create a HMAC_SHA1 digest handle.
520     @descr The HMAC_SHA1 digest algorithm is specified in
521 
522     RFC 2104 (Informational)
523       HMAC: Keyed-Hashing for Message Authentication
524     RFC 2898 (Informational)
525       PKCS #5: Password-Based Cryptography Specification Version 2.0
526 
527     @see rtl_digest_create()
528  */
529 rtlDigest SAL_CALL rtl_digest_createHMAC_SHA1 (void) SAL_THROW_EXTERN_C();
530 
531 
532 /** Destroy a HMAC_SHA1 digest handle.
533     @see rtl_digest_destroy()
534  */
535 void SAL_CALL rtl_digest_destroyHMAC_SHA1 (
536 	rtlDigest Digest
537 ) SAL_THROW_EXTERN_C();
538 
539 
540 /** Initialize a HMAC_SHA1 digest.
541     @see rtl_digest_init()
542 
543     @param  Digest   [in] digest handle.
544 	@param  pKeyData [in] key material buffer.
545 	@param  nKeyLen  [in] key material length.
546 
547 	@return rtl_Digest_E_None upon success.
548  */
549 rtlDigestError SAL_CALL rtl_digest_initHMAC_SHA1 (
550 	rtlDigest Digest,
551 	const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen
552 ) SAL_THROW_EXTERN_C();
553 
554 
555 /** Update a HMAC_SHA1 digest with given data.
556     @see rtl_digest_update()
557  */
558 rtlDigestError SAL_CALL rtl_digest_updateHMAC_SHA1 (
559 	rtlDigest Digest,
560 	const void *pData, sal_uInt32 nDatLen
561 ) SAL_THROW_EXTERN_C();
562 
563 
564 /** Finalize a HMAC_SHA1 digest and retrieve the digest value.
565     @see rtl_digest_get()
566  */
567 rtlDigestError SAL_CALL rtl_digest_getHMAC_SHA1 (
568 	rtlDigest Digest,
569 	sal_uInt8 *pBuffer, sal_uInt32 nBufLen
570 ) SAL_THROW_EXTERN_C();
571 
572 
573 /** Evaluate a HMAC_SHA1 digest value from given data.
574     @descr This function performs an optimized call sequence on a
575 	single data buffer, avoiding digest creation and destruction.
576 
577 	@see rtl_digest_initHMAC_SHA1()
578 	@see rtl_digest_updateHMAC_SHA1()
579 	@see rtl_digest_getHMAC_SHA1()
580 
581 	@param  pKeyData [in] key material buffer.
582 	@param  nKeyLen  [in] key material length.
583 	@param  pData    [in] data buffer.
584 	@param  nDatLen  [in] data length.
585 	@param  pBuffer  [in] digest value buffer.
586 	@param  nBufLen  [in] digest value length.
587 
588 	@return rtl_Digest_E_None upon success.
589  */
590 rtlDigestError SAL_CALL rtl_digest_HMAC_SHA1 (
591 	const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen,
592 	const void      *pData,    sal_uInt32 nDatLen,
593 	sal_uInt8       *pBuffer,  sal_uInt32 nBufLen
594 ) SAL_THROW_EXTERN_C();
595 
596 /*========================================================================
597  *
598  * rtl_digest_PBKDF2 interface.
599  *
600  *======================================================================*/
601 /** Password-Based Key Derivation Function.
602     @descr The PBKDF2 key derivation function is specified in
603 
604     RFC 2898 (Informational)
605       PKCS #5: Password-Based Cryptography Specification Version 2.0
606 
607     @param  pKeyData  [out] derived key
608     @param  nKeyLen   [in]  derived key length
609 	@param  pPassData [in]  password
610 	@param  nPassLen  [in]  password length
611 	@param  pSaltData [in]  salt
612 	@param  nSaltLen  [in]  salt length
613 	@param  nCount    [in]  iteration count
614 
615 	@return rtl_Digest_E_None upon success.
616 */
617 rtlDigestError SAL_CALL rtl_digest_PBKDF2 (
618 	sal_uInt8       *pKeyData , sal_uInt32 nKeyLen,
619 	const sal_uInt8 *pPassData, sal_uInt32 nPassLen,
620 	const sal_uInt8 *pSaltData, sal_uInt32 nSaltLen,
621 	sal_uInt32       nCount
622 ) SAL_THROW_EXTERN_C();
623 
624 /*========================================================================
625  *
626  * The End.
627  *
628  *======================================================================*/
629 
630 #ifdef __cplusplus
631 }
632 #endif
633 
634 #endif /* _RTL_DIGEST_H_ */
635 
636