security/nss/lib/freebl/blapi.h

   1 /*
   2  * crypto.h - public data structures and prototypes for the crypto library
   3  *
   4  * ***** BEGIN LICENSE BLOCK *****
   5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   6  *
   7  * The contents of this file are subject to the Mozilla Public License Version
   8  * 1.1 (the "License"); you may not use this file except in compliance with
   9  * the License. You may obtain a copy of the License at
  10  * http://www.mozilla.org/MPL/
  11  *
  12  * Software distributed under the License is distributed on an "AS IS" basis,
  13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14  * for the specific language governing rights and limitations under the
  15  * License.
  16  *
  17  * The Original Code is the Netscape security libraries.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *   Dr Vipul Gupta <vipul.gupta@sun.com>, Sun Microsystems Laboratories
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40 /* $Id: blapi.h,v 1.26 2007/02/28 19:47:37 rrelyea%redhat.com Exp $ */
  41
  42 #ifndef _BLAPI_H_
  43 #define _BLAPI_H_
  44
  45 #include "blapit.h"
  46 #include "hasht.h"
  47 #include "alghmac.h"
  48
  49 SEC_BEGIN_PROTOS
  50
  51 /*
  52 ** RSA encryption/decryption. When encrypting/decrypting the output
  53 ** buffer must be at least the size of the public key modulus.
  54 */
  55
  56 /*
  57 ** Generate and return a new RSA public and private key.
  58 **      Both keys are encoded in a single RSAPrivateKey structure.
  59 **      "cx" is the random number generator context
  60 **      "keySizeInBits" is the size of the key to be generated, in bits.
  61 **         512, 1024, etc.
  62 **      "publicExponent" when not NULL is a pointer to some data that
  63 **         represents the public exponent to use. The data is a byte
  64 **         encoded integer, in "big endian" order.
  65 */
  66 extern RSAPrivateKey *RSA_NewKey(int         keySizeInBits,
  67                                  SECItem *   publicExponent);
  68
  69 /*
  70 ** Perform a raw public-key operation
  71 **      Length of input and output buffers are equal to key's modulus len.
  72 */
  73 extern SECStatus RSA_PublicKeyOp(RSAPublicKey *   key,
  74                                  unsigned char *  output,
  75                                  const unsigned char *  input);
  76
  77 /*
  78 ** Perform a raw private-key operation
  79 **      Length of input and output buffers are equal to key's modulus len.
  80 */
  81 extern SECStatus RSA_PrivateKeyOp(RSAPrivateKey *  key,
  82                                   unsigned char *  output,
  83                                   const unsigned char *  input);
  84
  85 /*
  86 ** Perform a raw private-key operation, and check the parameters used in
  87 ** the operation for validity by performing a test operation first.
  88 **      Length of input and output buffers are equal to key's modulus len.
  89 */
  90 extern SECStatus RSA_PrivateKeyOpDoubleChecked(RSAPrivateKey *  key,
  91                                                unsigned char *  output,
  92                                                const unsigned char *  input);
  93
  94 /*
  95 ** Perform a check of private key parameters for consistency.
  96 */
  97 extern SECStatus RSA_PrivateKeyCheck(RSAPrivateKey *key);
  98
  99
 100 /********************************************************************
 101 ** DSA signing algorithm
 102 */
 103
 104 /*
 105 ** Generate and return a new DSA public and private key pair,
 106 **      both of which are encoded into a single DSAPrivateKey struct.
 107 **      "params" is a pointer to the PQG parameters for the domain
 108 **      Uses a random seed.
 109 */
 110 extern SECStatus DSA_NewKey(const PQGParams *     params,
 111                             DSAPrivateKey **      privKey);
 112
 113 /* signature is caller-supplied buffer of at least 20 bytes.
 114 ** On input,  signature->len == size of buffer to hold signature.
 115 **            digest->len    == size of digest.
 116 ** On output, signature->len == size of signature in buffer.
 117 ** Uses a random seed.
 118 */
 119 extern SECStatus DSA_SignDigest(DSAPrivateKey *   key,
 120                                 SECItem *         signature,
 121                                 const SECItem *   digest);
 122
 123 /* signature is caller-supplied buffer of at least 20 bytes.
 124 ** On input,  signature->len == size of buffer to hold signature.
 125 **            digest->len    == size of digest.
 126 */
 127 extern SECStatus DSA_VerifyDigest(DSAPublicKey *  key,
 128                                   const SECItem * signature,
 129                                   const SECItem * digest);
 130
 131 /* For FIPS compliance testing. Seed must be exactly 20 bytes long */
 132 extern SECStatus DSA_NewKeyFromSeed(const PQGParams *params,
 133                                     const unsigned char * seed,
 134                                     DSAPrivateKey **privKey);
 135
 136 /* For FIPS compliance testing. Seed must be exactly 20 bytes. */
 137 extern SECStatus DSA_SignDigestWithSeed(DSAPrivateKey * key,
 138                                         SECItem *       signature,
 139                                         const SECItem * digest,
 140                                         const unsigned char * seed);
 141
 142 /******************************************************
 143 ** Diffie Helman key exchange algorithm
 144 */
 145
 146 /* Generates parameters for Diffie-Helman key generation.
 147 **      primeLen is the length in bytes of prime P to be generated.
 148 */
 149 extern SECStatus DH_GenParam(int primeLen, DHParams ** params);
 150
 151 /* Generates a public and private key, both of which are encoded in a single
 152 **      DHPrivateKey struct. Params is input, privKey are output.
 153 **      This is Phase 1 of Diffie Hellman.
 154 */
 155 extern SECStatus DH_NewKey(DHParams *           params,
 156                            DHPrivateKey **      privKey);
 157
 158 /*
 159 ** DH_Derive does the Diffie-Hellman phase 2 calculation, using the
 160 ** other party's publicValue, and the prime and our privateValue.
 161 ** maxOutBytes is the requested length of the generated secret in bytes.
 162 ** A zero value means produce a value of any length up to the size of
 163 ** the prime.   If successful, derivedSecret->data is set
 164 ** to the address of the newly allocated buffer containing the derived
 165 ** secret, and derivedSecret->len is the size of the secret produced.
 166 ** The size of the secret produced will never be larger than the length
 167 ** of the prime, and it may be smaller than maxOutBytes.
 168 ** It is the caller's responsibility to free the allocated buffer
 169 ** containing the derived secret.
 170 */
 171 extern SECStatus DH_Derive(SECItem *    publicValue,
 172                            SECItem *    prime,
 173                            SECItem *    privateValue,
 174                            SECItem *    derivedSecret,
 175                            unsigned int maxOutBytes);
 176
 177 /*
 178 ** KEA_CalcKey returns octet string with the private key for a dual
 179 ** Diffie-Helman  key generation as specified for government key exchange.
 180 */
 181 extern SECStatus KEA_Derive(SECItem *prime,
 182                             SECItem *public1,
 183                             SECItem *public2,
 184                             SECItem *private1,
 185                             SECItem *private2,
 186                             SECItem *derivedSecret);
 187
 188 /*
 189  * verify that a KEA or DSA public key is a valid key for this prime and
 190  * subprime domain.
 191  */
 192 extern PRBool KEA_Verify(SECItem *Y, SECItem *prime, SECItem *subPrime);
 193
 194 /******************************************************
 195 ** Elliptic Curve algorithms
 196 */
 197
 198 /* Generates a public and private key, both of which are encoded
 199 ** in a single ECPrivateKey struct. Params is input, privKey are
 200 ** output.
 201 */
 202 extern SECStatus EC_NewKey(ECParams *          params,
 203                            ECPrivateKey **     privKey);
 204
 205 extern SECStatus EC_NewKeyFromSeed(ECParams *  params,
 206                            ECPrivateKey **     privKey,
 207                            const unsigned char* seed,
 208                            int                 seedlen);
 209
 210 /* Validates an EC public key as described in Section 5.2.2 of
 211  * X9.62. Such validation prevents against small subgroup attacks
 212  * when the ECDH primitive is used with the cofactor.
 213  */
 214 extern SECStatus EC_ValidatePublicKey(ECParams * params,
 215                            SECItem *           publicValue);
 216
 217 /*
 218 ** ECDH_Derive performs a scalar point multiplication of a point
 219 ** representing a (peer's) public key and a large integer representing
 220 ** a private key (its own). Both keys must use the same elliptic curve
 221 ** parameters. If the withCofactor parameter is true, the
 222 ** multiplication also uses the cofactor associated with the curve
 223 ** parameters.  The output of this scheme is the x-coordinate of the
 224 ** resulting point. If successful, derivedSecret->data is set to the
 225 ** address of the newly allocated buffer containing the derived
 226 ** secret, and derivedSecret->len is the size of the secret
 227 ** produced. It is the caller's responsibility to free the allocated
 228 ** buffer containing the derived secret.
 229 */
 230 extern SECStatus ECDH_Derive(SECItem *       publicValue,
 231                              ECParams *      params,
 232                              SECItem *       privateValue,
 233                              PRBool          withCofactor,
 234                              SECItem *       derivedSecret);
 235
 236 /* On input,  signature->len == size of buffer to hold signature.
 237 **            digest->len    == size of digest.
 238 ** On output, signature->len == size of signature in buffer.
 239 ** Uses a random seed.
 240 */
 241 extern SECStatus ECDSA_SignDigest(ECPrivateKey  *key,
 242                                   SECItem       *signature,
 243                                   const SECItem *digest);
 244
 245 /* On input,  signature->len == size of buffer to hold signature.
 246 **            digest->len    == size of digest.
 247 */
 248 extern SECStatus ECDSA_VerifyDigest(ECPublicKey   *key,
 249                                     const SECItem *signature,
 250                                     const SECItem *digest);
 251
 252 /* Uses the provided seed. */
 253 extern SECStatus ECDSA_SignDigestWithSeed(ECPrivateKey        *key,
 254                                           SECItem             *signature,
 255                                           const SECItem       *digest,
 256                                           const unsigned char *seed,
 257                                           const int           seedlen);
 258
 259 /******************************************/
 260 /*
 261 ** RC4 symmetric stream cypher
 262 */
 263
 264 /*
 265 ** Create a new RC4 context suitable for RC4 encryption/decryption.
 266 **      "key" raw key data
 267 **      "len" the number of bytes of key data
 268 */
 269 extern RC4Context *RC4_CreateContext(const unsigned char *key, int len);
 270
 271 extern RC4Context *RC4_AllocateContext(void);
 272 extern SECStatus   RC4_InitContext(RC4Context *cx,
 273                                    const unsigned char *key,
 274                                    unsigned int keylen,
 275                                    const unsigned char *,
 276                                    int,
 277                                    unsigned int ,
 278                                    unsigned int );
 279
 280 /*
 281 ** Destroy an RC4 encryption/decryption context.
 282 **      "cx" the context
 283 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 284 */
 285 extern void RC4_DestroyContext(RC4Context *cx, PRBool freeit);
 286
 287 /*
 288 ** Perform RC4 encryption.
 289 **      "cx" the context
 290 **      "output" the output buffer to store the encrypted data.
 291 **      "outputLen" how much data is stored in "output". Set by the routine
 292 **         after some data is stored in output.
 293 **      "maxOutputLen" the maximum amount of data that can ever be
 294 **         stored in "output"
 295 **      "input" the input data
 296 **      "inputLen" the amount of input data
 297 */
 298 extern SECStatus RC4_Encrypt(RC4Context *cx, unsigned char *output,
 299                             unsigned int *outputLen, unsigned int maxOutputLen,
 300                             const unsigned char *input, unsigned int inputLen);
 301
 302 /*
 303 ** Perform RC4 decryption.
 304 **      "cx" the context
 305 **      "output" the output buffer to store the decrypted data.
 306 **      "outputLen" how much data is stored in "output". Set by the routine
 307 **         after some data is stored in output.
 308 **      "maxOutputLen" the maximum amount of data that can ever be
 309 **         stored in "output"
 310 **      "input" the input data
 311 **      "inputLen" the amount of input data
 312 */
 313 extern SECStatus RC4_Decrypt(RC4Context *cx, unsigned char *output,
 314                             unsigned int *outputLen, unsigned int maxOutputLen,
 315                             const unsigned char *input, unsigned int inputLen);
 316
 317 /******************************************/
 318 /*
 319 ** RC2 symmetric block cypher
 320 */
 321
 322 /*
 323 ** Create a new RC2 context suitable for RC2 encryption/decryption.
 324 **      "key" raw key data
 325 **      "len" the number of bytes of key data
 326 **      "iv" is the CBC initialization vector (if mode is NSS_RC2_CBC)
 327 **      "mode" one of NSS_RC2 or NSS_RC2_CBC
 328 **      "effectiveKeyLen" is the effective key length (as specified in
 329 **          RFC 2268) in bytes (not bits).
 330 **
 331 ** When mode is set to NSS_RC2_CBC the RC2 cipher is run in "cipher block
 332 ** chaining" mode.
 333 */
 334 extern RC2Context *RC2_CreateContext(const unsigned char *key, unsigned int len,
 335                                      const unsigned char *iv, int mode,
 336                                      unsigned effectiveKeyLen);
 337 extern RC2Context *RC2_AllocateContext(void);
 338 extern SECStatus   RC2_InitContext(RC2Context *cx,
 339                                    const unsigned char *key,
 340                                    unsigned int keylen,
 341                                    const unsigned char *iv,
 342                                    int mode,
 343                                    unsigned int effectiveKeyLen,
 344                                    unsigned int );
 345
 346 /*
 347 ** Destroy an RC2 encryption/decryption context.
 348 **      "cx" the context
 349 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 350 */
 351 extern void RC2_DestroyContext(RC2Context *cx, PRBool freeit);
 352
 353 /*
 354 ** Perform RC2 encryption.
 355 **      "cx" the context
 356 **      "output" the output buffer to store the encrypted data.
 357 **      "outputLen" how much data is stored in "output". Set by the routine
 358 **         after some data is stored in output.
 359 **      "maxOutputLen" the maximum amount of data that can ever be
 360 **         stored in "output"
 361 **      "input" the input data
 362 **      "inputLen" the amount of input data
 363 */
 364 extern SECStatus RC2_Encrypt(RC2Context *cx, unsigned char *output,
 365                             unsigned int *outputLen, unsigned int maxOutputLen,
 366                             const unsigned char *input, unsigned int inputLen);
 367
 368 /*
 369 ** Perform RC2 decryption.
 370 **      "cx" the context
 371 **      "output" the output buffer to store the decrypted data.
 372 **      "outputLen" how much data is stored in "output". Set by the routine
 373 **         after some data is stored in output.
 374 **      "maxOutputLen" the maximum amount of data that can ever be
 375 **         stored in "output"
 376 **      "input" the input data
 377 **      "inputLen" the amount of input data
 378 */
 379 extern SECStatus RC2_Decrypt(RC2Context *cx, unsigned char *output,
 380                             unsigned int *outputLen, unsigned int maxOutputLen,
 381                             const unsigned char *input, unsigned int inputLen);
 382
 383 /******************************************/
 384 /*
 385 ** RC5 symmetric block cypher -- 64-bit block size
 386 */
 387
 388 /*
 389 ** Create a new RC5 context suitable for RC5 encryption/decryption.
 390 **      "key" raw key data
 391 **      "len" the number of bytes of key data
 392 **      "iv" is the CBC initialization vector (if mode is NSS_RC5_CBC)
 393 **      "mode" one of NSS_RC5 or NSS_RC5_CBC
 394 **
 395 ** When mode is set to NSS_RC5_CBC the RC5 cipher is run in "cipher block
 396 ** chaining" mode.
 397 */
 398 extern RC5Context *RC5_CreateContext(const SECItem *key, unsigned int rounds,
 399                      unsigned int wordSize, const unsigned char *iv, int mode);
 400 extern RC5Context *RC5_AllocateContext(void);
 401 extern SECStatus   RC5_InitContext(RC5Context *cx,
 402                                    const unsigned char *key,
 403                                    unsigned int keylen,
 404                                    const unsigned char *iv,
 405                                    int mode,
 406                                    unsigned int rounds,
 407                                    unsigned int wordSize);
 408
 409 /*
 410 ** Destroy an RC5 encryption/decryption context.
 411 **      "cx" the context
 412 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 413 */
 414 extern void RC5_DestroyContext(RC5Context *cx, PRBool freeit);
 415
 416 /*
 417 ** Perform RC5 encryption.
 418 **      "cx" the context
 419 **      "output" the output buffer to store the encrypted data.
 420 **      "outputLen" how much data is stored in "output". Set by the routine
 421 **         after some data is stored in output.
 422 **      "maxOutputLen" the maximum amount of data that can ever be
 423 **         stored in "output"
 424 **      "input" the input data
 425 **      "inputLen" the amount of input data
 426 */
 427 extern SECStatus RC5_Encrypt(RC5Context *cx, unsigned char *output,
 428                             unsigned int *outputLen, unsigned int maxOutputLen,
 429                             const unsigned char *input, unsigned int inputLen);
 430
 431 /*
 432 ** Perform RC5 decryption.
 433 **      "cx" the context
 434 **      "output" the output buffer to store the decrypted data.
 435 **      "outputLen" how much data is stored in "output". Set by the routine
 436 **         after some data is stored in output.
 437 **      "maxOutputLen" the maximum amount of data that can ever be
 438 **         stored in "output"
 439 **      "input" the input data
 440 **      "inputLen" the amount of input data
 441 */
 442
 443 extern SECStatus RC5_Decrypt(RC5Context *cx, unsigned char *output,
 444                             unsigned int *outputLen, unsigned int maxOutputLen,
 445                             const unsigned char *input, unsigned int inputLen);
 446
 447
 448
 449 /******************************************/
 450 /*
 451 ** DES symmetric block cypher
 452 */
 453
 454 /*
 455 ** Create a new DES context suitable for DES encryption/decryption.
 456 **      "key" raw key data
 457 **      "len" the number of bytes of key data
 458 **      "iv" is the CBC initialization vector (if mode is NSS_DES_CBC or
 459 **         mode is DES_EDE3_CBC)
 460 **      "mode" one of NSS_DES, NSS_DES_CBC, NSS_DES_EDE3 or NSS_DES_EDE3_CBC
 461 **      "encrypt" is PR_TRUE if the context will be used for encryption
 462 **
 463 ** When mode is set to NSS_DES_CBC or NSS_DES_EDE3_CBC then the DES
 464 ** cipher is run in "cipher block chaining" mode.
 465 */
 466 extern DESContext *DES_CreateContext(const unsigned char *key,
 467                                      const unsigned char *iv,
 468                                      int mode, PRBool encrypt);
 469 extern DESContext *DES_AllocateContext(void);
 470 extern SECStatus   DES_InitContext(DESContext *cx,
 471                                    const unsigned char *key,
 472                                    unsigned int keylen,
 473                                    const unsigned char *iv,
 474                                    int mode,
 475                                    unsigned int encrypt,
 476                                    unsigned int );
 477
 478 /*
 479 ** Destroy an DES encryption/decryption context.
 480 **      "cx" the context
 481 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 482 */
 483 extern void DES_DestroyContext(DESContext *cx, PRBool freeit);
 484
 485 /*
 486 ** Perform DES encryption.
 487 **      "cx" the context
 488 **      "output" the output buffer to store the encrypted data.
 489 **      "outputLen" how much data is stored in "output". Set by the routine
 490 **         after some data is stored in output.
 491 **      "maxOutputLen" the maximum amount of data that can ever be
 492 **         stored in "output"
 493 **      "input" the input data
 494 **      "inputLen" the amount of input data
 495 **
 496 ** NOTE: the inputLen must be a multiple of DES_KEY_LENGTH
 497 */
 498 extern SECStatus DES_Encrypt(DESContext *cx, unsigned char *output,
 499                             unsigned int *outputLen, unsigned int maxOutputLen,
 500                             const unsigned char *input, unsigned int inputLen);
 501
 502 /*
 503 ** Perform DES decryption.
 504 **      "cx" the context
 505 **      "output" the output buffer to store the decrypted data.
 506 **      "outputLen" how much data is stored in "output". Set by the routine
 507 **         after some data is stored in output.
 508 **      "maxOutputLen" the maximum amount of data that can ever be
 509 **         stored in "output"
 510 **      "input" the input data
 511 **      "inputLen" the amount of input data
 512 **
 513 ** NOTE: the inputLen must be a multiple of DES_KEY_LENGTH
 514 */
 515 extern SECStatus DES_Decrypt(DESContext *cx, unsigned char *output,
 516                             unsigned int *outputLen, unsigned int maxOutputLen,
 517                             const unsigned char *input, unsigned int inputLen);
 518
 519 /******************************************/
 520 /*
 521 ** AES symmetric block cypher (Rijndael)
 522 */
 523
 524 /*
 525 ** Create a new AES context suitable for AES encryption/decryption.
 526 **      "key" raw key data
 527 **      "keylen" the number of bytes of key data (16, 24, or 32)
 528 **      "blocklen" is the blocksize to use (16, 24, or 32)
 529 **                        XXX currently only blocksize==16 has been tested!
 530 */
 531 extern AESContext *
 532 AES_CreateContext(const unsigned char *key, const unsigned char *iv,
 533                   int mode, int encrypt,
 534                   unsigned int keylen, unsigned int blocklen);
 535 extern AESContext *AES_AllocateContext(void);
 536 extern SECStatus   AES_InitContext(AESContext *cx,
 537                                    const unsigned char *key,
 538                                    unsigned int keylen,
 539                                    const unsigned char *iv,
 540                                    int mode,
 541                                    unsigned int encrypt,
 542                                    unsigned int blocklen);
 543
 544 /*
 545 ** Destroy a AES encryption/decryption context.
 546 **      "cx" the context
 547 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 548 */
 549 extern void
 550 AES_DestroyContext(AESContext *cx, PRBool freeit);
 551
 552 /*
 553 ** Perform AES encryption.
 554 **      "cx" the context
 555 **      "output" the output buffer to store the encrypted data.
 556 **      "outputLen" how much data is stored in "output". Set by the routine
 557 **         after some data is stored in output.
 558 **      "maxOutputLen" the maximum amount of data that can ever be
 559 **         stored in "output"
 560 **      "input" the input data
 561 **      "inputLen" the amount of input data
 562 */
 563 extern SECStatus
 564 AES_Encrypt(AESContext *cx, unsigned char *output,
 565             unsigned int *outputLen, unsigned int maxOutputLen,
 566             const unsigned char *input, unsigned int inputLen);
 567
 568 /*
 569 ** Perform AES decryption.
 570 **      "cx" the context
 571 **      "output" the output buffer to store the decrypted data.
 572 **      "outputLen" how much data is stored in "output". Set by the routine
 573 **         after some data is stored in output.
 574 **      "maxOutputLen" the maximum amount of data that can ever be
 575 **         stored in "output"
 576 **      "input" the input data
 577 **      "inputLen" the amount of input data
 578 */
 579 extern SECStatus
 580 AES_Decrypt(AESContext *cx, unsigned char *output,
 581             unsigned int *outputLen, unsigned int maxOutputLen,
 582             const unsigned char *input, unsigned int inputLen);
 583
 584 /******************************************/
 585 /*
 586 ** AES key wrap algorithm, RFC 3394
 587 */
 588
 589 /*
 590 ** Create a new AES context suitable for AES encryption/decryption.
 591 **      "key" raw key data
 592 **      "iv"  The 8 byte "initial value"
 593 **      "encrypt", a boolean, true for key wrapping, false for unwrapping.
 594 **      "keylen" the number of bytes of key data (16, 24, or 32)
 595 */
 596 extern AESKeyWrapContext *
 597 AESKeyWrap_CreateContext(const unsigned char *key, const unsigned char *iv,
 598                          int encrypt, unsigned int keylen);
 599 extern AESKeyWrapContext * AESKeyWrap_AllocateContext(void);
 600 extern SECStatus
 601      AESKeyWrap_InitContext(AESKeyWrapContext *cx,
 602                                    const unsigned char *key,
 603                                    unsigned int keylen,
 604                                    const unsigned char *iv,
 605                                    int ,
 606                                    unsigned int encrypt,
 607                                    unsigned int );
 608
 609 /*
 610 ** Destroy a AES KeyWrap context.
 611 **      "cx" the context
 612 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 613 */
 614 extern void
 615 AESKeyWrap_DestroyContext(AESKeyWrapContext *cx, PRBool freeit);
 616
 617 /*
 618 ** Perform AES key wrap.
 619 **      "cx" the context
 620 **      "output" the output buffer to store the encrypted data.
 621 **      "outputLen" how much data is stored in "output". Set by the routine
 622 **         after some data is stored in output.
 623 **      "maxOutputLen" the maximum amount of data that can ever be
 624 **         stored in "output"
 625 **      "input" the input data
 626 **      "inputLen" the amount of input data
 627 */
 628 extern SECStatus
 629 AESKeyWrap_Encrypt(AESKeyWrapContext *cx, unsigned char *output,
 630             unsigned int *outputLen, unsigned int maxOutputLen,
 631             const unsigned char *input, unsigned int inputLen);
 632
 633 /*
 634 ** Perform AES key unwrap.
 635 **      "cx" the context
 636 **      "output" the output buffer to store the decrypted data.
 637 **      "outputLen" how much data is stored in "output". Set by the routine
 638 **         after some data is stored in output.
 639 **      "maxOutputLen" the maximum amount of data that can ever be
 640 **         stored in "output"
 641 **      "input" the input data
 642 **      "inputLen" the amount of input data
 643 */
 644 extern SECStatus
 645 AESKeyWrap_Decrypt(AESKeyWrapContext *cx, unsigned char *output,
 646             unsigned int *outputLen, unsigned int maxOutputLen,
 647             const unsigned char *input, unsigned int inputLen);
 648
 649  /******************************************/
 650 /*
 651 ** Camellia symmetric block cypher
 652 */
 653
 654 /*
 655 ** Create a new Camellia context suitable for Camellia encryption/decryption.
 656 **      "key" raw key data
 657 **      "keylen" the number of bytes of key data (16, 24, or 32)
 658 */
 659 extern CamelliaContext *
 660 Camellia_CreateContext(const unsigned char *key, const unsigned char *iv,
 661                        int mode, int encrypt, unsigned int keylen);
 662
 663 extern CamelliaContext *Camellia_AllocateContext(void);
 664 extern SECStatus   Camellia_InitContext(CamelliaContext *cx,
 665                                         const unsigned char *key,
 666                                         unsigned int keylen,
 667                                         const unsigned char *iv,
 668                                         int mode,
 669                                         unsigned int encrypt,
 670                                         unsigned int unused);
 671 /*
 672 ** Destroy a Camellia encryption/decryption context.
 673 **      "cx" the context
 674 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 675 */
 676 extern void
 677 Camellia_DestroyContext(CamelliaContext *cx, PRBool freeit);
 678
 679 /*
 680 ** Perform Camellia encryption.
 681 **      "cx" the context
 682 **      "output" the output buffer to store the encrypted data.
 683 **      "outputLen" how much data is stored in "output". Set by the routine
 684 **         after some data is stored in output.
 685 **      "maxOutputLen" the maximum amount of data that can ever be
 686 **         stored in "output"
 687 **      "input" the input data
 688 **      "inputLen" the amount of input data
 689 */
 690 extern SECStatus
 691 Camellia_Encrypt(CamelliaContext *cx, unsigned char *output,
 692                  unsigned int *outputLen, unsigned int maxOutputLen,
 693                  const unsigned char *input, unsigned int inputLen);
 694
 695 /*
 696 ** Perform Camellia decryption.
 697 **      "cx" the context
 698 **      "output" the output buffer to store the decrypted data.
 699 **      "outputLen" how much data is stored in "output". Set by the routine
 700 **         after some data is stored in output.
 701 **      "maxOutputLen" the maximum amount of data that can ever be
 702 **         stored in "output"
 703 **      "input" the input data
 704 **      "inputLen" the amount of input data
 705 */
 706 extern SECStatus
 707 Camellia_Decrypt(CamelliaContext *cx, unsigned char *output,
 708                  unsigned int *outputLen, unsigned int maxOutputLen,
 709                  const unsigned char *input, unsigned int inputLen);
 710
 711
 712 /******************************************/
 713 /*
 714 ** MD5 secure hash function
 715 */
 716
 717 /*
 718 ** Hash a null terminated string "src" into "dest" using MD5
 719 */
 720 extern SECStatus MD5_Hash(unsigned char *dest, const char *src);
 721
 722 /*
 723 ** Hash a non-null terminated string "src" into "dest" using MD5
 724 */
 725 extern SECStatus MD5_HashBuf(unsigned char *dest, const unsigned char *src,
 726                              uint32 src_length);
 727
 728 /*
 729 ** Create a new MD5 context
 730 */
 731 extern MD5Context *MD5_NewContext(void);
 732
 733
 734 /*
 735 ** Destroy an MD5 secure hash context.
 736 **      "cx" the context
 737 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 738 */
 739 extern void MD5_DestroyContext(MD5Context *cx, PRBool freeit);
 740
 741 /*
 742 ** Reset an MD5 context, preparing it for a fresh round of hashing
 743 */
 744 extern void MD5_Begin(MD5Context *cx);
 745
 746 /*
 747 ** Update the MD5 hash function with more data.
 748 **      "cx" the context
 749 **      "input" the data to hash
 750 **      "inputLen" the amount of data to hash
 751 */
 752 extern void MD5_Update(MD5Context *cx,
 753                        const unsigned char *input, unsigned int inputLen);
 754
 755 /*
 756 ** Finish the MD5 hash function. Produce the digested results in "digest"
 757 **      "cx" the context
 758 **      "digest" where the 16 bytes of digest data are stored
 759 **      "digestLen" where the digest length (16) is stored
 760 **      "maxDigestLen" the maximum amount of data that can ever be
 761 **         stored in "digest"
 762 */
 763 extern void MD5_End(MD5Context *cx, unsigned char *digest,
 764                     unsigned int *digestLen, unsigned int maxDigestLen);
 765
 766 /*
 767  * Return the the size of a buffer needed to flatten the MD5 Context into
 768  *    "cx" the context
 769  *  returns size;
 770  */
 771 extern unsigned int MD5_FlattenSize(MD5Context *cx);
 772
 773 /*
 774  * Flatten the MD5 Context into a buffer:
 775  *    "cx" the context
 776  *    "space" the buffer to flatten to
 777  *  returns status;
 778  */
 779 extern SECStatus MD5_Flatten(MD5Context *cx,unsigned char *space);
 780
 781 /*
 782  * Resurrect a flattened context into a MD5 Context
 783  *    "space" the buffer of the flattend buffer
 784  *    "arg" ptr to void used by cryptographic resurrect
 785  *  returns resurected context;
 786  */
 787 extern MD5Context * MD5_Resurrect(unsigned char *space, void *arg);
 788 extern void MD5_Clone(MD5Context *dest, MD5Context *src);
 789
 790 /*
 791 ** trace the intermediate state info of the MD5 hash.
 792 */
 793 extern void MD5_TraceState(MD5Context *cx);
 794
 795
 796 /******************************************/
 797 /*
 798 ** MD2 secure hash function
 799 */
 800
 801 /*
 802 ** Hash a null terminated string "src" into "dest" using MD2
 803 */
 804 extern SECStatus MD2_Hash(unsigned char *dest, const char *src);
 805
 806 /*
 807 ** Create a new MD2 context
 808 */
 809 extern MD2Context *MD2_NewContext(void);
 810
 811
 812 /*
 813 ** Destroy an MD2 secure hash context.
 814 **      "cx" the context
 815 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 816 */
 817 extern void MD2_DestroyContext(MD2Context *cx, PRBool freeit);
 818
 819 /*
 820 ** Reset an MD2 context, preparing it for a fresh round of hashing
 821 */
 822 extern void MD2_Begin(MD2Context *cx);
 823
 824 /*
 825 ** Update the MD2 hash function with more data.
 826 **      "cx" the context
 827 **      "input" the data to hash
 828 **      "inputLen" the amount of data to hash
 829 */
 830 extern void MD2_Update(MD2Context *cx,
 831                        const unsigned char *input, unsigned int inputLen);
 832
 833 /*
 834 ** Finish the MD2 hash function. Produce the digested results in "digest"
 835 **      "cx" the context
 836 **      "digest" where the 16 bytes of digest data are stored
 837 **      "digestLen" where the digest length (16) is stored
 838 **      "maxDigestLen" the maximum amount of data that can ever be
 839 **         stored in "digest"
 840 */
 841 extern void MD2_End(MD2Context *cx, unsigned char *digest,
 842                     unsigned int *digestLen, unsigned int maxDigestLen);
 843
 844 /*
 845  * Return the the size of a buffer needed to flatten the MD2 Context into
 846  *    "cx" the context
 847  *  returns size;
 848  */
 849 extern unsigned int MD2_FlattenSize(MD2Context *cx);
 850
 851 /*
 852  * Flatten the MD2 Context into a buffer:
 853  *    "cx" the context
 854  *    "space" the buffer to flatten to
 855  *  returns status;
 856  */
 857 extern SECStatus MD2_Flatten(MD2Context *cx,unsigned char *space);
 858
 859 /*
 860  * Resurrect a flattened context into a MD2 Context
 861  *    "space" the buffer of the flattend buffer
 862  *    "arg" ptr to void used by cryptographic resurrect
 863  *  returns resurected context;
 864  */
 865 extern MD2Context * MD2_Resurrect(unsigned char *space, void *arg);
 866 extern void MD2_Clone(MD2Context *dest, MD2Context *src);
 867
 868 /******************************************/
 869 /*
 870 ** SHA-1 secure hash function
 871 */
 872
 873 /*
 874 ** Hash a null terminated string "src" into "dest" using SHA-1
 875 */
 876 extern SECStatus SHA1_Hash(unsigned char *dest, const char *src);
 877
 878 /*
 879 ** Hash a non-null terminated string "src" into "dest" using SHA-1
 880 */
 881 extern SECStatus SHA1_HashBuf(unsigned char *dest, const unsigned char *src,
 882                               uint32 src_length);
 883
 884 /*
 885 ** Create a new SHA-1 context
 886 */
 887 extern SHA1Context *SHA1_NewContext(void);
 888
 889
 890 /*
 891 ** Destroy a SHA-1 secure hash context.
 892 **      "cx" the context
 893 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
 894 */
 895 extern void SHA1_DestroyContext(SHA1Context *cx, PRBool freeit);
 896
 897 /*
 898 ** Reset a SHA-1 context, preparing it for a fresh round of hashing
 899 */
 900 extern void SHA1_Begin(SHA1Context *cx);
 901
 902 /*
 903 ** Update the SHA-1 hash function with more data.
 904 **      "cx" the context
 905 **      "input" the data to hash
 906 **      "inputLen" the amount of data to hash
 907 */
 908 extern void SHA1_Update(SHA1Context *cx, const unsigned char *input,
 909                         unsigned int inputLen);
 910
 911 /*
 912 ** Finish the SHA-1 hash function. Produce the digested results in "digest"
 913 **      "cx" the context
 914 **      "digest" where the 16 bytes of digest data are stored
 915 **      "digestLen" where the digest length (20) is stored
 916 **      "maxDigestLen" the maximum amount of data that can ever be
 917 **         stored in "digest"
 918 */
 919 extern void SHA1_End(SHA1Context *cx, unsigned char *digest,
 920                      unsigned int *digestLen, unsigned int maxDigestLen);
 921
 922 /*
 923 ** trace the intermediate state info of the SHA1 hash.
 924 */
 925 extern void SHA1_TraceState(SHA1Context *cx);
 926
 927 /*
 928  * Return the the size of a buffer needed to flatten the SHA-1 Context into
 929  *    "cx" the context
 930  *  returns size;
 931  */
 932 extern unsigned int SHA1_FlattenSize(SHA1Context *cx);
 933
 934 /*
 935  * Flatten the SHA-1 Context into a buffer:
 936  *    "cx" the context
 937  *    "space" the buffer to flatten to
 938  *  returns status;
 939  */
 940 extern SECStatus SHA1_Flatten(SHA1Context *cx,unsigned char *space);
 941
 942 /*
 943  * Resurrect a flattened context into a SHA-1 Context
 944  *    "space" the buffer of the flattend buffer
 945  *    "arg" ptr to void used by cryptographic resurrect
 946  *  returns resurected context;
 947  */
 948 extern SHA1Context * SHA1_Resurrect(unsigned char *space, void *arg);
 949 extern void SHA1_Clone(SHA1Context *dest, SHA1Context *src);
 950
 951 /******************************************/
 952
 953 extern SHA256Context *SHA256_NewContext(void);
 954 extern void SHA256_DestroyContext(SHA256Context *cx, PRBool freeit);
 955 extern void SHA256_Begin(SHA256Context *cx);
 956 extern void SHA256_Update(SHA256Context *cx, const unsigned char *input,
 957                         unsigned int inputLen);
 958 extern void SHA256_End(SHA256Context *cx, unsigned char *digest,
 959                      unsigned int *digestLen, unsigned int maxDigestLen);
 960 extern SECStatus SHA256_HashBuf(unsigned char *dest, const unsigned char *src,
 961                               uint32 src_length);
 962 extern SECStatus SHA256_Hash(unsigned char *dest, const char *src);
 963 extern void SHA256_TraceState(SHA256Context *cx);
 964 extern unsigned int SHA256_FlattenSize(SHA256Context *cx);
 965 extern SECStatus SHA256_Flatten(SHA256Context *cx,unsigned char *space);
 966 extern SHA256Context * SHA256_Resurrect(unsigned char *space, void *arg);
 967 extern void SHA256_Clone(SHA256Context *dest, SHA256Context *src);
 968
 969 /******************************************/
 970
 971 extern SHA512Context *SHA512_NewContext(void);
 972 extern void SHA512_DestroyContext(SHA512Context *cx, PRBool freeit);
 973 extern void SHA512_Begin(SHA512Context *cx);
 974 extern void SHA512_Update(SHA512Context *cx, const unsigned char *input,
 975                         unsigned int inputLen);
 976 extern void SHA512_End(SHA512Context *cx, unsigned char *digest,
 977                      unsigned int *digestLen, unsigned int maxDigestLen);
 978 extern SECStatus SHA512_HashBuf(unsigned char *dest, const unsigned char *src,
 979                               uint32 src_length);
 980 extern SECStatus SHA512_Hash(unsigned char *dest, const char *src);
 981 extern void SHA512_TraceState(SHA512Context *cx);
 982 extern unsigned int SHA512_FlattenSize(SHA512Context *cx);
 983 extern SECStatus SHA512_Flatten(SHA512Context *cx,unsigned char *space);
 984 extern SHA512Context * SHA512_Resurrect(unsigned char *space, void *arg);
 985 extern void SHA512_Clone(SHA512Context *dest, SHA512Context *src);
 986
 987 /******************************************/
 988
 989 extern SHA384Context *SHA384_NewContext(void);
 990 extern void SHA384_DestroyContext(SHA384Context *cx, PRBool freeit);
 991 extern void SHA384_Begin(SHA384Context *cx);
 992 extern void SHA384_Update(SHA384Context *cx, const unsigned char *input,
 993                         unsigned int inputLen);
 994 extern void SHA384_End(SHA384Context *cx, unsigned char *digest,
 995                      unsigned int *digestLen, unsigned int maxDigestLen);
 996 extern SECStatus SHA384_HashBuf(unsigned char *dest, const unsigned char *src,
 997                               uint32 src_length);
 998 extern SECStatus SHA384_Hash(unsigned char *dest, const char *src);
 999 extern void SHA384_TraceState(SHA384Context *cx);
1000 extern unsigned int SHA384_FlattenSize(SHA384Context *cx);
1001 extern SECStatus SHA384_Flatten(SHA384Context *cx,unsigned char *space);
1002 extern SHA384Context * SHA384_Resurrect(unsigned char *space, void *arg);
1003 extern void SHA384_Clone(SHA384Context *dest, SHA384Context *src);
1004
1005 /****************************************
1006  * implement TLS Pseudo Random Function (PRF)
1007  */
1008
1009 extern SECStatus
1010 TLS_PRF(const SECItem *secret, const char *label, SECItem *seed,
1011          SECItem *result, PRBool isFIPS);
1012
1013 /******************************************/
1014 /*
1015 ** Pseudo Random Number Generation.  FIPS compliance desirable.
1016 */
1017
1018 /*
1019 ** Initialize the global RNG context and give it some seed input taken
1020 ** from the system.  This function is thread-safe and will only allow
1021 ** the global context to be initialized once.  The seed input is likely
1022 ** small, so it is imperative that RNG_RandomUpdate() be called with
1023 ** additional seed data before the generator is used.  A good way to
1024 ** provide the generator with additional entropy is to call
1025 ** RNG_SystemInfoForRNG().  Note that NSS_Init() does exactly that.
1026 */
1027 extern SECStatus RNG_RNGInit(void);
1028
1029 /*
1030 ** Update the global random number generator with more seeding
1031 ** material
1032 */
1033 extern SECStatus RNG_RandomUpdate(const void *data, size_t bytes);
1034
1035 /*
1036 ** Generate some random bytes, using the global random number generator
1037 ** object.
1038 */
1039 extern SECStatus RNG_GenerateGlobalRandomBytes(void *dest, size_t len);
1040
1041 /* Destroy the global RNG context.  After a call to RNG_RNGShutdown()
1042 ** a call to RNG_RNGInit() is required in order to use the generator again,
1043 ** along with seed data (see the comment above RNG_RNGInit()).
1044 */
1045 extern void  RNG_RNGShutdown(void);
1046
1047 extern void RNG_SystemInfoForRNG(void);
1048
1049 /*
1050  * FIPS 186-2 Change Notice 1 RNG Algorithm 1, used both to
1051  * generate the DSA X parameter and as a generic purpose RNG.
1052  *
1053  * The following two FIPS186Change functions are needed for
1054  * NIST RNG Validation System.
1055  */
1056
1057 /*
1058  * Given the seed-key and the seed, generate the random output.
1059  *
1060  * Parameters:
1061  *   XKEY [input/output]: the state of the RNG (seed-key)
1062  *   XSEEDj [input]: optional user input (seed)
1063  *   x_j [output]: output of the RNG
1064  *
1065  * Return value:
1066  * This function usually returns SECSuccess.  The only reason
1067  * this function returns SECFailure is that XSEEDj equals
1068  * XKEY, including the intermediate XKEY value between the two
1069  * iterations.  (This test is actually a FIPS 140-2 requirement
1070  * and not required for FIPS algorithm testing, but it is too
1071  * hard to separate from this function.)  If this function fails,
1072  * XKEY is not updated, but some data may have been written to
1073  * x_j, which should be ignored.
1074  */
1075 extern SECStatus
1076 FIPS186Change_GenerateX(unsigned char *XKEY,
1077                         const unsigned char *XSEEDj,
1078                         unsigned char *x_j);
1079
1080 /*
1081  * When generating the DSA X parameter, we generate 2*GSIZE bytes
1082  * of random output and reduce it mod q.
1083  *
1084  * Input: w, 2*GSIZE bytes
1085  *        q, DSA_SUBPRIME_LEN bytes
1086  * Output: xj, DSA_SUBPRIME_LEN bytes
1087  */
1088 extern SECStatus
1089 FIPS186Change_ReduceModQForDSA(const unsigned char *w,
1090                                const unsigned char *q,
1091                                unsigned char *xj);
1092
1093 /* Generate PQGParams and PQGVerify structs.
1094  * Length of seed and length of h both equal length of P.
1095  * All lengths are specified by "j", according to the table above.
1096  */
1097 extern SECStatus
1098 PQG_ParamGen(unsigned int j,       /* input : determines length of P. */
1099              PQGParams **pParams,  /* output: P Q and G returned here */
1100              PQGVerify **pVfy);    /* output: counter and seed. */
1101
1102 /* Generate PQGParams and PQGVerify structs.
1103  * Length of P specified by j.  Length of h will match length of P.
1104  * Length of SEED in bytes specified in seedBytes.
1105  * seedBbytes must be in the range [20..255] or an error will result.
1106  */
1107 extern SECStatus
1108 PQG_ParamGenSeedLen(
1109              unsigned int j,         /* input : determines length of P. */
1110              unsigned int seedBytes, /* input : length of seed in bytes.*/
1111              PQGParams **pParams,    /* output: P Q and G returned here */
1112              PQGVerify **pVfy);      /* output: counter and seed. */
1113
1114
1115 /*  Test PQGParams for validity as DSS PQG values.
1116  *  If vfy is non-NULL, test PQGParams to make sure they were generated
1117  *       using the specified seed, counter, and h values.
1118  *
1119  *  Return value indicates whether Verification operation ran succesfully
1120  *  to completion, but does not indicate if PQGParams are valid or not.
1121  *  If return value is SECSuccess, then *pResult has these meanings:
1122  *       SECSuccess: PQGParams are valid.
1123  *       SECFailure: PQGParams are invalid.
1124  *
1125  * Verify the following 12 facts about PQG counter SEED g and h
1126  * 1.  Q is 160 bits long.
1127  * 2.  P is one of the 9 valid lengths.
1128  * 3.  G < P
1129  * 4.  P % Q == 1
1130  * 5.  Q is prime
1131  * 6.  P is prime
1132  * Steps 7-12 are done only if the optional PQGVerify is supplied.
1133  * 7.  counter < 4096
1134  * 8.  g >= 160 and g < 2048   (g is length of seed in bits)
1135  * 9.  Q generated from SEED matches Q in PQGParams.
1136  * 10. P generated from (L, counter, g, SEED, Q) matches P in PQGParams.
1137  * 11. 1 < h < P-1
1138  * 12. G generated from h matches G in PQGParams.
1139  */
1140
1141 extern SECStatus   PQG_VerifyParams(const PQGParams *params,
1142                                     const PQGVerify *vfy, SECStatus *result);
1143
1144
1145 /*
1146  * clean-up any global tables freebl may have allocated after it starts up.
1147  * This function is not thread safe and should be called only after the
1148  * library has been quiessed.
1149  */
1150 extern void BL_Cleanup(void);
1151
1152 /* unload freebl shared library from memory */
1153 extern void BL_Unload(void);
1154
1155 /**************************************************************************
1156  *  Verify a given Shared library signature                               *
1157  **************************************************************************/
1158 PRBool BLAPI_SHVerify(const char *name, PRFuncPtr addr);
1159
1160 /**************************************************************************
1161  *  Verify Are Own Shared library signature                               *
1162  **************************************************************************/
1163 PRBool BLAPI_VerifySelf(const char *name);
1164
1165 /*********************************************************************/
1166 extern const SECHashObject * HASH_GetRawHashObject(HASH_HashType hashType);
1167
1168 SEC_END_PROTOS
1169
1170 #endif /* _BLAPI_H_ */