OSX/libsecurity_cms/lib/CMSEncoder.h

   1 /*
   2  * Copyright (c) 2006-2012 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*
  25  * CMSEncoder.h - encode, sign, and/or encrypt messages in the Cryptographic
  26  *                                Message Syntax (CMS), per RFC 3852.
  27  *
  28  * A CMS message can be signed, encrypted, or both. A message can be signed by
  29  * an arbitrary number of signers; in this module, signers are expressed as
  30  * SecIdentityRefs. A message can be encrypted for an arbitrary number of
  31  * recipients; recipients are expressed here as SecCertificateRefs.
  32  *
  33  * In CMS terminology, this module performs encryption using the EnvelopedData
  34  * ContentType and signing using the SignedData ContentType.
  35  *
  36  * If the message is both signed and encrypted, it uses "nested ContentInfos"
  37  * in CMS terminology; in this implementation, signed & encrypted messages
  38  * are implemented as an EnvelopedData containing a SignedData.
  39  */
  40
  41 #ifndef _CMS_ENCODER_H_
  42 #define _CMS_ENCODER_H_
  43
  44 #include <CoreFoundation/CoreFoundation.h>
  45 #include <Security/cssmtype.h>
  46 #include <stdint.h>
  47 #include <Availability.h>
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 CF_ASSUME_NONNULL_BEGIN
  54
  55 /*
  56  * Opaque reference to a CMS encoder object.
  57  * This is a CF object, with standard CF semantics; dispose of it
  58  * with CFRelease().
  59  */
  60 typedef struct CF_BRIDGED_TYPE(id) _CMSEncoder *CMSEncoderRef;
  61
  62 CFTypeID CMSEncoderGetTypeID(void)
  63     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
  64
  65 /*
  66  * Create a CMSEncoder. Result must eventually be freed via CFRelease().
  67  */
  68 OSStatus CMSEncoderCreate(
  69         CMSEncoderRef * __nonnull CF_RETURNS_RETAINED cmsEncoderOut)    /* RETURNED */
  70         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
  71
  72 extern const CFStringRef kCMSEncoderDigestAlgorithmSHA1;
  73 extern const CFStringRef kCMSEncoderDigestAlgorithmSHA256;
  74
  75 OSStatus CMSEncoderSetSignerAlgorithm(
  76         CMSEncoderRef           cmsEncoder,
  77         CFStringRef             digestAlgorithm)
  78     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_NA);
  79
  80 /*
  81  * Specify signers of the CMS message; implies that the message will be signed.
  82  *
  83  * -- Caller can pass in one signer, as a SecIdentityRef, or an array of
  84  *    signers, as a CFArray of SecIdentityRefs.
  85  * -- Can be called multiple times.
  86  * -- If the message is not to be signed, don't call this.
  87  * -- If this is called, it must be called before the first call to
  88  *    CMSEncoderUpdateContent().
  89  */
  90 OSStatus CMSEncoderAddSigners(
  91         CMSEncoderRef           cmsEncoder,
  92         CFTypeRef                       signerOrArray)
  93     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
  94
  95 /*
  96  * Obtain an array of signers as specified in CMSEncoderSetSigners().
  97  * Returns a NULL signers array if CMSEncoderSetSigners() has not been called.
  98  * Caller must CFRelease the result.
  99  */
 100 OSStatus CMSEncoderCopySigners(
 101         CMSEncoderRef           cmsEncoder,
 102         CFArrayRef * __nonnull CF_RETURNS_RETAINED signersOut)          /* RETURNED */
 103     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 104
 105 /*
 106  * Specify recipients of the message. Implies that the message will
 107  * be encrypted.
 108  *
 109  * -- Caller can pass in one recipient, as a SecCertificateRef, or an
 110  *    array of recipients, as a CFArray of SecCertificateRefs.
 111  * -- Can be called multiple times.
 112  * -- If the message is not to be encrypted, don't call this.
 113  * -- If this is called, it must be called before the first call to
 114  *    CMSEncoderUpdateContent().
 115  */
 116 OSStatus CMSEncoderAddRecipients(
 117         CMSEncoderRef           cmsEncoder,
 118         CFTypeRef                       recipientOrArray)
 119     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 120
 121 /*
 122  * Obtain an array of recipients as specified in CMSEncoderSetRecipients().
 123  * Returns a NULL recipients array if CMSEncoderSetRecipients() has not been
 124  * called.
 125  * Caller must CFRelease the result.
 126  */
 127 OSStatus CMSEncoderCopyRecipients(
 128         CMSEncoderRef           cmsEncoder,
 129         CFArrayRef * __nonnull CF_RETURNS_RETAINED recipientsOut)       /* RETURNED */
 130     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 131
 132 /*
 133  * A signed message optionally includes the data to be signed. If the message
 134  * is *not* to include the data to be signed, call this function with a value
 135  * of TRUE for detachedContent. The default, if this function is not called,
 136  * is detachedContent=FALSE, i.e., the message contains the data to be signed.
 137  *
 138  * -- Encrypted messages can not use detached content. (This restriction
 139  *    also applies to messages that are both signed and encrypted.)
 140  * -- If this is called, it must be called before the first call to
 141  *    CMSEncoderUpdateContent().
 142  */
 143 OSStatus CMSEncoderSetHasDetachedContent(
 144         CMSEncoderRef           cmsEncoder,
 145         Boolean                 detachedContent)
 146     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 147
 148 /*
 149  * Obtain a Boolean indicating whether the current message will have detached
 150  * content.
 151  * Returns the value specified in CMSEncoderHasDetachedContent() if that
 152  * function has been called; else returns the default FALSE.
 153  */
 154 OSStatus CMSEncoderGetHasDetachedContent(
 155         CMSEncoderRef           cmsEncoder,
 156         Boolean                 *detachedContentOut)    /* RETURNED */
 157     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 158
 159 /*
 160  * Optionally specify an eContentType OID for the inner EncapsulatedData for
 161  * a signed message. The default eContentType, used if this function is not
 162  * called, is id-data (which is the normal eContentType for applications such
 163  * as SMIME).
 164  *
 165  * If this is called, it must be called before the first call to
 166  * CMSEncoderUpdateContent().
 167  *
 168  * NOTE: This function is deprecated in Mac OS X 10.7 and later;
 169  * please use CMSEncoderSetEncapsulatedContentTypeOID() instead.
 170  */
 171 OSStatus CMSEncoderSetEncapsulatedContentType(
 172         CMSEncoderRef           cmsEncoder,
 173         const CSSM_OID  *eContentType)
 174     API_DEPRECATED_WITH_REPLACEMENT("CMSEncoderSetEncapsulatedContentTypeOID", macos(10.5, 10.7)) API_UNAVAILABLE(ios);
 175
 176 /*
 177  * Optionally specify an eContentType OID for the inner EncapsulatedData for
 178  * a signed message. The default eContentTypeOID, used if this function is not
 179  * called, is id-data (which is the normal eContentType for applications such
 180  * as SMIME).
 181  *
 182  * The eContentTypeOID parameter may be specified as a CF string, e.g.:
 183  * CFSTR("1.2.840.113549.1.7.1")
 184  *
 185  * If this is called, it must be called before the first call to
 186  * CMSEncoderUpdateContent().
 187  */
 188 OSStatus CMSEncoderSetEncapsulatedContentTypeOID(
 189         CMSEncoderRef           cmsEncoder,
 190         CFTypeRef                       eContentTypeOID)
 191     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 192
 193 /*
 194  * Obtain the eContentType OID specified in CMSEncoderSetEncapsulatedContentType().
 195  * If CMSEncoderSetEncapsulatedContentType() has not been called this returns a
 196  * NULL pointer.
 197  * The returned OID's data is in the same format as the data provided to
 198  * CMSEncoderSetEncapsulatedContentType;, i.e., it's the encoded content of
 199  * the OID, not including the tag and length bytes.
 200  */
 201 OSStatus CMSEncoderCopyEncapsulatedContentType(
 202         CMSEncoderRef           cmsEncoder,
 203         CFDataRef * __nonnull CF_RETURNS_RETAINED eContentTypeOut)              /* RETURNED */
 204     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 205
 206 /*
 207  * Signed CMS messages can contain arbitrary sets of certificates beyond those
 208  * indicating the identity of the signer(s). This function provides a means of
 209  * adding these other certs. For normal signed messages it is not necessary to
 210  * call this; the signer cert(s) and the intermediate certs needed to verify the
 211  * signer(s) will be included in the message implicitly.
 212  *
 213  * -- Caller can pass in one cert, as a SecCertificateRef, or an array of certs,
 214  *    as a CFArray of SecCertificateRefs.
 215  * -- If this is called, it must be called before the first call to
 216  *    CMSEncoderUpdateContent().
 217  * -- There is a "special case" use of CMS messages which involves neither
 218  *    signing nor encryption, but does include certificates. This is commonly
 219  *    used to transport "bags" of certificates. When constructing such a
 220  *    message, all an application needs to do is to create a CMSEncoderRef,
 221  *    call CMSEncoderAddSupportingCerts() one or more times, and then call
 222  *    CMSEncoderCopyEncodedContent() to get the resulting cert bag. No 'content'
 223  *    need be specified. (This is in fact the primary intended use for
 224  *    this function.)
 225  */
 226 OSStatus CMSEncoderAddSupportingCerts(
 227         CMSEncoderRef           cmsEncoder,
 228         CFTypeRef                       certOrArray)
 229     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 230
 231 /*
 232  * Obtain the SecCertificates provided in CMSEncoderAddSupportingCerts().
 233  * If CMSEncoderAddSupportingCerts() has not been called this will return a
 234  * NULL value for *certs.
 235  * Caller must CFRelease the result.
 236  */
 237 OSStatus CMSEncoderCopySupportingCerts(
 238         CMSEncoderRef           cmsEncoder,
 239         CFArrayRef * __nonnull CF_RETURNS_RETAINED certsOut)                    /* RETURNED */
 240     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 241
 242 /*
 243  * Standard signed attributes, optionally specified in
 244  * CMSEncoderAddSignedAttributes().
 245  */
 246 typedef CF_OPTIONS(uint32_t, CMSSignedAttributes) {
 247         kCMSAttrNone                                            = 0x0000,
 248     /*
 249      * S/MIME Capabilities - identifies supported signature, encryption, and
 250      * digest algorithms.
 251      */
 252     kCMSAttrSmimeCapabilities                   = 0x0001,
 253     /*
 254      * Indicates that a cert is the preferred cert for S/MIME encryption.
 255      */
 256     kCMSAttrSmimeEncryptionKeyPrefs             = 0x0002,
 257     /*
 258      * Same as kCMSSmimeEncryptionKeyPrefs, using an attribute OID preferred
 259      * by Microsoft.
 260      */
 261     kCMSAttrSmimeMSEncryptionKeyPrefs   = 0x0004,
 262     /*
 263      * Include the signing time.
 264      */
 265     kCMSAttrSigningTime                                 = 0x0008,
 266     /*
 267      * Include the Apple Codesigning Hash Agility.
 268      */
 269     kCMSAttrAppleCodesigningHashAgility = 0x0010,
 270     kCMSAttrAppleCodesigningHashAgilityV2 = 0x0020,
 271     /*
 272      * Include the expiration time.
 273      */
 274     kCMSAttrAppleExpirationTime         = 0x0040,
 275 };
 276
 277 /*
 278  * Optionally specify signed attributes. Only meaningful when creating a
 279  * signed message. If this is called, it must be called before
 280  * CMSEncoderUpdateContent().
 281  */
 282 OSStatus CMSEncoderAddSignedAttributes(
 283         CMSEncoderRef           cmsEncoder,
 284         CMSSignedAttributes     signedAttributes)
 285     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 286
 287 /*
 288  * Specification of what certificates to include in a signed message.
 289  */
 290 typedef CF_ENUM(uint32_t, CMSCertificateChainMode) {
 291         kCMSCertificateNone = 0,                /* don't include any certificates */
 292         kCMSCertificateSignerOnly,              /* only include signer certificate(s) */
 293         kCMSCertificateChain,                   /* signer certificate chain up to but not
 294                                                                          *   including root certiticate */
 295         kCMSCertificateChainWithRoot    /* signer certificate chain including root */
 296 };
 297
 298 /*
 299  * Optionally specify which certificates, if any, to include in a
 300  * signed CMS message. The default, if this is not called, is
 301  * kCMSCertificateChain, in which case the signer cert plus all CA
 302  * certs needed to verify the signer cert, except for the root
 303  * cert, are included.
 304  * If this is called, it must be called before
 305  * CMSEncoderUpdateContent().
 306  */
 307 OSStatus CMSEncoderSetCertificateChainMode(
 308         CMSEncoderRef                   cmsEncoder,
 309         CMSCertificateChainMode chainMode)
 310     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 311
 312 /*
 313  * Obtain indication of which signer certs are to be included
 314  * in a signed CMS message.
 315  */
 316 OSStatus CMSEncoderGetCertificateChainMode(
 317         CMSEncoderRef                   cmsEncoder,
 318         CMSCertificateChainMode *chainModeOut)
 319     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 320
 321 /*
 322  * Feed content bytes into the encoder.
 323  * Can be called multiple times.
 324  * No 'setter' routines can be called after this function has been called.
 325  */
 326 OSStatus CMSEncoderUpdateContent(
 327         CMSEncoderRef           cmsEncoder,
 328         const void                      *content,
 329         size_t                          contentLen)
 330     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 331
 332 /*
 333  * Finish encoding the message and obtain the encoded result.
 334  * Caller must CFRelease the result.
 335  */
 336 OSStatus CMSEncoderCopyEncodedContent(
 337         CMSEncoderRef           cmsEncoder,
 338         CFDataRef * __nonnull CF_RETURNS_RETAINED encodedContentOut)    /* RETURNED */
 339     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 340
 341 /*
 342  * High-level, one-shot encoder function.
 343  *
 344  * Inputs (all except for content optional, though at least one
 345  *         of {signers, recipients} must be non-NULL)
 346  * ------------------------------------------------------------
 347  * signers          : signer identities. Either a SecIdentityRef, or a
 348  *                    CFArray of them.
 349  * recipients       : recipient certificates. Either a SecCertificateRef,
 350  *                    or a CFArray of them.
 351  * eContentType     : contentType for inner EncapsulatedData.
 352  * detachedContent  : when true, do not include the signed data in the message.
 353  * signedAttributes : Specifies which standard signed attributes are to be
 354  *                    included in the message.
 355  * content          : raw content to be signed and/or encrypted.
 356  *
 357  * Output
 358  * ------
 359  * encodedContent   : the result of the encoding.
 360  *
 361  * NOTE: This function is deprecated in Mac OS X 10.7 and later;
 362  * please use CMSEncodeContent() instead.
 363  */
 364 OSStatus CMSEncode(
 365         CFTypeRef __nullable        signers,
 366         CFTypeRef __nullable        recipients,
 367         const CSSM_OID * __nullable eContentType,
 368         Boolean                     detachedContent,
 369         CMSSignedAttributes         signedAttributes,
 370         const void *                content,
 371         size_t                      contentLen,
 372         CFDataRef * __nonnull CF_RETURNS_RETAINED encodedContentOut)    /* RETURNED */
 373     API_DEPRECATED_WITH_REPLACEMENT("CMSEncodeContent", macos(10.5, 10.7)) API_UNAVAILABLE(ios);
 374
 375
 376 /*
 377  * High-level, one-shot encoder function.
 378  *
 379  * Inputs (all except for content optional, though at least one
 380  *         of {signers, recipients} must be non-NULL)
 381  * ------------------------------------------------------------
 382  * signers          : signer identities. Either a SecIdentityRef, or a
 383  *                    CFArray of them.
 384  * recipients       : recipient certificates. Either a SecCertificateRef,
 385  *                    or a CFArray of them.
 386  * eContentTypeOID  : contentType OID for inner EncapsulatedData, e.g.:
 387  *                    CFSTR("1.2.840.113549.1.7.1")
 388  * detachedContent  : when true, do not include the signed data in the message.
 389  * signedAttributes : Specifies which standard signed attributes are to be
 390  *                    included in the message.
 391  * content          : raw content to be signed and/or encrypted.
 392  *
 393  * Output
 394  * ------
 395  * encodedContent   : the result of the encoding.
 396  */
 397 OSStatus CMSEncodeContent(
 398         CFTypeRef __nullable    signers,
 399         CFTypeRef __nullable    recipients,
 400         CFTypeRef __nullable    eContentTypeOID,
 401         Boolean                 detachedContent,
 402         CMSSignedAttributes     signedAttributes,
 403         const void              *content,
 404         size_t                  contentLen,
 405         CFDataRef * __nullable CF_RETURNS_RETAINED encodedContentOut)   /* RETURNED */
 406     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 407
 408 OSStatus CMSEncoderCopySignerTimestamp(
 409         CMSEncoderRef           cmsEncoder,
 410         size_t                          signerIndex,        /* usually 0 */
 411         CFAbsoluteTime      *timestamp)                 /* RETURNED */
 412     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);
 413
 414 OSStatus CMSEncoderCopySignerTimestampWithPolicy(
 415     CMSEncoderRef           cmsEncoder,
 416     CFTypeRef __nullable    timeStampPolicy,
 417     size_t                  signerIndex,        /* usually 0 */
 418     CFAbsoluteTime          *timestamp)                 /* RETURNED */
 419     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
 420
 421 CF_ASSUME_NONNULL_END
 422
 423 #ifdef __cplusplus
 424 }
 425 #endif
 426
 427 #endif  /* _CMS_ENCODER_H_ */
 428