+++ /dev/null
-/*
- * 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/SecCmsEncoder.h>
-#include <Security/SecCmsDecoder.h>
-#include <Security/SecCmsMessage.h>
-#include <AvailabilityMacros.h>
-#include <stdint.h>
-
-__BEGIN_DECLS
-
-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_11_0);
-
-/*
- * 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_11_0);
-
-extern const CFStringRef kCMSEncoderDigestAlgorithmSHA1;
-extern const CFStringRef kCMSEncoderDigestAlgorithmSHA256;
-
-OSStatus CMSEncoderSetSignerAlgorithm(
- CMSEncoderRef cmsEncoder,
- CFStringRef digestAlgorithm)
- __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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,
- kCMSAttrAppleCodesigningHashAgilityV2 = 0x0020,
- /*
- * Include the expiration time.
- */
- kCMSAttrAppleExpirationTime = 0x0040,
-};
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-/*
- * 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_11_0);
-
-#if TIMESTAMPING_SUPPORTED
-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);
-
-void
-CmsMessageSetTSAContext(CMSEncoderRef cmsEncoder, CFTypeRef tsaContext);
-#endif // TIMESTAMPING_SUPPORTED
-
-/*
- * Obtain the SecCmsMessageRef associated with a CMSEncoderRef. Intended
- * to be called after (optionally) setting the encoder's various attributes
- * via CMSEncoderAddSigners(), CMSEncoderAddRecipients(), etc. and before
- * the first call to CMSEncoderUpdateContent(). The returned SecCmsMessageRef
- * will be initialized per the previously specified attributes; the caller
- * can manipulate the SecCmsMessageRef prior to proceeding with
- * CMSEncoderUpdateContent() calls.
- */
-OSStatus CMSEncoderGetCmsMessage(
- CMSEncoderRef cmsEncoder,
- SecCmsMessageRef _Nullable * _Nonnull cmsMessage); /* RETURNED */
-
-/*
- * Optionally specify a SecCmsEncoderRef to use with a CMSEncoderRef.
- * If this is called, it must be called before the first call to
- * CMSEncoderUpdateContent(). The CMSEncoderRef takes ownership of the
- * incoming SecCmsEncoderRef.
- */
-OSStatus CMSEncoderSetEncoder(
- CMSEncoderRef cmsEncoder,
- SecCmsEncoderRef encoder);
-
-/*
- * Obtain the SecCmsEncoderRef associated with a CMSEncoderRef.
- * Returns a NULL SecCmsEncoderRef if neither CMSEncoderSetEncoder nor
- * CMSEncoderUpdateContent() has been called.
- * The CMSEncoderRef retains ownership of the SecCmsEncoderRef.
- */
-OSStatus CMSEncoderGetEncoder(
- CMSEncoderRef cmsEncoder,
- SecCmsEncoderRef _Nullable * _Nonnull encoder); /* RETURNED */
-
-/*
- * Set the signing time for a CMSEncoder.
- * This is only used if the kCMSAttrSigningTime attribute is included.
- */
-OSStatus CMSEncoderSetSigningTime(
- CMSEncoderRef cmsEncoder,
- CFAbsoluteTime time);
-
-/*
- * Set the hash agility attribute for a CMSEncoder.
- * This is only used if the kCMSAttrAppleCodesigningHashAgility attribute
- * is included.
- */
-OSStatus CMSEncoderSetAppleCodesigningHashAgility(
- CMSEncoderRef cmsEncoder,
- CFDataRef hashAgilityAttrValue);
-
-/*
- * Set the hash agility attribute for a CMSEncoder.
- * This is only used if the kCMSAttrAppleCodesigningHashAgilityV2 attribute
- * is included. V2 encodes the hash agility values using DER.
- * The dictionary should have CFNumberRef keys, corresponding to SECOidTags
- * (from SecCmsBase.h) for digest algorithms, and CFDataRef values,
- * corresponding to the digest value for that digest algorithm.
- */
-OSStatus CMSEncoderSetAppleCodesigningHashAgilityV2(
- CMSEncoderRef cmsEncoder,
- CFDictionaryRef hashAgilityV2AttrValues);
-
-/*
- * Set the expiration time for a CMSEncoder.
- * This is only used if the kCMSAttrAppleExpirationTime attribute is included.
- */
-OSStatus CMSEncoderSetAppleExpirationTime(
- CMSEncoderRef cmsEncoder,
- CFAbsoluteTime time);
-
-
-CF_ASSUME_NONNULL_END
-
-__END_DECLS
-
-#endif /* _CMS_ENCODER_H_ */
-
projects / apple / security.git / blobdiff