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 "cmstpriv.h"
  43
  44 /************************************************************************/
  45 SEC_BEGIN_PROTOS
  46
  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 CSSM_DATAs 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 CSSM_CC_HANDLE
  99 SecCmsUtilGetHashObjByAlgID(SECAlgorithmID *algid);
 100
 101 /*
 102  * XXX I would *really* like to not have to do this, but the current
 103  * signing interface gives me little choice.
 104  */
 105 extern SECOidTag
 106 SecCmsUtilMakeSignatureAlgorithm(SECOidTag hashalg, SECOidTag encalg);
 107
 108 extern const SecAsn1Template *
 109 SecCmsUtilGetTemplateByTypeTag(SECOidTag type);
 110
 111 extern size_t
 112 SecCmsUtilGetSizeByTypeTag(SECOidTag type);
 113
 114 extern SecCmsContentInfoRef
 115 SecCmsContentGetContentInfo(void *msg, SECOidTag type);
 116
 117 /************************************************************************
 118 * cmsmessage.c - CMS message methods
 119 ************************************************************************/
 120
 121 /*!
 122 @function
 123  @abstract Set up a CMS message object for encoding or decoding.
 124  @discussion used internally.
 125  @param cmsg Pointer to a SecCmsMessage object
 126  @param pwfn callback function for getting token password for enveloped
 127  data content with a password recipient.
 128  @param pwfn_arg first argument passed to pwfn when it is called.
 129  @param encrypt_key_cb callback function for getting bulk key for encryptedData content.
 130  @param encrypt_key_cb_arg first argument passed to encrypt_key_cb when it is
 131  called.
 132  @param detached_digestalgs digest algorithms in detached_digests
 133  @param detached_digests digests from detached content (one for every element
 134                                                         in detached_digestalgs).
 135  */
 136 extern void
 137 SecCmsMessageSetEncodingParams(SecCmsMessageRef cmsg,
 138                                PK11PasswordFunc pwfn, void *pwfn_arg,
 139                                SecCmsGetDecryptKeyCallback encrypt_key_cb, void *encrypt_key_cb_arg,
 140                                SECAlgorithmID **detached_digestalgs, CSSM_DATA_PTR *detached_digests);
 141
 142 extern void
 143 SecCmsMessageSetTSACallback(SecCmsMessageRef cmsg, SecCmsTSACallback tsaCallback);
 144
 145 extern void
 146 SecCmsMessageSetTSAContext(SecCmsMessageRef cmsg, const void *tsaContext);   //CFTypeRef
 147
 148 /************************************************************************
 149  * cmscinfo.c - CMS contentInfo methods
 150  ************************************************************************/
 151
 152 /*!
 153     Destroy a CMS contentInfo and all of its sub-pieces.
 154     @param cinfo The contentInfo object to destroy.
 155  */
 156 extern void
 157 SecCmsContentInfoDestroy(SecCmsContentInfoRef cinfo);
 158
 159 /*
 160  * SecCmsContentInfoSetContent - set cinfo's content type & content to CMS object
 161  */
 162 extern OSStatus
 163 SecCmsContentInfoSetContent(SecCmsMessageRef cmsg, SecCmsContentInfoRef cinfo, SECOidTag type, void *ptr);
 164
 165
 166 /************************************************************************
 167  * cmssigdata.c - CMS signedData methods
 168  ************************************************************************/
 169
 170 extern OSStatus
 171 SecCmsSignedDataSetDigestValue(SecCmsSignedDataRef sigd,
 172                                 SECOidTag digestalgtag,
 173                                 CSSM_DATA_PTR digestdata);
 174
 175 extern OSStatus
 176 SecCmsSignedDataAddDigest(SecArenaPoolRef pool,
 177                                 SecCmsSignedDataRef sigd,
 178                                 SECOidTag digestalgtag,
 179                                 CSSM_DATA_PTR digest);
 180
 181 extern CSSM_DATA_PTR
 182 SecCmsSignedDataGetDigestByAlgTag(SecCmsSignedDataRef sigd, SECOidTag algtag);
 183
 184 extern CSSM_DATA_PTR
 185 SecCmsSignedDataGetDigestValue(SecCmsSignedDataRef sigd, SECOidTag digestalgtag);
 186
 187 /*
 188  * SecCmsSignedDataEncodeBeforeStart - do all the necessary things to a SignedData
 189  *     before start of encoding.
 190  *
 191  * In detail:
 192  *  - find out about the right value to put into sigd->version
 193  *  - come up with a list of digestAlgorithms (which should be the union of the algorithms
 194  *         in the signerinfos).
 195  *         If we happen to have a pre-set list of algorithms (and digest values!), we
 196  *         check if we have all the signerinfos' algorithms. If not, this is an error.
 197  */
 198 extern OSStatus
 199 SecCmsSignedDataEncodeBeforeStart(SecCmsSignedDataRef sigd);
 200
 201 extern OSStatus
 202 SecCmsSignedDataEncodeBeforeData(SecCmsSignedDataRef sigd);
 203
 204 /*
 205  * SecCmsSignedDataEncodeAfterData - do all the necessary things to a SignedData
 206  *     after all the encapsulated data was passed through the encoder.
 207  *
 208  * In detail:
 209  *  - create the signatures in all the SignerInfos
 210  *
 211  * Please note that nothing is done to the Certificates and CRLs in the message - this
 212  * is entirely the responsibility of our callers.
 213  */
 214 extern OSStatus
 215 SecCmsSignedDataEncodeAfterData(SecCmsSignedDataRef sigd);
 216
 217 extern OSStatus
 218 SecCmsSignedDataDecodeBeforeData(SecCmsSignedDataRef sigd);
 219
 220 /*
 221  * SecCmsSignedDataDecodeAfterData - do all the necessary things to a SignedData
 222  *     after all the encapsulated data was passed through the decoder.
 223  */
 224 extern OSStatus
 225 SecCmsSignedDataDecodeAfterData(SecCmsSignedDataRef sigd);
 226
 227 /*
 228  * SecCmsSignedDataDecodeAfterEnd - do all the necessary things to a SignedData
 229  *     after all decoding is finished.
 230  */
 231 extern OSStatus
 232 SecCmsSignedDataDecodeAfterEnd(SecCmsSignedDataRef sigd);
 233
 234 /*
 235  * Get SecCmsSignedDataRawCerts - obtain raw certs as a NULL_terminated array
 236  * of pointers.
 237  */
 238 extern OSStatus SecCmsSignedDataRawCerts(SecCmsSignedDataRef sigd,
 239     CSSM_DATA_PTR **rawCerts);
 240
 241 /************************************************************************
 242  * cmssiginfo.c - CMS signerInfo methods
 243  ************************************************************************/
 244
 245 /*
 246  * SecCmsSignerInfoSign - sign something
 247  *
 248  */
 249 extern OSStatus
 250 SecCmsSignerInfoSign(SecCmsSignerInfoRef signerinfo, CSSM_DATA_PTR digest, CSSM_DATA_PTR 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, CSSM_DATA_PTR digest, CSSM_DATA_PTR 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  * Determine whether Microsoft ECDSA compatibility mode is enabled.
 288  * See comments in SecCmsSignerInfo.h for details.
 289  * Implemented in siginfoUtils.cpp for access to C++ Dictionary class.
 290  */
 291 extern bool
 292 SecCmsMsEcdsaCompatMode();
 293
 294
 295 /************************************************************************
 296  * cmsenvdata.c - CMS envelopedData methods
 297  ************************************************************************/
 298
 299 /*
 300  * SecCmsEnvelopedDataEncodeBeforeStart - prepare this envelopedData for encoding
 301  *
 302  * at this point, we need
 303  * - recipientinfos set up with recipient's certificates
 304  * - a content encryption algorithm (if none, 3DES will be used)
 305  *
 306  * this function will generate a random content encryption key (aka bulk key),
 307  * initialize the recipientinfos with certificate identification and wrap the bulk key
 308  * using the proper algorithm for every certificiate.
 309  * it will finally set the bulk algorithm and key so that the encode step can find it.
 310  */
 311 extern OSStatus
 312 SecCmsEnvelopedDataEncodeBeforeStart(SecCmsEnvelopedDataRef envd);
 313
 314 /*
 315  * SecCmsEnvelopedDataEncodeBeforeData - set up encryption
 316  */
 317 extern OSStatus
 318 SecCmsEnvelopedDataEncodeBeforeData(SecCmsEnvelopedDataRef envd);
 319
 320 /*
 321  * SecCmsEnvelopedDataEncodeAfterData - finalize this envelopedData for encoding
 322  */
 323 extern OSStatus
 324 SecCmsEnvelopedDataEncodeAfterData(SecCmsEnvelopedDataRef envd);
 325
 326 /*
 327  * SecCmsEnvelopedDataDecodeBeforeData - find our recipientinfo,
 328  * derive bulk key & set up our contentinfo
 329  */
 330 extern OSStatus
 331 SecCmsEnvelopedDataDecodeBeforeData(SecCmsEnvelopedDataRef envd);
 332
 333 /*
 334  * SecCmsEnvelopedDataDecodeAfterData - finish decrypting this envelopedData's content
 335  */
 336 extern OSStatus
 337 SecCmsEnvelopedDataDecodeAfterData(SecCmsEnvelopedDataRef envd);
 338
 339 /*
 340  * SecCmsEnvelopedDataDecodeAfterEnd - finish decoding this envelopedData
 341  */
 342 extern OSStatus
 343 SecCmsEnvelopedDataDecodeAfterEnd(SecCmsEnvelopedDataRef envd);
 344
 345
 346 /************************************************************************
 347  * cmsrecinfo.c - CMS recipientInfo methods
 348  ************************************************************************/
 349
 350 extern int
 351 SecCmsRecipientInfoGetVersion(SecCmsRecipientInfoRef ri);
 352
 353 extern CSSM_DATA_PTR
 354 SecCmsRecipientInfoGetEncryptedKey(SecCmsRecipientInfoRef ri, int subIndex);
 355
 356
 357 extern SECOidTag
 358 SecCmsRecipientInfoGetKeyEncryptionAlgorithmTag(SecCmsRecipientInfoRef ri);
 359
 360 extern OSStatus
 361 SecCmsRecipientInfoWrapBulkKey(SecCmsRecipientInfoRef ri, SecSymmetricKeyRef bulkkey, SECOidTag bulkalgtag);
 362
 363 extern SecSymmetricKeyRef
 364 SecCmsRecipientInfoUnwrapBulkKey(SecCmsRecipientInfoRef ri, int subIndex,
 365                 SecCertificateRef cert, SecPrivateKeyRef privkey, SECOidTag bulkalgtag);
 366
 367
 368 /************************************************************************
 369  * cmsencdata.c - CMS encryptedData methods
 370  ************************************************************************/
 371
 372 /*
 373  * SecCmsEncryptedDataEncodeBeforeStart - do all the necessary things to a EncryptedData
 374  *     before encoding begins.
 375  *
 376  * In particular:
 377  *  - set the correct version value.
 378  *  - get the encryption key
 379  */
 380 extern OSStatus
 381 SecCmsEncryptedDataEncodeBeforeStart(SecCmsEncryptedDataRef encd);
 382
 383 /*
 384  * SecCmsEncryptedDataEncodeBeforeData - set up encryption
 385  */
 386 extern OSStatus
 387 SecCmsEncryptedDataEncodeBeforeData(SecCmsEncryptedDataRef encd);
 388
 389 /*
 390  * SecCmsEncryptedDataEncodeAfterData - finalize this encryptedData for encoding
 391  */
 392 extern OSStatus
 393 SecCmsEncryptedDataEncodeAfterData(SecCmsEncryptedDataRef encd);
 394
 395 /*
 396  * SecCmsEncryptedDataDecodeBeforeData - find bulk key & set up decryption
 397  */
 398 extern OSStatus
 399 SecCmsEncryptedDataDecodeBeforeData(SecCmsEncryptedDataRef encd);
 400
 401 /*
 402  * SecCmsEncryptedDataDecodeAfterData - finish decrypting this encryptedData's content
 403  */
 404 extern OSStatus
 405 SecCmsEncryptedDataDecodeAfterData(SecCmsEncryptedDataRef encd);
 406
 407 /*
 408  * SecCmsEncryptedDataDecodeAfterEnd - finish decoding this encryptedData
 409  */
 410 extern OSStatus
 411 SecCmsEncryptedDataDecodeAfterEnd(SecCmsEncryptedDataRef encd);
 412
 413
 414 /************************************************************************
 415  * cmsdigdata.c - CMS encryptedData methods
 416  ************************************************************************/
 417
 418 /*
 419  * SecCmsDigestedDataEncodeBeforeStart - do all the necessary things to a DigestedData
 420  *     before encoding begins.
 421  *
 422  * In particular:
 423  *  - set the right version number. The contentInfo's content type must be set up already.
 424  */
 425 extern OSStatus
 426 SecCmsDigestedDataEncodeBeforeStart(SecCmsDigestedDataRef digd);
 427
 428 /*
 429  * SecCmsDigestedDataEncodeBeforeData - do all the necessary things to a DigestedData
 430  *     before the encapsulated data is passed through the encoder.
 431  *
 432  * In detail:
 433  *  - set up the digests if necessary
 434  */
 435 extern OSStatus
 436 SecCmsDigestedDataEncodeBeforeData(SecCmsDigestedDataRef digd);
 437
 438 /*
 439  * SecCmsDigestedDataEncodeAfterData - do all the necessary things to a DigestedData
 440  *     after all the encapsulated data was passed through the encoder.
 441  *
 442  * In detail:
 443  *  - finish the digests
 444  */
 445 extern OSStatus
 446 SecCmsDigestedDataEncodeAfterData(SecCmsDigestedDataRef digd);
 447
 448 /*
 449  * SecCmsDigestedDataDecodeBeforeData - do all the necessary things to a DigestedData
 450  *     before the encapsulated data is passed through the encoder.
 451  *
 452  * In detail:
 453  *  - set up the digests if necessary
 454  */
 455 extern OSStatus
 456 SecCmsDigestedDataDecodeBeforeData(SecCmsDigestedDataRef digd);
 457
 458 /*
 459  * SecCmsDigestedDataDecodeAfterData - do all the necessary things to a DigestedData
 460  *     after all the encapsulated data was passed through the encoder.
 461  *
 462  * In detail:
 463  *  - finish the digests
 464  */
 465 extern OSStatus
 466 SecCmsDigestedDataDecodeAfterData(SecCmsDigestedDataRef digd);
 467
 468 /*
 469  * SecCmsDigestedDataDecodeAfterEnd - finalize a digestedData.
 470  *
 471  * In detail:
 472  *  - check the digests for equality
 473  */
 474 extern OSStatus
 475 SecCmsDigestedDataDecodeAfterEnd(SecCmsDigestedDataRef digd);
 476
 477
 478 /************************************************************************
 479  * cmsdigest.c - CMS encryptedData methods
 480  ************************************************************************/
 481
 482 /*
 483  * SecCmsDigestContextStartSingle - same as SecCmsDigestContextStartMultiple, but
 484  *  only one algorithm.
 485  */
 486 extern SecCmsDigestContextRef
 487 SecCmsDigestContextStartSingle(SECAlgorithmID *digestalg);
 488
 489 /*
 490  * SecCmsDigestContextFinishSingle - same as SecCmsDigestContextFinishMultiple,
 491  *  but for one digest.
 492  */
 493 extern OSStatus
 494 SecCmsDigestContextFinishSingle(SecCmsDigestContextRef cmsdigcx, SecArenaPoolRef arena,
 495                             CSSM_DATA_PTR digest);
 496
 497
 498 /************************************************************************/
 499 SEC_END_PROTOS
 500
 501 #endif /* _CMSPRIV_H_ */