/gecko_api/include/cryptohi.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: cryptohi.h,v 1.11 2006/03/15 21:42:21 rrelyea%redhat.com Exp $ */
 41
 42#ifndef _CRYPTOHI_H_
 43#define _CRYPTOHI_H_
 44
 45#include "blapit.h"
 46
 47#include "seccomon.h"
 48#include "secoidt.h"
 49#include "secdert.h"
 50#include "cryptoht.h"
 51#include "keyt.h"
 52#include "certt.h"
 53
 54
 55SEC_BEGIN_PROTOS
 56
 57
 58/****************************************/
 59/*
 60** DER encode/decode (EC)DSA signatures
 61*/
 62
 63/* ANSI X9.57 defines DSA signatures as DER encoded data.  Our DSA code (and
 64 * most of the rest of the world) just generates 40 bytes of raw data.  These
 65 * functions convert between formats.
 66 */
 67extern SECStatus DSAU_EncodeDerSig(SECItem *dest, SECItem *src);
 68extern SECItem *DSAU_DecodeDerSig(const SECItem *item);
 69
 70/*
 71 * Unlike DSA, raw ECDSA signatures do not have a fixed length.
 72 * Rather they contain two integers r and s whose length depends
 73 * on the size of the EC key used for signing.
 74 *
 75 * We can reuse the DSAU_EncodeDerSig interface to DER encode
 76 * raw ECDSA signature keeping in mind that the length of r 
 77 * is the same as that of s and exactly half of src->len.
 78 *
 79 * For decoding, we need to pass the length of the desired
 80 * raw signature (twice the key size) explicitly.
 81 */
 82extern SECStatus DSAU_EncodeDerSigWithLen(SECItem *dest, SECItem *src, 
 83					  unsigned int len);
 84extern SECItem *DSAU_DecodeDerSigToLen(const SECItem *item, unsigned int len);
 85
 86/****************************************/
 87/*
 88** Signature creation operations
 89*/
 90
 91/*
 92** Create a new signature context used for signing a data stream.
 93**	"alg" the signature algorithm to use (e.g. SEC_OID_RSA_WITH_MD5)
 94**	"privKey" the private key to use
 95*/
 96extern SGNContext *SGN_NewContext(SECOidTag alg, SECKEYPrivateKey *privKey);
 97
 98/*
 99** Destroy a signature-context object
100**	"key" the object
101**	"freeit" if PR_TRUE then free the object as well as its sub-objects
102*/
103extern void SGN_DestroyContext(SGNContext *cx, PRBool freeit);
104
105/*
106** Reset the signing context "cx" to its initial state, preparing it for
107** another stream of data.
108*/
109extern SECStatus SGN_Begin(SGNContext *cx);
110
111/*
112** Update the signing context with more data to sign.
113**	"cx" the context
114**	"input" the input data to sign
115**	"inputLen" the length of the input data
116*/
117extern SECStatus SGN_Update(SGNContext *cx, unsigned char *input,
118			   unsigned int inputLen);
119
120/*
121** Finish the signature process. Use either k0 or k1 to sign the data
122** stream that was input using SGN_Update. The resulting signature is
123** formatted using PKCS#1 and then encrypted using RSA private or public
124** encryption.
125**	"cx" the context
126**	"result" the final signature data (memory is allocated)
127*/
128extern SECStatus SGN_End(SGNContext *cx, SECItem *result);
129
130/*
131** Sign a single block of data using private key encryption and given
132** signature/hash algorithm.
133**	"result" the final signature data (memory is allocated)
134**	"buf" the input data to sign
135**	"len" the amount of data to sign
136**	"pk" the private key to encrypt with
137**	"algid" the signature/hash algorithm to sign with 
138**		(must be compatible with the key type).
139*/
140extern SECStatus SEC_SignData(SECItem *result, unsigned char *buf, int len,
141			     SECKEYPrivateKey *pk, SECOidTag algid);
142
143/*
144** Sign a pre-digested block of data using private key encryption, encoding
145**  The given signature/hash algorithm.
146**	"result" the final signature data (memory is allocated)
147**	"digest" the digest to sign
148**	"pk" the private key to encrypt with
149**	"algtag" The algorithm tag to encode (need for RSA only)
150*/
151extern SECStatus SGN_Digest(SECKEYPrivateKey *privKey,
152                SECOidTag algtag, SECItem *result, SECItem *digest);
153
154/*
155** DER sign a single block of data using private key encryption and the
156** MD5 hashing algorithm. This routine first computes a digital signature
157** using SEC_SignData, then wraps it with an CERTSignedData and then der
158** encodes the result.
159**	"arena" is the memory arena to use to allocate data from
160** 	"result" the final der encoded data (memory is allocated)
161** 	"buf" the input data to sign
162** 	"len" the amount of data to sign
163** 	"pk" the private key to encrypt with
164*/
165extern SECStatus SEC_DerSignData(PRArenaPool *arena, SECItem *result,
166				unsigned char *buf, int len,
167				SECKEYPrivateKey *pk, SECOidTag algid);
168
169/*
170** Destroy a signed-data object.
171**	"sd" the object
172**	"freeit" if PR_TRUE then free the object as well as its sub-objects
173*/
174extern void SEC_DestroySignedData(CERTSignedData *sd, PRBool freeit);
175
176/*
177** Get the signature algorithm tag number for the given key type and hash
178** algorithm tag. Returns SEC_OID_UNKNOWN if key type and hash algorithm
179** do not match or are not supported.
180*/
181extern SECOidTag SEC_GetSignatureAlgorithmOidTag(KeyType keyType,
182                                                 SECOidTag hashAlgTag);
183
184/****************************************/
185/*
186** Signature verification operations
187*/
188
189/*
190** Create a signature verification context. This version is deprecated,
191**  This function is deprecated. Use VFY_CreateContextDirect or 
192**  VFY_CreateContextWithAlgorithmID instead.
193**	"key" the public key to verify with
194**	"sig" the encrypted signature data if sig is NULL then
195**	   VFY_EndWithSignature must be called with the correct signature at
196**	   the end of the processing.
197**	"sigAlg" specifies the signing algorithm to use (including the 
198**         hash algorthim).  This must match the key type.
199**	"wincx" void pointer to the window context
200*/
201extern VFYContext *VFY_CreateContext(SECKEYPublicKey *key, SECItem *sig,
202				     SECOidTag sigAlg, void *wincx);
203/*
204** Create a signature verification context.
205**	"key" the public key to verify with
206**	"sig" the encrypted signature data if sig is NULL then
207**	   VFY_EndWithSignature must be called with the correct signature at
208**	   the end of the processing.
209**	"pubkAlg" specifies the cryptographic signing algorithm to use (the
210**         raw algorithm without any hash specified.  This must match the key 
211**         type.
212**	"hashAlg" specifies the hashing algorithm used. If the key is an 
213**	   RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
214**	   the hash is selected from data in the sig.
215**	"hash" optional pointer to return the actual hash algorithm used.
216**	   in practice this should always match the passed in hashAlg (the
217**	   exception is the case where hashAlg is SEC_OID_UNKNOWN above).
218**         If this value is NULL no, hash oid is returned.
219**	"wincx" void pointer to the window context
220*/
221extern VFYContext *VFY_CreateContextDirect(const SECKEYPublicKey *key,
222					   const SECItem *sig,
223	     				   SECOidTag pubkAlg, 
224					   SECOidTag hashAlg, 
225					   SECOidTag *hash, void *wincx);
226/*
227** Create a signature verification context from a algorithm ID.
228**	"key" the public key to verify with
229**	"sig" the encrypted signature data if sig is NULL then
230**	   VFY_EndWithSignature must be called with the correct signature at
231**	   the end of the processing.
232**	"algid" specifies the signing algorithm and parameters to use.
233**         This must match the key type.
234**      "hash" optional pointer to return the oid of the actual hash used in 
235**         the signature. If this value is NULL no, hash oid is returned.
236**	"wincx" void pointer to the window context
237*/
238extern VFYContext *VFY_CreateContextWithAlgorithmID(const SECKEYPublicKey *key, 
239				     const SECItem *sig,
240				     const SECAlgorithmID *algid, 
241				     SECOidTag *hash,
242				     void *wincx);
243
244/*
245** Destroy a verification-context object.
246**	"cx" the context to destroy
247**	"freeit" if PR_TRUE then free the object as well as its sub-objects
248*/
249extern void VFY_DestroyContext(VFYContext *cx, PRBool freeit);
250
251extern SECStatus VFY_Begin(VFYContext *cx);
252
253/*
254** Update a verification context with more input data. The input data
255** is fed to a secure hash function (depending on what was in the
256** encrypted signature data).
257**	"cx" the context
258**	"input" the input data
259**	"inputLen" the amount of input data
260*/
261extern SECStatus VFY_Update(VFYContext *cx, const unsigned char *input,
262			    unsigned int inputLen);
263
264/*
265** Finish the verification process. The return value is a status which
266** indicates success or failure. On success, the SECSuccess value is
267** returned. Otherwise, SECFailure is returned and the error code found
268** using PORT_GetError() indicates what failure occurred.
269** 	"cx" the context
270*/
271extern SECStatus VFY_End(VFYContext *cx);
272
273/*
274** Finish the verification process. The return value is a status which
275** indicates success or failure. On success, the SECSuccess value is
276** returned. Otherwise, SECFailure is returned and the error code found
277** using PORT_GetError() indicates what failure occurred. If signature is
278** supplied the verification uses this signature to verify, otherwise the
279** signature passed in VFY_CreateContext() is used. 
280** VFY_EndWithSignature(cx,NULL); is identical to VFY_End(cx);.
281** 	"cx" the context
282** 	"sig" the encrypted signature data
283*/
284extern SECStatus VFY_EndWithSignature(VFYContext *cx, SECItem *sig);
285
286
287/*
288** Verify the signature on a block of data for which we already have
289** the digest. The signature data is an RSA private key encrypted
290** block of data formatted according to PKCS#1.
291**  This function is deprecated. Use VFY_VerifyDigestDirect or 
292**  VFY_VerifyDigestWithAlgorithmID instead.
293** 	"dig" the digest
294** 	"key" the public key to check the signature with
295** 	"sig" the encrypted signature data
296**	"sigAlg" specifies the signing algorithm to use.  This must match
297**	    the key type.
298**	"wincx" void pointer to the window context
299**/
300extern SECStatus VFY_VerifyDigest(SECItem *dig, SECKEYPublicKey *key,
301				  SECItem *sig, SECOidTag sigAlg, void *wincx);
302/*
303** Verify the signature on a block of data for which we already have
304** the digest. The signature data is an RSA private key encrypted
305** block of data formatted according to PKCS#1.
306** 	"dig" the digest
307** 	"key" the public key to check the signature with
308** 	"sig" the encrypted signature data
309**	"pubkAlg" specifies the cryptographic signing algorithm to use (the
310**         raw algorithm without any hash specified.  This must match the key 
311**         type.
312**	"hashAlg" specifies the hashing algorithm used.
313**	"wincx" void pointer to the window context
314**/
315extern SECStatus VFY_VerifyDigestDirect(const SECItem *dig, 
316					const SECKEYPublicKey *key,
317					const SECItem *sig, SECOidTag pubkAlg, 
318					SECOidTag hashAlg, void *wincx);
319/*
320** Verify the signature on a block of data for which we already have
321** the digest. The signature data is an RSA private key encrypted
322** block of data formatted according to PKCS#1.
323**	"key" the public key to verify with
324**	"sig" the encrypted signature data if sig is NULL then
325**	   VFY_EndWithSignature must be called with the correct signature at
326**	   the end of the processing.
327**	"algid" specifies the signing algorithm and parameters to use.
328**         This must match the key type.
329**      "hash" oid of the actual hash used to create digest. If this  value is
330**         not set to SEC_OID_UNKNOWN, it must match the hash of the signature.
331**	"wincx" void pointer to the window context
332*/
333extern SECStatus VFY_VerifyDigestWithAlgorithmID(const SECItem *dig, 
334				const SECKEYPublicKey *key, const SECItem *sig,
335				const SECAlgorithmID *algid, SECOidTag hash,
336				void *wincx);
337
338/*
339** Verify the signature on a block of data. The signature data is an RSA
340** private key encrypted block of data formatted according to PKCS#1.
341**   This function is deprecated. Use VFY_VerifyDataDirect or 
342**   VFY_VerifyDataWithAlgorithmID instead.
343** 	"buf" the input data
344** 	"len" the length of the input data
345** 	"key" the public key to check the signature with
346** 	"sig" the encrypted signature data
347**	"sigAlg" specifies the signing algorithm to use.  This must match
348**	    the key type.
349**	"wincx" void pointer to the window context
350*/
351extern SECStatus VFY_VerifyData(unsigned char *buf, int len,
352				SECKEYPublicKey *key, SECItem *sig,
353				SECOidTag sigAlg, void *wincx);
354/*
355** Verify the signature on a block of data. The signature data is an RSA
356** private key encrypted block of data formatted according to PKCS#1.
357** 	"buf" the input data
358** 	"len" the length of the input data
359** 	"key" the public key to check the signature with
360** 	"sig" the encrypted signature data
361**	"pubkAlg" specifies the cryptographic signing algorithm to use (the
362**         raw algorithm without any hash specified.  This must match the key 
363**         type.
364**	"hashAlg" specifies the hashing algorithm used. If the key is an 
365**	   RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
366**	   the hash is selected from data in the sig.
367**	"hash" optional pointer to return the actual hash algorithm used.
368**	   in practice this should always match the passed in hashAlg (the
369**	   exception is the case where hashAlg is SEC_OID_UNKNOWN above).
370**         If this value is NULL no, hash oid is returned.
371**	"wincx" void pointer to the window context
372*/
373extern SECStatus VFY_VerifyDataDirect(const unsigned char *buf, int len,
374				      const SECKEYPublicKey *key, 
375				      const SECItem *sig,
376				      SECOidTag pubkAlg, SECOidTag hashAlg, 
377				      SECOidTag *hash, void *wincx);
378
379/*
380** Verify the signature on a block of data. The signature data is an RSA
381** private key encrypted block of data formatted according to PKCS#1.
382** 	"buf" the input data
383** 	"len" the length of the input data
384** 	"key" the public key to check the signature with
385** 	"sig" the encrypted signature data
386**	"algid" specifies the signing algorithm and parameters to use.
387**         This must match the key type.
388**      "hash" optional pointer to return the oid of the actual hash used in 
389**         the signature. If this value is NULL no, hash oid is returned.
390**	"wincx" void pointer to the window context
391*/
392extern SECStatus VFY_VerifyDataWithAlgorithmID(const unsigned char *buf, 
393				int len, const SECKEYPublicKey *key,
394				 const SECItem *sig,
395				const SECAlgorithmID *algid, SECOidTag *hash,
396				void *wincx);
397
398
399SEC_END_PROTOS
400
401#endif /* _CRYPTOHI_H_ */