You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
421 lines
16 KiB
421 lines
16 KiB
9 years ago
|
/*
|
||
|
* 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_ENUM(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
|
||
|
};
|
||
|
|
||
|
/*
|
||
|
* 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_ */
|
||
|
|