OSX/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 void *
  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  * SecCmsSignerInfoVerifyWithPolicy - verify the signature of a single SignerInfo
 271  *  use the designated policy for timeStamp signer verification
 272  * Just verifies the signature. The assumption is that verification of the certificate
 273  * is done already.
 274  */
 275 extern OSStatus
 276 SecCmsSignerInfoVerifyWithPolicy(SecCmsSignerInfoRef signerinfo,CFTypeRef timeStampPolicy, CSSM_DATA_PTR digest, CSSM_DATA_PTR contentType);
 277
 278 /*
 279  * SecCmsSignerInfoAddAuthAttr - add an attribute to the
 280  * authenticated (i.e. signed) attributes of "signerinfo".
 281  */
 282 extern OSStatus
 283 SecCmsSignerInfoAddAuthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
 284
 285 /*
 286  * SecCmsSignerInfoAddUnauthAttr - add an attribute to the
 287  * unauthenticated attributes of "signerinfo".
 288  */
 289 extern OSStatus
 290 SecCmsSignerInfoAddUnauthAttr(SecCmsSignerInfoRef signerinfo, SecCmsAttribute *attr);
 291
 292 extern int
 293 SecCmsSignerInfoGetVersion(SecCmsSignerInfoRef signerinfo);
 294
 295 /*
 296  * Determine whether Microsoft ECDSA compatibility mode is enabled.
 297  * See comments in SecCmsSignerInfo.h for details.
 298  * Implemented in siginfoUtils.cpp for access to C++ Dictionary class.
 299  */
 300 extern bool
 301 SecCmsMsEcdsaCompatMode(void);
 302
 303
 304 /************************************************************************
 305  * cmsenvdata.c - CMS envelopedData methods
 306  ************************************************************************/
 307
 308 /*
 309  * SecCmsEnvelopedDataEncodeBeforeStart - prepare this envelopedData for encoding
 310  *
 311  * at this point, we need
 312  * - recipientinfos set up with recipient's certificates
 313  * - a content encryption algorithm (if none, 3DES will be used)
 314  *
 315  * this function will generate a random content encryption key (aka bulk key),
 316  * initialize the recipientinfos with certificate identification and wrap the bulk key
 317  * using the proper algorithm for every certificiate.
 318  * it will finally set the bulk algorithm and key so that the encode step can find it.
 319  */
 320 extern OSStatus
 321 SecCmsEnvelopedDataEncodeBeforeStart(SecCmsEnvelopedDataRef envd);
 322
 323 /*
 324  * SecCmsEnvelopedDataEncodeBeforeData - set up encryption
 325  */
 326 extern OSStatus
 327 SecCmsEnvelopedDataEncodeBeforeData(SecCmsEnvelopedDataRef envd);
 328
 329 /*
 330  * SecCmsEnvelopedDataEncodeAfterData - finalize this envelopedData for encoding
 331  */
 332 extern OSStatus
 333 SecCmsEnvelopedDataEncodeAfterData(SecCmsEnvelopedDataRef envd);
 334
 335 /*
 336  * SecCmsEnvelopedDataDecodeBeforeData - find our recipientinfo,
 337  * derive bulk key & set up our contentinfo
 338  */
 339 extern OSStatus
 340 SecCmsEnvelopedDataDecodeBeforeData(SecCmsEnvelopedDataRef envd);
 341
 342 /*
 343  * SecCmsEnvelopedDataDecodeAfterData - finish decrypting this envelopedData's content
 344  */
 345 extern OSStatus
 346 SecCmsEnvelopedDataDecodeAfterData(SecCmsEnvelopedDataRef envd);
 347
 348 /*
 349  * SecCmsEnvelopedDataDecodeAfterEnd - finish decoding this envelopedData
 350  */
 351 extern OSStatus
 352 SecCmsEnvelopedDataDecodeAfterEnd(SecCmsEnvelopedDataRef envd);
 353
 354
 355 /************************************************************************
 356  * cmsrecinfo.c - CMS recipientInfo methods
 357  ************************************************************************/
 358
 359 extern int
 360 SecCmsRecipientInfoGetVersion(SecCmsRecipientInfoRef ri);
 361
 362 extern CSSM_DATA_PTR
 363 SecCmsRecipientInfoGetEncryptedKey(SecCmsRecipientInfoRef ri, int subIndex);
 364
 365
 366 extern SECOidTag
 367 SecCmsRecipientInfoGetKeyEncryptionAlgorithmTag(SecCmsRecipientInfoRef ri);
 368
 369 extern OSStatus
 370 SecCmsRecipientInfoWrapBulkKey(SecCmsRecipientInfoRef ri, SecSymmetricKeyRef bulkkey, SECOidTag bulkalgtag);
 371
 372 extern SecSymmetricKeyRef
 373 SecCmsRecipientInfoUnwrapBulkKey(SecCmsRecipientInfoRef ri, int subIndex,
 374                 SecCertificateRef cert, SecPrivateKeyRef privkey, SECOidTag bulkalgtag);
 375
 376
 377 /************************************************************************
 378  * cmsencdata.c - CMS encryptedData methods
 379  ************************************************************************/
 380
 381 /*
 382  * SecCmsEncryptedDataEncodeBeforeStart - do all the necessary things to a EncryptedData
 383  *     before encoding begins.
 384  *
 385  * In particular:
 386  *  - set the correct version value.
 387  *  - get the encryption key
 388  */
 389 extern OSStatus
 390 SecCmsEncryptedDataEncodeBeforeStart(SecCmsEncryptedDataRef encd);
 391
 392 /*
 393  * SecCmsEncryptedDataEncodeBeforeData - set up encryption
 394  */
 395 extern OSStatus
 396 SecCmsEncryptedDataEncodeBeforeData(SecCmsEncryptedDataRef encd);
 397
 398 /*
 399  * SecCmsEncryptedDataEncodeAfterData - finalize this encryptedData for encoding
 400  */
 401 extern OSStatus
 402 SecCmsEncryptedDataEncodeAfterData(SecCmsEncryptedDataRef encd);
 403
 404 /*
 405  * SecCmsEncryptedDataDecodeBeforeData - find bulk key & set up decryption
 406  */
 407 extern OSStatus
 408 SecCmsEncryptedDataDecodeBeforeData(SecCmsEncryptedDataRef encd);
 409
 410 /*
 411  * SecCmsEncryptedDataDecodeAfterData - finish decrypting this encryptedData's content
 412  */
 413 extern OSStatus
 414 SecCmsEncryptedDataDecodeAfterData(SecCmsEncryptedDataRef encd);
 415
 416 /*
 417  * SecCmsEncryptedDataDecodeAfterEnd - finish decoding this encryptedData
 418  */
 419 extern OSStatus
 420 SecCmsEncryptedDataDecodeAfterEnd(SecCmsEncryptedDataRef encd);
 421
 422
 423 /************************************************************************
 424  * cmsdigdata.c - CMS encryptedData methods
 425  ************************************************************************/
 426
 427 /*
 428  * SecCmsDigestedDataEncodeBeforeStart - do all the necessary things to a DigestedData
 429  *     before encoding begins.
 430  *
 431  * In particular:
 432  *  - set the right version number. The contentInfo's content type must be set up already.
 433  */
 434 extern OSStatus
 435 SecCmsDigestedDataEncodeBeforeStart(SecCmsDigestedDataRef digd);
 436
 437 /*
 438  * SecCmsDigestedDataEncodeBeforeData - do all the necessary things to a DigestedData
 439  *     before the encapsulated data is passed through the encoder.
 440  *
 441  * In detail:
 442  *  - set up the digests if necessary
 443  */
 444 extern OSStatus
 445 SecCmsDigestedDataEncodeBeforeData(SecCmsDigestedDataRef digd);
 446
 447 /*
 448  * SecCmsDigestedDataEncodeAfterData - do all the necessary things to a DigestedData
 449  *     after all the encapsulated data was passed through the encoder.
 450  *
 451  * In detail:
 452  *  - finish the digests
 453  */
 454 extern OSStatus
 455 SecCmsDigestedDataEncodeAfterData(SecCmsDigestedDataRef digd);
 456
 457 /*
 458  * SecCmsDigestedDataDecodeBeforeData - do all the necessary things to a DigestedData
 459  *     before the encapsulated data is passed through the encoder.
 460  *
 461  * In detail:
 462  *  - set up the digests if necessary
 463  */
 464 extern OSStatus
 465 SecCmsDigestedDataDecodeBeforeData(SecCmsDigestedDataRef digd);
 466
 467 /*
 468  * SecCmsDigestedDataDecodeAfterData - do all the necessary things to a DigestedData
 469  *     after all the encapsulated data was passed through the encoder.
 470  *
 471  * In detail:
 472  *  - finish the digests
 473  */
 474 extern OSStatus
 475 SecCmsDigestedDataDecodeAfterData(SecCmsDigestedDataRef digd);
 476
 477 /*
 478  * SecCmsDigestedDataDecodeAfterEnd - finalize a digestedData.
 479  *
 480  * In detail:
 481  *  - check the digests for equality
 482  */
 483 extern OSStatus
 484 SecCmsDigestedDataDecodeAfterEnd(SecCmsDigestedDataRef digd);
 485
 486
 487 /************************************************************************
 488  * cmsdigest.c - CMS encryptedData methods
 489  ************************************************************************/
 490
 491 /*
 492  * SecCmsDigestContextStartSingle - same as SecCmsDigestContextStartMultiple, but
 493  *  only one algorithm.
 494  */
 495 extern SecCmsDigestContextRef
 496 SecCmsDigestContextStartSingle(SECAlgorithmID *digestalg);
 497
 498 /*
 499  * SecCmsDigestContextFinishSingle - same as SecCmsDigestContextFinishMultiple,
 500  *  but for one digest.
 501  */
 502 extern OSStatus
 503 SecCmsDigestContextFinishSingle(SecCmsDigestContextRef cmsdigcx, SecArenaPoolRef arena,
 504                             CSSM_DATA_PTR digest);
 505
 506
 507 /************************************************************************/
 508 SEC_END_PROTOS
 509
 510 #endif /* _CMSPRIV_H_ */