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