Version 5.4.3.2, tag libreoffice-5.4.3.2
[LibreOffice.git] / include / rtl / digest.h
blob8568b990a6b83251114e4efa5c50805c659f63ec
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 * This file incorporates work covered by the following license notice:
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
20 #ifndef INCLUDED_RTL_DIGEST_H
21 #define INCLUDED_RTL_DIGEST_H
23 #include <sal/config.h>
25 #include <sal/saldllapi.h>
26 #include <sal/types.h>
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
32 /*========================================================================
34 * rtlDigest.
36 *======================================================================*/
37 /** Digest Handle opaque type.
39 typedef void* rtlDigest;
42 /** Digest Algorithm enumeration.
43 @see rtl_digest_create()
45 enum __rtl_DigestAlgorithm
47 rtl_Digest_AlgorithmMD2,
48 rtl_Digest_AlgorithmMD5,
49 rtl_Digest_AlgorithmSHA,
50 rtl_Digest_AlgorithmSHA1,
52 rtl_Digest_AlgorithmHMAC_MD5,
53 rtl_Digest_AlgorithmHMAC_SHA1,
55 rtl_Digest_AlgorithmInvalid,
56 rtl_Digest_Algorithm_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
59 /** Digest Algorithm type.
61 typedef enum __rtl_DigestAlgorithm rtlDigestAlgorithm;
64 /** Error Code enumeration.
66 enum __rtl_DigestError
68 rtl_Digest_E_None,
69 rtl_Digest_E_Argument,
70 rtl_Digest_E_Algorithm,
71 rtl_Digest_E_BufferSize,
72 rtl_Digest_E_Memory,
73 rtl_Digest_E_Unknown,
74 rtl_Digest_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
77 /** Error Code type.
79 typedef enum __rtl_DigestError rtlDigestError;
82 /** Create a digest handle for the given algorithm.
83 @see rtlDigestAlgorithm
85 @param Algorithm [in] digest algorithm.
86 @return Digest handle, or 0 upon failure.
88 SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_create (
89 rtlDigestAlgorithm Algorithm
90 ) SAL_THROW_EXTERN_C();
93 /** Destroy a digest handle.
94 @post Digest handle destroyed and invalid.
95 @param Digest [in] digest handle to be destroyed.
96 @return None.
98 SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroy (
99 rtlDigest Digest
100 ) SAL_THROW_EXTERN_C();
103 /** Query the algorithm of a given digest.
104 @param Digest [in] digest handle.
105 @return digest algorithm, or rtl_Digest_AlgorithmInvalid upon failure.
107 SAL_DLLPUBLIC rtlDigestAlgorithm SAL_CALL rtl_digest_queryAlgorithm (
108 rtlDigest Digest
109 ) SAL_THROW_EXTERN_C();
112 /** Query the length of a given digest.
113 @param Digest [in] digest handle.
114 @return digest length, or 0 upon failure.
116 SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_digest_queryLength (
117 rtlDigest Digest
118 ) SAL_THROW_EXTERN_C();
121 /** Initialize a digest with given data.
122 @param Digest [in] digest handle.
123 @param pData [in] data buffer.
124 @param nDatLen [in] data length.
126 @return rtl_Digest_E_None upon success.
128 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_init (
129 rtlDigest Digest,
130 const sal_uInt8 *pData, sal_uInt32 nDatLen
131 ) SAL_THROW_EXTERN_C();
134 /** Update a digest with given data.
135 @param Digest [in] digest handle.
136 @param pData [in] data buffer.
137 @param nDatLen [in] data length.
139 @return rtl_Digest_E_None upon success.
141 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_update (
142 rtlDigest Digest,
143 const void *pData, sal_uInt32 nDatLen
144 ) SAL_THROW_EXTERN_C();
147 /** Finalize a digest and retrieve the digest value.
148 @pre Digest value length must not be less than digest length.
149 @post Digest initialized to accept another update sequence.
150 @see rtl_digest_queryLength()
151 @see rtl_digest_update()
153 @param Digest [in] digest handle.
154 @param pBuffer [in] digest value buffer.
155 @param nBufLen [in] digest value length.
157 @return rtl_Digest_E_None upon success.
159 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_get (
160 rtlDigest Digest,
161 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
162 ) SAL_THROW_EXTERN_C();
164 /*========================================================================
166 * rtl_digest_MD2 interface.
168 *======================================================================*/
169 #define RTL_DIGEST_LENGTH_MD2 16
171 /** Create a MD2 digest handle.
173 The MD2 digest algorithm is specified in
174 RFC 1319 (Informational)
175 The MD2 Message-Digest Algorithm
177 @see rtl_digest_create()
179 SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createMD2 (void) SAL_THROW_EXTERN_C();
182 /** Destroy a MD2 digest handle.
183 @see rtl_digest_destroy()
185 SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroyMD2 (
186 rtlDigest Digest
187 ) SAL_THROW_EXTERN_C();
190 /** Update a MD2 digest with given data.
191 @see rtl_digest_update()
193 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateMD2 (
194 rtlDigest Digest,
195 const void *pData, sal_uInt32 nDatLen
196 ) SAL_THROW_EXTERN_C();
199 /** Finalize a MD2 digest and retrieve the digest value.
200 @see rtl_digest_get()
202 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getMD2 (
203 rtlDigest Digest,
204 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
205 ) SAL_THROW_EXTERN_C();
208 /** Evaluate a MD2 digest value from given data.
210 This function performs an optimized call sequence on a
211 single data buffer, avoiding digest creation and destruction.
213 @see rtl_digest_updateMD2()
214 @see rtl_digest_getMD2()
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.
221 @return rtl_Digest_E_None upon success.
223 SAL_DLLPUBLIC 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();
228 /*========================================================================
230 * rtl_digest_MD5 interface.
232 *======================================================================*/
233 #define RTL_DIGEST_LENGTH_MD5 16
235 /** Create a MD5 digest handle.
237 The MD5 digest algorithm is specified in
238 RFC 1321 (Informational)
239 The MD5 Message-Digest Algorithm
241 @see rtl_digest_create()
243 SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createMD5 (void) SAL_THROW_EXTERN_C();
246 /** Destroy a MD5 digest handle.
247 @see rtl_digest_destroy()
249 SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroyMD5 (
250 rtlDigest Digest
251 ) SAL_THROW_EXTERN_C();
254 /** Update a MD5 digest with given data.
255 @see rtl_digest_update()
257 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateMD5 (
258 rtlDigest Digest,
259 const void *pData, sal_uInt32 nDatLen
260 ) SAL_THROW_EXTERN_C();
263 /** Finalize a MD5 digest and retrieve the digest value.
264 @see rtl_digest_get()
266 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getMD5 (
267 rtlDigest Digest,
268 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
269 ) SAL_THROW_EXTERN_C();
272 /** Retrieve the raw (not finalized) MD5 digest value.
274 This function is a non-standard replacement for
275 rtl_digest_getMD5() and must be used with caution.
277 @post Digest initialized to accept another update sequence.
278 @see rtl_digest_get()
280 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_rawMD5 (
281 rtlDigest Digest,
282 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
283 ) SAL_THROW_EXTERN_C();
286 /** Evaluate a MD5 digest value from given data.
288 This function performs an optimized call sequence on a
289 single data buffer, avoiding digest creation and destruction.
291 @see rtl_digest_updateMD5()
292 @see rtl_digest_getMD5()
294 @param pData [in] data buffer.
295 @param nDatLen [in] data length.
296 @param pBuffer [in] digest value buffer.
297 @param nBufLen [in] digest value length.
299 @return rtl_Digest_E_None upon success.
301 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_MD5 (
302 const void *pData, sal_uInt32 nDatLen,
303 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
304 ) SAL_THROW_EXTERN_C();
306 /*========================================================================
308 * rtl_digest_SHA interface.
310 *======================================================================*/
311 #define RTL_DIGEST_LENGTH_SHA 20
313 /** Create a SHA digest handle.
315 The SHA digest algorithm is specified in
316 FIPS PUB 180 (Superseded by FIPS PUB 180-1)
317 Secure Hash Standard
319 @see rtl_digest_create()
321 SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createSHA (void) SAL_THROW_EXTERN_C();
324 /** Destroy a SHA digest handle.
325 @see rtl_digest_destroy()
327 SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroySHA (
328 rtlDigest Digest
329 ) SAL_THROW_EXTERN_C();
332 /** Update a SHA digest with given data.
333 @see rtl_digest_update()
335 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateSHA (
336 rtlDigest Digest,
337 const void *pData, sal_uInt32 nDatLen
338 ) SAL_THROW_EXTERN_C();
341 /** Finalize a SHA digest and retrieve the digest value.
342 @see rtl_digest_get()
344 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA (
345 rtlDigest Digest,
346 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
347 ) SAL_THROW_EXTERN_C();
350 /** Evaluate a SHA digest value from given data.
352 This function performs an optimized call sequence on a
353 single data buffer, avoiding digest creation and destruction.
355 @see rtl_digest_updateSHA()
356 @see rtl_digest_getSHA()
358 @param pData [in] data buffer.
359 @param nDatLen [in] data length.
360 @param pBuffer [in] digest value buffer.
361 @param nBufLen [in] digest value length.
363 @return rtl_Digest_E_None upon success.
365 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_SHA (
366 const void *pData, sal_uInt32 nDatLen,
367 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
368 ) SAL_THROW_EXTERN_C();
370 /*========================================================================
372 * rtl_digest_SHA1 interface.
374 *======================================================================*/
375 #define RTL_DIGEST_LENGTH_SHA1 20
377 /** Create a SHA1 digest handle.
379 The SHA1 digest algorithm is specified in
380 FIPS PUB 180-1 (Supersedes FIPS PUB 180)
381 Secure Hash Standard
383 @see rtl_digest_create()
385 SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createSHA1 (void) SAL_THROW_EXTERN_C();
388 /** Destroy a SHA1 digest handle.
389 @see rtl_digest_destroy()
391 SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroySHA1 (
392 rtlDigest Digest
393 ) SAL_THROW_EXTERN_C();
396 /** Update a SHA1 digest with given data.
397 @see rtl_digest_update()
399 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateSHA1 (
400 rtlDigest Digest,
401 const void *pData, sal_uInt32 nDatLen
402 ) SAL_THROW_EXTERN_C();
405 /** Finalize a SHA1 digest and retrieve the digest value.
406 @see rtl_digest_get()
408 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA1 (
409 rtlDigest Digest,
410 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
411 ) SAL_THROW_EXTERN_C();
414 /** Evaluate a SHA1 digest value from given data.
416 This function performs an optimized call sequence on a
417 single data buffer, avoiding digest creation and destruction.
419 @see rtl_digest_updateSHA1()
420 @see rtl_digest_getSHA1()
422 @param pData [in] data buffer.
423 @param nDatLen [in] data length.
424 @param pBuffer [in] digest value buffer.
425 @param nBufLen [in] digest value length.
427 @return rtl_Digest_E_None upon success.
429 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_SHA1 (
430 const void *pData, sal_uInt32 nDatLen,
431 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
432 ) SAL_THROW_EXTERN_C();
434 /*========================================================================
436 * rtl_digest_HMAC_MD5 interface.
438 *======================================================================*/
439 #define RTL_DIGEST_LENGTH_HMAC_MD5 RTL_DIGEST_LENGTH_MD5
441 /** Create a HMAC_MD5 digest handle.
443 The HMAC_MD5 digest algorithm is specified in
445 RFC 2104 (Informational)
446 HMAC: Keyed-Hashing for Message Authentication
448 @see rtl_digest_create()
450 SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createHMAC_MD5 (void) SAL_THROW_EXTERN_C();
453 /** Destroy a HMAC_MD5 digest handle.
454 @see rtl_digest_destroy()
456 SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroyHMAC_MD5 (
457 rtlDigest Digest
458 ) SAL_THROW_EXTERN_C();
461 /** Initialize a HMAC_MD5 digest.
462 @see rtl_digest_init()
464 @param Digest [in] digest handle.
465 @param pKeyData [in] key material buffer.
466 @param nKeyLen [in] key material length.
468 @return rtl_Digest_E_None upon success.
470 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_initHMAC_MD5 (
471 rtlDigest Digest,
472 const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen
473 ) SAL_THROW_EXTERN_C();
476 /** Update a HMAC_MD5 digest with given data.
477 @see rtl_digest_update()
479 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateHMAC_MD5 (
480 rtlDigest Digest,
481 const void *pData, sal_uInt32 nDatLen
482 ) SAL_THROW_EXTERN_C();
485 /** Finalize a HMAC_MD5 digest and retrieve the digest value.
486 @see rtl_digest_get()
488 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_MD5 (
489 rtlDigest Digest,
490 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
491 ) SAL_THROW_EXTERN_C();
494 /** Evaluate a HMAC_MD5 digest value from given data.
496 This function performs an optimized call sequence on a
497 single data buffer, avoiding digest creation and destruction.
499 @see rtl_digest_initHMAC_MD5()
500 @see rtl_digest_updateHMAC_MD5()
501 @see rtl_digest_getHMAC_MD5()
503 @param pKeyData [in] key material buffer.
504 @param nKeyLen [in] key material length.
505 @param pData [in] data buffer.
506 @param nDatLen [in] data length.
507 @param pBuffer [in] digest value buffer.
508 @param nBufLen [in] digest value length.
510 @return rtl_Digest_E_None upon success.
512 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_HMAC_MD5 (
513 const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen,
514 const void *pData, sal_uInt32 nDatLen,
515 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
516 ) SAL_THROW_EXTERN_C();
518 /*========================================================================
520 * rtl_digest_HMAC_SHA1 interface.
522 *======================================================================*/
523 #define RTL_DIGEST_LENGTH_HMAC_SHA1 RTL_DIGEST_LENGTH_SHA1
525 /** Create a HMAC_SHA1 digest handle.
527 The HMAC_SHA1 digest algorithm is specified in
528 RFC 2104 (Informational)
529 HMAC: Keyed-Hashing for Message Authentication
530 RFC 2898 (Informational)
531 PKCS #5: Password-Based Cryptography Specification Version 2.0
533 @see rtl_digest_create()
535 SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createHMAC_SHA1 (void) SAL_THROW_EXTERN_C();
538 /** Destroy a HMAC_SHA1 digest handle.
539 @see rtl_digest_destroy()
541 SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroyHMAC_SHA1 (
542 rtlDigest Digest
543 ) SAL_THROW_EXTERN_C();
546 /** Initialize a HMAC_SHA1 digest.
547 @see rtl_digest_init()
549 @param Digest [in] digest handle.
550 @param pKeyData [in] key material buffer.
551 @param nKeyLen [in] key material length.
553 @return rtl_Digest_E_None upon success.
555 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_initHMAC_SHA1 (
556 rtlDigest Digest,
557 const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen
558 ) SAL_THROW_EXTERN_C();
561 /** Update a HMAC_SHA1 digest with given data.
562 @see rtl_digest_update()
564 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateHMAC_SHA1 (
565 rtlDigest Digest,
566 const void *pData, sal_uInt32 nDatLen
567 ) SAL_THROW_EXTERN_C();
570 /** Finalize a HMAC_SHA1 digest and retrieve the digest value.
571 @see rtl_digest_get()
573 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_SHA1 (
574 rtlDigest Digest,
575 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
576 ) SAL_THROW_EXTERN_C();
579 /** Evaluate a HMAC_SHA1 digest value from given data.
581 This function performs an optimized call sequence on a
582 single data buffer, avoiding digest creation and destruction.
584 @see rtl_digest_initHMAC_SHA1()
585 @see rtl_digest_updateHMAC_SHA1()
586 @see rtl_digest_getHMAC_SHA1()
588 @param pKeyData [in] key material buffer.
589 @param nKeyLen [in] key material length.
590 @param pData [in] data buffer.
591 @param nDatLen [in] data length.
592 @param pBuffer [in] digest value buffer.
593 @param nBufLen [in] digest value length.
595 @return rtl_Digest_E_None upon success.
597 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_HMAC_SHA1 (
598 const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen,
599 const void *pData, sal_uInt32 nDatLen,
600 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
601 ) SAL_THROW_EXTERN_C();
603 /*========================================================================
605 * rtl_digest_PBKDF2 interface.
607 *======================================================================*/
608 /** Password-Based Key Derivation Function.
610 The PBKDF2 key derivation function is specified in
611 RFC 2898 (Informational)
612 PKCS #5: Password-Based Cryptography Specification Version 2.0
614 @param pKeyData [out] derived key
615 @param nKeyLen [in] derived key length
616 @param pPassData [in] password
617 @param nPassLen [in] password length
618 @param pSaltData [in] salt
619 @param nSaltLen [in] salt length
620 @param nCount [in] iteration count
622 @return rtl_Digest_E_None upon success.
624 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_PBKDF2 (
625 sal_uInt8 *pKeyData , sal_uInt32 nKeyLen,
626 const sal_uInt8 *pPassData, sal_uInt32 nPassLen,
627 const sal_uInt8 *pSaltData, sal_uInt32 nSaltLen,
628 sal_uInt32 nCount
629 ) SAL_THROW_EXTERN_C();
631 /*========================================================================
633 * The End.
635 *======================================================================*/
637 #ifdef __cplusplus
639 #endif
641 #endif // INCLUDED_RTL_DIGEST_H
643 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */