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