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 extern void *SecCmsUtilGetHashObjByAlgID(SECAlgorithmID *algid);
  99
 100 /*
 101  * XXX I would *really* like to not have to do this, but the current
 102  * signing interface gives me little choice.
 103  */
 104 extern SECOidTag
 105 SecCmsUtilMakeSignatureAlgorithm(SECOidTag hashalg, SECOidTag encalg);
 106
 107 extern const SecAsn1Template *
 108 SecCmsUtilGetTemplateByTypeTag(SECOidTag type);
 109
 110 extern size_t
 111 SecCmsUtilGetSizeByTypeTag(SECOidTag type);
 112
 113 extern SecCmsContentInfoRef
 114 SecCmsContentGetContentInfo(void *msg, SECOidTag type);
 115
 116 /************************************************************************
 117 * cmsmessage.c - CMS message methods
 118 ************************************************************************/
 119
 120 /*!
 121 @function
 122  @abstract Set up a CMS message object for encoding or decoding.
 123  @discussion used internally.
 124  @param cmsg Pointer to a SecCmsMessage object
 125  @param pwfn callback function for getting token password for enveloped
 126  data content with a password recipient.
 127  @param pwfn_arg first argument passed to pwfn when it is called.
 128  @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
 129  @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
 130  called.
 131  */
 132 extern void
 133 SecCmsMessageSetEncodingParams(SecCmsMessageRef cmsg,
 134                                PK11PasswordFunc pwfn, void *pwfn_arg,
 135                                SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg);
 136
 137 /************************************************************************
 138  * cmscinfo.c - CMS contentInfo methods
 139  ************************************************************************/
 140
 141 /*!
 142     Destroy a CMS contentInfo and all of its sub-pieces.
 143     @param cinfo The contentInfo object to destroy.
 144  */
 145 extern void
 146 SecCmsContentInfoDestroy(SecCmsContentInfoRef cinfo);
 147
 148 /*
 149  * SecCmsContentInfoSetContent - set cinfo's content type & content to CMS object
 150  */
 151 extern OSStatus
 152 SecCmsContentInfoSetContent(SecCmsContentInfoRef cinfo, SECOidTag type, void *ptr);
 153
 154
 155 /************************************************************************
 156  * cmssigdata.c - CMS signedData methods
 157  ************************************************************************/
 158
 159 extern OSStatus
 160 SecCmsSignedDataSetDigestValue(SecCmsSignedDataRef sigd,
 161                                 SECOidTag digestalgtag,
 162                                 SecAsn1Item * digestdata);
 163
 164 extern OSStatus
 165 SecCmsSignedDataAddDigest(PRArenaPool *poolp,
 166                                 SecCmsSignedDataRef sigd,
 167                                 SECOidTag digestalgtag,
 168                                 SecAsn1Item * digest);
 169
 170 extern SecAsn1Item *
 171 SecCmsSignedDataGetDigestByAlgTag(SecCmsSignedDataRef sigd, SECOidTag algtag);
 172
 173 extern SecAsn1Item *
 174 SecCmsSignedDataGetDigestValue(SecCmsSignedDataRef sigd, SECOidTag digestalgtag);
 175
 176 /*!
 177     @function
 178  */
 179 extern OSStatus
 180 SecCmsSignedDataAddSignerInfo(SecCmsSignedDataRef sigd,
 181                                 SecCmsSignerInfoRef signerinfo);
 182
 183 /*!
 184         @function
 185  */
 186 extern OSStatus
 187 SecCmsSignedDataSetDigests(SecCmsSignedDataRef sigd,
 188                                 SECAlgorithmID **digestalgs,
 189                                 SecAsn1Item * *digests);
 190
 191 /*
 192  * SecCmsSignedDataEncodeBeforeStart - do all the necessary things to a SignedData
 193  *     before start of encoding.
 194  *
 195  * In detail:
 196  *  - find out about the right value to put into sigd->version
 197  *  - come up with a list of digestAlgorithms (which should be the union of the algorithms
 198  *         in the signerinfos).
 199  *         If we happen to have a pre-set list of algorithms (and digest values!), we
 200  *         check if we have all the signerinfos' algorithms. If not, this is an error.
 201  */
 202 extern OSStatus
 203 SecCmsSignedDataEncodeBeforeStart(SecCmsSignedDataRef sigd);
 204
 205 extern OSStatus
 206 SecCmsSignedDataEncodeBeforeData(SecCmsSignedDataRef sigd);
 207
 208 /*
 209  * SecCmsSignedDataEncodeAfterData - do all the necessary things to a SignedData
 210  *     after all the encapsulated data was passed through the encoder.
 211  *
 212  * In detail:
 213  *  - create the signatures in all the SignerInfos
 214  *
 215  * Please note that nothing is done to the Certificates and CRLs in the message - this
 216  * is entirely the responsibility of our callers.
 217  */
 218 extern OSStatus
 219 SecCmsSignedDataEncodeAfterData(SecCmsSignedDataRef sigd);
 220
 221 extern OSStatus
 222 SecCmsSignedDataDecodeBeforeData(SecCmsSignedDataRef sigd);
 223
 224 /*
 225  * SecCmsSignedDataDecodeAfterData - do all the necessary things to a SignedData
 226  *     after all the encapsulated data was passed through the decoder.
 227  */
 228 extern OSStatus
 229 SecCmsSignedDataDecodeAfterData(SecCmsSignedDataRef sigd);
 230
 231 /*
 232  * SecCmsSignedDataDecodeAfterEnd - do all the necessary things to a SignedData
 233  *     after all decoding is finished.
 234  */
 235 extern OSStatus
 236 SecCmsSignedDataDecodeAfterEnd(SecCmsSignedDataRef sigd);
 237
 238
 239 /************************************************************************
 240  * cmssiginfo.c - CMS signerInfo methods
 241  ************************************************************************/
 242
 243 /*
 244  * SecCmsSignerInfoSign - sign something
 245  *
 246  */
 247 extern OSStatus
 248 SecCmsSignerInfoSign(SecCmsSignerInfoRef signerinfo, SecAsn1Item * digest, SecAsn1Item * contentType);
 249
 250 /*
 251  * If trustRef is NULL the cert chain is verified and the VerificationStatus is set accordingly.
 252  * Otherwise a SecTrust object is returned for the caller to evaluate using SecTrustEvaluate().
 253  */
 254 extern OSStatus
 255 SecCmsSignerInfoVerifyCertificate(SecCmsSignerInfoRef signerinfo, SecKeychainRef keychainOrArray,
 256                                   CFTypeRef policies, SecTrustRef *trustRef);
 257
 258 /*
 259  * SecCmsSignerInfoVerify - verify the signature of a single SignerInfo
 260  *
 261  * Just verifies the signature. The assumption is that verification of the certificate
 262  * is done already.
 263  */
 264 extern OSStatus
 265 SecCmsSignerInfoVerify(SecCmsSignerInfoRef signerinfo, SecAsn1Item * digest, SecAsn1Item * contentType);
 266
 267 /*
 268  * SecCmsSignerInfoAddAuthAttr - add an attribute to the
 269  * authenticated (i.e. signed) attributes of "signerinfo".
 270  */
 271 extern OSStatus
 272 SecCmsSignerInfoAddAuthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
 273
 274 /*
 275  * SecCmsSignerInfoAddUnauthAttr - add an attribute to the
 276  * unauthenticated attributes of "signerinfo".
 277  */
 278 extern OSStatus
 279 SecCmsSignerInfoAddUnauthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
 280
 281 extern int
 282 SecCmsSignerInfoGetVersion(SecCmsSignerInfoRef signerinfo);
 283
 284 /*!
 285     @function
 286     @abstract Destroy a SignerInfo data structure.
 287  */
 288 extern void
 289 SecCmsSignerInfoDestroy(SecCmsSignerInfoRef si);
 290
 291
 292 /************************************************************************
 293  * cmsenvdata.c - CMS envelopedData methods
 294  ************************************************************************/
 295
 296 /*!
 297     @function
 298     @abstract Add a recipientinfo to the enveloped data msg.
 299     @discussion Rip must be created on the same pool as edp - this is not enforced, though.
 300  */
 301 extern OSStatus
 302 SecCmsEnvelopedDataAddRecipient(SecCmsEnvelopedDataRef edp, SecCmsRecipientInfoRef rip);
 303
 304 /*
 305  * SecCmsEnvelopedDataEncodeBeforeStart - prepare this envelopedData for encoding
 306  *
 307  * at this point, we need
 308  * - recipientinfos set up with recipient's certificates
 309  * - a content encryption algorithm (if none, 3DES will be used)
 310  *
 311  * this function will generate a random content encryption key (aka bulk key),
 312  * initialize the recipientinfos with certificate identification and wrap the bulk key
 313  * using the proper algorithm for every certificiate.
 314  * it will finally set the bulk algorithm and key so that the encode step can find it.
 315  */
 316 extern OSStatus
 317 SecCmsEnvelopedDataEncodeBeforeStart(SecCmsEnvelopedDataRef envd);
 318
 319 /*
 320  * SecCmsEnvelopedDataEncodeBeforeData - set up encryption
 321  */
 322 extern OSStatus
 323 SecCmsEnvelopedDataEncodeBeforeData(SecCmsEnvelopedDataRef envd);
 324
 325 /*
 326  * SecCmsEnvelopedDataEncodeAfterData - finalize this envelopedData for encoding
 327  */
 328 extern OSStatus
 329 SecCmsEnvelopedDataEncodeAfterData(SecCmsEnvelopedDataRef envd);
 330
 331 /*
 332  * SecCmsEnvelopedDataDecodeBeforeData - find our recipientinfo,
 333  * derive bulk key & set up our contentinfo
 334  */
 335 extern OSStatus
 336 SecCmsEnvelopedDataDecodeBeforeData(SecCmsEnvelopedDataRef envd);
 337
 338 /*
 339  * SecCmsEnvelopedDataDecodeAfterData - finish decrypting this envelopedData's content
 340  */
 341 extern OSStatus
 342 SecCmsEnvelopedDataDecodeAfterData(SecCmsEnvelopedDataRef envd);
 343
 344 /*
 345  * SecCmsEnvelopedDataDecodeAfterEnd - finish decoding this envelopedData
 346  */
 347 extern OSStatus
 348 SecCmsEnvelopedDataDecodeAfterEnd(SecCmsEnvelopedDataRef envd);
 349
 350
 351 /************************************************************************
 352  * cmsrecinfo.c - CMS recipientInfo methods
 353  ************************************************************************/
 354
 355 extern int
 356 SecCmsRecipientInfoGetVersion(SecCmsRecipientInfoRef ri);
 357
 358 extern SecAsn1Item *
 359 SecCmsRecipientInfoGetEncryptedKey(SecCmsRecipientInfoRef ri, int subIndex);
 360
 361
 362 extern SECOidTag
 363 SecCmsRecipientInfoGetKeyEncryptionAlgorithmTag(SecCmsRecipientInfoRef ri);
 364
 365 extern OSStatus
 366 SecCmsRecipientInfoWrapBulkKey(SecCmsRecipientInfoRef ri, SecSymmetricKeyRef bulkkey, SECOidTag bulkalgtag);
 367
 368 extern SecSymmetricKeyRef
 369 SecCmsRecipientInfoUnwrapBulkKey(SecCmsRecipientInfoRef ri, int subIndex,
 370                 SecCertificateRef cert, SecPrivateKeyRef privkey, SECOidTag bulkalgtag);
 371
 372 /*!
 373     @function
 374  */
 375 extern void
 376 SecCmsRecipientInfoDestroy(SecCmsRecipientInfoRef ri);
 377
 378
 379 /************************************************************************
 380  * cmsencdata.c - CMS encryptedData methods
 381  ************************************************************************/
 382
 383 /*
 384  * SecCmsEncryptedDataEncodeBeforeStart - do all the necessary things to a EncryptedData
 385  *     before encoding begins.
 386  *
 387  * In particular:
 388  *  - set the correct version value.
 389  *  - get the encryption key
 390  */
 391 extern OSStatus
 392 SecCmsEncryptedDataEncodeBeforeStart(SecCmsEncryptedDataRef encd);
 393
 394 /*
 395  * SecCmsEncryptedDataEncodeBeforeData - set up encryption
 396  */
 397 extern OSStatus
 398 SecCmsEncryptedDataEncodeBeforeData(SecCmsEncryptedDataRef encd);
 399
 400 /*
 401  * SecCmsEncryptedDataEncodeAfterData - finalize this encryptedData for encoding
 402  */
 403 extern OSStatus
 404 SecCmsEncryptedDataEncodeAfterData(SecCmsEncryptedDataRef encd);
 405
 406 /*
 407  * SecCmsEncryptedDataDecodeBeforeData - find bulk key & set up decryption
 408  */
 409 extern OSStatus
 410 SecCmsEncryptedDataDecodeBeforeData(SecCmsEncryptedDataRef encd);
 411
 412 /*
 413  * SecCmsEncryptedDataDecodeAfterData - finish decrypting this encryptedData's content
 414  */
 415 extern OSStatus
 416 SecCmsEncryptedDataDecodeAfterData(SecCmsEncryptedDataRef encd);
 417
 418 /*
 419  * SecCmsEncryptedDataDecodeAfterEnd - finish decoding this encryptedData
 420  */
 421 extern OSStatus
 422 SecCmsEncryptedDataDecodeAfterEnd(SecCmsEncryptedDataRef encd);
 423
 424
 425 /************************************************************************
 426  * cmsdigdata.c - CMS encryptedData methods
 427  ************************************************************************/
 428
 429 /*
 430  * SecCmsDigestedDataEncodeBeforeStart - do all the necessary things to a DigestedData
 431  *     before encoding begins.
 432  *
 433  * In particular:
 434  *  - set the right version number. The contentInfo's content type must be set up already.
 435  */
 436 extern OSStatus
 437 SecCmsDigestedDataEncodeBeforeStart(SecCmsDigestedDataRef digd);
 438
 439 /*
 440  * SecCmsDigestedDataEncodeBeforeData - do all the necessary things to a DigestedData
 441  *     before the encapsulated data is passed through the encoder.
 442  *
 443  * In detail:
 444  *  - set up the digests if necessary
 445  */
 446 extern OSStatus
 447 SecCmsDigestedDataEncodeBeforeData(SecCmsDigestedDataRef digd);
 448
 449 /*
 450  * SecCmsDigestedDataEncodeAfterData - do all the necessary things to a DigestedData
 451  *     after all the encapsulated data was passed through the encoder.
 452  *
 453  * In detail:
 454  *  - finish the digests
 455  */
 456 extern OSStatus
 457 SecCmsDigestedDataEncodeAfterData(SecCmsDigestedDataRef digd);
 458
 459 /*
 460  * SecCmsDigestedDataDecodeBeforeData - do all the necessary things to a DigestedData
 461  *     before the encapsulated data is passed through the encoder.
 462  *
 463  * In detail:
 464  *  - set up the digests if necessary
 465  */
 466 extern OSStatus
 467 SecCmsDigestedDataDecodeBeforeData(SecCmsDigestedDataRef digd);
 468
 469 /*
 470  * SecCmsDigestedDataDecodeAfterData - do all the necessary things to a DigestedData
 471  *     after all the encapsulated data was passed through the encoder.
 472  *
 473  * In detail:
 474  *  - finish the digests
 475  */
 476 extern OSStatus
 477 SecCmsDigestedDataDecodeAfterData(SecCmsDigestedDataRef digd);
 478
 479 /*
 480  * SecCmsDigestedDataDecodeAfterEnd - finalize a digestedData.
 481  *
 482  * In detail:
 483  *  - check the digests for equality
 484  */
 485 extern OSStatus
 486 SecCmsDigestedDataDecodeAfterEnd(SecCmsDigestedDataRef digd);
 487
 488
 489 /************************************************************************
 490  * cmsdigest.c - CMS encryptedData methods
 491  ************************************************************************/
 492
 493 /*
 494  * SecCmsDigestContextStartSingle - same as SecCmsDigestContextStartMultiple, but
 495  *  only one algorithm.
 496  */
 497 extern SecCmsDigestContextRef
 498 SecCmsDigestContextStartSingle(SECAlgorithmID *digestalg);
 499
 500 /*
 501  * SecCmsDigestContextFinishSingle - same as SecCmsDigestContextFinishMultiple,
 502  *  but for one digest.
 503  */
 504 extern OSStatus
 505 SecCmsDigestContextFinishSingle(SecCmsDigestContextRef cmsdigcx,
 506                             SecAsn1Item * digest);
 507
 508 /*!
 509     @function
 510     @abstract Finish the digests being calculated and put them into to parralel
 511                 arrays of SecAsn1Items.
 512     @param cmsdigcx A DigestContext object.
 513     @param digestalgsp will contain a to an array of digest algorithms on
 514                 success.
 515     @param digestsp A EncryptedData object to set as the content of the cinfo
 516                 object.
 517     @result A result code. See "SecCmsBase.h" for possible results.
 518     @discussion This function requires a DigestContext object which can be made
 519                 by calling SecCmsDigestContextStartSingle or
 520                 SecCmsDigestContextStartMultiple.  The returned arrays remain valid
 521                 until SecCmsDigestContextDestroy is called.
 522     @availability 10.4 and later
 523  */
 524 extern OSStatus
 525 SecCmsDigestContextFinishMultiple(SecCmsDigestContextRef cmsdigcx,
 526                             SECAlgorithmID ***digestalgsp,
 527                             SecAsn1Item * **digestsp);
 528
 529
 530 /************************************************************************/
 531 SEC_END_PROTOS
 532
 533 #endif /* _CMSPRIV_H_ */