/security/nss/lib/cryptohi/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.15 2010/08/12 01:15:37 wtc%google.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, const 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,
141			     const unsigned char *buf, int len,
142			     SECKEYPrivateKey *pk, SECOidTag algid);
143
144/*
145** Sign a pre-digested block of data using private key encryption, encoding
146**  The given signature/hash algorithm.
147**	"result" the final signature data (memory is allocated)
148**	"digest" the digest to sign
149**	"pk" the private key to encrypt with
150**	"algtag" The algorithm tag to encode (need for RSA only)
151*/
152extern SECStatus SGN_Digest(SECKEYPrivateKey *privKey,
153                SECOidTag algtag, SECItem *result, SECItem *digest);
154
155/*
156** DER sign a single block of data using private key encryption and the
157** MD5 hashing algorithm. This routine first computes a digital signature
158** using SEC_SignData, then wraps it with an CERTSignedData and then der
159** encodes the result.
160**	"arena" is the memory arena to use to allocate data from
161** 	"result" the final der encoded data (memory is allocated)
162** 	"buf" the input data to sign
163** 	"len" the amount of data to sign
164** 	"pk" the private key to encrypt with
165*/
166extern SECStatus SEC_DerSignData(PLArenaPool *arena, SECItem *result,
167				const unsigned char *buf, int len,
168				SECKEYPrivateKey *pk, SECOidTag algid);
169
170/*
171** Destroy a signed-data object.
172**	"sd" the object
173**	"freeit" if PR_TRUE then free the object as well as its sub-objects
174*/
175extern void SEC_DestroySignedData(CERTSignedData *sd, PRBool freeit);
176
177/*
178** Get the signature algorithm tag number for the given key type and hash
179** algorithm tag. Returns SEC_OID_UNKNOWN if key type and hash algorithm
180** do not match or are not supported.
181*/
182extern SECOidTag SEC_GetSignatureAlgorithmOidTag(KeyType keyType,
183                                                 SECOidTag hashAlgTag);
184
185/****************************************/
186/*
187** Signature verification operations
188*/
189
190/*
191** Create a signature verification context. This version is deprecated,
192**  This function is deprecated. Use VFY_CreateContextDirect or 
193**  VFY_CreateContextWithAlgorithmID instead.
194**	"key" the public key to verify with
195**	"sig" the encrypted signature data if sig is NULL then
196**	   VFY_EndWithSignature must be called with the correct signature at
197**	   the end of the processing.
198**	"sigAlg" specifies the signing algorithm to use (including the 
199**         hash algorthim).  This must match the key type.
200**	"wincx" void pointer to the window context
201*/
202extern VFYContext *VFY_CreateContext(SECKEYPublicKey *key, SECItem *sig,
203				     SECOidTag sigAlg, void *wincx);
204/*
205** Create a signature verification context.
206**	"key" the public key to verify with
207**	"sig" the encrypted signature data if sig is NULL then
208**	   VFY_EndWithSignature must be called with the correct signature at
209**	   the end of the processing.
210**	"pubkAlg" specifies the cryptographic signing algorithm to use (the
211**         raw algorithm without any hash specified.  This must match the key 
212**         type.
213**	"hashAlg" specifies the hashing algorithm used. If the key is an 
214**	   RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
215**	   the hash is selected from data in the sig.
216**	"hash" optional pointer to return the actual hash algorithm used.
217**	   in practice this should always match the passed in hashAlg (the
218**	   exception is the case where hashAlg is SEC_OID_UNKNOWN above).
219**         If this value is NULL no, hash oid is returned.
220**	"wincx" void pointer to the window context
221*/
222extern VFYContext *VFY_CreateContextDirect(const SECKEYPublicKey *key,
223					   const SECItem *sig,
224	     				   SECOidTag pubkAlg, 
225					   SECOidTag hashAlg, 
226					   SECOidTag *hash, void *wincx);
227/*
228** Create a signature verification context from a algorithm ID.
229**	"key" the public key to verify with
230**	"sig" the encrypted signature data if sig is NULL then
231**	   VFY_EndWithSignature must be called with the correct signature at
232**	   the end of the processing.
233**	"algid" specifies the signing algorithm and parameters to use.
234**         This must match the key type.
235**      "hash" optional pointer to return the oid of the actual hash used in 
236**         the signature. If this value is NULL no, hash oid is returned.
237**	"wincx" void pointer to the window context
238*/
239extern VFYContext *VFY_CreateContextWithAlgorithmID(const SECKEYPublicKey *key, 
240				     const SECItem *sig,
241				     const SECAlgorithmID *algid, 
242				     SECOidTag *hash,
243				     void *wincx);
244
245/*
246** Destroy a verification-context object.
247**	"cx" the context to destroy
248**	"freeit" if PR_TRUE then free the object as well as its sub-objects
249*/
250extern void VFY_DestroyContext(VFYContext *cx, PRBool freeit);
251
252extern SECStatus VFY_Begin(VFYContext *cx);
253
254/*
255** Update a verification context with more input data. The input data
256** is fed to a secure hash function (depending on what was in the
257** encrypted signature data).
258**	"cx" the context
259**	"input" the input data
260**	"inputLen" the amount of input data
261*/
262extern SECStatus VFY_Update(VFYContext *cx, const unsigned char *input,
263			    unsigned int inputLen);
264
265/*
266** Finish the verification process. The return value is a status which
267** indicates success or failure. On success, the SECSuccess value is
268** returned. Otherwise, SECFailure is returned and the error code found
269** using PORT_GetError() indicates what failure occurred.
270** 	"cx" the context
271*/
272extern SECStatus VFY_End(VFYContext *cx);
273
274/*
275** Finish the verification process. The return value is a status which
276** indicates success or failure. On success, the SECSuccess value is
277** returned. Otherwise, SECFailure is returned and the error code found
278** using PORT_GetError() indicates what failure occurred. If signature is
279** supplied the verification uses this signature to verify, otherwise the
280** signature passed in VFY_CreateContext() is used. 
281** VFY_EndWithSignature(cx,NULL); is identical to VFY_End(cx);.
282** 	"cx" the context
283** 	"sig" the encrypted signature data
284*/
285extern SECStatus VFY_EndWithSignature(VFYContext *cx, SECItem *sig);
286
287
288/*
289** Verify the signature on a block of data for which we already have
290** the digest. The signature data is an RSA private key encrypted
291** block of data formatted according to PKCS#1.
292**  This function is deprecated. Use VFY_VerifyDigestDirect or 
293**  VFY_VerifyDigestWithAlgorithmID instead.
294** 	"dig" the digest
295** 	"key" the public key to check the signature with
296** 	"sig" the encrypted signature data
297**	"sigAlg" specifies the signing algorithm to use.  This must match
298**	    the key type.
299**	"wincx" void pointer to the window context
300**/
301extern SECStatus VFY_VerifyDigest(SECItem *dig, SECKEYPublicKey *key,
302				  SECItem *sig, SECOidTag sigAlg, void *wincx);
303/*
304** Verify the signature on a block of data for which we already have
305** the digest. The signature data is an RSA private key encrypted
306** block of data formatted according to PKCS#1.
307** 	"dig" the digest
308** 	"key" the public key to check the signature with
309** 	"sig" the encrypted signature data
310**	"pubkAlg" specifies the cryptographic signing algorithm to use (the
311**         raw algorithm without any hash specified.  This must match the key 
312**         type.
313**	"hashAlg" specifies the hashing algorithm used.
314**	"wincx" void pointer to the window context
315**/
316extern SECStatus VFY_VerifyDigestDirect(const SECItem *dig, 
317					const SECKEYPublicKey *key,
318					const SECItem *sig, SECOidTag pubkAlg, 
319					SECOidTag hashAlg, void *wincx);
320/*
321** Verify the signature on a block of data for which we already have
322** the digest. The signature data is an RSA private key encrypted
323** block of data formatted according to PKCS#1.
324**	"key" the public key to verify with
325**	"sig" the encrypted signature data if sig is NULL then
326**	   VFY_EndWithSignature must be called with the correct signature at
327**	   the end of the processing.
328**	"algid" specifies the signing algorithm and parameters to use.
329**         This must match the key type.
330**      "hash" oid of the actual hash used to create digest. If this  value is
331**         not set to SEC_OID_UNKNOWN, it must match the hash of the signature.
332**	"wincx" void pointer to the window context
333*/
334extern SECStatus VFY_VerifyDigestWithAlgorithmID(const SECItem *dig, 
335				const SECKEYPublicKey *key, const SECItem *sig,
336				const SECAlgorithmID *algid, SECOidTag hash,
337				void *wincx);
338
339/*
340** Verify the signature on a block of data. The signature data is an RSA
341** private key encrypted block of data formatted according to PKCS#1.
342**   This function is deprecated. Use VFY_VerifyDataDirect or 
343**   VFY_VerifyDataWithAlgorithmID instead.
344** 	"buf" the input data
345** 	"len" the length of the input data
346** 	"key" the public key to check the signature with
347** 	"sig" the encrypted signature data
348**	"sigAlg" specifies the signing algorithm to use.  This must match
349**	    the key type.
350**	"wincx" void pointer to the window context
351*/
352extern SECStatus VFY_VerifyData(const unsigned char *buf, int len,
353				const SECKEYPublicKey *key, const SECItem *sig,
354				SECOidTag sigAlg, void *wincx);
355/*
356** Verify the signature on a block of data. The signature data is an RSA
357** private key encrypted block of data formatted according to PKCS#1.
358** 	"buf" the input data
359** 	"len" the length of the input data
360** 	"key" the public key to check the signature with
361** 	"sig" the encrypted signature data
362**	"pubkAlg" specifies the cryptographic signing algorithm to use (the
363**         raw algorithm without any hash specified.  This must match the key 
364**         type.
365**	"hashAlg" specifies the hashing algorithm used. If the key is an 
366**	   RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
367**	   the hash is selected from data in the sig.
368**	"hash" optional pointer to return the actual hash algorithm used.
369**	   in practice this should always match the passed in hashAlg (the
370**	   exception is the case where hashAlg is SEC_OID_UNKNOWN above).
371**         If this value is NULL no, hash oid is returned.
372**	"wincx" void pointer to the window context
373*/
374extern SECStatus VFY_VerifyDataDirect(const unsigned char *buf, int len,
375				      const SECKEYPublicKey *key, 
376				      const SECItem *sig,
377				      SECOidTag pubkAlg, SECOidTag hashAlg, 
378				      SECOidTag *hash, void *wincx);
379
380/*
381** Verify the signature on a block of data. The signature data is an RSA
382** private key encrypted block of data formatted according to PKCS#1.
383** 	"buf" the input data
384** 	"len" the length of the input data
385** 	"key" the public key to check the signature with
386** 	"sig" the encrypted signature data
387**	"algid" specifies the signing algorithm and parameters to use.
388**         This must match the key type.
389**      "hash" optional pointer to return the oid of the actual hash used in 
390**         the signature. If this value is NULL no, hash oid is returned.
391**	"wincx" void pointer to the window context
392*/
393extern SECStatus VFY_VerifyDataWithAlgorithmID(const unsigned char *buf, 
394				int len, const SECKEYPublicKey *key,
395				const SECItem *sig,
396				const SECAlgorithmID *algid, SECOidTag *hash,
397				void *wincx);
398
399
400SEC_END_PROTOS
401
402#endif /* _CRYPTOHI_H_ */