Back to index

lightning-sunbird  0.9+nobinonly
blapi.h
Go to the documentation of this file.
00001 /*
00002  * crypto.h - public data structures and prototypes for the crypto library
00003  *
00004  * ***** BEGIN LICENSE BLOCK *****
00005  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00006  *
00007  * The contents of this file are subject to the Mozilla Public License Version
00008  * 1.1 (the "License"); you may not use this file except in compliance with
00009  * the License. You may obtain a copy of the License at
00010  * http://www.mozilla.org/MPL/
00011  *
00012  * Software distributed under the License is distributed on an "AS IS" basis,
00013  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00014  * for the specific language governing rights and limitations under the
00015  * License.
00016  *
00017  * The Original Code is the Netscape security libraries.
00018  *
00019  * The Initial Developer of the Original Code is
00020  * Netscape Communications Corporation.
00021  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00022  * the Initial Developer. All Rights Reserved.
00023  *
00024  * Contributor(s):
00025  *   Dr Vipul Gupta <vipul.gupta@sun.com>, Sun Microsystems Laboratories
00026  *
00027  * Alternatively, the contents of this file may be used under the terms of
00028  * either the GNU General Public License Version 2 or later (the "GPL"), or
00029  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00030  * in which case the provisions of the GPL or the LGPL are applicable instead
00031  * of those above. If you wish to allow use of your version of this file only
00032  * under the terms of either the GPL or the LGPL, and not to allow others to
00033  * use your version of this file under the terms of the MPL, indicate your
00034  * decision by deleting the provisions above and replace them with the notice
00035  * and other provisions required by the GPL or the LGPL. If you do not delete
00036  * the provisions above, a recipient may use your version of this file under
00037  * the terms of any one of the MPL, the GPL or the LGPL.
00038  *
00039  * ***** END LICENSE BLOCK ***** */
00040 /* $Id: blapi.h,v 1.23.2.2 2006/10/02 21:17:58 julien.pierre.bugs%sun.com Exp $ */
00041 
00042 #ifndef _BLAPI_H_
00043 #define _BLAPI_H_
00044 
00045 #include "blapit.h"
00046 #include "hasht.h"
00047 #include "alghmac.h"
00048 
00049 SEC_BEGIN_PROTOS
00050 
00051 /*
00052 ** RSA encryption/decryption. When encrypting/decrypting the output
00053 ** buffer must be at least the size of the public key modulus.
00054 */
00055 
00056 /*
00057 ** Generate and return a new RSA public and private key.
00058 **     Both keys are encoded in a single RSAPrivateKey structure.
00059 **     "cx" is the random number generator context
00060 **     "keySizeInBits" is the size of the key to be generated, in bits.
00061 **        512, 1024, etc.
00062 **     "publicExponent" when not NULL is a pointer to some data that
00063 **        represents the public exponent to use. The data is a byte
00064 **        encoded integer, in "big endian" order.
00065 */
00066 extern RSAPrivateKey *RSA_NewKey(int         keySizeInBits,
00067                              SECItem *   publicExponent);
00068 
00069 /*
00070 ** Perform a raw public-key operation 
00071 **     Length of input and output buffers are equal to key's modulus len.
00072 */
00073 extern SECStatus RSA_PublicKeyOp(RSAPublicKey *   key,
00074                              unsigned char *  output,
00075                              const unsigned char *  input);
00076 
00077 /*
00078 ** Perform a raw private-key operation 
00079 **     Length of input and output buffers are equal to key's modulus len.
00080 */
00081 extern SECStatus RSA_PrivateKeyOp(RSAPrivateKey *  key,
00082                               unsigned char *  output,
00083                               const unsigned char *  input);
00084 
00085 /*
00086 ** Perform a raw private-key operation, and check the parameters used in
00087 ** the operation for validity by performing a test operation first.
00088 **     Length of input and output buffers are equal to key's modulus len.
00089 */
00090 extern SECStatus RSA_PrivateKeyOpDoubleChecked(RSAPrivateKey *  key,
00091                                            unsigned char *  output,
00092                                            const unsigned char *  input);
00093 
00094 /*
00095 ** Perform a check of private key parameters for consistency.
00096 */
00097 extern SECStatus RSA_PrivateKeyCheck(RSAPrivateKey *key);
00098 
00099 
00100 /********************************************************************
00101 ** DSA signing algorithm
00102 */
00103 
00104 /*
00105 ** Generate and return a new DSA public and private key pair,
00106 **     both of which are encoded into a single DSAPrivateKey struct.
00107 **     "params" is a pointer to the PQG parameters for the domain
00108 **     Uses a random seed.
00109 */
00110 extern SECStatus DSA_NewKey(const PQGParams *     params, 
00111                           DSAPrivateKey **      privKey);
00112 
00113 /* signature is caller-supplied buffer of at least 20 bytes.
00114 ** On input,  signature->len == size of buffer to hold signature.
00115 **            digest->len    == size of digest.
00116 ** On output, signature->len == size of signature in buffer.
00117 ** Uses a random seed.
00118 */
00119 extern SECStatus DSA_SignDigest(DSAPrivateKey *   key,
00120                             SECItem *         signature,
00121                             const SECItem *   digest);
00122 
00123 /* signature is caller-supplied buffer of at least 20 bytes.
00124 ** On input,  signature->len == size of buffer to hold signature.
00125 **            digest->len    == size of digest.
00126 */
00127 extern SECStatus DSA_VerifyDigest(DSAPublicKey *  key,
00128                               const SECItem * signature,
00129                               const SECItem * digest);
00130 
00131 /* For FIPS compliance testing. Seed must be exactly 20 bytes long */
00132 extern SECStatus DSA_NewKeyFromSeed(const PQGParams *params, 
00133                                     const unsigned char * seed,
00134                                     DSAPrivateKey **privKey);
00135 
00136 /* For FIPS compliance testing. Seed must be exactly 20 bytes. */
00137 extern SECStatus DSA_SignDigestWithSeed(DSAPrivateKey * key,
00138                                         SECItem *       signature,
00139                                         const SECItem * digest,
00140                                         const unsigned char * seed);
00141 
00142 /******************************************************
00143 ** Diffie Helman key exchange algorithm 
00144 */
00145 
00146 /* Generates parameters for Diffie-Helman key generation.
00147 **     primeLen is the length in bytes of prime P to be generated.
00148 */
00149 extern SECStatus DH_GenParam(int primeLen, DHParams ** params);
00150 
00151 /* Generates a public and private key, both of which are encoded in a single
00152 **     DHPrivateKey struct. Params is input, privKey are output.  
00153 **     This is Phase 1 of Diffie Hellman.
00154 */
00155 extern SECStatus DH_NewKey(DHParams *           params, 
00156                            DHPrivateKey **       privKey);
00157 
00158 /* 
00159 ** DH_Derive does the Diffie-Hellman phase 2 calculation, using the 
00160 ** other party's publicValue, and the prime and our privateValue.
00161 ** maxOutBytes is the requested length of the generated secret in bytes.  
00162 ** A zero value means produce a value of any length up to the size of 
00163 ** the prime.   If successful, derivedSecret->data is set 
00164 ** to the address of the newly allocated buffer containing the derived 
00165 ** secret, and derivedSecret->len is the size of the secret produced.
00166 ** The size of the secret produced will never be larger than the length
00167 ** of the prime, and it may be smaller than maxOutBytes.
00168 ** It is the caller's responsibility to free the allocated buffer 
00169 ** containing the derived secret.
00170 */
00171 extern SECStatus DH_Derive(SECItem *    publicValue, 
00172                          SECItem *    prime, 
00173                         SECItem *    privateValue, 
00174                         SECItem *    derivedSecret,
00175                         unsigned int maxOutBytes);
00176 
00177 /* 
00178 ** KEA_CalcKey returns octet string with the private key for a dual
00179 ** Diffie-Helman  key generation as specified for government key exchange.
00180 */
00181 extern SECStatus KEA_Derive(SECItem *prime, 
00182                             SECItem *public1, 
00183                             SECItem *public2, 
00184                          SECItem *private1, 
00185                          SECItem *private2,
00186                          SECItem *derivedSecret);
00187 
00188 /*
00189  * verify that a KEA or DSA public key is a valid key for this prime and
00190  * subprime domain.
00191  */
00192 extern PRBool KEA_Verify(SECItem *Y, SECItem *prime, SECItem *subPrime);
00193 
00194 /******************************************************
00195 ** Elliptic Curve algorithms
00196 */
00197 
00198 /* Generates a public and private key, both of which are encoded 
00199 ** in a single ECPrivateKey struct. Params is input, privKey are
00200 ** output.
00201 */
00202 extern SECStatus EC_NewKey(ECParams *          params, 
00203                            ECPrivateKey **     privKey);
00204 
00205 extern SECStatus EC_NewKeyFromSeed(ECParams *  params, 
00206                            ECPrivateKey **     privKey,
00207                            const unsigned char* seed,
00208                            int                 seedlen);
00209 
00210 /* Validates an EC public key as described in Section 5.2.2 of
00211  * X9.62. Such validation prevents against small subgroup attacks
00212  * when the ECDH primitive is used with the cofactor.
00213  */
00214 extern SECStatus EC_ValidatePublicKey(ECParams * params, 
00215                            SECItem *           publicValue);
00216 
00217 /* 
00218 ** ECDH_Derive performs a scalar point multiplication of a point
00219 ** representing a (peer's) public key and a large integer representing
00220 ** a private key (its own). Both keys must use the same elliptic curve
00221 ** parameters. If the withCofactor parameter is true, the
00222 ** multiplication also uses the cofactor associated with the curve
00223 ** parameters.  The output of this scheme is the x-coordinate of the
00224 ** resulting point. If successful, derivedSecret->data is set to the
00225 ** address of the newly allocated buffer containing the derived
00226 ** secret, and derivedSecret->len is the size of the secret
00227 ** produced. It is the caller's responsibility to free the allocated
00228 ** buffer containing the derived secret.
00229 */
00230 extern SECStatus ECDH_Derive(SECItem *       publicValue,
00231                              ECParams *      params,
00232                              SECItem *       privateValue,
00233                              PRBool          withCofactor,
00234                              SECItem *       derivedSecret);
00235 
00236 /* On input,  signature->len == size of buffer to hold signature.
00237 **            digest->len    == size of digest.
00238 ** On output, signature->len == size of signature in buffer.
00239 ** Uses a random seed.
00240 */
00241 extern SECStatus ECDSA_SignDigest(ECPrivateKey  *key, 
00242                                   SECItem       *signature, 
00243                                   const SECItem *digest);
00244 
00245 /* On input,  signature->len == size of buffer to hold signature.
00246 **            digest->len    == size of digest.
00247 */
00248 extern SECStatus ECDSA_VerifyDigest(ECPublicKey   *key, 
00249                                     const SECItem *signature, 
00250                                     const SECItem *digest);
00251 
00252 /* Uses the provided seed. */
00253 extern SECStatus ECDSA_SignDigestWithSeed(ECPrivateKey        *key,
00254                                           SECItem             *signature,
00255                                           const SECItem       *digest,
00256                                           const unsigned char *seed, 
00257                                           const int           seedlen);
00258 
00259 /******************************************/
00260 /*
00261 ** RC4 symmetric stream cypher
00262 */
00263 
00264 /*
00265 ** Create a new RC4 context suitable for RC4 encryption/decryption.
00266 **     "key" raw key data
00267 **     "len" the number of bytes of key data
00268 */
00269 extern RC4Context *RC4_CreateContext(const unsigned char *key, int len);
00270 
00271 extern RC4Context *RC4_AllocateContext(void);
00272 extern SECStatus   RC4_InitContext(RC4Context *cx, 
00273                                const unsigned char *key, 
00274                                unsigned int keylen,
00275                                const unsigned char *, 
00276                                int, 
00277                                unsigned int ,
00278                                unsigned int );
00279 
00280 /*
00281 ** Destroy an RC4 encryption/decryption context.
00282 **     "cx" the context
00283 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00284 */
00285 extern void RC4_DestroyContext(RC4Context *cx, PRBool freeit);
00286 
00287 /*
00288 ** Perform RC4 encryption.
00289 **     "cx" the context
00290 **     "output" the output buffer to store the encrypted data.
00291 **     "outputLen" how much data is stored in "output". Set by the routine
00292 **        after some data is stored in output.
00293 **     "maxOutputLen" the maximum amount of data that can ever be
00294 **        stored in "output"
00295 **     "input" the input data
00296 **     "inputLen" the amount of input data
00297 */
00298 extern SECStatus RC4_Encrypt(RC4Context *cx, unsigned char *output,
00299                          unsigned int *outputLen, unsigned int maxOutputLen,
00300                          const unsigned char *input, unsigned int inputLen);
00301 
00302 /*
00303 ** Perform RC4 decryption.
00304 **     "cx" the context
00305 **     "output" the output buffer to store the decrypted data.
00306 **     "outputLen" how much data is stored in "output". Set by the routine
00307 **        after some data is stored in output.
00308 **     "maxOutputLen" the maximum amount of data that can ever be
00309 **        stored in "output"
00310 **     "input" the input data
00311 **     "inputLen" the amount of input data
00312 */
00313 extern SECStatus RC4_Decrypt(RC4Context *cx, unsigned char *output,
00314                          unsigned int *outputLen, unsigned int maxOutputLen,
00315                          const unsigned char *input, unsigned int inputLen);
00316 
00317 /******************************************/
00318 /*
00319 ** RC2 symmetric block cypher
00320 */
00321 
00322 /*
00323 ** Create a new RC2 context suitable for RC2 encryption/decryption.
00324 **     "key" raw key data
00325 **     "len" the number of bytes of key data
00326 **     "iv" is the CBC initialization vector (if mode is NSS_RC2_CBC)
00327 **     "mode" one of NSS_RC2 or NSS_RC2_CBC
00328 **     "effectiveKeyLen" is the effective key length (as specified in 
00329 **         RFC 2268) in bytes (not bits).
00330 **
00331 ** When mode is set to NSS_RC2_CBC the RC2 cipher is run in "cipher block
00332 ** chaining" mode.
00333 */
00334 extern RC2Context *RC2_CreateContext(const unsigned char *key, unsigned int len,
00335                                  const unsigned char *iv, int mode, 
00336                                  unsigned effectiveKeyLen);
00337 extern RC2Context *RC2_AllocateContext(void);
00338 extern SECStatus   RC2_InitContext(RC2Context *cx,
00339                                const unsigned char *key, 
00340                                unsigned int keylen,
00341                                const unsigned char *iv, 
00342                                int mode, 
00343                                unsigned int effectiveKeyLen,
00344                                unsigned int );
00345 
00346 /*
00347 ** Destroy an RC2 encryption/decryption context.
00348 **     "cx" the context
00349 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00350 */
00351 extern void RC2_DestroyContext(RC2Context *cx, PRBool freeit);
00352 
00353 /*
00354 ** Perform RC2 encryption.
00355 **     "cx" the context
00356 **     "output" the output buffer to store the encrypted data.
00357 **     "outputLen" how much data is stored in "output". Set by the routine
00358 **        after some data is stored in output.
00359 **     "maxOutputLen" the maximum amount of data that can ever be
00360 **        stored in "output"
00361 **     "input" the input data
00362 **     "inputLen" the amount of input data
00363 */
00364 extern SECStatus RC2_Encrypt(RC2Context *cx, unsigned char *output,
00365                          unsigned int *outputLen, unsigned int maxOutputLen,
00366                          const unsigned char *input, unsigned int inputLen);
00367 
00368 /*
00369 ** Perform RC2 decryption.
00370 **     "cx" the context
00371 **     "output" the output buffer to store the decrypted data.
00372 **     "outputLen" how much data is stored in "output". Set by the routine
00373 **        after some data is stored in output.
00374 **     "maxOutputLen" the maximum amount of data that can ever be
00375 **        stored in "output"
00376 **     "input" the input data
00377 **     "inputLen" the amount of input data
00378 */
00379 extern SECStatus RC2_Decrypt(RC2Context *cx, unsigned char *output,
00380                          unsigned int *outputLen, unsigned int maxOutputLen,
00381                          const unsigned char *input, unsigned int inputLen);
00382 
00383 /******************************************/
00384 /*
00385 ** RC5 symmetric block cypher -- 64-bit block size
00386 */
00387 
00388 /*
00389 ** Create a new RC5 context suitable for RC5 encryption/decryption.
00390 **      "key" raw key data
00391 **      "len" the number of bytes of key data
00392 **      "iv" is the CBC initialization vector (if mode is NSS_RC5_CBC)
00393 **      "mode" one of NSS_RC5 or NSS_RC5_CBC
00394 **
00395 ** When mode is set to NSS_RC5_CBC the RC5 cipher is run in "cipher block
00396 ** chaining" mode.
00397 */
00398 extern RC5Context *RC5_CreateContext(const SECItem *key, unsigned int rounds,
00399                      unsigned int wordSize, const unsigned char *iv, int mode);
00400 extern RC5Context *RC5_AllocateContext(void);
00401 extern SECStatus   RC5_InitContext(RC5Context *cx, 
00402                                const unsigned char *key, 
00403                                unsigned int keylen,
00404                                const unsigned char *iv, 
00405                                int mode,
00406                                unsigned int rounds, 
00407                                unsigned int wordSize);
00408 
00409 /*
00410 ** Destroy an RC5 encryption/decryption context.
00411 **      "cx" the context
00412 **      "freeit" if PR_TRUE then free the object as well as its sub-objects
00413 */
00414 extern void RC5_DestroyContext(RC5Context *cx, PRBool freeit);
00415 
00416 /*
00417 ** Perform RC5 encryption.
00418 **      "cx" the context
00419 **      "output" the output buffer to store the encrypted data.
00420 **      "outputLen" how much data is stored in "output". Set by the routine
00421 **         after some data is stored in output.
00422 **      "maxOutputLen" the maximum amount of data that can ever be
00423 **         stored in "output"
00424 **      "input" the input data
00425 **      "inputLen" the amount of input data
00426 */
00427 extern SECStatus RC5_Encrypt(RC5Context *cx, unsigned char *output,
00428                             unsigned int *outputLen, unsigned int maxOutputLen,
00429                             const unsigned char *input, unsigned int inputLen);
00430 
00431 /*
00432 ** Perform RC5 decryption.
00433 **      "cx" the context
00434 **      "output" the output buffer to store the decrypted data.
00435 **      "outputLen" how much data is stored in "output". Set by the routine
00436 **         after some data is stored in output.
00437 **      "maxOutputLen" the maximum amount of data that can ever be
00438 **         stored in "output"
00439 **      "input" the input data
00440 **      "inputLen" the amount of input data
00441 */
00442 
00443 extern SECStatus RC5_Decrypt(RC5Context *cx, unsigned char *output,
00444                             unsigned int *outputLen, unsigned int maxOutputLen,
00445                             const unsigned char *input, unsigned int inputLen);
00446 
00447 
00448 
00449 /******************************************/
00450 /*
00451 ** DES symmetric block cypher
00452 */
00453 
00454 /*
00455 ** Create a new DES context suitable for DES encryption/decryption.
00456 **     "key" raw key data
00457 **     "len" the number of bytes of key data
00458 **     "iv" is the CBC initialization vector (if mode is NSS_DES_CBC or
00459 **        mode is DES_EDE3_CBC)
00460 **     "mode" one of NSS_DES, NSS_DES_CBC, NSS_DES_EDE3 or NSS_DES_EDE3_CBC
00461 **     "encrypt" is PR_TRUE if the context will be used for encryption
00462 **
00463 ** When mode is set to NSS_DES_CBC or NSS_DES_EDE3_CBC then the DES
00464 ** cipher is run in "cipher block chaining" mode.
00465 */
00466 extern DESContext *DES_CreateContext(const unsigned char *key, 
00467                                      const unsigned char *iv,
00468                                  int mode, PRBool encrypt);
00469 extern DESContext *DES_AllocateContext(void);
00470 extern SECStatus   DES_InitContext(DESContext *cx,
00471                                const unsigned char *key, 
00472                                unsigned int keylen,
00473                                const unsigned char *iv, 
00474                                int mode,
00475                                unsigned int encrypt,
00476                                unsigned int );
00477 
00478 /*
00479 ** Destroy an DES encryption/decryption context.
00480 **     "cx" the context
00481 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00482 */
00483 extern void DES_DestroyContext(DESContext *cx, PRBool freeit);
00484 
00485 /*
00486 ** Perform DES encryption.
00487 **     "cx" the context
00488 **     "output" the output buffer to store the encrypted data.
00489 **     "outputLen" how much data is stored in "output". Set by the routine
00490 **        after some data is stored in output.
00491 **     "maxOutputLen" the maximum amount of data that can ever be
00492 **        stored in "output"
00493 **     "input" the input data
00494 **     "inputLen" the amount of input data
00495 **
00496 ** NOTE: the inputLen must be a multiple of DES_KEY_LENGTH
00497 */
00498 extern SECStatus DES_Encrypt(DESContext *cx, unsigned char *output,
00499                          unsigned int *outputLen, unsigned int maxOutputLen,
00500                          const unsigned char *input, unsigned int inputLen);
00501 
00502 /*
00503 ** Perform DES decryption.
00504 **     "cx" the context
00505 **     "output" the output buffer to store the decrypted data.
00506 **     "outputLen" how much data is stored in "output". Set by the routine
00507 **        after some data is stored in output.
00508 **     "maxOutputLen" the maximum amount of data that can ever be
00509 **        stored in "output"
00510 **     "input" the input data
00511 **     "inputLen" the amount of input data
00512 **
00513 ** NOTE: the inputLen must be a multiple of DES_KEY_LENGTH
00514 */
00515 extern SECStatus DES_Decrypt(DESContext *cx, unsigned char *output,
00516                          unsigned int *outputLen, unsigned int maxOutputLen,
00517                          const unsigned char *input, unsigned int inputLen);
00518 
00519 /******************************************/
00520 /*
00521 ** AES symmetric block cypher (Rijndael)
00522 */
00523 
00524 /*
00525 ** Create a new AES context suitable for AES encryption/decryption.
00526 **     "key" raw key data
00527 **     "keylen" the number of bytes of key data (16, 24, or 32)
00528 **      "blocklen" is the blocksize to use (16, 24, or 32)
00529 **                        XXX currently only blocksize==16 has been tested!
00530 */
00531 extern AESContext *
00532 AES_CreateContext(const unsigned char *key, const unsigned char *iv, 
00533                   int mode, int encrypt,
00534                   unsigned int keylen, unsigned int blocklen);
00535 extern AESContext *AES_AllocateContext(void);
00536 extern SECStatus   AES_InitContext(AESContext *cx,
00537                                const unsigned char *key, 
00538                                unsigned int keylen, 
00539                                const unsigned char *iv, 
00540                                int mode, 
00541                                unsigned int encrypt,
00542                                unsigned int blocklen);
00543 
00544 /*
00545 ** Destroy a AES encryption/decryption context.
00546 **     "cx" the context
00547 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00548 */
00549 extern void 
00550 AES_DestroyContext(AESContext *cx, PRBool freeit);
00551 
00552 /*
00553 ** Perform AES encryption.
00554 **     "cx" the context
00555 **     "output" the output buffer to store the encrypted data.
00556 **     "outputLen" how much data is stored in "output". Set by the routine
00557 **        after some data is stored in output.
00558 **     "maxOutputLen" the maximum amount of data that can ever be
00559 **        stored in "output"
00560 **     "input" the input data
00561 **     "inputLen" the amount of input data
00562 */
00563 extern SECStatus 
00564 AES_Encrypt(AESContext *cx, unsigned char *output,
00565             unsigned int *outputLen, unsigned int maxOutputLen,
00566             const unsigned char *input, unsigned int inputLen);
00567 
00568 /*
00569 ** Perform AES decryption.
00570 **     "cx" the context
00571 **     "output" the output buffer to store the decrypted data.
00572 **     "outputLen" how much data is stored in "output". Set by the routine
00573 **        after some data is stored in output.
00574 **     "maxOutputLen" the maximum amount of data that can ever be
00575 **        stored in "output"
00576 **     "input" the input data
00577 **     "inputLen" the amount of input data
00578 */
00579 extern SECStatus 
00580 AES_Decrypt(AESContext *cx, unsigned char *output,
00581             unsigned int *outputLen, unsigned int maxOutputLen,
00582             const unsigned char *input, unsigned int inputLen);
00583 
00584 /******************************************/
00585 /*
00586 ** AES key wrap algorithm, RFC 3394
00587 */
00588 
00589 /*
00590 ** Create a new AES context suitable for AES encryption/decryption.
00591 **     "key" raw key data
00592 **      "iv"  The 8 byte "initial value"
00593 **      "encrypt", a boolean, true for key wrapping, false for unwrapping.
00594 **     "keylen" the number of bytes of key data (16, 24, or 32)
00595 */
00596 extern AESKeyWrapContext *
00597 AESKeyWrap_CreateContext(const unsigned char *key, const unsigned char *iv, 
00598                          int encrypt, unsigned int keylen);
00599 extern AESKeyWrapContext * AESKeyWrap_AllocateContext(void);
00600 extern SECStatus  
00601      AESKeyWrap_InitContext(AESKeyWrapContext *cx, 
00602                                const unsigned char *key, 
00603                                unsigned int keylen,
00604                                const unsigned char *iv, 
00605                                int ,
00606                                unsigned int encrypt,
00607                                unsigned int );
00608 
00609 /*
00610 ** Destroy a AES KeyWrap context.
00611 **     "cx" the context
00612 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00613 */
00614 extern void 
00615 AESKeyWrap_DestroyContext(AESKeyWrapContext *cx, PRBool freeit);
00616 
00617 /*
00618 ** Perform AES key wrap.
00619 **     "cx" the context
00620 **     "output" the output buffer to store the encrypted data.
00621 **     "outputLen" how much data is stored in "output". Set by the routine
00622 **        after some data is stored in output.
00623 **     "maxOutputLen" the maximum amount of data that can ever be
00624 **        stored in "output"
00625 **     "input" the input data
00626 **     "inputLen" the amount of input data
00627 */
00628 extern SECStatus 
00629 AESKeyWrap_Encrypt(AESKeyWrapContext *cx, unsigned char *output,
00630             unsigned int *outputLen, unsigned int maxOutputLen,
00631             const unsigned char *input, unsigned int inputLen);
00632 
00633 /*
00634 ** Perform AES key unwrap.
00635 **     "cx" the context
00636 **     "output" the output buffer to store the decrypted data.
00637 **     "outputLen" how much data is stored in "output". Set by the routine
00638 **        after some data is stored in output.
00639 **     "maxOutputLen" the maximum amount of data that can ever be
00640 **        stored in "output"
00641 **     "input" the input data
00642 **     "inputLen" the amount of input data
00643 */
00644 extern SECStatus 
00645 AESKeyWrap_Decrypt(AESKeyWrapContext *cx, unsigned char *output,
00646             unsigned int *outputLen, unsigned int maxOutputLen,
00647             const unsigned char *input, unsigned int inputLen);
00648 
00649 
00650 /******************************************/
00651 /*
00652 ** MD5 secure hash function
00653 */
00654 
00655 /*
00656 ** Hash a null terminated string "src" into "dest" using MD5
00657 */
00658 extern SECStatus MD5_Hash(unsigned char *dest, const char *src);
00659 
00660 /*
00661 ** Hash a non-null terminated string "src" into "dest" using MD5
00662 */
00663 extern SECStatus MD5_HashBuf(unsigned char *dest, const unsigned char *src,
00664                           uint32 src_length);
00665 
00666 /*
00667 ** Create a new MD5 context
00668 */
00669 extern MD5Context *MD5_NewContext(void);
00670 
00671 
00672 /*
00673 ** Destroy an MD5 secure hash context.
00674 **     "cx" the context
00675 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00676 */
00677 extern void MD5_DestroyContext(MD5Context *cx, PRBool freeit);
00678 
00679 /*
00680 ** Reset an MD5 context, preparing it for a fresh round of hashing
00681 */
00682 extern void MD5_Begin(MD5Context *cx);
00683 
00684 /*
00685 ** Update the MD5 hash function with more data.
00686 **     "cx" the context
00687 **     "input" the data to hash
00688 **     "inputLen" the amount of data to hash
00689 */
00690 extern void MD5_Update(MD5Context *cx,
00691                      const unsigned char *input, unsigned int inputLen);
00692 
00693 /*
00694 ** Finish the MD5 hash function. Produce the digested results in "digest"
00695 **     "cx" the context
00696 **     "digest" where the 16 bytes of digest data are stored
00697 **     "digestLen" where the digest length (16) is stored
00698 **     "maxDigestLen" the maximum amount of data that can ever be
00699 **        stored in "digest"
00700 */
00701 extern void MD5_End(MD5Context *cx, unsigned char *digest,
00702                   unsigned int *digestLen, unsigned int maxDigestLen);
00703 
00704 /*
00705  * Return the the size of a buffer needed to flatten the MD5 Context into
00706  *    "cx" the context
00707  *  returns size;
00708  */
00709 extern unsigned int MD5_FlattenSize(MD5Context *cx);
00710 
00711 /*
00712  * Flatten the MD5 Context into a buffer:
00713  *    "cx" the context
00714  *    "space" the buffer to flatten to
00715  *  returns status;
00716  */
00717 extern SECStatus MD5_Flatten(MD5Context *cx,unsigned char *space);
00718 
00719 /*
00720  * Resurrect a flattened context into a MD5 Context
00721  *    "space" the buffer of the flattend buffer
00722  *    "arg" ptr to void used by cryptographic resurrect
00723  *  returns resurected context;
00724  */
00725 extern MD5Context * MD5_Resurrect(unsigned char *space, void *arg);
00726 extern void MD5_Clone(MD5Context *dest, MD5Context *src);
00727 
00728 /*
00729 ** trace the intermediate state info of the MD5 hash.
00730 */
00731 extern void MD5_TraceState(MD5Context *cx);
00732 
00733 
00734 /******************************************/
00735 /*
00736 ** MD2 secure hash function
00737 */
00738 
00739 /*
00740 ** Hash a null terminated string "src" into "dest" using MD2
00741 */
00742 extern SECStatus MD2_Hash(unsigned char *dest, const char *src);
00743 
00744 /*
00745 ** Create a new MD2 context
00746 */
00747 extern MD2Context *MD2_NewContext(void);
00748 
00749 
00750 /*
00751 ** Destroy an MD2 secure hash context.
00752 **     "cx" the context
00753 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00754 */
00755 extern void MD2_DestroyContext(MD2Context *cx, PRBool freeit);
00756 
00757 /*
00758 ** Reset an MD2 context, preparing it for a fresh round of hashing
00759 */
00760 extern void MD2_Begin(MD2Context *cx);
00761 
00762 /*
00763 ** Update the MD2 hash function with more data.
00764 **     "cx" the context
00765 **     "input" the data to hash
00766 **     "inputLen" the amount of data to hash
00767 */
00768 extern void MD2_Update(MD2Context *cx,
00769                      const unsigned char *input, unsigned int inputLen);
00770 
00771 /*
00772 ** Finish the MD2 hash function. Produce the digested results in "digest"
00773 **     "cx" the context
00774 **     "digest" where the 16 bytes of digest data are stored
00775 **     "digestLen" where the digest length (16) is stored
00776 **     "maxDigestLen" the maximum amount of data that can ever be
00777 **        stored in "digest"
00778 */
00779 extern void MD2_End(MD2Context *cx, unsigned char *digest,
00780                   unsigned int *digestLen, unsigned int maxDigestLen);
00781 
00782 /*
00783  * Return the the size of a buffer needed to flatten the MD2 Context into
00784  *    "cx" the context
00785  *  returns size;
00786  */
00787 extern unsigned int MD2_FlattenSize(MD2Context *cx);
00788 
00789 /*
00790  * Flatten the MD2 Context into a buffer:
00791  *    "cx" the context
00792  *    "space" the buffer to flatten to
00793  *  returns status;
00794  */
00795 extern SECStatus MD2_Flatten(MD2Context *cx,unsigned char *space);
00796 
00797 /*
00798  * Resurrect a flattened context into a MD2 Context
00799  *    "space" the buffer of the flattend buffer
00800  *    "arg" ptr to void used by cryptographic resurrect
00801  *  returns resurected context;
00802  */
00803 extern MD2Context * MD2_Resurrect(unsigned char *space, void *arg);
00804 extern void MD2_Clone(MD2Context *dest, MD2Context *src);
00805 
00806 /******************************************/
00807 /*
00808 ** SHA-1 secure hash function
00809 */
00810 
00811 /*
00812 ** Hash a null terminated string "src" into "dest" using SHA-1
00813 */
00814 extern SECStatus SHA1_Hash(unsigned char *dest, const char *src);
00815 
00816 /*
00817 ** Hash a non-null terminated string "src" into "dest" using SHA-1
00818 */
00819 extern SECStatus SHA1_HashBuf(unsigned char *dest, const unsigned char *src,
00820                            uint32 src_length);
00821 
00822 /*
00823 ** Create a new SHA-1 context
00824 */
00825 extern SHA1Context *SHA1_NewContext(void);
00826 
00827 
00828 /*
00829 ** Destroy a SHA-1 secure hash context.
00830 **     "cx" the context
00831 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00832 */
00833 extern void SHA1_DestroyContext(SHA1Context *cx, PRBool freeit);
00834 
00835 /*
00836 ** Reset a SHA-1 context, preparing it for a fresh round of hashing
00837 */
00838 extern void SHA1_Begin(SHA1Context *cx);
00839 
00840 /*
00841 ** Update the SHA-1 hash function with more data.
00842 **     "cx" the context
00843 **     "input" the data to hash
00844 **     "inputLen" the amount of data to hash
00845 */
00846 extern void SHA1_Update(SHA1Context *cx, const unsigned char *input,
00847                      unsigned int inputLen);
00848 
00849 /*
00850 ** Finish the SHA-1 hash function. Produce the digested results in "digest"
00851 **     "cx" the context
00852 **     "digest" where the 16 bytes of digest data are stored
00853 **     "digestLen" where the digest length (20) is stored
00854 **     "maxDigestLen" the maximum amount of data that can ever be
00855 **        stored in "digest"
00856 */
00857 extern void SHA1_End(SHA1Context *cx, unsigned char *digest,
00858                    unsigned int *digestLen, unsigned int maxDigestLen);
00859 
00860 /*
00861 ** trace the intermediate state info of the SHA1 hash.
00862 */
00863 extern void SHA1_TraceState(SHA1Context *cx);
00864 
00865 /*
00866  * Return the the size of a buffer needed to flatten the SHA-1 Context into
00867  *    "cx" the context
00868  *  returns size;
00869  */
00870 extern unsigned int SHA1_FlattenSize(SHA1Context *cx);
00871 
00872 /*
00873  * Flatten the SHA-1 Context into a buffer:
00874  *    "cx" the context
00875  *    "space" the buffer to flatten to
00876  *  returns status;
00877  */
00878 extern SECStatus SHA1_Flatten(SHA1Context *cx,unsigned char *space);
00879 
00880 /*
00881  * Resurrect a flattened context into a SHA-1 Context
00882  *    "space" the buffer of the flattend buffer
00883  *    "arg" ptr to void used by cryptographic resurrect
00884  *  returns resurected context;
00885  */
00886 extern SHA1Context * SHA1_Resurrect(unsigned char *space, void *arg);
00887 extern void SHA1_Clone(SHA1Context *dest, SHA1Context *src);
00888 
00889 /******************************************/
00890 
00891 extern SHA256Context *SHA256_NewContext(void);
00892 extern void SHA256_DestroyContext(SHA256Context *cx, PRBool freeit);
00893 extern void SHA256_Begin(SHA256Context *cx);
00894 extern void SHA256_Update(SHA256Context *cx, const unsigned char *input,
00895                      unsigned int inputLen);
00896 extern void SHA256_End(SHA256Context *cx, unsigned char *digest,
00897                    unsigned int *digestLen, unsigned int maxDigestLen);
00898 extern SECStatus SHA256_HashBuf(unsigned char *dest, const unsigned char *src,
00899                            uint32 src_length);
00900 extern SECStatus SHA256_Hash(unsigned char *dest, const char *src);
00901 extern void SHA256_TraceState(SHA256Context *cx);
00902 extern unsigned int SHA256_FlattenSize(SHA256Context *cx);
00903 extern SECStatus SHA256_Flatten(SHA256Context *cx,unsigned char *space);
00904 extern SHA256Context * SHA256_Resurrect(unsigned char *space, void *arg);
00905 extern void SHA256_Clone(SHA256Context *dest, SHA256Context *src);
00906 
00907 /******************************************/
00908 
00909 extern SHA512Context *SHA512_NewContext(void);
00910 extern void SHA512_DestroyContext(SHA512Context *cx, PRBool freeit);
00911 extern void SHA512_Begin(SHA512Context *cx);
00912 extern void SHA512_Update(SHA512Context *cx, const unsigned char *input,
00913                      unsigned int inputLen);
00914 extern void SHA512_End(SHA512Context *cx, unsigned char *digest,
00915                    unsigned int *digestLen, unsigned int maxDigestLen);
00916 extern SECStatus SHA512_HashBuf(unsigned char *dest, const unsigned char *src,
00917                            uint32 src_length);
00918 extern SECStatus SHA512_Hash(unsigned char *dest, const char *src);
00919 extern void SHA512_TraceState(SHA512Context *cx);
00920 extern unsigned int SHA512_FlattenSize(SHA512Context *cx);
00921 extern SECStatus SHA512_Flatten(SHA512Context *cx,unsigned char *space);
00922 extern SHA512Context * SHA512_Resurrect(unsigned char *space, void *arg);
00923 extern void SHA512_Clone(SHA512Context *dest, SHA512Context *src);
00924 
00925 /******************************************/
00926 
00927 extern SHA384Context *SHA384_NewContext(void);
00928 extern void SHA384_DestroyContext(SHA384Context *cx, PRBool freeit);
00929 extern void SHA384_Begin(SHA384Context *cx);
00930 extern void SHA384_Update(SHA384Context *cx, const unsigned char *input,
00931                      unsigned int inputLen);
00932 extern void SHA384_End(SHA384Context *cx, unsigned char *digest,
00933                    unsigned int *digestLen, unsigned int maxDigestLen);
00934 extern SECStatus SHA384_HashBuf(unsigned char *dest, const unsigned char *src,
00935                            uint32 src_length);
00936 extern SECStatus SHA384_Hash(unsigned char *dest, const char *src);
00937 extern void SHA384_TraceState(SHA384Context *cx);
00938 extern unsigned int SHA384_FlattenSize(SHA384Context *cx);
00939 extern SECStatus SHA384_Flatten(SHA384Context *cx,unsigned char *space);
00940 extern SHA384Context * SHA384_Resurrect(unsigned char *space, void *arg);
00941 extern void SHA384_Clone(SHA384Context *dest, SHA384Context *src);
00942 
00943 /****************************************
00944  * implement TLS Pseudo Random Function (PRF)
00945  */
00946 
00947 extern SECStatus
00948 TLS_PRF(const SECItem *secret, const char *label, SECItem *seed, 
00949          SECItem *result, PRBool isFIPS);
00950 
00951 /******************************************/
00952 /*
00953 ** Pseudo Random Number Generation.  FIPS compliance desirable.
00954 */
00955 
00956 /*
00957 ** Initialize the global RNG context and give it some seed input taken
00958 ** from the system.  This function is thread-safe and will only allow
00959 ** the global context to be initialized once.  The seed input is likely
00960 ** small, so it is imperative that RNG_RandomUpdate() be called with
00961 ** additional seed data before the generator is used.  A good way to
00962 ** provide the generator with additional entropy is to call
00963 ** RNG_SystemInfoForRNG().  Note that NSS_Init() does exactly that.
00964 */
00965 extern SECStatus RNG_RNGInit(void);
00966 
00967 /*
00968 ** Update the global random number generator with more seeding
00969 ** material
00970 */
00971 extern SECStatus RNG_RandomUpdate(const void *data, size_t bytes);
00972 
00973 /*
00974 ** Generate some random bytes, using the global random number generator
00975 ** object.
00976 */
00977 extern SECStatus RNG_GenerateGlobalRandomBytes(void *dest, size_t len);
00978 
00979 /* Destroy the global RNG context.  After a call to RNG_RNGShutdown()
00980 ** a call to RNG_RNGInit() is required in order to use the generator again,
00981 ** along with seed data (see the comment above RNG_RNGInit()).
00982 */
00983 extern void  RNG_RNGShutdown(void);
00984 
00985 extern void RNG_SystemInfoForRNG(void);
00986 
00987 /*
00988  * FIPS 186-2 Change Notice 1 RNG Algorithm 1, used both to
00989  * generate the DSA X parameter and as a generic purpose RNG.
00990  *
00991  * The following two FIPS186Change functions are needed for
00992  * NIST RNG Validation System.
00993  */
00994 
00995 /*
00996  * Given the seed-key and the seed, generate the random output.
00997  *
00998  * Parameters:
00999  *   XKEY [input/output]: the state of the RNG (seed-key)
01000  *   XSEEDj [input]: optional user input (seed)
01001  *   x_j [output]: output of the RNG
01002  *
01003  * Return value:
01004  * This function usually returns SECSuccess.  The only reason
01005  * this function returns SECFailure is that XSEEDj equals
01006  * XKEY, including the intermediate XKEY value between the two
01007  * iterations.  (This test is actually a FIPS 140-2 requirement
01008  * and not required for FIPS algorithm testing, but it is too
01009  * hard to separate from this function.)  If this function fails,
01010  * XKEY is not updated, but some data may have been written to
01011  * x_j, which should be ignored.
01012  */
01013 extern SECStatus
01014 FIPS186Change_GenerateX(unsigned char *XKEY,
01015                         const unsigned char *XSEEDj,
01016                         unsigned char *x_j);
01017 
01018 /*
01019  * When generating the DSA X parameter, we generate 2*GSIZE bytes
01020  * of random output and reduce it mod q.
01021  *
01022  * Input: w, 2*GSIZE bytes
01023  *        q, DSA_SUBPRIME_LEN bytes
01024  * Output: xj, DSA_SUBPRIME_LEN bytes
01025  */
01026 extern SECStatus
01027 FIPS186Change_ReduceModQForDSA(const unsigned char *w,
01028                                const unsigned char *q,
01029                                unsigned char *xj);
01030 
01031 /* Generate PQGParams and PQGVerify structs.
01032  * Length of seed and length of h both equal length of P. 
01033  * All lengths are specified by "j", according to the table above.
01034  */
01035 extern SECStatus
01036 PQG_ParamGen(unsigned int j,          /* input : determines length of P. */
01037              PQGParams **pParams,  /* output: P Q and G returned here */
01038             PQGVerify **pVfy);    /* output: counter and seed. */
01039 
01040 /* Generate PQGParams and PQGVerify structs.
01041  * Length of P specified by j.  Length of h will match length of P.
01042  * Length of SEED in bytes specified in seedBytes.
01043  * seedBbytes must be in the range [20..255] or an error will result.
01044  */
01045 extern SECStatus
01046 PQG_ParamGenSeedLen(
01047              unsigned int j,            /* input : determines length of P. */
01048             unsigned int seedBytes, /* input : length of seed in bytes.*/
01049              PQGParams **pParams,    /* output: P Q and G returned here */
01050             PQGVerify **pVfy);      /* output: counter and seed. */
01051 
01052 
01053 /*  Test PQGParams for validity as DSS PQG values.
01054  *  If vfy is non-NULL, test PQGParams to make sure they were generated
01055  *       using the specified seed, counter, and h values.
01056  *
01057  *  Return value indicates whether Verification operation ran succesfully
01058  *  to completion, but does not indicate if PQGParams are valid or not.
01059  *  If return value is SECSuccess, then *pResult has these meanings:
01060  *       SECSuccess: PQGParams are valid.
01061  *       SECFailure: PQGParams are invalid.
01062  *
01063  * Verify the following 12 facts about PQG counter SEED g and h
01064  * 1.  Q is 160 bits long.
01065  * 2.  P is one of the 9 valid lengths.
01066  * 3.  G < P
01067  * 4.  P % Q == 1
01068  * 5.  Q is prime
01069  * 6.  P is prime
01070  * Steps 7-12 are done only if the optional PQGVerify is supplied.
01071  * 7.  counter < 4096
01072  * 8.  g >= 160 and g < 2048   (g is length of seed in bits)
01073  * 9.  Q generated from SEED matches Q in PQGParams.
01074  * 10. P generated from (L, counter, g, SEED, Q) matches P in PQGParams.
01075  * 11. 1 < h < P-1
01076  * 12. G generated from h matches G in PQGParams.
01077  */
01078 
01079 extern SECStatus   PQG_VerifyParams(const PQGParams *params, 
01080                                     const PQGVerify *vfy, SECStatus *result);
01081 
01082 
01083 /*
01084  * clean-up any global tables freebl may have allocated after it starts up.
01085  * This function is not thread safe and should be called only after the
01086  * library has been quiessed.
01087  */
01088 extern void BL_Cleanup(void);
01089 
01090 /* unload freebl shared library from memory */
01091 extern void BL_Unload(void);
01092 
01093 /**************************************************************************
01094  *  Verify a given Shared library signature                               *
01095  **************************************************************************/
01096 PRBool BLAPI_SHVerify(const char *name, PRFuncPtr addr);
01097 
01098 /**************************************************************************
01099  *  Verify Are Own Shared library signature                               *
01100  **************************************************************************/
01101 PRBool BLAPI_VerifySelf(const char *name);
01102 
01103 /*********************************************************************/
01104 extern const SECHashObject * HASH_GetRawHashObject(HASH_HashType hashType);
01105 
01106 SEC_END_PROTOS
01107 
01108 #endif /* _BLAPI_H_ */