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