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