[apple/security.git] / OSX / libsecurity_cms / lib / CMSEncoder.h

/*
 * Copyright (c) 2006-2012 Apple Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

/*
 * CMSEncoder.h - encode, sign, and/or encrypt messages in the Cryptographic
 *				  Message Syntax (CMS), per RFC 3852.
 *
 * A CMS message can be signed, encrypted, or both. A message can be signed by
 * an arbitrary number of signers; in this module, signers are expressed as
 * SecIdentityRefs. A message can be encrypted for an arbitrary number of
 * recipients; recipients are expressed here as SecCertificateRefs. 
 * 
 * In CMS terminology, this module performs encryption using the EnvelopedData 
 * ContentType and signing using the SignedData ContentType.
 *
 * If the message is both signed and encrypted, it uses "nested ContentInfos" 
 * in CMS terminology; in this implementation, signed & encrypted messages 
 * are implemented as an EnvelopedData containing a SignedData. 
 */
 
#ifndef _CMS_ENCODER_H_
#define _CMS_ENCODER_H_

#include <CoreFoundation/CoreFoundation.h>
#include <Security/cssmtype.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

CF_ASSUME_NONNULL_BEGIN

/*
 * Opaque reference to a CMS encoder object. 
 * This is a CF object, with standard CF semantics; dispose of it
 * with CFRelease().
 */
typedef struct CF_BRIDGED_TYPE(id) _CMSEncoder *CMSEncoderRef;

CFTypeID CMSEncoderGetTypeID(void)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Create a CMSEncoder. Result must eventually be freed via CFRelease().
 */
OSStatus CMSEncoderCreate(
	CMSEncoderRef * __nonnull CF_RETURNS_RETAINED cmsEncoderOut)	/* RETURNED */
	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

extern const CFStringRef kCMSEncoderDigestAlgorithmSHA1;
extern const CFStringRef kCMSEncoderDigestAlgorithmSHA256;

OSStatus CMSEncoderSetSignerAlgorithm(
	CMSEncoderRef		cmsEncoder,
	CFStringRef		digestAlgorithm)
    __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_NA);

/* 
 * Specify signers of the CMS message; implies that the message will be signed. 
 *
 * -- Caller can pass in one signer, as a SecIdentityRef, or an array of 
 *    signers, as a CFArray of SecIdentityRefs. 
 * -- Can be called multiple times. 
 * -- If the message is not to be signed, don't call this.  
 * -- If this is called, it must be called before the first call to 
 *    CMSEncoderUpdateContent().
 */
OSStatus CMSEncoderAddSigners(
	CMSEncoderRef		cmsEncoder,
	CFTypeRef			signerOrArray)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain an array of signers as specified in CMSEncoderSetSigners(). 
 * Returns a NULL signers array if CMSEncoderSetSigners() has not been called.  
 * Caller must CFRelease the result. 
 */
OSStatus CMSEncoderCopySigners(
	CMSEncoderRef		cmsEncoder,
	CFArrayRef * __nonnull CF_RETURNS_RETAINED signersOut)		/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Specify recipients of the message. Implies that the message will 
 * be encrypted. 
 *
 * -- Caller can pass in one recipient, as a SecCertificateRef, or an 
 *    array of recipients, as a CFArray of SecCertificateRefs. 
 * -- Can be called multiple times. 
 * -- If the message is not to be encrypted, don't call this.  
 * -- If this is called, it must be called before the first call to 
 *    CMSEncoderUpdateContent().
 */
OSStatus CMSEncoderAddRecipients(
	CMSEncoderRef		cmsEncoder,
	CFTypeRef			recipientOrArray)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain an array of recipients as specified in CMSEncoderSetRecipients(). 
 * Returns a NULL recipients array if CMSEncoderSetRecipients() has not been 
 * called.  
 * Caller must CFRelease the result. 
 */
OSStatus CMSEncoderCopyRecipients(
	CMSEncoderRef		cmsEncoder,
	CFArrayRef * __nonnull CF_RETURNS_RETAINED recipientsOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/* 
 * A signed message optionally includes the data to be signed. If the message
 * is *not* to include the data to be signed, call this function with a value
 * of TRUE for detachedContent. The default, if this function is not called,
 * is detachedContent=FALSE, i.e., the message contains the data to be signed.
 * 
 * -- Encrypted messages can not use detached content. (This restriction 
 *    also applies to messages that are both signed and encrypted.)
 * -- If this is called, it must be called before the first call to 
 *    CMSEncoderUpdateContent().
 */ 
OSStatus CMSEncoderSetHasDetachedContent(
	CMSEncoderRef		cmsEncoder,
	Boolean			detachedContent)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/* 
 * Obtain a Boolean indicating whether the current message will have detached 
 * content.
 * Returns the value specified in CMSEncoderHasDetachedContent() if that
 * function has been called; else returns the default FALSE.
 */
OSStatus CMSEncoderGetHasDetachedContent(
	CMSEncoderRef		cmsEncoder,
	Boolean			*detachedContentOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Optionally specify an eContentType OID for the inner EncapsulatedData for
 * a signed message. The default eContentType, used if this function is not
 * called, is id-data (which is the normal eContentType for applications such
 * as SMIME).
 *
 * If this is called, it must be called before the first call to 
 * CMSEncoderUpdateContent().
 *
 * NOTE: This function is deprecated in Mac OS X 10.7 and later;
 * please use CMSEncoderSetEncapsulatedContentTypeOID() instead.
 */
OSStatus CMSEncoderSetEncapsulatedContentType(
	CMSEncoderRef		cmsEncoder,
	const CSSM_OID	*eContentType)
	/* DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Optionally specify an eContentType OID for the inner EncapsulatedData for
 * a signed message. The default eContentTypeOID, used if this function is not
 * called, is id-data (which is the normal eContentType for applications such
 * as SMIME).
 *
 * The eContentTypeOID parameter may be specified as a CF string, e.g.:
 * CFSTR("1.2.840.113549.1.7.1")
 *
 * If this is called, it must be called before the first call to 
 * CMSEncoderUpdateContent().
 */
OSStatus CMSEncoderSetEncapsulatedContentTypeOID(
	CMSEncoderRef		cmsEncoder,
	CFTypeRef			eContentTypeOID)
    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);

/*
 * Obtain the eContentType OID specified in CMSEncoderSetEncapsulatedContentType().
 * If CMSEncoderSetEncapsulatedContentType() has not been called this returns a 
 * NULL pointer.
 * The returned OID's data is in the same format as the data provided to 
 * CMSEncoderSetEncapsulatedContentType;, i.e., it's the encoded content of 
 * the OID, not including the tag and length bytes. 
 */
OSStatus CMSEncoderCopyEncapsulatedContentType(
	CMSEncoderRef		cmsEncoder,
	CFDataRef * __nonnull CF_RETURNS_RETAINED eContentTypeOut)		/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Signed CMS messages can contain arbitrary sets of certificates beyond those
 * indicating the identity of the signer(s). This function provides a means of 
 * adding these other certs. For normal signed messages it is not necessary to 
 * call this; the signer cert(s) and the intermediate certs needed to verify the
 * signer(s) will be included in the message implicitly. 
 *
 * -- Caller can pass in one cert, as a SecCertificateRef, or an array of certs,
 *    as a CFArray of SecCertificateRefs. 
 * -- If this is called, it must be called before the first call to 
 *    CMSEncoderUpdateContent().
 * -- There is a "special case" use of CMS messages which involves neither
 *    signing nor encryption, but does include certificates. This is commonly
 *    used to transport "bags" of certificates. When constructing such a 
 *    message, all an application needs to do is to create a CMSEncoderRef,
 *    call CMSEncoderAddSupportingCerts() one or more times, and then call 
 *    CMSEncoderCopyEncodedContent() to get the resulting cert bag. No 'content'
 *    need be specified. (This is in fact the primary intended use for
 *    this function.)
 */
OSStatus CMSEncoderAddSupportingCerts(
	CMSEncoderRef		cmsEncoder,
	CFTypeRef			certOrArray)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the SecCertificates provided in CMSEncoderAddSupportingCerts(). 
 * If CMSEncoderAddSupportingCerts() has not been called this will return a
 * NULL value for *certs.
 * Caller must CFRelease the result.
 */
OSStatus CMSEncoderCopySupportingCerts(
	CMSEncoderRef		cmsEncoder,
	CFArrayRef * __nonnull CF_RETURNS_RETAINED certsOut)			/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Standard signed attributes, optionally specified in 
 * CMSEncoderAddSignedAttributes().
 */
typedef CF_OPTIONS(uint32_t, CMSSignedAttributes) {
	kCMSAttrNone						= 0x0000,
    /* 
     * S/MIME Capabilities - identifies supported signature, encryption, and
     * digest algorithms.
     */
    kCMSAttrSmimeCapabilities			= 0x0001,
    /*
     * Indicates that a cert is the preferred cert for S/MIME encryption.
     */
    kCMSAttrSmimeEncryptionKeyPrefs		= 0x0002,
    /* 
     * Same as kCMSSmimeEncryptionKeyPrefs, using an attribute OID preferred
     * by Microsoft.
     */
    kCMSAttrSmimeMSEncryptionKeyPrefs	= 0x0004,
    /*
     * Include the signing time.
     */
    kCMSAttrSigningTime					= 0x0008,
    /*
     * Include the Apple Codesigning Hash Agility.
     */
    kCMSAttrAppleCodesigningHashAgility = 0x0010
};

/*
 * Optionally specify signed attributes. Only meaningful when creating a 
 * signed message. If this is called, it must be called before
 * CMSEncoderUpdateContent().
 */
OSStatus CMSEncoderAddSignedAttributes(
	CMSEncoderRef		cmsEncoder,
	CMSSignedAttributes	signedAttributes)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Specification of what certificates to include in a signed message.
 */
typedef CF_ENUM(uint32_t, CMSCertificateChainMode) {
	kCMSCertificateNone = 0,		/* don't include any certificates */
	kCMSCertificateSignerOnly,		/* only include signer certificate(s) */
	kCMSCertificateChain,			/* signer certificate chain up to but not 
									 *   including root certiticate */ 
	kCMSCertificateChainWithRoot	/* signer certificate chain including root */
};

/* 
 * Optionally specify which certificates, if any, to include in a 
 * signed CMS message. The default, if this is not called, is
 * kCMSCertificateChain, in which case the signer cert plus all CA
 * certs needed to verify the signer cert, except for the root 
 * cert, are included.
 * If this is called, it must be called before
 * CMSEncoderUpdateContent().
 */
OSStatus CMSEncoderSetCertificateChainMode(
	CMSEncoderRef			cmsEncoder,
	CMSCertificateChainMode	chainMode)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/* 
 * Obtain indication of which signer certs are to be included
 * in a signed CMS message. 
 */
OSStatus CMSEncoderGetCertificateChainMode(
	CMSEncoderRef			cmsEncoder,
	CMSCertificateChainMode	*chainModeOut)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Feed content bytes into the encoder. 
 * Can be called multiple times. 
 * No 'setter' routines can be called after this function has been called. 
 */ 
OSStatus CMSEncoderUpdateContent(
	CMSEncoderRef		cmsEncoder,
	const void			*content,
	size_t				contentLen)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Finish encoding the message and obtain the encoded result.
 * Caller must CFRelease the result. 
 */
OSStatus CMSEncoderCopyEncodedContent(
	CMSEncoderRef		cmsEncoder,
	CFDataRef * __nonnull CF_RETURNS_RETAINED encodedContentOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * High-level, one-shot encoder function.
 *
 * Inputs (all except for content optional, though at least one 
 *         of {signers, recipients} must be non-NULL)
 * ------------------------------------------------------------
 * signers          : signer identities. Either a SecIdentityRef, or a 
 *                    CFArray of them.
 * recipients       : recipient certificates. Either a SecCertificateRef, 
 *                    or a CFArray of them.
 * eContentType     : contentType for inner EncapsulatedData.
 * detachedContent  : when true, do not include the signed data in the message.
 * signedAttributes : Specifies which standard signed attributes are to be 
 *                    included in the message. 
 * content          : raw content to be signed and/or encrypted.
 *
 * Output
 * ------
 * encodedContent   : the result of the encoding.
 *
 * NOTE: This function is deprecated in Mac OS X 10.7 and later;
 * please use CMSEncodeContent() instead.
 */
OSStatus CMSEncode(
	CFTypeRef __nullable        signers,
	CFTypeRef __nullable        recipients,
	const CSSM_OID * __nullable eContentType,
	Boolean                     detachedContent,
	CMSSignedAttributes         signedAttributes,
	const void *                content,
	size_t                      contentLen,
	CFDataRef * __nonnull CF_RETURNS_RETAINED encodedContentOut)	/* RETURNED */
	/* DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);


/*
 * High-level, one-shot encoder function.
 *
 * Inputs (all except for content optional, though at least one 
 *         of {signers, recipients} must be non-NULL)
 * ------------------------------------------------------------
 * signers          : signer identities. Either a SecIdentityRef, or a 
 *                    CFArray of them.
 * recipients       : recipient certificates. Either a SecCertificateRef, 
 *                    or a CFArray of them.
 * eContentTypeOID  : contentType OID for inner EncapsulatedData, e.g.:
 *                    CFSTR("1.2.840.113549.1.7.1")
 * detachedContent  : when true, do not include the signed data in the message.
 * signedAttributes : Specifies which standard signed attributes are to be 
 *                    included in the message. 
 * content          : raw content to be signed and/or encrypted.
 *
 * Output
 * ------
 * encodedContent   : the result of the encoding.
 */
OSStatus CMSEncodeContent(
	CFTypeRef __nullable    signers,
	CFTypeRef __nullable    recipients,
	CFTypeRef __nullable    eContentTypeOID,
	Boolean                 detachedContent,
	CMSSignedAttributes     signedAttributes,
	const void              *content,
	size_t                  contentLen,
	CFDataRef * __nullable CF_RETURNS_RETAINED encodedContentOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);

OSStatus CMSEncoderCopySignerTimestamp(
	CMSEncoderRef		cmsEncoder,
	size_t				signerIndex,        /* usually 0 */
	CFAbsoluteTime      *timestamp)			/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);

OSStatus CMSEncoderCopySignerTimestampWithPolicy(
    CMSEncoderRef           cmsEncoder,
    CFTypeRef __nullable    timeStampPolicy,
    size_t                  signerIndex,        /* usually 0 */
    CFAbsoluteTime          *timestamp)			/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);

CF_ASSUME_NONNULL_END

#ifdef __cplusplus
}
#endif

#endif	/* _CMS_ENCODER_H_ */
Commit	Line	Data
b1ab9ed8	1	/*
d8f41ccd	2	* Copyright (c) 2006-2012 Apple Inc. All Rights Reserved.
b1ab9ed8 A	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
	48	#ifdef __cplusplus
	49	extern "C" {
	50	#endif
	51
5c19dc3a A	52	CF_ASSUME_NONNULL_BEGIN
5c19dc3a A	53
b1ab9ed8 A	54	/*
	55	* Opaque reference to a CMS encoder object.
	56	* This is a CF object, with standard CF semantics; dispose of it
	57	* with CFRelease().
	58	*/
5c19dc3a	59	typedef struct CF_BRIDGED_TYPE(id) _CMSEncoder *CMSEncoderRef;
b1ab9ed8 A	60
	61	CFTypeID CMSEncoderGetTypeID(void)
	62	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	63
	64	/*
	65	* Create a CMSEncoder. Result must eventually be freed via CFRelease().
	66	*/
	67	OSStatus CMSEncoderCreate(
5c19dc3a	68	CMSEncoderRef * __nonnull CF_RETURNS_RETAINED cmsEncoderOut) /* RETURNED */
b1ab9ed8 A	69	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
b1ab9ed8 A	70
5c19dc3a A	71	extern const CFStringRef kCMSEncoderDigestAlgorithmSHA1;
	72	extern const CFStringRef kCMSEncoderDigestAlgorithmSHA256;
	73
	74	OSStatus CMSEncoderSetSignerAlgorithm(
	75	CMSEncoderRef cmsEncoder,
	76	CFStringRef digestAlgorithm)
	77	__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_NA);
	78
b1ab9ed8 A	79	/*
	80	* Specify signers of the CMS message; implies that the message will be signed.
	81	*
	82	* -- Caller can pass in one signer, as a SecIdentityRef, or an array of
	83	* signers, as a CFArray of SecIdentityRefs.
	84	* -- Can be called multiple times.
	85	* -- If the message is not to be signed, don't call this.
	86	* -- If this is called, it must be called before the first call to
	87	* CMSEncoderUpdateContent().
	88	*/
	89	OSStatus CMSEncoderAddSigners(
	90	CMSEncoderRef cmsEncoder,
	91	CFTypeRef signerOrArray)
	92	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	93
	94	/*
	95	* Obtain an array of signers as specified in CMSEncoderSetSigners().
	96	* Returns a NULL signers array if CMSEncoderSetSigners() has not been called.
	97	* Caller must CFRelease the result.
	98	*/
	99	OSStatus CMSEncoderCopySigners(
	100	CMSEncoderRef cmsEncoder,
5c19dc3a	101	CFArrayRef * __nonnull CF_RETURNS_RETAINED signersOut) /* RETURNED */
b1ab9ed8 A	102	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	103
	104	/*
	105	* Specify recipients of the message. Implies that the message will
	106	* be encrypted.
	107	*
	108	* -- Caller can pass in one recipient, as a SecCertificateRef, or an
	109	* array of recipients, as a CFArray of SecCertificateRefs.
	110	* -- Can be called multiple times.
	111	* -- If the message is not to be encrypted, don't call this.
	112	* -- If this is called, it must be called before the first call to
	113	* CMSEncoderUpdateContent().
	114	*/
	115	OSStatus CMSEncoderAddRecipients(
	116	CMSEncoderRef cmsEncoder,
	117	CFTypeRef recipientOrArray)
	118	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	119
	120	/*
	121	* Obtain an array of recipients as specified in CMSEncoderSetRecipients().
	122	* Returns a NULL recipients array if CMSEncoderSetRecipients() has not been
	123	* called.
	124	* Caller must CFRelease the result.
	125	*/
	126	OSStatus CMSEncoderCopyRecipients(
	127	CMSEncoderRef cmsEncoder,
5c19dc3a	128	CFArrayRef * __nonnull CF_RETURNS_RETAINED recipientsOut) /* RETURNED */
b1ab9ed8 A	129	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	130
	131	/*
	132	* A signed message optionally includes the data to be signed. If the message
	133	* is not to include the data to be signed, call this function with a value
	134	* of TRUE for detachedContent. The default, if this function is not called,
	135	* is detachedContent=FALSE, i.e., the message contains the data to be signed.
	136	*
	137	* -- Encrypted messages can not use detached content. (This restriction
	138	* also applies to messages that are both signed and encrypted.)
	139	* -- If this is called, it must be called before the first call to
	140	* CMSEncoderUpdateContent().
	141	*/
	142	OSStatus CMSEncoderSetHasDetachedContent(
	143	CMSEncoderRef cmsEncoder,
	144	Boolean detachedContent)
	145	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	146
	147	/*
	148	* Obtain a Boolean indicating whether the current message will have detached
	149	* content.
	150	* Returns the value specified in CMSEncoderHasDetachedContent() if that
	151	* function has been called; else returns the default FALSE.
	152	*/
	153	OSStatus CMSEncoderGetHasDetachedContent(
	154	CMSEncoderRef cmsEncoder,
	155	Boolean detachedContentOut) / RETURNED */
	156	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	157
	158	/*
	159	* Optionally specify an eContentType OID for the inner EncapsulatedData for
	160	* a signed message. The default eContentType, used if this function is not
	161	* called, is id-data (which is the normal eContentType for applications such
	162	* as SMIME).
	163	*
	164	* If this is called, it must be called before the first call to
	165	* CMSEncoderUpdateContent().
	166	*
	167	* NOTE: This function is deprecated in Mac OS X 10.7 and later;
	168	* please use CMSEncoderSetEncapsulatedContentTypeOID() instead.
	169	*/
	170	OSStatus CMSEncoderSetEncapsulatedContentType(
	171	CMSEncoderRef cmsEncoder,
	172	const CSSM_OID *eContentType)
	173	/* DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; */
	174	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	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,
5c19dc3a	203	CFDataRef * __nonnull CF_RETURNS_RETAINED eContentTypeOut) /* RETURNED */
b1ab9ed8 A	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,
5c19dc3a	239	CFArrayRef * __nonnull CF_RETURNS_RETAINED certsOut) /* RETURNED */
b1ab9ed8 A	240	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	241
	242	/*
	243	* Standard signed attributes, optionally specified in
	244	* CMSEncoderAddSignedAttributes().
	245	*/
6b200bc3	246	typedef CF_OPTIONS(uint32_t, CMSSignedAttributes) {
b1ab9ed8 A	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	*/
e3d460c9 A	265	kCMSAttrSigningTime = 0x0008,
	266	/*
	267	* Include the Apple Codesigning Hash Agility.
	268	*/
	269	kCMSAttrAppleCodesigningHashAgility = 0x0010
b1ab9ed8	270	};
b1ab9ed8 A	271
	272	/*
	273	* Optionally specify signed attributes. Only meaningful when creating a
	274	* signed message. If this is called, it must be called before
	275	* CMSEncoderUpdateContent().
	276	*/
	277	OSStatus CMSEncoderAddSignedAttributes(
	278	CMSEncoderRef cmsEncoder,
	279	CMSSignedAttributes signedAttributes)
	280	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	281
	282	/*
	283	* Specification of what certificates to include in a signed message.
	284	*/
5c19dc3a	285	typedef CF_ENUM(uint32_t, CMSCertificateChainMode) {
b1ab9ed8 A	286	kCMSCertificateNone = 0, /* don't include any certificates */
	287	kCMSCertificateSignerOnly, /* only include signer certificate(s) */
	288	kCMSCertificateChain, /* signer certificate chain up to but not
	289	* including root certiticate */
	290	kCMSCertificateChainWithRoot /* signer certificate chain including root */
	291	};
b1ab9ed8 A	292
	293	/*
	294	* Optionally specify which certificates, if any, to include in a
	295	* signed CMS message. The default, if this is not called, is
	296	* kCMSCertificateChain, in which case the signer cert plus all CA
	297	* certs needed to verify the signer cert, except for the root
	298	* cert, are included.
	299	* If this is called, it must be called before
	300	* CMSEncoderUpdateContent().
	301	*/
	302	OSStatus CMSEncoderSetCertificateChainMode(
	303	CMSEncoderRef cmsEncoder,
	304	CMSCertificateChainMode chainMode)
	305	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	306
	307	/*
	308	* Obtain indication of which signer certs are to be included
	309	* in a signed CMS message.
	310	*/
	311	OSStatus CMSEncoderGetCertificateChainMode(
	312	CMSEncoderRef cmsEncoder,
	313	CMSCertificateChainMode *chainModeOut)
	314	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	315
	316	/*
	317	* Feed content bytes into the encoder.
	318	* Can be called multiple times.
	319	* No 'setter' routines can be called after this function has been called.
	320	*/
	321	OSStatus CMSEncoderUpdateContent(
	322	CMSEncoderRef cmsEncoder,
	323	const void *content,
	324	size_t contentLen)
	325	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	326
	327	/*
	328	* Finish encoding the message and obtain the encoded result.
	329	* Caller must CFRelease the result.
	330	*/
	331	OSStatus CMSEncoderCopyEncodedContent(
	332	CMSEncoderRef cmsEncoder,
5c19dc3a	333	CFDataRef * __nonnull CF_RETURNS_RETAINED encodedContentOut) /* RETURNED */
b1ab9ed8 A	334	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	335
	336	/*
	337	* High-level, one-shot encoder function.
	338	*
	339	* Inputs (all except for content optional, though at least one
	340	* of {signers, recipients} must be non-NULL)
	341	* ------------------------------------------------------------
	342	* signers : signer identities. Either a SecIdentityRef, or a
	343	* CFArray of them.
	344	* recipients : recipient certificates. Either a SecCertificateRef,
	345	* or a CFArray of them.
	346	* eContentType : contentType for inner EncapsulatedData.
	347	* detachedContent : when true, do not include the signed data in the message.
	348	* signedAttributes : Specifies which standard signed attributes are to be
	349	* included in the message.
	350	* content : raw content to be signed and/or encrypted.
	351	*
	352	* Output
	353	* ------
	354	* encodedContent : the result of the encoding.
	355	*
	356	* NOTE: This function is deprecated in Mac OS X 10.7 and later;
	357	* please use CMSEncodeContent() instead.
	358	*/
	359	OSStatus CMSEncode(
5c19dc3a A	360	CFTypeRef __nullable signers,
	361	CFTypeRef __nullable recipients,
	362	const CSSM_OID * __nullable eContentType,
	363	Boolean detachedContent,
	364	CMSSignedAttributes signedAttributes,
	365	const void * content,
	366	size_t contentLen,
	367	CFDataRef * __nonnull CF_RETURNS_RETAINED encodedContentOut) /* RETURNED */
b1ab9ed8 A	368	/* DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER; */
	369	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	370
	371
	372	/*
	373	* High-level, one-shot encoder function.
	374	*
	375	* Inputs (all except for content optional, though at least one
	376	* of {signers, recipients} must be non-NULL)
	377	* ------------------------------------------------------------
	378	* signers : signer identities. Either a SecIdentityRef, or a
	379	* CFArray of them.
	380	* recipients : recipient certificates. Either a SecCertificateRef,
	381	* or a CFArray of them.
	382	* eContentTypeOID : contentType OID for inner EncapsulatedData, e.g.:
	383	* CFSTR("1.2.840.113549.1.7.1")
	384	* detachedContent : when true, do not include the signed data in the message.
	385	* signedAttributes : Specifies which standard signed attributes are to be
	386	* included in the message.
	387	* content : raw content to be signed and/or encrypted.
	388	*
	389	* Output
	390	* ------
	391	* encodedContent : the result of the encoding.
	392	*/
	393	OSStatus CMSEncodeContent(
5c19dc3a A	394	CFTypeRef __nullable signers,
	395	CFTypeRef __nullable recipients,
	396	CFTypeRef __nullable eContentTypeOID,
	397	Boolean detachedContent,
	398	CMSSignedAttributes signedAttributes,
	399	const void *content,
	400	size_t contentLen,
	401	CFDataRef * __nullable CF_RETURNS_RETAINED encodedContentOut) /* RETURNED */
b1ab9ed8 A	402	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
	403
	404	OSStatus CMSEncoderCopySignerTimestamp(
	405	CMSEncoderRef cmsEncoder,
	406	size_t signerIndex, /* usually 0 */
	407	CFAbsoluteTime timestamp) / RETURNED */
	408	__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);
	409
d8f41ccd	410	OSStatus CMSEncoderCopySignerTimestampWithPolicy(
5c19dc3a A	411	CMSEncoderRef cmsEncoder,
	412	CFTypeRef __nullable timeStampPolicy,
	413	size_t signerIndex, /* usually 0 */
	414	CFAbsoluteTime timestamp) / RETURNED */
d8f41ccd A	415	__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
d8f41ccd A	416
5c19dc3a A	417	CF_ASSUME_NONNULL_END
5c19dc3a A	418
b1ab9ed8 A	419	#ifdef __cplusplus
	420	}
	421	#endif
	422
	423	#endif /* _CMS_ENCODER_H_ */
	424