libsecurity_smime/lib/cmspriv.h

   1 /*
   2  * The contents of this file are subject to the Mozilla Public
   3  * License Version 1.1 (the "License"); you may not use this file
   4  * except in compliance with the License. You may obtain a copy of
   5  * the License at http://www.mozilla.org/MPL/
   6  *
   7  * Software distributed under the License is distributed on an "AS
   8  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
   9  * implied. See the License for the specific language governing
  10  * rights and limitations under the License.
  11  *
  12  * The Original Code is the Netscape security libraries.
  13  *
  14  * The Initial Developer of the Original Code is Netscape
  15  * Communications Corporation.  Portions created by Netscape are
  16  * Copyright (C) 1994-2000 Netscape Communications Corporation.  All
  17  * Rights Reserved.
  18  *
  19  * Contributor(s):
  20  *
  21  * Alternatively, the contents of this file may be used under the
  22  * terms of the GNU General Public License Version 2 or later (the
  23  * "GPL"), in which case the provisions of the GPL are applicable
  24  * instead of those above.  If you wish to allow use of your
  25  * version of this file only under the terms of the GPL and not to
  26  * allow others to use your version of this file under the MPL,
  27  * indicate your decision by deleting the provisions above and
  28  * replace them with the notice and other provisions required by
  29  * the GPL.  If you do not delete the provisions above, a recipient
  30  * may use your version of this file under either the MPL or the
  31  * GPL.
  32  */
  33
  34 /*
  35  * Interfaces of the CMS implementation.
  36  */
  37
  38 #ifndef _CMSPRIV_H_
  39 #define _CMSPRIV_H_
  40
  41 #include <Security/SecTrust.h>
  42 #include <security_asn1/seccomon.h> // SEC_BEGIN_PROTOS
  43 #include "cmstpriv.h"
  44
  45 /************************************************************************/
  46 SEC_BEGIN_PROTOS
  47
  48 /************************************************************************
  49  * cmsutil.c - CMS misc utility functions
  50  ************************************************************************/
  51
  52
  53 /*
  54  * SecCmsArraySortByDER - sort array of objects by objects' DER encoding
  55  *
  56  * make sure that the order of the objects guarantees valid DER (which must be
  57  * in lexigraphically ascending order for a SET OF); if reordering is necessary it
  58  * will be done in place (in objs).
  59  */
  60 extern OSStatus
  61 SecCmsArraySortByDER(void **objs, const SecAsn1Template *objtemplate, void **objs2);
  62
  63 /*
  64  * SecCmsUtilDERCompare - for use with SecCmsArraySort to
  65  *  sort arrays of SecAsn1Items containing DER
  66  */
  67 extern int
  68 SecCmsUtilDERCompare(void *a, void *b);
  69
  70 /*
  71  * SecCmsAlgArrayGetIndexByAlgID - find a specific algorithm in an array of
  72  * algorithms.
  73  *
  74  * algorithmArray - array of algorithm IDs
  75  * algid - algorithmid of algorithm to pick
  76  *
  77  * Returns:
  78  *  An integer containing the index of the algorithm in the array or -1 if
  79  *  algorithm was not found.
  80  */
  81 extern int
  82 SecCmsAlgArrayGetIndexByAlgID(SECAlgorithmID **algorithmArray, SECAlgorithmID *algid);
  83
  84 /*
  85  * SecCmsAlgArrayGetIndexByAlgID - find a specific algorithm in an array of
  86  * algorithms.
  87  *
  88  * algorithmArray - array of algorithm IDs
  89  * algiddata - id of algorithm to pick
  90  *
  91  * Returns:
  92  *  An integer containing the index of the algorithm in the array or -1 if
  93  *  algorithm was not found.
  94  */
  95 extern int
  96 SecCmsAlgArrayGetIndexByAlgTag(SECAlgorithmID **algorithmArray, SECOidTag algtag);
  97
  98 #if USE_CDSA_CRYPTO
  99 extern CSSM_CC_HANDLE
 100 #else
 101 extern void *
 102 #endif
 103 SecCmsUtilGetHashObjByAlgID(SECAlgorithmID *algid);
 104
 105 /*
 106  * XXX I would *really* like to not have to do this, but the current
 107  * signing interface gives me little choice.
 108  */
 109 extern SECOidTag
 110 SecCmsUtilMakeSignatureAlgorithm(SECOidTag hashalg, SECOidTag encalg);
 111
 112 extern const SecAsn1Template *
 113 SecCmsUtilGetTemplateByTypeTag(SECOidTag type);
 114
 115 extern size_t
 116 SecCmsUtilGetSizeByTypeTag(SECOidTag type);
 117
 118 extern SecCmsContentInfoRef
 119 SecCmsContentGetContentInfo(void *msg, SECOidTag type);
 120
 121 /************************************************************************
 122 * cmsmessage.c - CMS message methods
 123 ************************************************************************/
 124
 125 /*!
 126 @function
 127  @abstract Set up a CMS message object for encoding or decoding.
 128  @discussion used internally.
 129  @param cmsg Pointer to a SecCmsMessage object
 130  @param pwfn callback function for getting token password for enveloped
 131  data content with a password recipient.
 132  @param pwfn_arg first argument passed to pwfn when it is called.
 133  @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
 134  @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
 135  called.
 136  @param detached_digestalgs digest algorithms in detached_digests
 137  @param detached_digests digests from detached content (one for every element
 138                                                         in detached_digestalgs).
 139  */
 140 extern void
 141 SecCmsMessageSetEncodingParams(SecCmsMessageRef cmsg,
 142                                PK11PasswordFunc pwfn, void *pwfn_arg,
 143                                SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg);
 144
 145 /************************************************************************
 146  * cmscinfo.c - CMS contentInfo methods
 147  ************************************************************************/
 148
 149 /*!
 150     Destroy a CMS contentInfo and all of its sub-pieces.
 151     @param cinfo The contentInfo object to destroy.
 152  */
 153 extern void
 154 SecCmsContentInfoDestroy(SecCmsContentInfoRef cinfo);
 155
 156 /*
 157  * SecCmsContentInfoSetContent - set cinfo's content type & content to CMS object
 158  */
 159 extern OSStatus
 160 SecCmsContentInfoSetContent(SecCmsContentInfoRef cinfo, SECOidTag type, void *ptr);
 161
 162
 163 /************************************************************************
 164  * cmssigdata.c - CMS signedData methods
 165  ************************************************************************/
 166
 167 extern OSStatus
 168 SecCmsSignedDataSetDigestValue(SecCmsSignedDataRef sigd,
 169                                 SECOidTag digestalgtag,
 170                                 SecAsn1Item * digestdata);
 171
 172 extern OSStatus
 173 SecCmsSignedDataAddDigest(PRArenaPool *poolp,
 174                                 SecCmsSignedDataRef sigd,
 175                                 SECOidTag digestalgtag,
 176                                 SecAsn1Item * digest);
 177
 178 extern SecAsn1Item *
 179 SecCmsSignedDataGetDigestByAlgTag(SecCmsSignedDataRef sigd, SECOidTag algtag);
 180
 181 extern SecAsn1Item *
 182 SecCmsSignedDataGetDigestValue(SecCmsSignedDataRef sigd, SECOidTag digestalgtag);
 183
 184 /*!
 185     @function
 186  */
 187 extern OSStatus
 188 SecCmsSignedDataAddSignerInfo(SecCmsSignedDataRef sigd,
 189                                 SecCmsSignerInfoRef signerinfo);
 190
 191 /*!
 192         @function
 193  */
 194 extern OSStatus
 195 SecCmsSignedDataSetDigests(SecCmsSignedDataRef sigd,
 196                                 SECAlgorithmID **digestalgs,
 197                                 SecAsn1Item * *digests);
 198
 199 /*
 200  * SecCmsSignedDataEncodeBeforeStart - do all the necessary things to a SignedData
 201  *     before start of encoding.
 202  *
 203  * In detail:
 204  *  - find out about the right value to put into sigd->version
 205  *  - come up with a list of digestAlgorithms (which should be the union of the algorithms
 206  *         in the signerinfos).
 207  *         If we happen to have a pre-set list of algorithms (and digest values!), we
 208  *         check if we have all the signerinfos' algorithms. If not, this is an error.
 209  */
 210 extern OSStatus
 211 SecCmsSignedDataEncodeBeforeStart(SecCmsSignedDataRef sigd);
 212
 213 extern OSStatus
 214 SecCmsSignedDataEncodeBeforeData(SecCmsSignedDataRef sigd);
 215
 216 /*
 217  * SecCmsSignedDataEncodeAfterData - do all the necessary things to a SignedData
 218  *     after all the encapsulated data was passed through the encoder.
 219  *
 220  * In detail:
 221  *  - create the signatures in all the SignerInfos
 222  *
 223  * Please note that nothing is done to the Certificates and CRLs in the message - this
 224  * is entirely the responsibility of our callers.
 225  */
 226 extern OSStatus
 227 SecCmsSignedDataEncodeAfterData(SecCmsSignedDataRef sigd);
 228
 229 extern OSStatus
 230 SecCmsSignedDataDecodeBeforeData(SecCmsSignedDataRef sigd);
 231
 232 /*
 233  * SecCmsSignedDataDecodeAfterData - do all the necessary things to a SignedData
 234  *     after all the encapsulated data was passed through the decoder.
 235  */
 236 extern OSStatus
 237 SecCmsSignedDataDecodeAfterData(SecCmsSignedDataRef sigd);
 238
 239 /*
 240  * SecCmsSignedDataDecodeAfterEnd - do all the necessary things to a SignedData
 241  *     after all decoding is finished.
 242  */
 243 extern OSStatus
 244 SecCmsSignedDataDecodeAfterEnd(SecCmsSignedDataRef sigd);
 245
 246
 247 /************************************************************************
 248  * cmssiginfo.c - CMS signerInfo methods
 249  ************************************************************************/
 250
 251 /*
 252  * SecCmsSignerInfoSign - sign something
 253  *
 254  */
 255 extern OSStatus
 256 SecCmsSignerInfoSign(SecCmsSignerInfoRef signerinfo, SecAsn1Item * digest, SecAsn1Item * contentType);
 257
 258 /*
 259  * If trustRef is NULL the cert chain is verified and the VerificationStatus is set accordingly.
 260  * Otherwise a SecTrust object is returned for the caller to evaluate using SecTrustEvaluate().
 261  */
 262 extern OSStatus
 263 SecCmsSignerInfoVerifyCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray,
 264                                   CFTypeRef policies, SecTrustRef *trustRef);
 265
 266 /*
 267  * SecCmsSignerInfoVerify - verify the signature of a single SignerInfo
 268  *
 269  * Just verifies the signature. The assumption is that verification of the certificate
 270  * is done already.
 271  */
 272 extern OSStatus
 273 SecCmsSignerInfoVerify(SecCmsSignerInfoRef signerinfo, SecAsn1Item * digest, SecAsn1Item * contentType);
 274
 275 /*
 276  * SecCmsSignerInfoAddAuthAttr - add an attribute to the
 277  * authenticated (i.e. signed) attributes of "signerinfo".
 278  */
 279 extern OSStatus
 280 SecCmsSignerInfoAddAuthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
 281
 282 /*
 283  * SecCmsSignerInfoAddUnauthAttr - add an attribute to the
 284  * unauthenticated attributes of "signerinfo".
 285  */
 286 extern OSStatus
 287 SecCmsSignerInfoAddUnauthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
 288
 289 extern int
 290 SecCmsSignerInfoGetVersion(SecCmsSignerInfoRef signerinfo);
 291
 292 /*!
 293     @function
 294     @abstract Destroy a SignerInfo data structure.
 295  */
 296 extern void
 297 SecCmsSignerInfoDestroy(SecCmsSignerInfoRef si);
 298
 299
 300 /************************************************************************
 301  * cmsenvdata.c - CMS envelopedData methods
 302  ************************************************************************/
 303
 304 /*!
 305     @function
 306     @abstract Add a recipientinfo to the enveloped data msg.
 307     @discussion Rip must be created on the same pool as edp - this is not enforced, though.
 308  */
 309 extern OSStatus
 310 SecCmsEnvelopedDataAddRecipient(SecCmsEnvelopedDataRef edp, SecCmsRecipientInfoRef rip);
 311
 312 /*
 313  * SecCmsEnvelopedDataEncodeBeforeStart - prepare this envelopedData for encoding
 314  *
 315  * at this point, we need
 316  * - recipientinfos set up with recipient's certificates
 317  * - a content encryption algorithm (if none, 3DES will be used)
 318  *
 319  * this function will generate a random content encryption key (aka bulk key),
 320  * initialize the recipientinfos with certificate identification and wrap the bulk key
 321  * using the proper algorithm for every certificiate.
 322  * it will finally set the bulk algorithm and key so that the encode step can find it.
 323  */
 324 extern OSStatus
 325 SecCmsEnvelopedDataEncodeBeforeStart(SecCmsEnvelopedDataRef envd);
 326
 327 /*
 328  * SecCmsEnvelopedDataEncodeBeforeData - set up encryption
 329  */
 330 extern OSStatus
 331 SecCmsEnvelopedDataEncodeBeforeData(SecCmsEnvelopedDataRef envd);
 332
 333 /*
 334  * SecCmsEnvelopedDataEncodeAfterData - finalize this envelopedData for encoding
 335  */
 336 extern OSStatus
 337 SecCmsEnvelopedDataEncodeAfterData(SecCmsEnvelopedDataRef envd);
 338
 339 /*
 340  * SecCmsEnvelopedDataDecodeBeforeData - find our recipientinfo,
 341  * derive bulk key & set up our contentinfo
 342  */
 343 extern OSStatus
 344 SecCmsEnvelopedDataDecodeBeforeData(SecCmsEnvelopedDataRef envd);
 345
 346 /*
 347  * SecCmsEnvelopedDataDecodeAfterData - finish decrypting this envelopedData's content
 348  */
 349 extern OSStatus
 350 SecCmsEnvelopedDataDecodeAfterData(SecCmsEnvelopedDataRef envd);
 351
 352 /*
 353  * SecCmsEnvelopedDataDecodeAfterEnd - finish decoding this envelopedData
 354  */
 355 extern OSStatus
 356 SecCmsEnvelopedDataDecodeAfterEnd(SecCmsEnvelopedDataRef envd);
 357
 358
 359 /************************************************************************
 360  * cmsrecinfo.c - CMS recipientInfo methods
 361  ************************************************************************/
 362
 363 extern int
 364 SecCmsRecipientInfoGetVersion(SecCmsRecipientInfoRef ri);
 365
 366 extern SecAsn1Item *
 367 SecCmsRecipientInfoGetEncryptedKey(SecCmsRecipientInfoRef ri, int subIndex);
 368
 369
 370 extern SECOidTag
 371 SecCmsRecipientInfoGetKeyEncryptionAlgorithmTag(SecCmsRecipientInfoRef ri);
 372
 373 extern OSStatus
 374 SecCmsRecipientInfoWrapBulkKey(SecCmsRecipientInfoRef ri, SecSymmetricKeyRef bulkkey, SECOidTag bulkalgtag);
 375
 376 extern SecSymmetricKeyRef
 377 SecCmsRecipientInfoUnwrapBulkKey(SecCmsRecipientInfoRef ri, int subIndex,
 378                 SecCertificateRef cert, SecPrivateKeyRef privkey, SECOidTag bulkalgtag);
 379
 380 /*!
 381     @function
 382  */
 383 extern void
 384 SecCmsRecipientInfoDestroy(SecCmsRecipientInfoRef ri);
 385
 386
 387 /************************************************************************
 388  * cmsencdata.c - CMS encryptedData methods
 389  ************************************************************************/
 390
 391 /*
 392  * SecCmsEncryptedDataEncodeBeforeStart - do all the necessary things to a EncryptedData
 393  *     before encoding begins.
 394  *
 395  * In particular:
 396  *  - set the correct version value.
 397  *  - get the encryption key
 398  */
 399 extern OSStatus
 400 SecCmsEncryptedDataEncodeBeforeStart(SecCmsEncryptedDataRef encd);
 401
 402 /*
 403  * SecCmsEncryptedDataEncodeBeforeData - set up encryption
 404  */
 405 extern OSStatus
 406 SecCmsEncryptedDataEncodeBeforeData(SecCmsEncryptedDataRef encd);
 407
 408 /*
 409  * SecCmsEncryptedDataEncodeAfterData - finalize this encryptedData for encoding
 410  */
 411 extern OSStatus
 412 SecCmsEncryptedDataEncodeAfterData(SecCmsEncryptedDataRef encd);
 413
 414 /*
 415  * SecCmsEncryptedDataDecodeBeforeData - find bulk key & set up decryption
 416  */
 417 extern OSStatus
 418 SecCmsEncryptedDataDecodeBeforeData(SecCmsEncryptedDataRef encd);
 419
 420 /*
 421  * SecCmsEncryptedDataDecodeAfterData - finish decrypting this encryptedData's content
 422  */
 423 extern OSStatus
 424 SecCmsEncryptedDataDecodeAfterData(SecCmsEncryptedDataRef encd);
 425
 426 /*
 427  * SecCmsEncryptedDataDecodeAfterEnd - finish decoding this encryptedData
 428  */
 429 extern OSStatus
 430 SecCmsEncryptedDataDecodeAfterEnd(SecCmsEncryptedDataRef encd);
 431
 432
 433 /************************************************************************
 434  * cmsdigdata.c - CMS encryptedData methods
 435  ************************************************************************/
 436
 437 /*
 438  * SecCmsDigestedDataEncodeBeforeStart - do all the necessary things to a DigestedData
 439  *     before encoding begins.
 440  *
 441  * In particular:
 442  *  - set the right version number. The contentInfo's content type must be set up already.
 443  */
 444 extern OSStatus
 445 SecCmsDigestedDataEncodeBeforeStart(SecCmsDigestedDataRef digd);
 446
 447 /*
 448  * SecCmsDigestedDataEncodeBeforeData - do all the necessary things to a DigestedData
 449  *     before the encapsulated data is passed through the encoder.
 450  *
 451  * In detail:
 452  *  - set up the digests if necessary
 453  */
 454 extern OSStatus
 455 SecCmsDigestedDataEncodeBeforeData(SecCmsDigestedDataRef digd);
 456
 457 /*
 458  * SecCmsDigestedDataEncodeAfterData - do all the necessary things to a DigestedData
 459  *     after all the encapsulated data was passed through the encoder.
 460  *
 461  * In detail:
 462  *  - finish the digests
 463  */
 464 extern OSStatus
 465 SecCmsDigestedDataEncodeAfterData(SecCmsDigestedDataRef digd);
 466
 467 /*
 468  * SecCmsDigestedDataDecodeBeforeData - do all the necessary things to a DigestedData
 469  *     before the encapsulated data is passed through the encoder.
 470  *
 471  * In detail:
 472  *  - set up the digests if necessary
 473  */
 474 extern OSStatus
 475 SecCmsDigestedDataDecodeBeforeData(SecCmsDigestedDataRef digd);
 476
 477 /*
 478  * SecCmsDigestedDataDecodeAfterData - do all the necessary things to a DigestedData
 479  *     after all the encapsulated data was passed through the encoder.
 480  *
 481  * In detail:
 482  *  - finish the digests
 483  */
 484 extern OSStatus
 485 SecCmsDigestedDataDecodeAfterData(SecCmsDigestedDataRef digd);
 486
 487 /*
 488  * SecCmsDigestedDataDecodeAfterEnd - finalize a digestedData.
 489  *
 490  * In detail:
 491  *  - check the digests for equality
 492  */
 493 extern OSStatus
 494 SecCmsDigestedDataDecodeAfterEnd(SecCmsDigestedDataRef digd);
 495
 496
 497 /************************************************************************
 498  * cmsdigest.c - CMS encryptedData methods
 499  ************************************************************************/
 500
 501 /*
 502  * SecCmsDigestContextStartSingle - same as SecCmsDigestContextStartMultiple, but
 503  *  only one algorithm.
 504  */
 505 extern SecCmsDigestContextRef
 506 SecCmsDigestContextStartSingle(SECAlgorithmID *digestalg);
 507
 508 /*
 509  * SecCmsDigestContextFinishSingle - same as SecCmsDigestContextFinishMultiple,
 510  *  but for one digest.
 511  */
 512 extern OSStatus
 513 SecCmsDigestContextFinishSingle(SecCmsDigestContextRef cmsdigcx,
 514                             SecAsn1Item * digest);
 515
 516 /*!
 517     @function
 518     @abstract Finish the digests being calculated and put them into to parralel
 519                 arrays of SecAsn1Items.
 520     @param cmsdigcx A DigestContext object.
 521     @param digestalgsp will contain a to an array of digest algorithms on
 522                 success.
 523     @param digestsp A EncryptedData object to set as the content of the cinfo
 524                 object.
 525     @result A result code. See "SecCmsBase.h" for possible results.
 526     @discussion This function requires a DigestContext object which can be made
 527                 by calling SecCmsDigestContextStartSingle or
 528                 SecCmsDigestContextStartMultiple.  The returned arrays remain valid
 529                 until SecCmsDigestContextDestroy is called.
 530     @availability 10.4 and later
 531  */
 532 extern OSStatus
 533 SecCmsDigestContextFinishMultiple(SecCmsDigestContextRef cmsdigcx,
 534                             SECAlgorithmID ***digestalgsp,
 535                             SecAsn1Item * **digestsp);
 536
 537
 538 /************************************************************************/
 539 SEC_END_PROTOS
 540
 541 #endif /* _CMSPRIV_H_ */