sal/inc/rtl/digest.h

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