X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/80e2389990082500d76eb566d4946be3e786c3ef..d8f41ccd20de16f8ebe2ccc84d47bf1cb2b26bbb:/Security/libsecurity_cms/lib/CMSEncoder.h?ds=inline diff --git a/Security/libsecurity_cms/lib/CMSEncoder.h b/Security/libsecurity_cms/lib/CMSEncoder.h new file mode 100644 index 00000000..b887f4de --- /dev/null +++ b/Security/libsecurity_cms/lib/CMSEncoder.h @@ -0,0 +1,410 @@ +/* + * 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 +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * Opaque reference to a CMS encoder object. + * This is a CF object, with standard CF semantics; dispose of it + * with CFRelease(). + */ +typedef struct _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 *cmsEncoderOut) /* RETURNED */ + __OSX_AVAILABLE_STARTING(__MAC_10_5, __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 *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 *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 *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 *certsOut) /* RETURNED */ + __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); + +/* + * Standard signed attributes, optionally specified in + * CMSEncoderAddSignedAttributes(). + */ +enum { + 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 +}; +typedef uint32_t CMSSignedAttributes; + +/* + * 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. + */ +enum { + 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 */ +}; +typedef uint32_t CMSCertificateChainMode; + +/* + * 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 *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 signers, + CFTypeRef recipients, + const CSSM_OID *eContentType, + Boolean detachedContent, + CMSSignedAttributes signedAttributes, + const void *content, + size_t contentLen, + CFDataRef *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 signers, + CFTypeRef recipients, + CFTypeRef eContentTypeOID, + Boolean detachedContent, + CMSSignedAttributes signedAttributes, + const void *content, + size_t contentLen, + CFDataRef *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 timeStampPolicy, + size_t signerIndex, /* usually 0 */ + CFAbsoluteTime *timestamp) /* RETURNED */ + __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA); + +#ifdef __cplusplus +} +#endif + +#endif /* _CMS_ENCODER_H_ */ +