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