1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2/*
3 * This file is part of the LibreOffice project.
4 *
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/.
8 *
9 * This file incorporates work covered by the following license notice:
10 *
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 .
18 */
19
20#ifndef INCLUDED_RTL_DIGEST_H
21#define INCLUDED_RTL_DIGEST_H
22
23#include <sal/config.h>
24
25#include <sal/saldllapi.h>
26#include <sal/types.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/*========================================================================
33 *
34 * rtlDigest.
35 *
36 *======================================================================*/
37/** Digest Handle opaque type.
38 */
39typedef void* rtlDigest;
40
41
42/** Digest Algorithm enumeration.
43 @see rtl_digest_create()
44 */
45enum __rtl_DigestAlgorithm
46{
47 rtl_Digest_AlgorithmMD2,
48 rtl_Digest_AlgorithmMD5,
49 rtl_Digest_AlgorithmSHA,
50 rtl_Digest_AlgorithmSHA1,
51
52 rtl_Digest_AlgorithmHMAC_MD5,
53 rtl_Digest_AlgorithmHMAC_SHA1,
54
55 rtl_Digest_AlgorithmInvalid,
56 rtl_Digest_Algorithm_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
57};
58
59/** Digest Algorithm type.
60 */
61typedef enum __rtl_DigestAlgorithm rtlDigestAlgorithm;
62
63
64/** Error Code enumeration.
65 */
66enum __rtl_DigestError
67{
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
75};
76
77/** Error Code type.
78 */
79typedef enum __rtl_DigestError rtlDigestError;
80
81
82/** Create a digest handle for the given algorithm.
83 @see rtlDigestAlgorithm
84
85 @param Algorithm [in] digest algorithm.
86 @return Digest handle, or 0 upon failure.
87 */
88SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_create (
89 rtlDigestAlgorithm Algorithm
90) SAL_THROW_EXTERN_C();
91
92
93/** Destroy a digest handle.
94 @post Digest handle destroyed and invalid.
95 @param Digest [in] digest handle to be destroyed.
96 @return None.
97 */
98SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroy (
99 rtlDigest Digest
100) SAL_THROW_EXTERN_C();
101
102
103/** Query the algorithm of a given digest.
104 @param Digest [in] digest handle.
105 @return digest algorithm, or rtl_Digest_AlgorithmInvalid upon failure.
106 */
107SAL_DLLPUBLIC rtlDigestAlgorithm SAL_CALL rtl_digest_queryAlgorithm (
108 rtlDigest Digest
109) SAL_THROW_EXTERN_C();
110
111
112/** Query the length of a given digest.
113 @param Digest [in] digest handle.
114 @return digest length, or 0 upon failure.
115 */
116SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_digest_queryLength (
117 rtlDigest Digest
118) SAL_THROW_EXTERN_C();
119
120
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.
125
126 @return rtl_Digest_E_None upon success.
127 */
128SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_init (
129 rtlDigest Digest,
130 const sal_uInt8 *pData, sal_uInt32 nDatLen
131) SAL_THROW_EXTERN_C();
132
133
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.
138
139 @return rtl_Digest_E_None upon success.
140 */
141SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_update (
142 rtlDigest Digest,
143 const void *pData, sal_uInt32 nDatLen
144) SAL_THROW_EXTERN_C();
145
146
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()
152
153 @param Digest [in] digest handle.
154 @param pBuffer [in] digest value buffer.
155 @param nBufLen [in] digest value length.
156
157 @return rtl_Digest_E_None upon success.
158 */
159SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_get (
160 rtlDigest Digest,
161 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
162) SAL_THROW_EXTERN_C();
163
164/*========================================================================
165 *
166 * rtl_digest_MD2 interface.
167 *
168 *======================================================================*/
169#define RTL_DIGEST_LENGTH_MD2 16
170
171/** Create a MD2 digest handle.
172
173 The MD2 digest algorithm is specified in
174 RFC 1319 (Informational)
175 The MD2 Message-Digest Algorithm
176
177 @see rtl_digest_create()
178 */
179SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createMD2 (void) SAL_THROW_EXTERN_C();
180
181
182/** Destroy a MD2 digest handle.
183 @see rtl_digest_destroy()
184 */
185SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroyMD2 (
186 rtlDigest Digest
187) SAL_THROW_EXTERN_C();
188
189
190/** Update a MD2 digest with given data.
191 @see rtl_digest_update()
192 */
193SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateMD2 (
194 rtlDigest Digest,
195 const void *pData, sal_uInt32 nDatLen
196) SAL_THROW_EXTERN_C();
197
198
199/** Finalize a MD2 digest and retrieve the digest value.
200 @see rtl_digest_get()
201 */
202SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getMD2 (
203 rtlDigest Digest,
204 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
205) SAL_THROW_EXTERN_C();
206
207
208/** Evaluate a MD2 digest value from given data.
209
210 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 */
223SAL_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();
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
237 The MD5 digest algorithm is specified in
238 RFC 1321 (Informational)
239 The MD5 Message-Digest Algorithm
240
241 @see rtl_digest_create()
242 */
243SAL_DLLPUBLIC 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 */
249SAL_DLLPUBLIC 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 */
257SAL_DLLPUBLIC 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 */
266SAL_DLLPUBLIC 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
274 This function is a non-standard replacement for
275 rtl_digest_getMD5() and must be used with caution.
276
277 @post Digest initialized to accept another update sequence.
278 @see rtl_digest_get()
279 */
280SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_rawMD5 (
281 rtlDigest Digest,
282 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
283) SAL_THROW_EXTERN_C();
284
285
286/** Evaluate a MD5 digest value from given data.
287
288 This function performs an optimized call sequence on a
289 single data buffer, avoiding digest creation and destruction.
290
291 @see rtl_digest_updateMD5()
292 @see rtl_digest_getMD5()
293
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.
298
299 @return rtl_Digest_E_None upon success.
300 */
301SAL_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();
305
306/*========================================================================
307 *
308 * rtl_digest_SHA interface.
309 *
310 *======================================================================*/
311#define RTL_DIGEST_LENGTH_SHA 20
312
313/** Create a SHA digest handle.
314
315 The SHA digest algorithm is specified in
316 FIPS PUB 180 (Superseded by FIPS PUB 180-1)
317 Secure Hash Standard
318
319 @see rtl_digest_create()
320 */
321SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createSHA (void) SAL_THROW_EXTERN_C();
322
323
324/** Destroy a SHA digest handle.
325 @see rtl_digest_destroy()
326 */
327SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroySHA (
328 rtlDigest Digest
329) SAL_THROW_EXTERN_C();
330
331
332/** Update a SHA digest with given data.
333 @see rtl_digest_update()
334 */
335SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateSHA (
336 rtlDigest Digest,
337 const void *pData, sal_uInt32 nDatLen
338) SAL_THROW_EXTERN_C();
339
340
341/** Finalize a SHA digest and retrieve the digest value.
342 @see rtl_digest_get()
343 */
344SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA (
345 rtlDigest Digest,
346 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
347) SAL_THROW_EXTERN_C();
348
349
350/** Evaluate a SHA digest value from given data.
351
352 This function performs an optimized call sequence on a
353 single data buffer, avoiding digest creation and destruction.
354
355 @see rtl_digest_updateSHA()
356 @see rtl_digest_getSHA()
357
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.
362
363 @return rtl_Digest_E_None upon success.
364 */
365SAL_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();
369
370/*========================================================================
371 *
372 * rtl_digest_SHA1 interface.
373 *
374 *======================================================================*/
375#define RTL_DIGEST_LENGTH_SHA1 20
376
377/** Create a SHA1 digest handle.
378
379 The SHA1 digest algorithm is specified in
380 FIPS PUB 180-1 (Supersedes FIPS PUB 180)
381 Secure Hash Standard
382
383 @see rtl_digest_create()
384 */
385SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createSHA1 (void) SAL_THROW_EXTERN_C();
386
387
388/** Destroy a SHA1 digest handle.
389 @see rtl_digest_destroy()
390 */
391SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroySHA1 (
392 rtlDigest Digest
393) SAL_THROW_EXTERN_C();
394
395
396/** Update a SHA1 digest with given data.
397 @see rtl_digest_update()
398 */
399SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateSHA1 (
400 rtlDigest Digest,
401 const void *pData, sal_uInt32 nDatLen
402) SAL_THROW_EXTERN_C();
403
404
405/** Finalize a SHA1 digest and retrieve the digest value.
406 @see rtl_digest_get()
407 */
408SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA1 (
409 rtlDigest Digest,
410 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
411) SAL_THROW_EXTERN_C();
412
413
414/** Evaluate a SHA1 digest value from given data.
415
416 This function performs an optimized call sequence on a
417 single data buffer, avoiding digest creation and destruction.
418
419 @see rtl_digest_updateSHA1()
420 @see rtl_digest_getSHA1()
421
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.
426
427 @return rtl_Digest_E_None upon success.
428 */
429SAL_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();
433
434/*========================================================================
435 *
436 * rtl_digest_HMAC_MD5 interface.
437 *
438 *======================================================================*/
439#define RTL_DIGEST_LENGTH_HMAC_MD5 RTL_DIGEST_LENGTH_MD5
440
441/** Create a HMAC_MD5 digest handle.
442
443 The HMAC_MD5 digest algorithm is specified in
444
445 RFC 2104 (Informational)
446 HMAC: Keyed-Hashing for Message Authentication
447
448 @see rtl_digest_create()
449 */
450SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createHMAC_MD5 (void) SAL_THROW_EXTERN_C();
451
452
453/** Destroy a HMAC_MD5 digest handle.
454 @see rtl_digest_destroy()
455 */
456SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroyHMAC_MD5 (
457 rtlDigest Digest
458) SAL_THROW_EXTERN_C();
459
460
461/** Initialize a HMAC_MD5 digest.
462 @see rtl_digest_init()
463
464 @param Digest [in] digest handle.
465 @param pKeyData [in] key material buffer.
466 @param nKeyLen [in] key material length.
467
468 @return rtl_Digest_E_None upon success.
469 */
470SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_initHMAC_MD5 (
471 rtlDigest Digest,
472 const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen
473) SAL_THROW_EXTERN_C();
474
475
476/** Update a HMAC_MD5 digest with given data.
477 @see rtl_digest_update()
478 */
479SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateHMAC_MD5 (
480 rtlDigest Digest,
481 const void *pData, sal_uInt32 nDatLen
482) SAL_THROW_EXTERN_C();
483
484
485/** Finalize a HMAC_MD5 digest and retrieve the digest value.
486 @see rtl_digest_get()
487 */
488SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_MD5 (
489 rtlDigest Digest,
490 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
491) SAL_THROW_EXTERN_C();
492
493
494/** Evaluate a HMAC_MD5 digest value from given data.
495
496 This function performs an optimized call sequence on a
497 single data buffer, avoiding digest creation and destruction.
498
499 @see rtl_digest_initHMAC_MD5()
500 @see rtl_digest_updateHMAC_MD5()
501 @see rtl_digest_getHMAC_MD5()
502
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.
509
510 @return rtl_Digest_E_None upon success.
511 */
512SAL_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();
517
518/*========================================================================
519 *
520 * rtl_digest_HMAC_SHA1 interface.
521 *
522 *======================================================================*/
523#define RTL_DIGEST_LENGTH_HMAC_SHA1 RTL_DIGEST_LENGTH_SHA1
524
525/** Create a HMAC_SHA1 digest handle.
526
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
532
533 @see rtl_digest_create()
534 */
535SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_createHMAC_SHA1 (void) SAL_THROW_EXTERN_C();
536
537
538/** Destroy a HMAC_SHA1 digest handle.
539 @see rtl_digest_destroy()
540 */
541SAL_DLLPUBLIC void SAL_CALL rtl_digest_destroyHMAC_SHA1 (
542 rtlDigest Digest
543) SAL_THROW_EXTERN_C();
544
545
546/** Initialize a HMAC_SHA1 digest.
547 @see rtl_digest_init()
548
549 @param Digest [in] digest handle.
550 @param pKeyData [in] key material buffer.
551 @param nKeyLen [in] key material length.
552
553 @return rtl_Digest_E_None upon success.
554 */
555SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_initHMAC_SHA1 (
556 rtlDigest Digest,
557 const sal_uInt8 *pKeyData, sal_uInt32 nKeyLen
558) SAL_THROW_EXTERN_C();
559
560
561/** Update a HMAC_SHA1 digest with given data.
562 @see rtl_digest_update()
563 */
564SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_updateHMAC_SHA1 (
565 rtlDigest Digest,
566 const void *pData, sal_uInt32 nDatLen
567) SAL_THROW_EXTERN_C();
568
569
570/** Finalize a HMAC_SHA1 digest and retrieve the digest value.
571 @see rtl_digest_get()
572 */
573SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_SHA1 (
574 rtlDigest Digest,
575 sal_uInt8 *pBuffer, sal_uInt32 nBufLen
576) SAL_THROW_EXTERN_C();
577
578
579/** Evaluate a HMAC_SHA1 digest value from given data.
580
581 This function performs an optimized call sequence on a
582 single data buffer, avoiding digest creation and destruction.
583
584 @see rtl_digest_initHMAC_SHA1()
585 @see rtl_digest_updateHMAC_SHA1()
586 @see rtl_digest_getHMAC_SHA1()
587
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.
594
595 @return rtl_Digest_E_None upon success.
596 */
597SAL_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();
602
603/*========================================================================
604 *
605 * rtl_digest_PBKDF2 interface.
606 *
607 *======================================================================*/
608/** Password-Based Key Derivation Function.
609
610 The PBKDF2 key derivation function is specified in
611 RFC 2898 (Informational)
612 PKCS #5: Password-Based Cryptography Specification Version 2.0
613
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
621
622 @return rtl_Digest_E_None upon success.
623*/
624SAL_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();
630
631/*========================================================================
632 *
633 * The End.
634 *
635 *======================================================================*/
636
637#ifdef __cplusplus
638}
639#endif
640
641#endif // INCLUDED_RTL_DIGEST_H
642
643/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
644