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