cryptohi.h (20677B)
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 20 SEC_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 */ 31 extern SECStatus DSAU_EncodeDerSig(SECItem *dest, SECItem *src); 32 extern 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 */ 46 extern SECStatus DSAU_EncodeDerSigWithLen(SECItem *dest, SECItem *src, 47 unsigned int len); 48 extern 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 */ 60 extern 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 */ 67 extern 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 */ 75 extern 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 */ 81 extern 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 */ 89 extern 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 */ 100 extern 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 */ 112 extern 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 */ 126 extern 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 */ 139 extern 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 */ 153 extern 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 */ 171 extern 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 */ 183 extern 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 */ 190 extern SECOidTag SEC_GetSignatureAlgorithmOidTag(KeyType keyType, 191 SECOidTag hashAlgTag); 192 193 /* 194 ** Get the signature algorithm tag for a given key. This works for both public 195 ** keys and private keys. You must supply one and only one key, The other 196 ** must be NULL. The private key is first and the public key is second. Doing 197 ** it this way let's the compiler help us make sure we have the right key 198 ** when we call the function. 199 */ 200 extern SECOidTag SEC_GetSignatureAlgorithmOidTagByKey(const SECKEYPrivateKey *privKey, 201 const SECKEYPublicKey *pubKey, 202 SECOidTag hashAlgTag); 203 204 /* 205 ** Create algorithm parameters for signing. Return a new item 206 ** allocated from arena, or NULL on failure. 207 ** "arena" is the memory arena to use to allocate data from 208 ** "result" the encoded parameters (memory is allocated) 209 ** "signAlgTag" is the signing algorithm 210 ** "hashAlgTag" is the preferred hash algorithm 211 ** "params" is the default parameters 212 ** "key" is the private key 213 */ 214 extern SECItem *SEC_CreateSignatureAlgorithmParameters(PLArenaPool *arena, 215 SECItem *result, 216 SECOidTag signAlgTag, 217 SECOidTag hashAlgTag, 218 const SECItem *params, 219 const SECKEYPrivateKey *key); 220 221 /* 222 ** Create algorithm parameters for signing. Return a new item 223 ** allocated from arena, or NULL on failure. 224 ** "arena" is the memory arena to use to allocate data from 225 ** "result" the encoded parameters (memory is allocated) 226 ** "signAlgTag" is the signing algorithm 227 ** "hashAlgTag" is the preferred hash algorithm 228 ** "params" is the default parameters 229 ** "key" is the public key 230 */ 231 extern SECItem *SEC_CreateVerifyAlgorithmParameters(PLArenaPool *arena, 232 SECItem *result, 233 SECOidTag signAlgTag, 234 SECOidTag hashAlgTag, 235 const SECItem *params, 236 const SECKEYPublicKey *key); 237 /* 238 ** Create algorithm parameters for signing. Return a new item 239 ** allocated from arena, or NULL on failure. 240 ** "arena" is the memory arena to use to allocate data from 241 ** "sigAlgID" sigAlgID to use. 242 ** "hashAlgTag" is the preferred hash algorithm 243 ** "params" is the default parameters 244 ** "privKey" is the private key 245 ** "pubKey" is the public key 246 ** one and only one of privKey and pubKey should be supplied and the other 247 ** should be NULL. 248 */ 249 extern SECStatus SEC_CreateSignatureAlgorithmID(PLArenaPool *arena, 250 SECAlgorithmID *sigAlgID, 251 SECOidTag sigAlgTag, 252 SECOidTag hashAlgTag, 253 const SECItem *params, 254 const SECKEYPrivateKey *privKey, 255 const SECKEYPublicKey *pubKey); 256 257 /****************************************/ 258 /* 259 ** Signature verification operations 260 */ 261 262 /* 263 ** Create a signature verification context. This version is deprecated, 264 ** This function is deprecated. Use VFY_CreateContextDirect or 265 ** VFY_CreateContextWithAlgorithmID instead. 266 ** "key" the public key to verify with 267 ** "sig" the encrypted signature data if sig is NULL then 268 ** VFY_EndWithSignature must be called with the correct signature at 269 ** the end of the processing. 270 ** "sigAlg" specifies the signing algorithm to use (including the 271 ** hash algorthim). This must match the key type. 272 ** "wincx" void pointer to the window context 273 */ 274 extern VFYContext *VFY_CreateContext(SECKEYPublicKey *key, SECItem *sig, 275 SECOidTag sigAlg, void *wincx); 276 /* 277 ** Create a signature verification context. 278 ** "key" the public key to verify with 279 ** "sig" the encrypted signature data if sig is NULL then 280 ** VFY_EndWithSignature must be called with the correct signature at 281 ** the end of the processing. 282 ** "pubkAlg" specifies the cryptographic signing algorithm to use (the 283 ** raw algorithm without any hash specified. This must match the key 284 ** type. 285 ** "hashAlg" specifies the hashing algorithm used. If the key is an 286 ** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN. 287 ** the hash is selected from data in the sig. 288 ** "hash" optional pointer to return the actual hash algorithm used. 289 ** in practice this should always match the passed in hashAlg (the 290 ** exception is the case where hashAlg is SEC_OID_UNKNOWN above). 291 ** If this value is NULL no, hash oid is returned. 292 ** "wincx" void pointer to the window context 293 */ 294 extern VFYContext *VFY_CreateContextDirect(const SECKEYPublicKey *key, 295 const SECItem *sig, 296 SECOidTag pubkAlg, 297 SECOidTag hashAlg, 298 SECOidTag *hash, void *wincx); 299 /* 300 ** Create a signature verification context from a algorithm ID. 301 ** "key" the public key to verify with 302 ** "sig" the encrypted signature data if sig is NULL then 303 ** VFY_EndWithSignature must be called with the correct signature at 304 ** the end of the processing. 305 ** "algid" specifies the signing algorithm and parameters to use. 306 ** This must match the key type. 307 ** "hash" optional pointer to return the oid of the actual hash used in 308 ** the signature. If this value is NULL no, hash oid is returned. 309 ** "wincx" void pointer to the window context 310 */ 311 extern VFYContext *VFY_CreateContextWithAlgorithmID(const SECKEYPublicKey *key, 312 const SECItem *sig, 313 const SECAlgorithmID *algid, 314 SECOidTag *hash, 315 void *wincx); 316 317 /* 318 ** Destroy a verification-context object. 319 ** "cx" the context to destroy 320 ** "freeit" if PR_TRUE then free the object as well as its sub-objects 321 */ 322 extern void VFY_DestroyContext(VFYContext *cx, PRBool freeit); 323 324 extern SECStatus VFY_Begin(VFYContext *cx); 325 326 /* 327 ** Update a verification context with more input data. The input data 328 ** is fed to a secure hash function (depending on what was in the 329 ** encrypted signature data). 330 ** "cx" the context 331 ** "input" the input data 332 ** "inputLen" the amount of input data 333 */ 334 extern SECStatus VFY_Update(VFYContext *cx, const unsigned char *input, 335 unsigned int inputLen); 336 337 /* 338 ** Finish the verification process. The return value is a status which 339 ** indicates success or failure. On success, the SECSuccess value is 340 ** returned. Otherwise, SECFailure is returned and the error code found 341 ** using PORT_GetError() indicates what failure occurred. 342 ** "cx" the context 343 */ 344 extern SECStatus VFY_End(VFYContext *cx); 345 346 /* 347 ** Finish the verification process. The return value is a status which 348 ** indicates success or failure. On success, the SECSuccess value is 349 ** returned. Otherwise, SECFailure is returned and the error code found 350 ** using PORT_GetError() indicates what failure occurred. If signature is 351 ** supplied the verification uses this signature to verify, otherwise the 352 ** signature passed in VFY_CreateContext() is used. 353 ** VFY_EndWithSignature(cx,NULL); is identical to VFY_End(cx);. 354 ** "cx" the context 355 ** "sig" the encrypted signature data 356 */ 357 extern SECStatus VFY_EndWithSignature(VFYContext *cx, SECItem *sig); 358 359 /* 360 ** Verify the signature on a block of data for which we already have 361 ** the digest. The signature data is an RSA private key encrypted 362 ** block of data formatted according to PKCS#1. 363 ** This function is deprecated. Use VFY_VerifyDigestDirect or 364 ** VFY_VerifyDigestWithAlgorithmID instead. 365 ** "dig" the digest 366 ** "key" the public key to check the signature with 367 ** "sig" the encrypted signature data 368 ** "sigAlg" specifies the signing algorithm to use. This must match 369 ** the key type. 370 ** "wincx" void pointer to the window context 371 **/ 372 extern SECStatus VFY_VerifyDigest(SECItem *dig, SECKEYPublicKey *key, 373 SECItem *sig, SECOidTag sigAlg, void *wincx); 374 /* 375 ** Verify the signature on a block of data for which we already have 376 ** the digest. The signature data is an RSA private key encrypted 377 ** block of data formatted according to PKCS#1. 378 ** "dig" the digest 379 ** "key" the public key to check the signature with 380 ** "sig" the encrypted signature data 381 ** "pubkAlg" specifies the cryptographic signing algorithm to use (the 382 ** raw algorithm without any hash specified. This must match the key 383 ** type. 384 ** "hashAlg" specifies the hashing algorithm used. 385 ** "wincx" void pointer to the window context 386 **/ 387 extern SECStatus VFY_VerifyDigestDirect(const SECItem *dig, 388 const SECKEYPublicKey *key, 389 const SECItem *sig, SECOidTag pubkAlg, 390 SECOidTag hashAlg, void *wincx); 391 /* 392 ** Verify the signature on a block of data for which we already have 393 ** the digest. The signature data is an RSA private key encrypted 394 ** block of data formatted according to PKCS#1. 395 ** "key" the public key to verify with 396 ** "sig" the encrypted signature data if sig is NULL then 397 ** VFY_EndWithSignature must be called with the correct signature at 398 ** the end of the processing. 399 ** "algid" specifies the signing algorithm and parameters to use. 400 ** This must match the key type. 401 ** "hash" oid of the actual hash used to create digest. If this value is 402 ** not set to SEC_OID_UNKNOWN, it must match the hash of the signature. 403 ** "wincx" void pointer to the window context 404 */ 405 extern SECStatus VFY_VerifyDigestWithAlgorithmID(const SECItem *dig, 406 const SECKEYPublicKey *key, const SECItem *sig, 407 const SECAlgorithmID *algid, SECOidTag hash, 408 void *wincx); 409 410 /* 411 ** Verify the signature on a block of data. The signature data is an RSA 412 ** private key encrypted block of data formatted according to PKCS#1. 413 ** This function is deprecated. Use VFY_VerifyDataDirect or 414 ** VFY_VerifyDataWithAlgorithmID instead. 415 ** "buf" the input data 416 ** "len" the length of the input data 417 ** "key" the public key to check the signature with 418 ** "sig" the encrypted signature data 419 ** "sigAlg" specifies the signing algorithm to use. This must match 420 ** the key type. 421 ** "wincx" void pointer to the window context 422 */ 423 extern SECStatus VFY_VerifyData(const unsigned char *buf, int len, 424 const SECKEYPublicKey *key, const SECItem *sig, 425 SECOidTag sigAlg, void *wincx); 426 /* 427 ** Verify the signature on a block of data. The signature data is an RSA 428 ** private key encrypted block of data formatted according to PKCS#1. 429 ** "buf" the input data 430 ** "len" the length of the input data 431 ** "key" the public key to check the signature with 432 ** "sig" the encrypted signature data 433 ** "pubkAlg" specifies the cryptographic signing algorithm to use (the 434 ** raw algorithm without any hash specified. This must match the key 435 ** type. 436 ** "hashAlg" specifies the hashing algorithm used. If the key is an 437 ** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN. 438 ** the hash is selected from data in the sig. 439 ** "hash" optional pointer to return the actual hash algorithm used. 440 ** in practice this should always match the passed in hashAlg (the 441 ** exception is the case where hashAlg is SEC_OID_UNKNOWN above). 442 ** If this value is NULL no, hash oid is returned. 443 ** "wincx" void pointer to the window context 444 */ 445 extern SECStatus VFY_VerifyDataDirect(const unsigned char *buf, int len, 446 const SECKEYPublicKey *key, 447 const SECItem *sig, 448 SECOidTag pubkAlg, SECOidTag hashAlg, 449 SECOidTag *hash, void *wincx); 450 451 /* 452 ** Verify the signature on a block of data. The signature data is an RSA 453 ** private key encrypted block of data formatted according to PKCS#1. 454 ** "buf" the input data 455 ** "len" the length of the input data 456 ** "key" the public key to check the signature with 457 ** "sig" the encrypted signature data 458 ** "algid" specifies the signing algorithm and parameters to use. 459 ** This must match the key type. 460 ** "hash" optional pointer to return the oid of the actual hash used in 461 ** the signature. If this value is NULL no, hash oid is returned. 462 ** "wincx" void pointer to the window context 463 */ 464 extern SECStatus VFY_VerifyDataWithAlgorithmID(const unsigned char *buf, 465 int len, const SECKEYPublicKey *key, 466 const SECItem *sig, 467 const SECAlgorithmID *algid, SECOidTag *hash, 468 void *wincx); 469 470 SEC_END_PROTOS 471 472 #endif /* _CRYPTOHI_H_ */