cms.h (39833B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 /* 6 * Interfaces of the CMS implementation. 7 */ 8 9 #ifndef _CMS_H_ 10 #define _CMS_H_ 11 12 #include "seccomon.h" 13 14 #include "secoidt.h" 15 #include "certt.h" 16 #include "keythi.h" 17 #include "hasht.h" 18 #include "cmst.h" 19 20 /************************************************************************/ 21 SEC_BEGIN_PROTOS 22 23 /************************************************************************ 24 * cmsdecode.c - CMS decoding 25 ************************************************************************/ 26 27 /* 28 * NSS_CMSDecoder_Start - set up decoding of a DER-encoded CMS message 29 * 30 * "poolp" - pointer to arena for message, or NULL if new pool should be created 31 * "cb", "cb_arg" - callback function and argument for delivery of inner content 32 * inner content will be stored in the message if cb is NULL. 33 * "pwfn", pwfn_arg" - callback function for getting token password 34 * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData 35 */ 36 extern NSSCMSDecoderContext * 37 NSS_CMSDecoder_Start(PLArenaPool *poolp, 38 NSSCMSContentCallback cb, void *cb_arg, 39 PK11PasswordFunc pwfn, void *pwfn_arg, 40 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg); 41 42 /* 43 * NSS_CMSDecoder_Update - feed DER-encoded data to decoder 44 */ 45 extern SECStatus 46 NSS_CMSDecoder_Update(NSSCMSDecoderContext *p7dcx, const char *buf, unsigned long len); 47 48 /* 49 * NSS_CMSDecoder_Cancel - cancel a decoding process 50 */ 51 extern void 52 NSS_CMSDecoder_Cancel(NSSCMSDecoderContext *p7dcx); 53 54 /* 55 * NSS_CMSDecoder_Finish - mark the end of inner content and finish decoding 56 */ 57 extern NSSCMSMessage * 58 NSS_CMSDecoder_Finish(NSSCMSDecoderContext *p7dcx); 59 60 /* 61 * NSS_CMSMessage_CreateFromDER - decode a CMS message from DER encoded data 62 */ 63 extern NSSCMSMessage * 64 NSS_CMSMessage_CreateFromDER(SECItem *DERmessage, 65 NSSCMSContentCallback cb, void *cb_arg, 66 PK11PasswordFunc pwfn, void *pwfn_arg, 67 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg); 68 69 /************************************************************************ 70 * cmsencode.c - CMS encoding 71 ************************************************************************/ 72 73 /* 74 * NSS_CMSEncoder_Start - set up encoding of a CMS message 75 * 76 * "cmsg" - message to encode 77 * "outputfn", "outputarg" - callback function for delivery of DER-encoded output 78 * will not be called if NULL. 79 * "dest" - if non-NULL, pointer to SECItem that will hold the DER-encoded output 80 * "destpoolp" - pool to allocate DER-encoded output in 81 * "pwfn", pwfn_arg" - callback function for getting token password 82 * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData 83 * "detached_digestalgs", "detached_digests" - digests from detached content 84 */ 85 extern NSSCMSEncoderContext * 86 NSS_CMSEncoder_Start(NSSCMSMessage *cmsg, 87 NSSCMSContentCallback outputfn, void *outputarg, 88 SECItem *dest, PLArenaPool *destpoolp, 89 PK11PasswordFunc pwfn, void *pwfn_arg, 90 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg, 91 SECAlgorithmID **detached_digestalgs, SECItem **detached_digests); 92 93 /* 94 * NSS_CMSEncoder_Update - take content data delivery from the user 95 * 96 * "p7ecx" - encoder context 97 * "data" - content data 98 * "len" - length of content data 99 */ 100 extern SECStatus 101 NSS_CMSEncoder_Update(NSSCMSEncoderContext *p7ecx, const char *data, unsigned long len); 102 103 /* 104 * NSS_CMSEncoder_Cancel - stop all encoding 105 */ 106 extern SECStatus 107 NSS_CMSEncoder_Cancel(NSSCMSEncoderContext *p7ecx); 108 109 /* 110 * NSS_CMSEncoder_Finish - signal the end of data 111 * 112 * we need to walk down the chain of encoders and the finish them from the innermost out 113 */ 114 extern SECStatus 115 NSS_CMSEncoder_Finish(NSSCMSEncoderContext *p7ecx); 116 117 /************************************************************************ 118 * cmsmessage.c - CMS message object 119 ************************************************************************/ 120 121 /* 122 * NSS_CMSMessage_Create - create a CMS message object 123 * 124 * "poolp" - arena to allocate memory from, or NULL if new arena should be created 125 */ 126 extern NSSCMSMessage * 127 NSS_CMSMessage_Create(PLArenaPool *poolp); 128 129 /* 130 * NSS_CMSMessage_SetEncodingParams - set up a CMS message object for encoding or decoding 131 * 132 * "cmsg" - message object 133 * "pwfn", pwfn_arg" - callback function for getting token password 134 * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData 135 * "detached_digestalgs", "detached_digests" - digests from detached content 136 * 137 * used internally. 138 */ 139 extern void 140 NSS_CMSMessage_SetEncodingParams(NSSCMSMessage *cmsg, 141 PK11PasswordFunc pwfn, void *pwfn_arg, 142 NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg, 143 SECAlgorithmID **detached_digestalgs, SECItem **detached_digests); 144 145 /* 146 * NSS_CMSMessage_Destroy - destroy a CMS message and all of its sub-pieces. 147 */ 148 extern void 149 NSS_CMSMessage_Destroy(NSSCMSMessage *cmsg); 150 151 /* 152 * NSS_CMSMessage_Copy - return a copy of the given message. 153 * 154 * The copy may be virtual or may be real -- either way, the result needs 155 * to be passed to NSS_CMSMessage_Destroy later (as does the original). 156 */ 157 extern NSSCMSMessage * 158 NSS_CMSMessage_Copy(NSSCMSMessage *cmsg); 159 160 /* 161 * NSS_CMSMessage_GetArena - return a pointer to the message's arena pool 162 */ 163 extern PLArenaPool * 164 NSS_CMSMessage_GetArena(NSSCMSMessage *cmsg); 165 166 /* 167 * NSS_CMSMessage_GetContentInfo - return a pointer to the top level contentInfo 168 */ 169 extern NSSCMSContentInfo * 170 NSS_CMSMessage_GetContentInfo(NSSCMSMessage *cmsg); 171 172 /* 173 * Return a pointer to the actual content. 174 * In the case of those types which are encrypted, this returns the *plain* content. 175 * In case of nested contentInfos, this descends and retrieves the innermost content. 176 */ 177 extern SECItem * 178 NSS_CMSMessage_GetContent(NSSCMSMessage *cmsg); 179 180 /* 181 * NSS_CMSMessage_ContentLevelCount - count number of levels of CMS content objects in this message 182 * 183 * CMS data content objects do not count. 184 */ 185 extern int 186 NSS_CMSMessage_ContentLevelCount(NSSCMSMessage *cmsg); 187 188 /* 189 * NSS_CMSMessage_ContentLevel - find content level #n 190 * 191 * CMS data content objects do not count. 192 */ 193 extern NSSCMSContentInfo * 194 NSS_CMSMessage_ContentLevel(NSSCMSMessage *cmsg, int n); 195 196 /* 197 * NSS_CMSMessage_ContainsCertsOrCrls - see if message contains certs along the way 198 */ 199 extern PRBool 200 NSS_CMSMessage_ContainsCertsOrCrls(NSSCMSMessage *cmsg); 201 202 /* 203 * NSS_CMSMessage_IsEncrypted - see if message contains a encrypted submessage 204 */ 205 extern PRBool 206 NSS_CMSMessage_IsEncrypted(NSSCMSMessage *cmsg); 207 208 /* 209 * NSS_CMSMessage_IsSigned - see if message contains a signed submessage 210 * 211 * If the CMS message has a SignedData with a signature (not just a SignedData) 212 * return true; false otherwise. This can/should be called before calling 213 * VerifySignature, which will always indicate failure if no signature is 214 * present, but that does not mean there even was a signature! 215 * Note that the content itself can be empty (detached content was sent 216 * another way); it is the presence of the signature that matters. 217 */ 218 extern PRBool 219 NSS_CMSMessage_IsSigned(NSSCMSMessage *cmsg); 220 221 /* 222 * NSS_CMSMessage_IsContentEmpty - see if content is empty 223 * 224 * returns PR_TRUE is innermost content length is < minLen 225 * XXX need the encrypted content length (why?) 226 */ 227 extern PRBool 228 NSS_CMSMessage_IsContentEmpty(NSSCMSMessage *cmsg, unsigned int minLen); 229 230 /************************************************************************ 231 * cmscinfo.c - CMS contentInfo methods 232 ************************************************************************/ 233 234 /* 235 * NSS_CMSContentInfo_Destroy - destroy a CMS contentInfo and all of its sub-pieces. 236 */ 237 extern void 238 NSS_CMSContentInfo_Destroy(NSSCMSContentInfo *cinfo); 239 240 /* 241 * NSS_CMSContentInfo_GetChildContentInfo - get content's contentInfo (if it exists) 242 */ 243 extern NSSCMSContentInfo * 244 NSS_CMSContentInfo_GetChildContentInfo(NSSCMSContentInfo *cinfo); 245 246 /* 247 * NSS_CMSContentInfo_SetContent - set cinfo's content type & content to CMS object 248 */ 249 extern SECStatus 250 NSS_CMSContentInfo_SetContent(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECOidTag type, void *ptr); 251 252 /* 253 * NSS_CMSContentInfo_SetContent_XXXX - typesafe wrappers for NSS_CMSContentInfo_SetType 254 * set cinfo's content type & content to CMS object 255 */ 256 extern SECStatus 257 NSS_CMSContentInfo_SetContent_Data(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECItem *data, PRBool detached); 258 259 extern SECStatus 260 NSS_CMSContentInfo_SetContent_SignedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSSignedData *sigd); 261 262 extern SECStatus 263 NSS_CMSContentInfo_SetContent_EnvelopedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEnvelopedData *envd); 264 265 extern SECStatus 266 NSS_CMSContentInfo_SetContent_DigestedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSDigestedData *digd); 267 268 extern SECStatus 269 NSS_CMSContentInfo_SetContent_EncryptedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEncryptedData *encd); 270 271 /* 272 * turn off streaming for this content type. 273 * This could fail with SEC_ERROR_NO_MEMORY in memory constrained conditions. 274 */ 275 extern SECStatus 276 NSS_CMSContentInfo_SetDontStream(NSSCMSContentInfo *cinfo, PRBool dontStream); 277 278 /* 279 * NSS_CMSContentInfo_GetContent - get pointer to inner content 280 * 281 * needs to be casted... 282 */ 283 extern void * 284 NSS_CMSContentInfo_GetContent(NSSCMSContentInfo *cinfo); 285 286 /* 287 * NSS_CMSContentInfo_GetInnerContent - get pointer to innermost content 288 * 289 * this is typically only called by NSS_CMSMessage_GetContent() 290 */ 291 extern SECItem * 292 NSS_CMSContentInfo_GetInnerContent(NSSCMSContentInfo *cinfo); 293 294 /* 295 * NSS_CMSContentInfo_GetContentType{Tag,OID} - find out (saving pointer to lookup result 296 * for future reference) and return the inner content type. 297 */ 298 extern SECOidTag 299 NSS_CMSContentInfo_GetContentTypeTag(NSSCMSContentInfo *cinfo); 300 301 extern SECItem * 302 NSS_CMSContentInfo_GetContentTypeOID(NSSCMSContentInfo *cinfo); 303 304 /* 305 * NSS_CMSContentInfo_GetContentEncAlgTag - find out (saving pointer to lookup result 306 * for future reference) and return the content encryption algorithm tag. 307 */ 308 extern SECOidTag 309 NSS_CMSContentInfo_GetContentEncAlgTag(NSSCMSContentInfo *cinfo); 310 311 /* 312 * NSS_CMSContentInfo_GetContentEncAlg - find out and return the content encryption algorithm tag. 313 */ 314 extern SECAlgorithmID * 315 NSS_CMSContentInfo_GetContentEncAlg(NSSCMSContentInfo *cinfo); 316 317 extern SECStatus 318 NSS_CMSContentInfo_SetContentEncAlg(PLArenaPool *poolp, NSSCMSContentInfo *cinfo, 319 SECOidTag bulkalgtag, SECItem *parameters, int keysize); 320 321 extern SECStatus 322 NSS_CMSContentInfo_SetContentEncAlgID(PLArenaPool *poolp, NSSCMSContentInfo *cinfo, 323 SECAlgorithmID *algid, int keysize); 324 325 extern void 326 NSS_CMSContentInfo_SetBulkKey(NSSCMSContentInfo *cinfo, PK11SymKey *bulkkey); 327 328 extern PK11SymKey * 329 NSS_CMSContentInfo_GetBulkKey(NSSCMSContentInfo *cinfo); 330 331 extern int 332 NSS_CMSContentInfo_GetBulkKeySize(NSSCMSContentInfo *cinfo); 333 334 /************************************************************************ 335 * cmsutil.c - CMS misc utility functions 336 ************************************************************************/ 337 338 /* 339 * NSS_CMSArray_SortByDER - sort array of objects by objects' DER encoding 340 * 341 * make sure that the order of the objects guarantees valid DER (which must be 342 * in lexigraphically ascending order for a SET OF); if reordering is necessary it 343 * will be done in place (in objs). 344 */ 345 extern SECStatus 346 NSS_CMSArray_SortByDER(void **objs, const SEC_ASN1Template *objtemplate, void **objs2); 347 348 /* 349 * NSS_CMSUtil_DERCompare - for use with NSS_CMSArray_Sort to 350 * sort arrays of SECItems containing DER 351 */ 352 extern int 353 NSS_CMSUtil_DERCompare(void *a, void *b); 354 355 /* 356 * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of 357 * algorithms. 358 * 359 * algorithmArray - array of algorithm IDs 360 * algid - algorithmid of algorithm to pick 361 * 362 * Returns: 363 * An integer containing the index of the algorithm in the array or -1 if 364 * algorithm was not found. 365 */ 366 extern int 367 NSS_CMSAlgArray_GetIndexByAlgID(SECAlgorithmID **algorithmArray, SECAlgorithmID *algid); 368 369 /* 370 * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of 371 * algorithms. 372 * 373 * algorithmArray - array of algorithm IDs 374 * algiddata - id of algorithm to pick 375 * 376 * Returns: 377 * An integer containing the index of the algorithm in the array or -1 if 378 * algorithm was not found. 379 */ 380 extern int 381 NSS_CMSAlgArray_GetIndexByAlgTag(SECAlgorithmID **algorithmArray, SECOidTag algtag); 382 383 extern const SECHashObject * 384 NSS_CMSUtil_GetHashObjByAlgID(SECAlgorithmID *algid); 385 386 extern const SEC_ASN1Template * 387 NSS_CMSUtil_GetTemplateByTypeTag(SECOidTag type); 388 389 extern size_t 390 NSS_CMSUtil_GetSizeByTypeTag(SECOidTag type); 391 392 extern NSSCMSContentInfo * 393 NSS_CMSContent_GetContentInfo(void *msg, SECOidTag type); 394 395 extern const char * 396 NSS_CMSUtil_VerificationStatusToString(NSSCMSVerificationStatus vs); 397 398 /************************************************************************ 399 * cmssigdata.c - CMS signedData methods 400 ************************************************************************/ 401 402 extern NSSCMSSignedData * 403 NSS_CMSSignedData_Create(NSSCMSMessage *cmsg); 404 405 extern void 406 NSS_CMSSignedData_Destroy(NSSCMSSignedData *sigd); 407 408 /* 409 * NSS_CMSSignedData_Encode_BeforeStart - do all the necessary things to a SignedData 410 * before start of encoding. 411 * 412 * In detail: 413 * - find out about the right value to put into sigd->version 414 * - come up with a list of digestAlgorithms (which should be the union of the algorithms 415 * in the signerinfos). 416 * If we happen to have a pre-set list of algorithms (and digest values!), we 417 * check if we have all the signerinfos' algorithms. If not, this is an error. 418 */ 419 extern SECStatus 420 NSS_CMSSignedData_Encode_BeforeStart(NSSCMSSignedData *sigd); 421 422 extern SECStatus 423 NSS_CMSSignedData_Encode_BeforeData(NSSCMSSignedData *sigd); 424 425 /* 426 * NSS_CMSSignedData_Encode_AfterData - do all the necessary things to a SignedData 427 * after all the encapsulated data was passed through the encoder. 428 * 429 * In detail: 430 * - create the signatures in all the SignerInfos 431 * 432 * Please note that nothing is done to the Certificates and CRLs in the message - this 433 * is entirely the responsibility of our callers. 434 */ 435 extern SECStatus 436 NSS_CMSSignedData_Encode_AfterData(NSSCMSSignedData *sigd); 437 438 extern SECStatus 439 NSS_CMSSignedData_Decode_BeforeData(NSSCMSSignedData *sigd); 440 441 /* 442 * NSS_CMSSignedData_Decode_AfterData - do all the necessary things to a SignedData 443 * after all the encapsulated data was passed through the decoder. 444 */ 445 extern SECStatus 446 NSS_CMSSignedData_Decode_AfterData(NSSCMSSignedData *sigd); 447 448 /* 449 * NSS_CMSSignedData_Decode_AfterEnd - do all the necessary things to a SignedData 450 * after all decoding is finished. 451 */ 452 extern SECStatus 453 NSS_CMSSignedData_Decode_AfterEnd(NSSCMSSignedData *sigd); 454 455 /* 456 * NSS_CMSSignedData_GetSignerInfos - retrieve the SignedData's signer list 457 */ 458 extern NSSCMSSignerInfo ** 459 NSS_CMSSignedData_GetSignerInfos(NSSCMSSignedData *sigd); 460 461 extern int 462 NSS_CMSSignedData_SignerInfoCount(NSSCMSSignedData *sigd); 463 464 extern NSSCMSSignerInfo * 465 NSS_CMSSignedData_GetSignerInfo(NSSCMSSignedData *sigd, int i); 466 467 /* 468 * NSS_CMSSignedData_GetDigestAlgs - retrieve the SignedData's digest algorithm list 469 */ 470 extern SECAlgorithmID ** 471 NSS_CMSSignedData_GetDigestAlgs(NSSCMSSignedData *sigd); 472 473 /* 474 * NSS_CMSSignedData_GetContentInfo - return pointer to this signedData's contentinfo 475 */ 476 extern NSSCMSContentInfo * 477 NSS_CMSSignedData_GetContentInfo(NSSCMSSignedData *sigd); 478 479 /* 480 * NSS_CMSSignedData_GetCertificateList - retrieve the SignedData's certificate list 481 */ 482 extern SECItem ** 483 NSS_CMSSignedData_GetCertificateList(NSSCMSSignedData *sigd); 484 485 extern SECStatus 486 NSS_CMSSignedData_ImportCerts(NSSCMSSignedData *sigd, CERTCertDBHandle *certdb, 487 SECCertUsage certusage, PRBool keepcerts); 488 489 /* 490 * NSS_CMSSignedData_HasDigests - see if we have digests in place 491 */ 492 extern PRBool 493 NSS_CMSSignedData_HasDigests(NSSCMSSignedData *sigd); 494 495 /* 496 * NSS_CMSSignedData_VerifySignerInfo - check a signature. 497 * 498 * The digests were either calculated during decoding (and are stored in the 499 * signedData itself) or set after decoding using NSS_CMSSignedData_SetDigests. 500 * 501 * The verification checks if the signing cert is valid and has a trusted chain 502 * for the purpose specified by "certusage". 503 */ 504 extern SECStatus 505 NSS_CMSSignedData_VerifySignerInfo(NSSCMSSignedData *sigd, int i, CERTCertDBHandle *certdb, 506 SECCertUsage certusage); 507 508 /* 509 * NSS_CMSSignedData_VerifyCertsOnly - verify the certs in a certs-only message 510 */ 511 extern SECStatus 512 NSS_CMSSignedData_VerifyCertsOnly(NSSCMSSignedData *sigd, 513 CERTCertDBHandle *certdb, 514 SECCertUsage usage); 515 516 extern SECStatus 517 NSS_CMSSignedData_AddCertList(NSSCMSSignedData *sigd, CERTCertificateList *certlist); 518 519 /* 520 * NSS_CMSSignedData_AddCertChain - add cert and its entire chain to the set of certs 521 */ 522 extern SECStatus 523 NSS_CMSSignedData_AddCertChain(NSSCMSSignedData *sigd, CERTCertificate *cert); 524 525 extern SECStatus 526 NSS_CMSSignedData_AddCertificate(NSSCMSSignedData *sigd, CERTCertificate *cert); 527 528 extern PRBool 529 NSS_CMSSignedData_ContainsCertsOrCrls(NSSCMSSignedData *sigd); 530 531 extern SECStatus 532 NSS_CMSSignedData_AddSignerInfo(NSSCMSSignedData *sigd, 533 NSSCMSSignerInfo *signerinfo); 534 535 extern SECStatus 536 NSS_CMSSignedData_SetDigests(NSSCMSSignedData *sigd, 537 SECAlgorithmID **digestalgs, 538 SECItem **digests); 539 540 extern SECStatus 541 NSS_CMSSignedData_SetDigestValue(NSSCMSSignedData *sigd, 542 SECOidTag digestalgtag, 543 SECItem *digestdata); 544 545 extern SECStatus 546 NSS_CMSSignedData_AddDigest(PLArenaPool *poolp, 547 NSSCMSSignedData *sigd, 548 SECOidTag digestalgtag, 549 SECItem *digest); 550 551 extern SECItem * 552 NSS_CMSSignedData_GetDigestValue(NSSCMSSignedData *sigd, SECOidTag digestalgtag); 553 554 /* 555 * NSS_CMSSignedData_CreateCertsOnly - create a certs-only SignedData. 556 * 557 * cert - base certificates that will be included 558 * include_chain - if true, include the complete cert chain for cert 559 * 560 * More certs and chains can be added via AddCertificate and AddCertChain. 561 * 562 * An error results in a return value of NULL and an error set. 563 */ 564 extern NSSCMSSignedData * 565 NSS_CMSSignedData_CreateCertsOnly(NSSCMSMessage *cmsg, CERTCertificate *cert, PRBool include_chain); 566 567 /************************************************************************ 568 * cmssiginfo.c - signerinfo methods 569 ************************************************************************/ 570 571 extern NSSCMSSignerInfo * 572 NSS_CMSSignerInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert, SECOidTag digestalgtag); 573 extern NSSCMSSignerInfo * 574 NSS_CMSSignerInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg, SECItem *subjKeyID, SECKEYPublicKey *pubKey, SECKEYPrivateKey *signingKey, SECOidTag digestalgtag); 575 576 /* 577 * NSS_CMSSignerInfo_Destroy - destroy a SignerInfo data structure 578 */ 579 extern void 580 NSS_CMSSignerInfo_Destroy(NSSCMSSignerInfo *si); 581 582 /* 583 * NSS_CMSSignerInfo_Sign - sign something 584 * 585 */ 586 extern SECStatus 587 NSS_CMSSignerInfo_Sign(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType); 588 589 extern SECStatus 590 NSS_CMSSignerInfo_VerifyCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb, 591 SECCertUsage certusage); 592 593 /* 594 * NSS_CMSSignerInfo_Verify - verify the signature of a single SignerInfo 595 * 596 * Just verifies the signature. The assumption is that verification of the certificate 597 * is done already. 598 */ 599 extern SECStatus 600 NSS_CMSSignerInfo_Verify(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType); 601 602 extern NSSCMSVerificationStatus 603 NSS_CMSSignerInfo_GetVerificationStatus(NSSCMSSignerInfo *signerinfo); 604 605 extern SECOidData * 606 NSS_CMSSignerInfo_GetDigestAlg(NSSCMSSignerInfo *signerinfo); 607 608 extern SECOidTag 609 NSS_CMSSignerInfo_GetDigestAlgTag(NSSCMSSignerInfo *signerinfo); 610 611 extern int 612 NSS_CMSSignerInfo_GetVersion(NSSCMSSignerInfo *signerinfo); 613 614 extern CERTCertificateList * 615 NSS_CMSSignerInfo_GetCertList(NSSCMSSignerInfo *signerinfo); 616 617 /* 618 * NSS_CMSSignerInfo_GetSigningTime - return the signing time, 619 * in UTCTime format, of a CMS signerInfo. 620 * 621 * sinfo - signerInfo data for this signer 622 * 623 * Returns a pointer to XXXX (what?) 624 * A return value of NULL is an error. 625 */ 626 extern SECStatus 627 NSS_CMSSignerInfo_GetSigningTime(NSSCMSSignerInfo *sinfo, PRTime *stime); 628 629 /* 630 * Return the signing cert of a CMS signerInfo. 631 * 632 * the certs in the enclosing SignedData must have been imported already 633 */ 634 extern CERTCertificate * 635 NSS_CMSSignerInfo_GetSigningCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb); 636 637 /* 638 * NSS_CMSSignerInfo_GetSignerCommonName - return the common name of the signer 639 * 640 * sinfo - signerInfo data for this signer 641 * 642 * Returns a pointer to allocated memory, which must be freed with PORT_Free. 643 * A return value of NULL is an error. 644 */ 645 extern char * 646 NSS_CMSSignerInfo_GetSignerCommonName(NSSCMSSignerInfo *sinfo); 647 648 /* 649 * NSS_CMSSignerInfo_GetSignerEmailAddress - return the common name of the signer 650 * 651 * sinfo - signerInfo data for this signer 652 * 653 * Returns a pointer to allocated memory, which must be freed. 654 * A return value of NULL is an error. 655 */ 656 extern char * 657 NSS_CMSSignerInfo_GetSignerEmailAddress(NSSCMSSignerInfo *sinfo); 658 659 /* 660 * NSS_CMSSignerInfo_AddAuthAttr - add an attribute to the 661 * authenticated (i.e. signed) attributes of "signerinfo". 662 */ 663 extern SECStatus 664 NSS_CMSSignerInfo_AddAuthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr); 665 666 /* 667 * NSS_CMSSignerInfo_AddUnauthAttr - add an attribute to the 668 * unauthenticated attributes of "signerinfo". 669 */ 670 extern SECStatus 671 NSS_CMSSignerInfo_AddUnauthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr); 672 673 /* 674 * NSS_CMSSignerInfo_AddSigningTime - add the signing time to the 675 * authenticated (i.e. signed) attributes of "signerinfo". 676 * 677 * This is expected to be included in outgoing signed 678 * messages for email (S/MIME) but is likely useful in other situations. 679 * 680 * This should only be added once; a second call will do nothing. 681 * 682 * XXX This will probably just shove the current time into "signerinfo" 683 * but it will not actually get signed until the entire item is 684 * processed for encoding. Is this (expected to be small) delay okay? 685 */ 686 extern SECStatus 687 NSS_CMSSignerInfo_AddSigningTime(NSSCMSSignerInfo *signerinfo, PRTime t); 688 689 /* 690 * NSS_CMSSignerInfo_AddSMIMECaps - add a SMIMECapabilities attribute to the 691 * authenticated (i.e. signed) attributes of "signerinfo". 692 * 693 * This is expected to be included in outgoing signed 694 * messages for email (S/MIME). 695 */ 696 extern SECStatus 697 NSS_CMSSignerInfo_AddSMIMECaps(NSSCMSSignerInfo *signerinfo); 698 699 /* 700 * NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the 701 * authenticated (i.e. signed) attributes of "signerinfo". 702 * 703 * This is expected to be included in outgoing signed messages for email (S/MIME). 704 */ 705 SECStatus 706 NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb); 707 708 /* 709 * NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the 710 * authenticated (i.e. signed) attributes of "signerinfo", using the OID preferred by Microsoft. 711 * 712 * This is expected to be included in outgoing signed messages for email (S/MIME), 713 * if compatibility with Microsoft mail clients is wanted. 714 */ 715 SECStatus 716 NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb); 717 718 /* 719 * NSS_CMSSignerInfo_AddCounterSignature - countersign a signerinfo 720 */ 721 extern SECStatus 722 NSS_CMSSignerInfo_AddCounterSignature(NSSCMSSignerInfo *signerinfo, 723 SECOidTag digestalg, CERTCertificate signingcert); 724 725 /* 726 * XXXX the following needs to be done in the S/MIME layer code 727 * after signature of a signerinfo is verified 728 */ 729 extern SECStatus 730 NSS_SMIMESignerInfo_SaveSMIMEProfile(NSSCMSSignerInfo *signerinfo); 731 732 /* 733 * NSS_CMSSignerInfo_IncludeCerts - set cert chain inclusion mode for this signer 734 */ 735 extern SECStatus 736 NSS_CMSSignerInfo_IncludeCerts(NSSCMSSignerInfo *signerinfo, NSSCMSCertChainMode cm, SECCertUsage usage); 737 738 /************************************************************************ 739 * cmsenvdata.c - CMS envelopedData methods 740 ************************************************************************/ 741 742 /* 743 * NSS_CMSEnvelopedData_Create - create an enveloped data message 744 */ 745 extern NSSCMSEnvelopedData * 746 NSS_CMSEnvelopedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize); 747 748 /* 749 * NSS_CMSEnvelopedData_Destroy - destroy an enveloped data message 750 */ 751 extern void 752 NSS_CMSEnvelopedData_Destroy(NSSCMSEnvelopedData *edp); 753 754 /* 755 * NSS_CMSEnvelopedData_GetContentInfo - return pointer to this envelopedData's contentinfo 756 */ 757 extern NSSCMSContentInfo * 758 NSS_CMSEnvelopedData_GetContentInfo(NSSCMSEnvelopedData *envd); 759 760 /* 761 * NSS_CMSEnvelopedData_AddRecipient - add a recipientinfo to the enveloped data msg 762 * 763 * rip must be created on the same pool as edp - this is not enforced, though. 764 */ 765 extern SECStatus 766 NSS_CMSEnvelopedData_AddRecipient(NSSCMSEnvelopedData *edp, NSSCMSRecipientInfo *rip); 767 768 /* 769 * NSS_CMSEnvelopedData_Encode_BeforeStart - prepare this envelopedData for encoding 770 * 771 * at this point, we need 772 * - recipientinfos set up with recipient's certificates 773 * - a content encryption algorithm (if none, 3DES will be used) 774 * 775 * this function will generate a random content encryption key (aka bulk key), 776 * initialize the recipientinfos with certificate identification and wrap the bulk key 777 * using the proper algorithm for every certificiate. 778 * it will finally set the bulk algorithm and key so that the encode step can find it. 779 */ 780 extern SECStatus 781 NSS_CMSEnvelopedData_Encode_BeforeStart(NSSCMSEnvelopedData *envd); 782 783 /* 784 * NSS_CMSEnvelopedData_Encode_BeforeData - set up encryption 785 */ 786 extern SECStatus 787 NSS_CMSEnvelopedData_Encode_BeforeData(NSSCMSEnvelopedData *envd); 788 789 /* 790 * NSS_CMSEnvelopedData_Encode_AfterData - finalize this envelopedData for encoding 791 */ 792 extern SECStatus 793 NSS_CMSEnvelopedData_Encode_AfterData(NSSCMSEnvelopedData *envd); 794 795 /* 796 * NSS_CMSEnvelopedData_Decode_BeforeData - find our recipientinfo, 797 * derive bulk key & set up our contentinfo 798 */ 799 extern SECStatus 800 NSS_CMSEnvelopedData_Decode_BeforeData(NSSCMSEnvelopedData *envd); 801 802 /* 803 * NSS_CMSEnvelopedData_Decode_AfterData - finish decrypting this envelopedData's content 804 */ 805 extern SECStatus 806 NSS_CMSEnvelopedData_Decode_AfterData(NSSCMSEnvelopedData *envd); 807 808 /* 809 * NSS_CMSEnvelopedData_Decode_AfterEnd - finish decoding this envelopedData 810 */ 811 extern SECStatus 812 NSS_CMSEnvelopedData_Decode_AfterEnd(NSSCMSEnvelopedData *envd); 813 814 /************************************************************************ 815 * cmsrecinfo.c - CMS recipientInfo methods 816 ************************************************************************/ 817 818 extern PRBool 819 NSS_CMSRecipient_IsSupported(CERTCertificate *cert); 820 821 /* 822 * NSS_CMSRecipientInfo_Create - create a recipientinfo 823 * 824 * we currently do not create KeyAgreement recipientinfos with multiple recipientEncryptedKeys 825 * the certificate is supposed to have been verified by the caller 826 */ 827 extern NSSCMSRecipientInfo * 828 NSS_CMSRecipientInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert); 829 830 extern NSSCMSRecipientInfo * 831 NSS_CMSRecipientInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg, 832 SECItem *subjKeyID, 833 SECKEYPublicKey *pubKey); 834 835 extern NSSCMSRecipientInfo * 836 NSS_CMSRecipientInfo_CreateWithSubjKeyIDFromCert(NSSCMSMessage *cmsg, 837 CERTCertificate *cert); 838 839 /* 840 * NSS_CMSRecipientInfo_CreateNew - create a blank recipientinfo for 841 * applications which want to encode their own CMS structures and 842 * key exchange types. 843 */ 844 extern NSSCMSRecipientInfo * 845 NSS_CMSRecipientInfo_CreateNew(void *pwfn_arg); 846 847 /* 848 * NSS_CMSRecipientInfo_CreateFromDER - create a recipientinfo from partially 849 * decoded DER data for applications which want to encode their own CMS 850 * structures and key exchange types. 851 */ 852 extern NSSCMSRecipientInfo * 853 NSS_CMSRecipientInfo_CreateFromDER(SECItem *input, void *pwfn_arg); 854 855 extern void 856 NSS_CMSRecipientInfo_Destroy(NSSCMSRecipientInfo *ri); 857 858 /* 859 * NSS_CMSRecipientInfo_GetCertAndKey - retrieve the cert and key from the 860 * recipientInfo struct. If retcert or retkey are NULL, the cert or 861 * key (respectively) would not be returned). This function is a no-op if both 862 * retcert and retkey are NULL. Caller inherits ownership of the cert and key 863 * he requested (and is responsible to free them). 864 */ 865 SECStatus NSS_CMSRecipientInfo_GetCertAndKey(NSSCMSRecipientInfo *ri, 866 CERTCertificate **retcert, 867 SECKEYPrivateKey **retkey); 868 869 extern int 870 NSS_CMSRecipientInfo_GetVersion(NSSCMSRecipientInfo *ri); 871 872 extern SECItem * 873 NSS_CMSRecipientInfo_GetEncryptedKey(NSSCMSRecipientInfo *ri, int subIndex); 874 875 /* 876 * NSS_CMSRecipientInfo_Encode - encode an NSS_CMSRecipientInfo as ASN.1 877 */ 878 SECStatus NSS_CMSRecipientInfo_Encode(PLArenaPool *poolp, 879 const NSSCMSRecipientInfo *src, 880 SECItem *returned); 881 882 extern SECOidTag 883 NSS_CMSRecipientInfo_GetKeyEncryptionAlgorithmTag(NSSCMSRecipientInfo *ri); 884 885 extern SECStatus 886 NSS_CMSRecipientInfo_WrapBulkKey(NSSCMSRecipientInfo *ri, PK11SymKey *bulkkey, 887 SECOidTag bulkalgtag); 888 889 extern PK11SymKey * 890 NSS_CMSRecipientInfo_UnwrapBulkKey(NSSCMSRecipientInfo *ri, int subIndex, 891 CERTCertificate *cert, SECKEYPrivateKey *privkey, 892 SECOidTag bulkalgtag); 893 894 /************************************************************************ 895 * cmsencdata.c - CMS encryptedData methods 896 ************************************************************************/ 897 /* 898 * NSS_CMSEncryptedData_Create - create an empty encryptedData object. 899 * 900 * "algorithm" specifies the bulk encryption algorithm to use. 901 * "keysize" is the key size. 902 * 903 * An error results in a return value of NULL and an error set. 904 * (Retrieve specific errors via PORT_GetError()/XP_GetError().) 905 */ 906 extern NSSCMSEncryptedData * 907 NSS_CMSEncryptedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize); 908 909 /* 910 * NSS_CMSEncryptedData_Destroy - destroy an encryptedData object 911 */ 912 extern void 913 NSS_CMSEncryptedData_Destroy(NSSCMSEncryptedData *encd); 914 915 /* 916 * NSS_CMSEncryptedData_GetContentInfo - return pointer to encryptedData object's contentInfo 917 */ 918 extern NSSCMSContentInfo * 919 NSS_CMSEncryptedData_GetContentInfo(NSSCMSEncryptedData *encd); 920 921 /* 922 * NSS_CMSEncryptedData_Encode_BeforeStart - do all the necessary things to a EncryptedData 923 * before encoding begins. 924 * 925 * In particular: 926 * - set the correct version value. 927 * - get the encryption key 928 */ 929 extern SECStatus 930 NSS_CMSEncryptedData_Encode_BeforeStart(NSSCMSEncryptedData *encd); 931 932 /* 933 * NSS_CMSEncryptedData_Encode_BeforeData - set up encryption 934 */ 935 extern SECStatus 936 NSS_CMSEncryptedData_Encode_BeforeData(NSSCMSEncryptedData *encd); 937 938 /* 939 * NSS_CMSEncryptedData_Encode_AfterData - finalize this encryptedData for encoding 940 */ 941 extern SECStatus 942 NSS_CMSEncryptedData_Encode_AfterData(NSSCMSEncryptedData *encd); 943 944 /* 945 * NSS_CMSEncryptedData_Decode_BeforeData - find bulk key & set up decryption 946 */ 947 extern SECStatus 948 NSS_CMSEncryptedData_Decode_BeforeData(NSSCMSEncryptedData *encd); 949 950 /* 951 * NSS_CMSEncryptedData_Decode_AfterData - finish decrypting this encryptedData's content 952 */ 953 extern SECStatus 954 NSS_CMSEncryptedData_Decode_AfterData(NSSCMSEncryptedData *encd); 955 956 /* 957 * NSS_CMSEncryptedData_Decode_AfterEnd - finish decoding this encryptedData 958 */ 959 extern SECStatus 960 NSS_CMSEncryptedData_Decode_AfterEnd(NSSCMSEncryptedData *encd); 961 962 /************************************************************************ 963 * cmsdigdata.c - CMS encryptedData methods 964 ************************************************************************/ 965 /* 966 * NSS_CMSDigestedData_Create - create a digestedData object (presumably for encoding) 967 * 968 * version will be set by NSS_CMSDigestedData_Encode_BeforeStart 969 * digestAlg is passed as parameter 970 * contentInfo must be filled by the user 971 * digest will be calculated while encoding 972 */ 973 extern NSSCMSDigestedData * 974 NSS_CMSDigestedData_Create(NSSCMSMessage *cmsg, SECAlgorithmID *digestalg); 975 976 /* 977 * NSS_CMSDigestedData_Destroy - destroy a digestedData object 978 */ 979 extern void 980 NSS_CMSDigestedData_Destroy(NSSCMSDigestedData *digd); 981 982 /* 983 * NSS_CMSDigestedData_GetContentInfo - return pointer to digestedData object's contentInfo 984 */ 985 extern NSSCMSContentInfo * 986 NSS_CMSDigestedData_GetContentInfo(NSSCMSDigestedData *digd); 987 988 /* 989 * NSS_CMSDigestedData_Encode_BeforeStart - do all the necessary things to a DigestedData 990 * before encoding begins. 991 * 992 * In particular: 993 * - set the right version number. The contentInfo's content type must be set up already. 994 */ 995 extern SECStatus 996 NSS_CMSDigestedData_Encode_BeforeStart(NSSCMSDigestedData *digd); 997 998 /* 999 * NSS_CMSDigestedData_Encode_BeforeData - do all the necessary things to a DigestedData 1000 * before the encapsulated data is passed through the encoder. 1001 * 1002 * In detail: 1003 * - set up the digests if necessary 1004 */ 1005 extern SECStatus 1006 NSS_CMSDigestedData_Encode_BeforeData(NSSCMSDigestedData *digd); 1007 1008 /* 1009 * NSS_CMSDigestedData_Encode_AfterData - do all the necessary things to a DigestedData 1010 * after all the encapsulated data was passed through the encoder. 1011 * 1012 * In detail: 1013 * - finish the digests 1014 */ 1015 extern SECStatus 1016 NSS_CMSDigestedData_Encode_AfterData(NSSCMSDigestedData *digd); 1017 1018 /* 1019 * NSS_CMSDigestedData_Decode_BeforeData - do all the necessary things to a DigestedData 1020 * before the encapsulated data is passed through the encoder. 1021 * 1022 * In detail: 1023 * - set up the digests if necessary 1024 */ 1025 extern SECStatus 1026 NSS_CMSDigestedData_Decode_BeforeData(NSSCMSDigestedData *digd); 1027 1028 /* 1029 * NSS_CMSDigestedData_Decode_AfterData - do all the necessary things to a DigestedData 1030 * after all the encapsulated data was passed through the encoder. 1031 * 1032 * In detail: 1033 * - finish the digests 1034 */ 1035 extern SECStatus 1036 NSS_CMSDigestedData_Decode_AfterData(NSSCMSDigestedData *digd); 1037 1038 /* 1039 * NSS_CMSDigestedData_Decode_AfterEnd - finalize a digestedData. 1040 * 1041 * In detail: 1042 * - check the digests for equality 1043 */ 1044 extern SECStatus 1045 NSS_CMSDigestedData_Decode_AfterEnd(NSSCMSDigestedData *digd); 1046 1047 /************************************************************************ 1048 * cmsdigest.c - digestion routines 1049 ************************************************************************/ 1050 1051 /* 1052 * NSS_CMSDigestContext_StartMultiple - start digest calculation using all the 1053 * digest algorithms in "digestalgs" in parallel. 1054 */ 1055 extern NSSCMSDigestContext * 1056 NSS_CMSDigestContext_StartMultiple(SECAlgorithmID **digestalgs); 1057 1058 /* 1059 * NSS_CMSDigestContext_StartSingle - same as NSS_CMSDigestContext_StartMultiple, but 1060 * only one algorithm. 1061 */ 1062 extern NSSCMSDigestContext * 1063 NSS_CMSDigestContext_StartSingle(SECAlgorithmID *digestalg); 1064 1065 /* 1066 * NSS_CMSDigestContext_Update - feed more data into the digest machine 1067 */ 1068 extern void 1069 NSS_CMSDigestContext_Update(NSSCMSDigestContext *cmsdigcx, const unsigned char *data, int len); 1070 1071 /* 1072 * NSS_CMSDigestContext_Cancel - cancel digesting operation 1073 */ 1074 extern void 1075 NSS_CMSDigestContext_Cancel(NSSCMSDigestContext *cmsdigcx); 1076 1077 /* 1078 * NSS_CMSDigestContext_FinishMultiple - finish the digests and put them 1079 * into an array of SECItems (allocated on poolp) 1080 */ 1081 extern SECStatus 1082 NSS_CMSDigestContext_FinishMultiple(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp, 1083 SECItem ***digestsp); 1084 1085 /* 1086 * NSS_CMSDigestContext_FinishSingle - same as NSS_CMSDigestContext_FinishMultiple, 1087 * but for one digest. 1088 */ 1089 extern SECStatus 1090 NSS_CMSDigestContext_FinishSingle(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp, 1091 SECItem *digest); 1092 1093 /************************************************************************ 1094 * 1095 ************************************************************************/ 1096 1097 /* shortcuts for basic use */ 1098 1099 /* 1100 * NSS_CMSDEREncode - DER Encode a CMS message, with input being 1101 * the plaintext message and derOut being the output, 1102 * stored in arena's pool. 1103 */ 1104 extern SECStatus 1105 NSS_CMSDEREncode(NSSCMSMessage *cmsg, SECItem *input, SECItem *derOut, 1106 PLArenaPool *arena); 1107 1108 /************************************************************************ 1109 * 1110 ************************************************************************/ 1111 1112 /* 1113 * define new S/MIME content type entries 1114 * 1115 * S/MIME uses the builtin PKCS7 oid types for encoding and decoding the 1116 * various S/MIME content. Some applications have their own content type 1117 * which is different from the standard content type defined by S/MIME. 1118 * 1119 * This function allows you to register new content types. There are basically 1120 * Two different types of content, Wrappping content, and Data. 1121 * 1122 * For data types, All the functions below can be zero or NULL excext 1123 * type and is isData, which should be your oid tag and PR_FALSE respectively 1124 * 1125 * For wrapping types, everything must be provided, or you will get encoder 1126 * failures. 1127 * 1128 * If NSS doesn't already define the OID that you need, you can register 1129 * your own with SECOID_AddEntry. 1130 * 1131 * Once you have defined your new content type, you can pass your new content 1132 * type to NSS_CMSContentInfo_SetContent(). 1133 * 1134 * If you are using a wrapping type you can pass your own data structure in 1135 * the ptr field, but it must contain and embedded NSSCMSGenericWrappingData 1136 * structure as the first element. The size you pass to 1137 * NSS_CMSType_RegisterContentType is the total size of your self defined 1138 * data structure. NSS_CMSContentInfo_GetContent will return that data 1139 * structure from the content info. Your ASN1Template will be evaluated 1140 * against that data structure. 1141 */ 1142 SECStatus NSS_CMSType_RegisterContentType(SECOidTag type, 1143 SEC_ASN1Template *asn1Template, size_t size, 1144 NSSCMSGenericWrapperDataDestroy destroy, 1145 NSSCMSGenericWrapperDataCallback decode_before, 1146 NSSCMSGenericWrapperDataCallback decode_after, 1147 NSSCMSGenericWrapperDataCallback decode_end, 1148 NSSCMSGenericWrapperDataCallback encode_start, 1149 NSSCMSGenericWrapperDataCallback encode_before, 1150 NSSCMSGenericWrapperDataCallback encode_after, 1151 PRBool isData); 1152 1153 /************************************************************************/ 1154 SEC_END_PROTOS 1155 1156 #endif /* _CMS_H_ */