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

source code of include/nss/cryptohi.h