Back to index

lightning-sunbird  0.9+nobinonly
cryptohi.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: cryptohi.h,v 1.9.28.1 2006/01/21 19:01:30 rrelyea%redhat.com Exp $ */
00041 
00042 #ifndef _CRYPTOHI_H_
00043 #define _CRYPTOHI_H_
00044 
00045 #include "blapit.h"
00046 
00047 #include "seccomon.h"
00048 #include "secoidt.h"
00049 #include "secdert.h"
00050 #include "cryptoht.h"
00051 #include "keyt.h"
00052 #include "certt.h"
00053 
00054 
00055 SEC_BEGIN_PROTOS
00056 
00057 
00058 /****************************************/
00059 /*
00060 ** DER encode/decode (EC)DSA signatures
00061 */
00062 
00063 /* ANSI X9.57 defines DSA signatures as DER encoded data.  Our DSA code (and
00064  * most of the rest of the world) just generates 40 bytes of raw data.  These
00065  * functions convert between formats.
00066  */
00067 extern SECStatus DSAU_EncodeDerSig(SECItem *dest, SECItem *src);
00068 extern SECItem *DSAU_DecodeDerSig(SECItem *item);
00069 
00070 /*
00071  * Unlike DSA, raw ECDSA signatures do not have a fixed length.
00072  * Rather they contain two integers r and s whose length depends
00073  * on the size of the EC key used for signing.
00074  *
00075  * We can reuse the DSAU_EncodeDerSig interface to DER encode
00076  * raw ECDSA signature keeping in mind that the length of r 
00077  * is the same as that of s and exactly half of src->len.
00078  *
00079  * For decoding, we need to pass the length of the desired
00080  * raw signature (twice the key size) explicitly.
00081  */
00082 extern SECStatus DSAU_EncodeDerSigWithLen(SECItem *dest, SECItem *src, 
00083                                      unsigned int len);
00084 extern SECItem *DSAU_DecodeDerSigToLen(SECItem *item, unsigned int len);
00085 
00086 /****************************************/
00087 /*
00088 ** Signature creation operations
00089 */
00090 
00091 /*
00092 ** Create a new signature context used for signing a data stream.
00093 **     "alg" the signature algorithm to use (e.g. SEC_OID_RSA_WITH_MD5)
00094 **     "privKey" the private key to use
00095 */
00096 extern SGNContext *SGN_NewContext(SECOidTag alg, SECKEYPrivateKey *privKey);
00097 
00098 /*
00099 ** Destroy a signature-context object
00100 **     "key" the object
00101 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00102 */
00103 extern void SGN_DestroyContext(SGNContext *cx, PRBool freeit);
00104 
00105 /*
00106 ** Reset the signing context "cx" to its initial state, preparing it for
00107 ** another stream of data.
00108 */
00109 extern SECStatus SGN_Begin(SGNContext *cx);
00110 
00111 /*
00112 ** Update the signing context with more data to sign.
00113 **     "cx" the context
00114 **     "input" the input data to sign
00115 **     "inputLen" the length of the input data
00116 */
00117 extern SECStatus SGN_Update(SGNContext *cx, unsigned char *input,
00118                         unsigned int inputLen);
00119 
00120 /*
00121 ** Finish the signature process. Use either k0 or k1 to sign the data
00122 ** stream that was input using SGN_Update. The resulting signature is
00123 ** formatted using PKCS#1 and then encrypted using RSA private or public
00124 ** encryption.
00125 **     "cx" the context
00126 **     "result" the final signature data (memory is allocated)
00127 */
00128 extern SECStatus SGN_End(SGNContext *cx, SECItem *result);
00129 
00130 /*
00131 ** Sign a single block of data using private key encryption and given
00132 ** signature/hash algorithm.
00133 **     "result" the final signature data (memory is allocated)
00134 **     "buf" the input data to sign
00135 **     "len" the amount of data to sign
00136 **     "pk" the private key to encrypt with
00137 **     "algid" the signature/hash algorithm to sign with 
00138 **            (must be compatible with the key type).
00139 */
00140 extern SECStatus SEC_SignData(SECItem *result, unsigned char *buf, int len,
00141                           SECKEYPrivateKey *pk, SECOidTag algid);
00142 
00143 /*
00144 ** Sign a pre-digested block of data using private key encryption, encoding
00145 **  The given signature/hash algorithm.
00146 **     "result" the final signature data (memory is allocated)
00147 **     "digest" the digest to sign
00148 **     "pk" the private key to encrypt with
00149 **     "algtag" The algorithm tag to encode (need for RSA only)
00150 */
00151 extern SECStatus SGN_Digest(SECKEYPrivateKey *privKey,
00152                 SECOidTag algtag, SECItem *result, SECItem *digest);
00153 
00154 /*
00155 ** DER sign a single block of data using private key encryption and the
00156 ** MD5 hashing algorithm. This routine first computes a digital signature
00157 ** using SEC_SignData, then wraps it with an CERTSignedData and then der
00158 ** encodes the result.
00159 **     "arena" is the memory arena to use to allocate data from
00160 **     "result" the final der encoded data (memory is allocated)
00161 **     "buf" the input data to sign
00162 **     "len" the amount of data to sign
00163 **     "pk" the private key to encrypt with
00164 */
00165 extern SECStatus SEC_DerSignData(PRArenaPool *arena, SECItem *result,
00166                             unsigned char *buf, int len,
00167                             SECKEYPrivateKey *pk, SECOidTag algid);
00168 
00169 /*
00170 ** Destroy a signed-data object.
00171 **     "sd" the object
00172 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00173 */
00174 extern void SEC_DestroySignedData(CERTSignedData *sd, PRBool freeit);
00175 
00176 /*
00177 ** Get the hash algorithm tag number for the given type of the key and
00178 ** algorithm tag. Returns SEC_OID_UNKNOWN if key and algorithm
00179 ** are not match.
00180 */
00181 extern SECOidTag SEC_GetSignatureAlgorithmOidTag(KeyType keyType,
00182                                                  SECOidTag hashAlgTag);
00183 
00184 /****************************************/
00185 /*
00186 ** Signature verification operations
00187 */
00188 
00189 /*
00190 ** Create a signature verification context.
00191 **     "key" the public key to verify with
00192 **     "sig" the encrypted signature data if sig is NULL then
00193 **        VFY_EndWithSignature must be called with the correct signature at
00194 **        the end of the processing.
00195 **     "algid" specifies the signing algorithm to use.  This must match
00196 **         the key type.
00197 **     "wincx" void pointer to the window context
00198 */
00199 extern VFYContext *VFY_CreateContext(SECKEYPublicKey *key, SECItem *sig,
00200                                  SECOidTag algid, void *wincx);
00201 
00202 /*
00203 ** Destroy a verification-context object.
00204 **     "cx" the context to destroy
00205 **     "freeit" if PR_TRUE then free the object as well as its sub-objects
00206 */
00207 extern void VFY_DestroyContext(VFYContext *cx, PRBool freeit);
00208 
00209 extern SECStatus VFY_Begin(VFYContext *cx);
00210 
00211 /*
00212 ** Update a verification context with more input data. The input data
00213 ** is fed to a secure hash function (depending on what was in the
00214 ** encrypted signature data).
00215 **     "cx" the context
00216 **     "input" the input data
00217 **     "inputLen" the amount of input data
00218 */
00219 extern SECStatus VFY_Update(VFYContext *cx, unsigned char *input,
00220                          unsigned int inputLen);
00221 
00222 /*
00223 ** Finish the verification process. The return value is a status which
00224 ** indicates success or failure. On success, the SECSuccess value is
00225 ** returned. Otherwise, SECFailure is returned and the error code found
00226 ** using PORT_GetError() indicates what failure occurred.
00227 **     "cx" the context
00228 */
00229 extern SECStatus VFY_End(VFYContext *cx);
00230 
00231 /*
00232 ** Finish the verification process. The return value is a status which
00233 ** indicates success or failure. On success, the SECSuccess value is
00234 ** returned. Otherwise, SECFailure is returned and the error code found
00235 ** using PORT_GetError() indicates what failure occurred. If signature is
00236 ** supplied the verification uses this signature to verify, otherwise the
00237 ** signature passed in VFY_CreateContext() is used. 
00238 ** VFY_EndWithSignature(cx,NULL); is identical to VFY_End(cx);.
00239 **     "cx" the context
00240 **     "sig" the encrypted signature data
00241 */
00242 extern SECStatus VFY_EndWithSignature(VFYContext *cx, SECItem *sig);
00243 
00244 
00245 /*
00246 ** Verify the signature on a block of data for which we already have
00247 ** the digest. The signature data is an RSA private key encrypted
00248 ** block of data formatted according to PKCS#1.
00249 **     "dig" the digest
00250 **     "key" the public key to check the signature with
00251 **     "sig" the encrypted signature data
00252 **     "algid" specifies the signing algorithm to use.  This must match
00253 **         the key type.
00254 **/
00255 extern SECStatus VFY_VerifyDigest(SECItem *dig, SECKEYPublicKey *key,
00256                               SECItem *sig, SECOidTag algid, void *wincx);
00257 
00258 /*
00259 ** Verify the signature on a block of data. The signature data is an RSA
00260 ** private key encrypted block of data formatted according to PKCS#1.
00261 **     "buf" the input data
00262 **     "len" the length of the input data
00263 **     "key" the public key to check the signature with
00264 **     "sig" the encrypted signature data
00265 **     "algid" specifies the signing algorithm to use.  This must match
00266 **         the key type.
00267 */
00268 extern SECStatus VFY_VerifyData(unsigned char *buf, int len,
00269                             SECKEYPublicKey *key, SECItem *sig,
00270                             SECOidTag algid, void *wincx);
00271 
00272 /*
00273  * NOTE: This function is private in NSS 3.11.x
00274 ** Verify the signature on a block of data. 
00275 **      "buf" the input data
00276 **      "len" the length of the input data
00277 **      "key" the public key to check the signature with
00278 **      "sig" the encrypted signature data
00279 **      "algid" specifies the signing algorithm and parameters to use.
00280 **         This must match the key type.
00281 **      "reserved" must be NULL in this version.
00282 **      "wincx" void pointer to the window context
00283 */
00284 extern SECStatus VFY_VerifyDataWithAlgorithmID(const unsigned char *buf,
00285                             int len, const SECKEYPublicKey *key,
00286                             const SECItem *sig,
00287                             const SECAlgorithmID *algid, 
00288                             SECOidTag *reserved,
00289                             void *wincx);
00290 
00291 
00292 SEC_END_PROTOS
00293 
00294 #endif /* _CRYPTOHI_H_ */