Security-55471.14.18.tar.gz

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

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

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

CFTypeID CMSDecoderGetTypeID(void);

/*
 * Status of signature and signer information in a signed message.
 */
enum {
	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 */
};
typedef uint32_t CMSSignerStatus;

/*
 * Create a CMSDecoder. Result must eventually be freed via CFRelease().
 */
OSStatus CMSDecoderCreate(
	CMSDecoderRef		*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			*detachedContentOut)	/* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * Optionally specify a SecKeychainRef, or an array of them, containing
 * intermediate certs to be used in verifying a signed message's signer
 * certs. By default, the default keychain search list is used for this. 
 * Specify an empty CFArrayRef to search *no* keychains for intermediate
 * certs. 
 * If this is called, it must be called before CMSDecoderCopySignerStatus().
 */
OSStatus CMSDecoderSetSearchKeychain(
	CMSDecoderRef		cmsDecoder,
	CFTypeRef			keychainOrArray)
    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*
 * 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		*signerStatusOut,			/* optional; RETURNED */
	SecTrustRef			*secTrustOut,				/* optional; RETURNED */
	OSStatus			*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			*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	*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			*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			*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			*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 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          *certificateRefs)       /* RETURNED */
    __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);

#ifdef __cplusplus
}
#endif

#endif	/* _CMS_DECODER_H_ */