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

/*
 * Copyright (c) 2006-2013 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@
 */

/*
 * CMSDecoder.h - decode, decrypt, and/or verify signatures of messages in the 
 *				  Cryptographic Message Syntax (CMS), per RFC 3852.
 *
 * See CMSEncoder.h for general information about CMS messages. 
 */
 
#ifndef _CMS_DECODER_H_
#define _CMS_DECODER_H_

#include <CoreFoundation/CoreFoundation.h>
#include <Security/SecCertificate.h>
#include <Security/SecTrust.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

CF_ASSUME_NONNULL_BEGIN

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

CFTypeID CMSDecoderGetTypeID(void);

/*
 * Status of signature and signer information in a signed message.
 */
typedef CF_ENUM(uint32_t, CMSSignerStatus) {
	kCMSSignerUnsigned = 0,				/* message was not signed */
	kCMSSignerValid,					/* message was signed and signature verify OK */
	kCMSSignerNeedsDetachedContent,		/* message was signed but needs detached content 
										 *   to verify */
	kCMSSignerInvalidSignature,			/* message was signed but had a signature error */
	kCMSSignerInvalidCert,				/* message was signed but an error occurred in verifying
										 *   the signer's certificate */
	kCMSSignerInvalidIndex				/* specified signer index out of range */
};

/*
 * Create a CMSDecoder. Result must eventually be freed via CFRelease().
 */
OSStatus CMSDecoderCreate(
	CMSDecoderRef * __nonnull CF_RETURNS_RETAINED cmsDecoderOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/* 
 * Feed raw bytes of the message to be decoded into the decoder. Can be called
 * multiple times. 
 * Returns errSecUnknownFormat upon detection of improperly formatted CMS
 * message. 
 */
OSStatus CMSDecoderUpdateMessage(
	CMSDecoderRef		cmsDecoder,
	const void			*msgBytes,
	size_t				msgBytesLen)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	
/* 
 * Indicate that no more CMSDecoderUpdateMessage() calls are forthcoming;
 * finish decoding the message. 
 * Returns errSecUnknownFormat upon detection of improperly formatted CMS
 * message. 
 */
OSStatus CMSDecoderFinalizeMessage(
	CMSDecoderRef		cmsDecoder)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * A signed CMS message optionally includes the data which was signed. If the
 * message does not include the signed data, caller specifies the signed data
 * (the "detached content") here. 
 *
 * This can be called either before or after the actual decoding of the message
 * (via CMSDecoderUpdateMessage() and CMSDecoderFinalizeMessage()); the only
 * restriction is that, if detached content is required, this function must 
 * be called befoere successfully ascertaining the signature status via 
 * CMSDecoderCopySignerStatus().
 */
OSStatus CMSDecoderSetDetachedContent(
	CMSDecoderRef		cmsDecoder,
	CFDataRef			detachedContent)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the detached content specified in CMSDecoderSetDetachedContent().
 * Returns a NULL detachedContent if no detached content has been specified. 
 * Caller must CFRelease() the result.
 */
OSStatus CMSDecoderCopyDetachedContent(
	CMSDecoderRef		cmsDecoder,
	CFDataRef * __nonnull CF_RETURNS_RETAINED detachedContentOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * This function no longer affects the behavior of the CMS Decoder. Please
 * discontinue use.
 */
OSStatus CMSDecoderSetSearchKeychain(
	CMSDecoderRef		cmsDecoder,
	CFTypeRef			keychainOrArray)
    __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_5, __MAC_10_13, __IPHONE_NA, __IPHONE_NA,
                                       "To change the search keychains call SecKeychainSetSearchList.");

/*
 * Obtain the number of signers of a message. A result of zero indicates that
 * the message was not signed. 
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderGetNumSigners(
	CMSDecoderRef		cmsDecoder,
	size_t				*numSignersOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the status of a CMS message's signature. A CMS message can 
 * be signed my multiple signers; this function returns the status
 * associated with signer 'n' as indicated by the signerIndex parameter. 
 *
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 *
 * Note that signature and certificate verification of a decoded message
 * does *not* occur until this routine is called. 
 *
 * All returned values are optional - pass NULL if you don't need a
 * particular parameter. 
 *
 * Note that errors like "bad signature" and "bad cert" do NOT cause this 
 * routine to return a nonzero error status itself; such errors are reported
 * in the various out parameters, listed below. 
 *
 * Inputs:
 * -------
 * cmsDecoder       : a CMSDecoder which has successfully performed a 
 *                    CMSDecoderFinalizeMessage().
 * signerIndex      : indicates which of 'n' signers is being examined.
 *                    Range is 0...(numSigners-1).
 * policyOrArray    : Either a SecPolicyRef or a CFArray of them.
 *                    These policies are used to verify the signer's certificate. 
 * evaluateSecTrust : When TRUE, causes the SecTrust oebject created for the 
 *                    evaluation of the signer cert to actually be evaluated
 *                    via SecTrustEvaluate(). When FALSE, the caller performs 
 *                    the SecTrustEvaluate() operation on the SecTrust object 
 *                    returned via the secTrust out parameter. 
 *                    NOTE: it is hazardous and not recommended to pass in FALSE
 *                    for the evaluateSecTrust parameter as well as NULL for the
 *                    secTrust out parameter, since no evaluation of the signer
 *                    cert can occur in that situation.
 *
 * Outputs:
 * --------
 *	signerStatusOut			-- An enum indicating the overall status.
 *		kCMSSignerUnsigned         : message was not signed.
 *		kCMSSignerValid            : both signature and signer certificate verified OK.
 *		kCMSSignerNeedsDetachedContent : a call to CMSDecoderSetDetachedContent()
 *							         is required to ascertain the signature status.
 *		kCMSSignerInvalidSignature : bad signature.
 *		kCMSSignerInvalidCert      : an error occurred verifying the signer's certificate.
 *							         Further information available via the secTrust and 
 *							         certVerifyResultCode parameters. This will never be 
 *								     returned if evaluateSecTrust is FALSE. 
 *		kCMSSignerInvalidIndex     : specified signerIndex is larger than the number of 
 *								     signers (minus 1).
 *
 *	secTrustOut				-- The SecTrust object used to verify the signer's 
 *							   certificate. Caller must CFRelease this. 
 *	certVerifyResultCodeOut	-- The result of the certificate verification. If 
 *							   the evaluateSecTrust argument is set to FALSE on 
 *							   input, this out parameter is undefined on return.
 *
 * The certVerifyResultCode value can indicate a large number of errors; some of 
 * the most common and interesting errors are:
 *
 * CSSMERR_TP_INVALID_ANCHOR_CERT : The cert was verified back to a 
 *		self-signed (root) cert which was present in the message, but 
 *		that root cert is not a known, trusted root cert. 
 * CSSMERR_TP_NOT_TRUSTED: The cert could not be verified back to 
 *		a root cert.
 * CSSMERR_TP_VERIFICATION_FAILURE: A root cert was found which does
 *   	not self-verify. 
 * CSSMERR_TP_VERIFY_ACTION_FAILED: Indicates a failure of the requested 
 *		policy action. 
 * CSSMERR_TP_INVALID_CERTIFICATE: Indicates a bad leaf cert. 
 * CSSMERR_TP_CERT_EXPIRED: A cert in the chain was expired at the time of
 *		verification.
 * CSSMERR_TP_CERT_NOT_VALID_YET: A cert in the chain was not yet valie at 
 *		the time of	verification.
 */
OSStatus CMSDecoderCopySignerStatus(
	CMSDecoderRef               cmsDecoder,
	size_t                      signerIndex,
	CFTypeRef                   policyOrArray,
	Boolean                     evaluateSecTrust,
	CMSSignerStatus * __nullable signerStatusOut,               /* optional; RETURNED */
	SecTrustRef * __nullable CF_RETURNS_RETAINED secTrustOut,   /* optional; RETURNED */
    OSStatus * __nullable certVerifyResultCodeOut)              /* optional; RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the email address of signer 'signerIndex' of a CMS message, if
 * present. 
 *
 * Returns errSecParam if the CMS message was not signed or if signerIndex
 * is greater than the number of signers of the message minus one. 
 *
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderCopySignerEmailAddress(
	CMSDecoderRef		cmsDecoder,
	size_t				signerIndex,
	CFStringRef	* __nonnull CF_RETURNS_RETAINED signerEmailAddressOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the certificate of signer 'signerIndex' of a CMS message, if
 * present. 
 *
 * Returns errSecParam if the CMS message was not signed or if signerIndex
 * is greater than the number of signers of the message minus one. 
 *
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderCopySignerCert(
	CMSDecoderRef		cmsDecoder,
	size_t				signerIndex,
	SecCertificateRef * __nonnull CF_RETURNS_RETAINED signerCertOut)    /* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/* 
 * Determine whether a CMS message was encrypted. Returns TRUE if so, FALSE if not.
 * Note that if the message was encrypted, and the decoding succeeded, (i.e.,
 * CMSDecoderFinalizeMessage() returned errSecSuccess), then the message was successfully
 * decrypted. 
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderIsContentEncrypted(
	CMSDecoderRef		cmsDecoder,
	Boolean				*isEncryptedOut)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the eContentType OID for a SignedData's EncapsulatedContentType, if 
 * present. If the message was not signed this will return NULL.
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 * The returned OID's data is in the same format as a CSSM_OID; i.e., it's
 * the encoded content of the OID, not including the tag and length bytes. 
 */
OSStatus CMSDecoderCopyEncapsulatedContentType(
	CMSDecoderRef		cmsDecoder,
	CFDataRef * __nonnull CF_RETURNS_RETAINED eContentTypeOut)  /* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain an array of all of the certificates in a message. Elements of the 
 * returned array are SecCertificateRefs. The caller must CFRelease the returned 
 * array. If a message does not contain any certificates (which is the case for
 * a message which is encrypted but not signed), the returned *certs value 
 * is NULL. The function will return errSecSuccess in this case.
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderCopyAllCerts(
	CMSDecoderRef		cmsDecoder,
	CFArrayRef * __nonnull CF_RETURNS_RETAINED certsOut)    /* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the actual message content (payload), if any. If the message was
 * signed with detached content this will return NULL.
 * Caller must CFRelease the result. 
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderCopyContent(
	CMSDecoderRef		cmsDecoder,
	CFDataRef * __nonnull CF_RETURNS_RETAINED contentOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Obtain the signing time of signer 'signerIndex' of a CMS message, if
 * present. This is an unauthenticate time, although it is part of the
 * signed attributes of the message.
 *
 * Returns errSecParam if the CMS message was not signed or if signerIndex
 * is greater than the number of signers of the message minus one. 
 *
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderCopySignerSigningTime(
	CMSDecoderRef		cmsDecoder,
	size_t				signerIndex,
	CFAbsoluteTime      *signingTime)			/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);

/*
 * Obtain the timestamp of signer 'signerIndex' of a CMS message, if
 * present. This timestamp is an authenticated timestamp provided by
 * a timestamping authority.
 *
 * Returns errSecParam if the CMS message was not signed or if signerIndex
 * is greater than the number of signers of the message minus one. 
 *
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderCopySignerTimestamp(
	CMSDecoderRef		cmsDecoder,
	size_t				signerIndex,
	CFAbsoluteTime      *timestamp)			/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);

    /*
     * Obtain the timestamp of signer 'signerIndex' of a CMS message, if
     * present. This timestamp is an authenticated timestamp provided by
     * a timestamping authority. Use the policy provided as a parameter
     *
     * Returns errSecParam if the CMS message was not signed or if signerIndex
     * is greater than the number of signers of the message minus one.
     *
     * This cannot be called until after CMSDecoderFinalizeMessage() is called.
     */
OSStatus CMSDecoderCopySignerTimestampWithPolicy(
                                                    CMSDecoderRef		cmsDecoder,
                                                    CFTypeRef __nullable timeStampPolicy,
                                                    size_t				signerIndex,        /* usually 0 */
                                                    CFAbsoluteTime      *timestamp)			/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);

/*
 * Obtain an array of the certificates in a timestamp response. Elements of the 
 * returned array are SecCertificateRefs. The caller must CFRelease the returned
 * array. This timestamp is an authenticated timestamp provided by
 * a timestamping authority.
 *
 * Returns errSecParam if the CMS message was not signed or if signerIndex
 * is greater than the number of signers of the message minus one. It returns
 * errSecItemNotFound if no certificates were found.
 *
 * This cannot be called until after CMSDecoderFinalizeMessage() is called. 
 */
OSStatus CMSDecoderCopySignerTimestampCertificates(
	CMSDecoderRef		cmsDecoder,
	size_t				signerIndex,                            /* usually 0 */
	CFArrayRef * __nonnull CF_RETURNS_RETAINED certificateRefs) /* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);

CF_ASSUME_NONNULL_END

#ifdef __cplusplus
}
#endif

#endif	/* _CMS_DECODER_H_ */
Commit	Line	Data
b1ab9ed8	1	/*
d8f41ccd	2	* Copyright (c) 2006-2013 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	* CMSDecoder.h - decode, decrypt, and/or verify signatures of messages in the
	26	* Cryptographic Message Syntax (CMS), per RFC 3852.
	27	*
	28	* See CMSEncoder.h for general information about CMS messages.
	29	*/
	30
	31	#ifndef _CMS_DECODER_H_
	32	#define _CMS_DECODER_H_
	33
	34	#include <CoreFoundation/CoreFoundation.h>
	35	#include <Security/SecCertificate.h>
	36	#include <Security/SecTrust.h>
	37	#include <stdint.h>
	38
	39	#ifdef __cplusplus
	40	extern "C" {
	41	#endif
	42
5c19dc3a A	43	CF_ASSUME_NONNULL_BEGIN
5c19dc3a A	44
b1ab9ed8 A	45	/*
	46	* Opaque reference to a CMS decoder object.
	47	* This is a CF object, with standard CF semantics; dispose of it
	48	* with CFRelease().
	49	*/
5c19dc3a	50	typedef struct CF_BRIDGED_TYPE(id) _CMSDecoder *CMSDecoderRef;
b1ab9ed8 A	51
	52	CFTypeID CMSDecoderGetTypeID(void);
	53
	54	/*
	55	* Status of signature and signer information in a signed message.
	56	*/
5c19dc3a	57	typedef CF_ENUM(uint32_t, CMSSignerStatus) {
b1ab9ed8 A	58	kCMSSignerUnsigned = 0, /* message was not signed */
	59	kCMSSignerValid, /* message was signed and signature verify OK */
	60	kCMSSignerNeedsDetachedContent, /* message was signed but needs detached content
	61	* to verify */
	62	kCMSSignerInvalidSignature, /* message was signed but had a signature error */
	63	kCMSSignerInvalidCert, /* message was signed but an error occurred in verifying
	64	* the signer's certificate */
	65	kCMSSignerInvalidIndex /* specified signer index out of range */
	66	};
b1ab9ed8 A	67
	68	/*
	69	* Create a CMSDecoder. Result must eventually be freed via CFRelease().
	70	*/
	71	OSStatus CMSDecoderCreate(
5c19dc3a	72	CMSDecoderRef * __nonnull CF_RETURNS_RETAINED cmsDecoderOut) /* RETURNED */
b1ab9ed8 A	73	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	74
	75	/*
	76	* Feed raw bytes of the message to be decoded into the decoder. Can be called
	77	* multiple times.
	78	* Returns errSecUnknownFormat upon detection of improperly formatted CMS
	79	* message.
	80	*/
	81	OSStatus CMSDecoderUpdateMessage(
	82	CMSDecoderRef cmsDecoder,
	83	const void *msgBytes,
	84	size_t msgBytesLen)
	85	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	86
	87	/*
	88	* Indicate that no more CMSDecoderUpdateMessage() calls are forthcoming;
	89	* finish decoding the message.
	90	* Returns errSecUnknownFormat upon detection of improperly formatted CMS
	91	* message.
	92	*/
	93	OSStatus CMSDecoderFinalizeMessage(
	94	CMSDecoderRef cmsDecoder)
	95	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	96
	97	/*
	98	* A signed CMS message optionally includes the data which was signed. If the
	99	* message does not include the signed data, caller specifies the signed data
	100	* (the "detached content") here.
	101	*
	102	* This can be called either before or after the actual decoding of the message
	103	* (via CMSDecoderUpdateMessage() and CMSDecoderFinalizeMessage()); the only
	104	* restriction is that, if detached content is required, this function must
	105	* be called befoere successfully ascertaining the signature status via
	106	* CMSDecoderCopySignerStatus().
	107	*/
	108	OSStatus CMSDecoderSetDetachedContent(
	109	CMSDecoderRef cmsDecoder,
	110	CFDataRef detachedContent)
	111	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	112
	113	/*
	114	* Obtain the detached content specified in CMSDecoderSetDetachedContent().
	115	* Returns a NULL detachedContent if no detached content has been specified.
	116	* Caller must CFRelease() the result.
	117	*/
	118	OSStatus CMSDecoderCopyDetachedContent(
	119	CMSDecoderRef cmsDecoder,
5c19dc3a	120	CFDataRef * __nonnull CF_RETURNS_RETAINED detachedContentOut) /* RETURNED */
b1ab9ed8 A	121	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	122
	123	/*
866f8763 A	124	* This function no longer affects the behavior of the CMS Decoder. Please
866f8763 A	125	* discontinue use.
b1ab9ed8 A	126	*/
	127	OSStatus CMSDecoderSetSearchKeychain(
	128	CMSDecoderRef cmsDecoder,
	129	CFTypeRef keychainOrArray)
866f8763 A	130	__OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_5, __MAC_10_13, __IPHONE_NA, __IPHONE_NA,
866f8763 A	131	"To change the search keychains call SecKeychainSetSearchList.");
b1ab9ed8 A	132
	133	/*
	134	* Obtain the number of signers of a message. A result of zero indicates that
	135	* the message was not signed.
	136	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	137	*/
	138	OSStatus CMSDecoderGetNumSigners(
	139	CMSDecoderRef cmsDecoder,
	140	size_t numSignersOut) / RETURNED */
	141	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	142
	143	/*
	144	* Obtain the status of a CMS message's signature. A CMS message can
	145	* be signed my multiple signers; this function returns the status
	146	* associated with signer 'n' as indicated by the signerIndex parameter.
	147	*
	148	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	149	*
	150	* Note that signature and certificate verification of a decoded message
	151	* does not occur until this routine is called.
	152	*
	153	* All returned values are optional - pass NULL if you don't need a
	154	* particular parameter.
	155	*
	156	* Note that errors like "bad signature" and "bad cert" do NOT cause this
	157	* routine to return a nonzero error status itself; such errors are reported
	158	* in the various out parameters, listed below.
	159	*
	160	* Inputs:
	161	* -------
	162	* cmsDecoder : a CMSDecoder which has successfully performed a
	163	* CMSDecoderFinalizeMessage().
	164	* signerIndex : indicates which of 'n' signers is being examined.
	165	* Range is 0...(numSigners-1).
	166	* policyOrArray : Either a SecPolicyRef or a CFArray of them.
	167	* These policies are used to verify the signer's certificate.
	168	* evaluateSecTrust : When TRUE, causes the SecTrust oebject created for the
	169	* evaluation of the signer cert to actually be evaluated
	170	* via SecTrustEvaluate(). When FALSE, the caller performs
	171	* the SecTrustEvaluate() operation on the SecTrust object
	172	* returned via the secTrust out parameter.
	173	* NOTE: it is hazardous and not recommended to pass in FALSE
	174	* for the evaluateSecTrust parameter as well as NULL for the
	175	* secTrust out parameter, since no evaluation of the signer
	176	* cert can occur in that situation.
	177	*
	178	* Outputs:
	179	* --------
	180	* signerStatusOut -- An enum indicating the overall status.
	181	* kCMSSignerUnsigned : message was not signed.
	182	* kCMSSignerValid : both signature and signer certificate verified OK.
	183	* kCMSSignerNeedsDetachedContent : a call to CMSDecoderSetDetachedContent()
	184	* is required to ascertain the signature status.
	185	* kCMSSignerInvalidSignature : bad signature.
	186	* kCMSSignerInvalidCert : an error occurred verifying the signer's certificate.
	187	* Further information available via the secTrust and
	188	* certVerifyResultCode parameters. This will never be
	189	* returned if evaluateSecTrust is FALSE.
	190	* kCMSSignerInvalidIndex : specified signerIndex is larger than the number of
	191	* signers (minus 1).
	192	*
	193	* secTrustOut -- The SecTrust object used to verify the signer's
	194	* certificate. Caller must CFRelease this.
	195	* certVerifyResultCodeOut -- The result of the certificate verification. If
196	* the evaluateSecTrust argument is set to FALSE on
197	* input, this out parameter is undefined on return.
198	*
199	* The certVerifyResultCode value can indicate a large number of errors; some of
200	* the most common and interesting errors are:
201	*
202	* CSSMERR_TP_INVALID_ANCHOR_CERT : The cert was verified back to a
203	* self-signed (root) cert which was present in the message, but
204	* that root cert is not a known, trusted root cert.
205	* CSSMERR_TP_NOT_TRUSTED: The cert could not be verified back to
206	* a root cert.
207	* CSSMERR_TP_VERIFICATION_FAILURE: A root cert was found which does
208	* not self-verify.
209	* CSSMERR_TP_VERIFY_ACTION_FAILED: Indicates a failure of the requested
210	* policy action.
211	* CSSMERR_TP_INVALID_CERTIFICATE: Indicates a bad leaf cert.
212	* CSSMERR_TP_CERT_EXPIRED: A cert in the chain was expired at the time of
213	* verification.
214	* CSSMERR_TP_CERT_NOT_VALID_YET: A cert in the chain was not yet valie at
215	* the time of verification.
216	*/
217	OSStatus CMSDecoderCopySignerStatus(
5c19dc3a A	218	CMSDecoderRef cmsDecoder,
	219	size_t signerIndex,
	220	CFTypeRef policyOrArray,
	221	Boolean evaluateSecTrust,
	222	CMSSignerStatus * __nullable signerStatusOut, /* optional; RETURNED */
	223	SecTrustRef * __nullable CF_RETURNS_RETAINED secTrustOut, /* optional; RETURNED */
	224	OSStatus * __nullable certVerifyResultCodeOut) /* optional; RETURNED */
b1ab9ed8 A	225	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	226
	227	/*
	228	* Obtain the email address of signer 'signerIndex' of a CMS message, if
	229	* present.
	230	*
427c49bc	231	* Returns errSecParam if the CMS message was not signed or if signerIndex
b1ab9ed8 A	232	* is greater than the number of signers of the message minus one.
	233	*
	234	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	235	*/
	236	OSStatus CMSDecoderCopySignerEmailAddress(
	237	CMSDecoderRef cmsDecoder,
	238	size_t signerIndex,
5c19dc3a	239	CFStringRef * __nonnull CF_RETURNS_RETAINED signerEmailAddressOut) /* RETURNED */
b1ab9ed8 A	240	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	241
	242	/*
	243	* Obtain the certificate of signer 'signerIndex' of a CMS message, if
	244	* present.
	245	*
427c49bc	246	* Returns errSecParam if the CMS message was not signed or if signerIndex
b1ab9ed8 A	247	* is greater than the number of signers of the message minus one.
	248	*
	249	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	250	*/
	251	OSStatus CMSDecoderCopySignerCert(
	252	CMSDecoderRef cmsDecoder,
	253	size_t signerIndex,
5c19dc3a	254	SecCertificateRef * __nonnull CF_RETURNS_RETAINED signerCertOut) /* RETURNED */
b1ab9ed8 A	255	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	256
	257	/*
	258	* Determine whether a CMS message was encrypted. Returns TRUE if so, FALSE if not.
	259	* Note that if the message was encrypted, and the decoding succeeded, (i.e.,
427c49bc	260	* CMSDecoderFinalizeMessage() returned errSecSuccess), then the message was successfully
b1ab9ed8 A	261	* decrypted.
	262	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	263	*/
	264	OSStatus CMSDecoderIsContentEncrypted(
	265	CMSDecoderRef cmsDecoder,
	266	Boolean *isEncryptedOut)
	267	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	268
	269	/*
	270	* Obtain the eContentType OID for a SignedData's EncapsulatedContentType, if
	271	* present. If the message was not signed this will return NULL.
	272	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	273	* The returned OID's data is in the same format as a CSSM_OID; i.e., it's
	274	* the encoded content of the OID, not including the tag and length bytes.
	275	*/
	276	OSStatus CMSDecoderCopyEncapsulatedContentType(
	277	CMSDecoderRef cmsDecoder,
5c19dc3a	278	CFDataRef * __nonnull CF_RETURNS_RETAINED eContentTypeOut) /* RETURNED */
b1ab9ed8 A	279	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	280
	281	/*
	282	* Obtain an array of all of the certificates in a message. Elements of the
	283	* returned array are SecCertificateRefs. The caller must CFRelease the returned
	284	* array. If a message does not contain any certificates (which is the case for
	285	* a message which is encrypted but not signed), the returned *certs value
427c49bc	286	* is NULL. The function will return errSecSuccess in this case.
b1ab9ed8 A	287	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	288	*/
	289	OSStatus CMSDecoderCopyAllCerts(
	290	CMSDecoderRef cmsDecoder,
5c19dc3a	291	CFArrayRef * __nonnull CF_RETURNS_RETAINED certsOut) /* RETURNED */
b1ab9ed8 A	292	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	293
	294	/*
	295	* Obtain the actual message content (payload), if any. If the message was
	296	* signed with detached content this will return NULL.
	297	* Caller must CFRelease the result.
	298	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	299	*/
	300	OSStatus CMSDecoderCopyContent(
	301	CMSDecoderRef cmsDecoder,
5c19dc3a	302	CFDataRef * __nonnull CF_RETURNS_RETAINED contentOut) /* RETURNED */
b1ab9ed8 A	303	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	304
	305	/*
	306	* Obtain the signing time of signer 'signerIndex' of a CMS message, if
	307	* present. This is an unauthenticate time, although it is part of the
	308	* signed attributes of the message.
	309	*
427c49bc	310	* Returns errSecParam if the CMS message was not signed or if signerIndex
b1ab9ed8 A	311	* is greater than the number of signers of the message minus one.
	312	*
	313	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	314	*/
	315	OSStatus CMSDecoderCopySignerSigningTime(
	316	CMSDecoderRef cmsDecoder,
	317	size_t signerIndex,
	318	CFAbsoluteTime signingTime) / RETURNED */
	319	__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);
	320
	321	/*
	322	* Obtain the timestamp of signer 'signerIndex' of a CMS message, if
	323	* present. This timestamp is an authenticated timestamp provided by
	324	* a timestamping authority.
	325	*
427c49bc	326	* Returns errSecParam if the CMS message was not signed or if signerIndex
b1ab9ed8 A	327	* is greater than the number of signers of the message minus one.
	328	*
	329	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	330	*/
	331	OSStatus CMSDecoderCopySignerTimestamp(
	332	CMSDecoderRef cmsDecoder,
	333	size_t signerIndex,
	334	CFAbsoluteTime timestamp) / RETURNED */
	335	__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);
	336
d8f41ccd A	337	/*
	338	* Obtain the timestamp of signer 'signerIndex' of a CMS message, if
	339	* present. This timestamp is an authenticated timestamp provided by
	340	* a timestamping authority. Use the policy provided as a parameter
	341	*
	342	* Returns errSecParam if the CMS message was not signed or if signerIndex
	343	* is greater than the number of signers of the message minus one.
	344	*
	345	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	346	*/
	347	OSStatus CMSDecoderCopySignerTimestampWithPolicy(
	348	CMSDecoderRef cmsDecoder,
5c19dc3a	349	CFTypeRef __nullable timeStampPolicy,
d8f41ccd A	350	size_t signerIndex, /* usually 0 */
	351	CFAbsoluteTime timestamp) / RETURNED */
	352	__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_NA);
	353
b1ab9ed8 A	354	/*
	355	* Obtain an array of the certificates in a timestamp response. Elements of the
	356	* returned array are SecCertificateRefs. The caller must CFRelease the returned
	357	* array. This timestamp is an authenticated timestamp provided by
	358	* a timestamping authority.
	359	*
427c49bc	360	* Returns errSecParam if the CMS message was not signed or if signerIndex
b1ab9ed8 A	361	* is greater than the number of signers of the message minus one. It returns
	362	* errSecItemNotFound if no certificates were found.
	363	*
	364	* This cannot be called until after CMSDecoderFinalizeMessage() is called.
	365	*/
	366	OSStatus CMSDecoderCopySignerTimestampCertificates(
	367	CMSDecoderRef cmsDecoder,
5c19dc3a A	368	size_t signerIndex, /* usually 0 */
5c19dc3a A	369	CFArrayRef * __nonnull CF_RETURNS_RETAINED certificateRefs) /* RETURNED */
b1ab9ed8 A	370	__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);
b1ab9ed8 A	371
5c19dc3a A	372	CF_ASSUME_NONNULL_END
5c19dc3a A	373
b1ab9ed8 A	374	#ifdef __cplusplus
	375	}
	376	#endif
	377
	378	#endif /* _CMS_DECODER_H_ */
	379