[apple/security.git] / AppleX509TP / TPCertInfo.h

/*
 * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
 * 
 * The contents of this file constitute Original Code as defined in and are
 * subject to the Apple Public Source License Version 1.2 (the 'License').
 * You may not use this file except in compliance with the License. Please obtain
 * a copy of the License at http://www.apple.com/publicsource and read it before
 * using this file.
 * 
 * This 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.
 */


/*
 * TPCertInfo.h - TP's private certificate info and cert group classes
 *
 * Written 10/23/2000 by Doug Mitchell.
 */
 
#ifndef	_TP_CERT_INFO_H_
#define _TP_CERT_INFO_H_

#include <Security/cssmtype.h>
#include <Security/utilities.h>
#include <Security/cssmalloc.h>
#include <Security/threading.h>
#include <Security/globalizer.h>

/* protects TP-wide access to time() and gmtime() */
extern ModuleNexus<Mutex> tpTimeLock;

/* 
 * Prototypes for functions which are isomorphic between certs and CRLs at the
 * CL API.
 */
typedef CSSM_RETURN (*clGetFirstFieldFcn)(
	CSSM_CL_HANDLE CLHandle,
	CSSM_HANDLE ItemHandle,			// cached cert or CRL
	const CSSM_OID *ItemField,
	CSSM_HANDLE_PTR ResultsHandle,
	uint32 *NumberOfMatchedFields,
	CSSM_DATA_PTR *Value);
typedef CSSM_RETURN (*clAbortQueryFcn)(
	CSSM_CL_HANDLE CLHandle,
	CSSM_HANDLE ResultsHandle);		// from clGetFirstFieldFcn
typedef CSSM_RETURN (*clCacheItemFcn)(
	CSSM_CL_HANDLE CLHandle,
	const CSSM_DATA *Item,			// raw cert or CRL
	CSSM_HANDLE_PTR CertHandle);
typedef CSSM_RETURN (*clAbortCacheFcn)(
	CSSM_CL_HANDLE CLHandle,
	CSSM_HANDLE ItemHandle);		// from clCacheItemFcn
typedef CSSM_RETURN (*clItemVfyFcn)(
	CSSM_CL_HANDLE CLHandle,
	CSSM_CC_HANDLE CCHandle,
	const CSSM_DATA *CrlOrCertToBeVerified,
	const CSSM_DATA *SignerCert,
	const CSSM_FIELD *VerifyScope,
	uint32 ScopeSize);

typedef struct {
	/* CL/cert-specific functions */
	clGetFirstFieldFcn	getField;
	clAbortQueryFcn		abortQuery;
	clCacheItemFcn		cacheItem;
	clAbortCacheFcn		abortCache;
	clItemVfyFcn		itemVerify;
	/* CL/cert-specific OIDs */
	const CSSM_OID		*notBeforeOid;
	const CSSM_OID		*notAfterOid;
	/* CL/cert specific errors */
	CSSM_RETURN			invalidItemRtn;	// CSSMERR_TP_INVALID_{CERT,CRL}_POINTER
	CSSM_RETURN			expiredRtn;		
	CSSM_RETURN			notValidYetRtn;
} TPClItemCalls;

class TPCertInfo;

/*
 * On construction of a TPClItemInfo, specifies whether or not to 
 * copy the incoming item data (in which we free it upon destruction)
 * or to use caller's data as is (in which case the caller maintains 
 * the data).
 */
typedef enum {
	TIC_None = 0,		// never used
	TIC_NoCopy,			// caller maintains
	TIC_CopyData		// we copy and free
} TPItemCopy;
 
/*
 * State of a cert's mIsRoot flag. We do signature self-verify on demand.
 */
typedef enum {
	TRS_Unknown,		// initial state
	TRS_NamesMatch,		// subject == issuer, but no sig verify yet
	TRS_NotRoot,		// subject != issuer, OR sig verify failed
	TRS_IsRoot			// it's a root
} TPRootState;

/*
 * Base class for TPCertInfo and TPCrlInfo. Encapsulates caching of 
 * an entity within the CL, field lookup/free, and signature verify,
 * all of which use similar functions at the CL API.
 */
class TPClItemInfo
{
	NOCOPY(TPClItemInfo)
public:
	TPClItemInfo(
		CSSM_CL_HANDLE		clHand,
		CSSM_CSP_HANDLE		cspHand,
		const TPClItemCalls	&clCalls,
		const CSSM_DATA		*itemData,
		TPItemCopy			copyItemData,		
		const char			*verifyTime);		// may be NULL
				
	~TPClItemInfo();
	void releaseResources();
	
	/* 
	 * Fetch arbitrary field from cached cert.
	 * Only should be used when caller is sure there is either zero or one
	 * of the requested fields present in the cert.
	 */
	CSSM_RETURN fetchField(
		const CSSM_OID	*fieldOid,
		CSSM_DATA_PTR	*fieldData);			// mallocd by CL and RETURNED

	/* free arbitrary field obtained from fetchField() */
	CSSM_RETURN freeField( 
		const CSSM_OID	*fieldOid,
		CSSM_DATA_PTR	fieldData);

	/* 
	 * Verify with an issuer cert - works on certs and CRLs.
	 * Issuer/subject name match already performed by caller.
	 * May return CSSMERR_CSP_APPLE_PUBLIC_KEY_INCOMPLETE without
	 * performing a signature op, in which case it is the caller's 
	 * resposibility to complete this operation later when 
	 * sufficient information is available.
	 *
	 * Optional paramCert is used to provide parameters when issuer
	 * has a partial public key.
	 */
	CSSM_RETURN verifyWithIssuer(
		TPCertInfo		*issuerCert,
		TPCertInfo		*paramCert = NULL) const;

	/* accessors */
	CSSM_CL_HANDLE	clHand()	  	const { return mClHand; }
	CSSM_CSP_HANDLE	cspHand()	  	const { return mCspHand; }
	CSSM_HANDLE		cacheHand()	  	const { return mCacheHand; }
	const CSSM_DATA *itemData()	  	const { return mItemData; }
	const CSSM_DATA *issuerName() 	const { return mIssuerName; };				
	unsigned 		index()			const { return mIndex; }	
	void 			index(unsigned dex)	  { mIndex = dex; }
	bool			isExpired()			  { return mIsExpired; }
	bool			isNotValidYet()		  { return mIsNotValidYet; }
	
	/* 
	 * Calculate validity (not before/after). Returns 
	 * 		CSSMERR_{TP_CERT,APPLETP_CRL}_NOT_VALID_YET
	 *		CSSMERR_xxx_T_EXPIRED
	 *		CSSM_OK
	 *		CSSMERR_xxx_INVALID_CERT_POINTER, other "bogus cert" errors
	 */
	CSSM_RETURN calculateCurrent(
		const char 			*verifyString = NULL);
		
private:

	/* Tell CL to parse and cache the item */
	CSSM_RETURN cacheItem(
		const CSSM_DATA		*itemData,
		TPItemCopy			copyItemData);			
													
		
	/* fetch not before/after fields */
	void fetchNotBeforeAfter();
		
	CSSM_CL_HANDLE			mClHand;				// always valid
	CSSM_CSP_HANDLE			mCspHand;				// always valid
	const TPClItemCalls		&mClCalls;
	bool					mWeOwnTheData;			// if true, we have to free 
													//    mCertData
	/* following four valid subsequent to cacheItem(), generally
	 * called by subclass's constructor */
	CSSM_HANDLE				mCacheHand;	
	CSSM_DATA_PTR			mIssuerName;
	CSSM_DATA				*mItemData;	
	CSSM_ALGORITHMS			mSigAlg;

	/* calculated implicitly at construction */
	struct tm				mNotBefore;
	struct tm				mNotAfter;
	
	/* also calculated at construction, but can be recalculated at will */
	bool					mIsExpired;
	bool					mIsNotValidYet;
	
	unsigned				mIndex;
};

/*
 * Class representing one certificate. The raw cert data usually comes from
 * a client (via incoming cert groups in CertGroupConstruct() and 
 * CertGroupVerify()); in this case, we don't own the raw data and 
 * don't copy or free it. Caller can optionally specify that we copy 
 * (and own and eventually free) the raw cert data. Currently this is 
 * only done when we find a cert in a DlDb. The constructor throws 
 * on any error (bad cert data); subsequent to successful construction, no CSSM 
 * errors are thrown and it's guaranteed that the cert is basically good and 
 * successfully cached in the CL, and that we have a locally cached subject 
 * and issuer name (in normalized encoded format). 
 */ 
class TPCertInfo : public TPClItemInfo
{
	NOCOPY(TPCertInfo)
public:
	/* 
	 * No default constructor - this is the only way.
	 * This caches the cert and fetches subjectName and issuerName
	 * to ensure the incoming certData is well-constructed.
	 */
	TPCertInfo(
		CSSM_CL_HANDLE		clHand,
		CSSM_CSP_HANDLE		cspHand,
		const CSSM_DATA		*certData,
		TPItemCopy			copyCertData,	
											
		const char			*verifyTime);		// may be NULL
		
	/* frees mSubjectName, mIssuerName, mCacheHand via mClHand */
	~TPCertInfo();
	
	/* accessors */
	const CSSM_DATA *subjectName();

	bool 		isSelfSigned();

	bool		isAnchor()				{ return mIsAnchor; }
	void		isAnchor(bool a)		{ mIsAnchor = a; }
	bool		isFromNet()				{ return mIsFromNet; }
	void		isFromNet(bool n)		{ mIsFromNet = n; };
	unsigned	numStatusCodes()		{ return mNumStatusCodes; }
	CSSM_RETURN	*statusCodes()			{ return mStatusCodes; }
	CSSM_DL_DB_HANDLE dlDbHandle()		{ return mDlDbHandle; }
	void dlDbHandle(CSSM_DL_DB_HANDLE hand)
										{ mDlDbHandle = hand; }
	CSSM_DB_UNIQUE_RECORD_PTR uniqueRecord()
										{ return mUniqueRecord; }
	void uniqueRecord(CSSM_DB_UNIQUE_RECORD_PTR rec)
										{ mUniqueRecord = rec; }
	CSSM_KEY_PTR pubKey()				{ return mPublicKey; }
	bool		used()					{ return mUsed; }
	void 		used(bool u)			{ mUsed = u; }
	bool		isLeaf()				{ return mIsLeaf; }
	void		isLeaf(bool l)			{ mIsLeaf = l; }
	/*
	 * Am I the issuer of the specified subject item? Returns true if so.
	 * Works for subject certs as well as CRLs. 
	 */
	bool isIssuerOf(
		const TPClItemInfo	&subject);
		
	void addStatusCode(
		CSSM_RETURN 		code);

	/* 
	 * Indicate whether this cert's public key is a CSSM_KEYATTR_PARTIAL
	 * key.
	 */
	bool 					hasPartialKey();
	 
private:
	/* obtained from CL at construction */
	CSSM_DATA_PTR			mSubjectName;		// always valid
	CSSM_KEY_PTR			mPublicKey;
	
	/* maintained by caller, default at constructor 0/false */
	bool					mIsAnchor;
	bool					mIsFromDb;
	bool					mIsFromNet;
	unsigned				mNumStatusCodes;
	CSSM_RETURN				*mStatusCodes;
	CSSM_DL_DB_HANDLE		mDlDbHandle;
	CSSM_DB_UNIQUE_RECORD_PTR mUniqueRecord;
	bool					mUsed;			// e.g., used in current loop 
	bool					mIsLeaf;		// first in chain
	TPRootState				mIsRoot;		// subject == issuer

	void 					releaseResources();
};

/* Describe who owns the items in a TP{Cert,Crl}Group */
typedef enum {
	TGO_None = 0,		// not used
	TGO_Group,			// TP{Cert,Crl}Group owns the items
	TGO_Caller			// caller owns the items
} TPGroupOwner;

/*
 * TP's private Cert Group class. Provides a list of TPCertInfo pointers, 
 * to which caller can append additional elements, access an element at 
 * an arbitrary position, and remover an element at an arbitrrary position. 
 */
class TPCertGroup
{
	NOCOPY(TPCertGroup)
public:
	/*
	 * No default constructor.
	 * This one creates an empty TPCertGroup.
	 */
	TPCertGroup(
		CssmAllocator		&alloc,
		TPGroupOwner		whoOwns);		// if TGO_Group, we delete
	
	/*
	 * Construct from unordered, untrusted CSSM_CERTGROUP. Resulting
	 * TPCertInfos are more or less in the same order as the incoming
	 * certs, though incoming certs are discarded if they don't parse.
	 * No verification of any sort is performed. 
	 */
	TPCertGroup(
		const CSSM_CERTGROUP 	&CertGroupFrag,
		CSSM_CL_HANDLE 			clHand,
		CSSM_CSP_HANDLE 		cspHand,
		CssmAllocator			&alloc,
		const char				*verifyString,			// may be NULL
		bool					firstCertMustBeValid,
		TPGroupOwner			whoOwns);	
		
	/*
	 * Deletes all TPCertInfo's.
	 */
	~TPCertGroup();
	
	/*
	 * Construct ordered, verified cert chain from a variety of inputs. 
	 * Time validity is ignored and needs to be checked by caller (it's
	 * stored in each TPCertInfo we add to ourself during construction).
	 * The only error returned is CSSMERR_APPLETP_INVALID_ROOT, meaning 
	 * we verified back to a supposed root cert which did not in fact
	 * self-verify. Other interesting status is returned via the
	 * verifiedToRoot and verifiedToAnchor flags. 
	 *
	 * NOTE: is it the caller's responsibility to call setAllUnused() 
	 * for both incoming cert groups (inCertGroup and gatheredCerts). 
	 * We don't do that here because we may call ourself recursively. 
	 *
	 * subjectItem may or may not be in the cert group (currently, it
	 * is in the group if it's a cert and it's not if it's a CRL, but 
	 * we don't rely on that). 
	 */
	CSSM_RETURN buildCertGroup(
		const TPClItemInfo		&subjectItem,	// Cert or CRL
		TPCertGroup				*inCertGroup,	// optional
		const CSSM_DL_DB_LIST 	*dbList,		// optional
		CSSM_CL_HANDLE 			clHand,
		CSSM_CSP_HANDLE 		cspHand,
		const char 				*verifyString,	// optional, for establishing
												//   validity of new TPCertInfos
		/* trusted anchors, optional */
		/* FIXME - maybe this should be a TPCertGroup */
		uint32 					numAnchorCerts,
		const CSSM_DATA			*anchorCerts,
		
		/* 
		 * Certs to be freed by caller (i.e., TPCertInfo which we allocate
		 * as a result of using a cert from anchorCerts or dbList) are added
		 * to this group.
		 */
		TPCertGroup				&certsToBeFreed,
		
		/*
		* Other certificates gathered during the course of this operation,
		* currently consisting of certs fetched from DBs and from the net.
		* This is not used when called by AppleTPSession::CertGroupConstructPriv;
		* it's an optimization for the case when we're building a cert group
		* for TPCrlInfo::verifyWithContext - we avoid re-fetching certs from
		* the net which are needed to verify both the subject cert and a CRL.
		*/
		TPCertGroup				*gatheredCerts,
		
		/*
		* Indicates that subjectItem is the last element in this cert group.
		* If true, that cert will be tested for "root-ness", including 
		*   -- subject/issuer compare
		*   -- signature self-verify
		*   -- anchor compare
		*/
		CSSM_BOOL				subjectIsInGroup,
		
		/* currently, only CSSM_TP_ACTION_FETCH_CERT_FROM_NET is 
		 * interesting */
		CSSM_APPLE_TP_ACTION_FLAGS	actionFlags,
		
		/* returned */
		CSSM_BOOL				&verifiedToRoot,	// end of chain self-verifies
		CSSM_BOOL				&verifiedToAnchor);	// end of chain in anchors
		
	/* add/remove/access TPTCertInfo's. */
	void appendCert(
		TPCertInfo			*certInfo);			// appends to end of mCertInfo
	TPCertInfo *certAtIndex(
		unsigned			index);
	TPCertInfo *removeCertAtIndex(
		unsigned			index);				// doesn't delete the cert, just 
												// removes it from our list
	unsigned numCerts() const 					// how many do we have? 
		{ return mNumCerts; }
		
	/* 
	 * Convenience accessors for first and last cert, only valid when we have
	 * at least one cert.
	 */
	TPCertInfo *firstCert();
	TPCertInfo *lastCert();
		
	/* build a CSSM_CERTGROUP corresponding with our mCertInfo */
	CSSM_CERTGROUP_PTR buildCssmCertGroup();

	/* build a CSSM_TP_APPLE_EVIDENCE_INFO array corresponding with our
	 * mCertInfo */
	CSSM_TP_APPLE_EVIDENCE_INFO *buildCssmEvidenceInfo();
		
	/* Given a status for basic construction of a cert group and a status
	 * of (optional) policy verification, plus the implicit notBefore/notAfter
	 * status in the certs, calculate a global return code. This just 
	 * encapsulates a policy for CertGroupeConstruct and CertGroupVerify.
	 */
	CSSM_RETURN getReturnCode(
		CSSM_RETURN constructStatus,
		CSSM_BOOL	allowExpired,
		CSSM_BOOL	allowExpiredRoot,
		CSSM_RETURN policyStatus = CSSM_OK);
	 
	CssmAllocator
		&alloc() {return mAlloc; }
	
	/* set all TPCertInfo.mUsed flags false */
	void					setAllUnused();
	
private:
	
	/* 
	 * Search unused incoming certs to find an issuer of specified 
	 * cert or CRL.
	 * WARNING this assumes a valied "used" state for all certs 
	 * in this group.
	 * If partialIssuerKey is true on return, caller must re-verify signature
     * of subject later when sufficient info is available. 
	 */ 
	TPCertInfo *findIssuerForCertOrCrl(
		const TPClItemInfo 	&subject,
		bool				&partialIssuerKey);

	/* 
	 * Called from buildCertGroup as final processing of a constructed
	 * group when CSSMERR_CSP_APPLE_PUBLIC_KEY_INCOMPLETE has been
	 * detected. Perform partial public key processing.
	 * Returns:
	 *   	CSSMERR_TP_CERTIFICATE_CANT_OPERATE - can't complete partial key
	 *		CSSMERR_TP_INVALID_CERT_AUTHORITY - sig verify failed with 
	 *			(supposedly) completed partial key
	 */
	CSSM_RETURN				verifyWithPartialKeys(
		const TPClItemInfo	&subjectItem);		// Cert or CRL
	
	CssmAllocator			&mAlloc;
	TPCertInfo				**mCertInfo;		// just an array of pointers
	unsigned				mNumCerts;			// valid certs in certInfo
	unsigned				mSizeofCertInfo;	// mallocd space in certInfo
	TPGroupOwner			mWhoOwns;			// if TGO_Group, we delete certs 
												//    upon destruction
};
#endif	/* _TP_CERT_INFO_H_ */
Commit	Line	Data
bac41a7b A	1	/*
	2	* Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
	3	*
	4	* The contents of this file constitute Original Code as defined in and are
	5	* subject to the Apple Public Source License Version 1.2 (the 'License').
	6	* You may not use this file except in compliance with the License. Please obtain
	7	* a copy of the License at http://www.apple.com/publicsource and read it before
	8	* using this file.
	9	*
	10	* This Original Code and all software distributed under the License are
	11	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
	12	* OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
	13	* LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
	14	* PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
	15	* specific language governing rights and limitations under the License.
	16	*/
	17
	18
	19	/*
	20	* TPCertInfo.h - TP's private certificate info and cert group classes
	21	*
	22	* Written 10/23/2000 by Doug Mitchell.
	23	*/
	24
	25	#ifndef _TP_CERT_INFO_H_
	26	#define _TP_CERT_INFO_H_
	27
	28	#include <Security/cssmtype.h>
	29	#include <Security/utilities.h>
	30	#include <Security/cssmalloc.h>
29654253 A	31	#include <Security/threading.h>
	32	#include <Security/globalizer.h>
	33
29654253 A	34	/* protects TP-wide access to time() and gmtime() */
29654253 A	35	extern ModuleNexus<Mutex> tpTimeLock;
bac41a7b	36
df0e469f A	37	/*
	38	* Prototypes for functions which are isomorphic between certs and CRLs at the
	39	* CL API.
	40	*/
	41	typedef CSSM_RETURN (*clGetFirstFieldFcn)(
	42	CSSM_CL_HANDLE CLHandle,
	43	CSSM_HANDLE ItemHandle, // cached cert or CRL
	44	const CSSM_OID *ItemField,
	45	CSSM_HANDLE_PTR ResultsHandle,
	46	uint32 *NumberOfMatchedFields,
	47	CSSM_DATA_PTR *Value);
	48	typedef CSSM_RETURN (*clAbortQueryFcn)(
	49	CSSM_CL_HANDLE CLHandle,
	50	CSSM_HANDLE ResultsHandle); // from clGetFirstFieldFcn
	51	typedef CSSM_RETURN (*clCacheItemFcn)(
	52	CSSM_CL_HANDLE CLHandle,
	53	const CSSM_DATA *Item, // raw cert or CRL
	54	CSSM_HANDLE_PTR CertHandle);
	55	typedef CSSM_RETURN (*clAbortCacheFcn)(
	56	CSSM_CL_HANDLE CLHandle,
	57	CSSM_HANDLE ItemHandle); // from clCacheItemFcn
	58	typedef CSSM_RETURN (*clItemVfyFcn)(
	59	CSSM_CL_HANDLE CLHandle,
	60	CSSM_CC_HANDLE CCHandle,
	61	const CSSM_DATA *CrlOrCertToBeVerified,
	62	const CSSM_DATA *SignerCert,
	63	const CSSM_FIELD *VerifyScope,
	64	uint32 ScopeSize);
	65
	66	typedef struct {
	67	/* CL/cert-specific functions */
	68	clGetFirstFieldFcn getField;
	69	clAbortQueryFcn abortQuery;
	70	clCacheItemFcn cacheItem;
	71	clAbortCacheFcn abortCache;
	72	clItemVfyFcn itemVerify;
	73	/* CL/cert-specific OIDs */
	74	const CSSM_OID *notBeforeOid;
	75	const CSSM_OID *notAfterOid;
	76	/* CL/cert specific errors */
	77	CSSM_RETURN invalidItemRtn; // CSSMERR_TP_INVALID_{CERT,CRL}_POINTER
	78	CSSM_RETURN expiredRtn;
	79	CSSM_RETURN notValidYetRtn;
	80	} TPClItemCalls;
	81
	82	class TPCertInfo;
	83
bac41a7b	84	/*
df0e469f A	85	* On construction of a TPClItemInfo, specifies whether or not to
	86	* copy the incoming item data (in which we free it upon destruction)
	87	* or to use caller's data as is (in which case the caller maintains
	88	* the data).
	89	*/
	90	typedef enum {
	91	TIC_None = 0, // never used
	92	TIC_NoCopy, // caller maintains
	93	TIC_CopyData // we copy and free
	94	} TPItemCopy;
	95
	96	/*
	97	* State of a cert's mIsRoot flag. We do signature self-verify on demand.
	98	*/
	99	typedef enum {
	100	TRS_Unknown, // initial state
	101	TRS_NamesMatch, // subject == issuer, but no sig verify yet
	102	TRS_NotRoot, // subject != issuer, OR sig verify failed
	103	TRS_IsRoot // it's a root
	104	} TPRootState;
	105
	106	/*
	107	* Base class for TPCertInfo and TPCrlInfo. Encapsulates caching of
	108	* an entity within the CL, field lookup/free, and signature verify,
	109	* all of which use similar functions at the CL API.
	110	*/
	111	class TPClItemInfo
bac41a7b	112	{
df0e469f	113	NOCOPY(TPClItemInfo)
bac41a7b	114	public:
df0e469f	115	TPClItemInfo(
bac41a7b	116	CSSM_CL_HANDLE clHand,
df0e469f A	117	CSSM_CSP_HANDLE cspHand,
	118	const TPClItemCalls &clCalls,
	119	const CSSM_DATA *itemData,
	120	TPItemCopy copyItemData,
	121	const char *verifyTime); // may be NULL
	122
	123	~TPClItemInfo();
	124	void releaseResources();
bac41a7b A	125
	126	/*
	127	* Fetch arbitrary field from cached cert.
	128	* Only should be used when caller is sure there is either zero or one
	129	* of the requested fields present in the cert.
	130	*/
	131	CSSM_RETURN fetchField(
	132	const CSSM_OID *fieldOid,
	133	CSSM_DATA_PTR *fieldData); // mallocd by CL and RETURNED
	134
	135	/* free arbitrary field obtained from fetchField() */
	136	CSSM_RETURN freeField(
	137	const CSSM_OID *fieldOid,
	138	CSSM_DATA_PTR fieldData);
df0e469f A	139
	140	/*
	141	* Verify with an issuer cert - works on certs and CRLs.
	142	* Issuer/subject name match already performed by caller.
	143	* May return CSSMERR_CSP_APPLE_PUBLIC_KEY_INCOMPLETE without
	144	* performing a signature op, in which case it is the caller's
	145	* resposibility to complete this operation later when
	146	* sufficient information is available.
	147	*
	148	* Optional paramCert is used to provide parameters when issuer
	149	* has a partial public key.
	150	*/
	151	CSSM_RETURN verifyWithIssuer(
	152	TPCertInfo *issuerCert,
	153	TPCertInfo *paramCert = NULL) const;
	154
	155	/* accessors */
	156	CSSM_CL_HANDLE clHand() const { return mClHand; }
	157	CSSM_CSP_HANDLE cspHand() const { return mCspHand; }
	158	CSSM_HANDLE cacheHand() const { return mCacheHand; }
	159	const CSSM_DATA *itemData() const { return mItemData; }
	160	const CSSM_DATA *issuerName() const { return mIssuerName; };
	161	unsigned index() const { return mIndex; }
	162	void index(unsigned dex) { mIndex = dex; }
	163	bool isExpired() { return mIsExpired; }
	164	bool isNotValidYet() { return mIsNotValidYet; }
	165
	166	/*
	167	* Calculate validity (not before/after). Returns
	168	* CSSMERR_{TP_CERT,APPLETP_CRL}_NOT_VALID_YET
	169	* CSSMERR_xxx_T_EXPIRED
	170	* CSSM_OK
	171	* CSSMERR_xxx_INVALID_CERT_POINTER, other "bogus cert" errors
	172	*/
	173	CSSM_RETURN calculateCurrent(
	174	const char *verifyString = NULL);
	175
	176	private:
	177
	178	/* Tell CL to parse and cache the item */
	179	CSSM_RETURN cacheItem(
	180	const CSSM_DATA *itemData,
	181	TPItemCopy copyItemData);
	182
	183
	184	/* fetch not before/after fields */
	185	void fetchNotBeforeAfter();
	186
	187	CSSM_CL_HANDLE mClHand; // always valid
	188	CSSM_CSP_HANDLE mCspHand; // always valid
	189	const TPClItemCalls &mClCalls;
	190	bool mWeOwnTheData; // if true, we have to free
	191	// mCertData
	192	/* following four valid subsequent to cacheItem(), generally
	193	* called by subclass's constructor */
	194	CSSM_HANDLE mCacheHand;
	195	CSSM_DATA_PTR mIssuerName;
	196	CSSM_DATA *mItemData;
	197	CSSM_ALGORITHMS mSigAlg;
	198
	199	/* calculated implicitly at construction */
	200	struct tm mNotBefore;
	201	struct tm mNotAfter;
	202
203	/* also calculated at construction, but can be recalculated at will */
204	bool mIsExpired;
205	bool mIsNotValidYet;
206
207	unsigned mIndex;
208	};
209
210	/*
211	* Class representing one certificate. The raw cert data usually comes from
212	* a client (via incoming cert groups in CertGroupConstruct() and
213	* CertGroupVerify()); in this case, we don't own the raw data and
214	* don't copy or free it. Caller can optionally specify that we copy
215	* (and own and eventually free) the raw cert data. Currently this is
216	* only done when we find a cert in a DlDb. The constructor throws
217	* on any error (bad cert data); subsequent to successful construction, no CSSM
218	* errors are thrown and it's guaranteed that the cert is basically good and
219	* successfully cached in the CL, and that we have a locally cached subject
220	* and issuer name (in normalized encoded format).
221	*/
222	class TPCertInfo : public TPClItemInfo
223	{
224	NOCOPY(TPCertInfo)
225	public:
226	/*
227	* No default constructor - this is the only way.
228	* This caches the cert and fetches subjectName and issuerName
229	* to ensure the incoming certData is well-constructed.
230	*/
231	TPCertInfo(
232	CSSM_CL_HANDLE clHand,
233	CSSM_CSP_HANDLE cspHand,
234	const CSSM_DATA *certData,
235	TPItemCopy copyCertData,
236
237	const char *verifyTime); // may be NULL
bac41a7b	238
df0e469f A	239	/* frees mSubjectName, mIssuerName, mCacheHand via mClHand */
	240	~TPCertInfo();
	241
bac41a7b	242	/* accessors */
bac41a7b	243	const CSSM_DATA *subjectName();
bac41a7b	244
df0e469f	245	bool isSelfSigned();
29654253	246
29654253 A	247	bool isAnchor() { return mIsAnchor; }
29654253 A	248	void isAnchor(bool a) { mIsAnchor = a; }
df0e469f A	249	bool isFromNet() { return mIsFromNet; }
df0e469f A	250	void isFromNet(bool n) { mIsFromNet = n; };
29654253 A	251	unsigned numStatusCodes() { return mNumStatusCodes; }
29654253 A	252	CSSM_RETURN *statusCodes() { return mStatusCodes; }
29654253 A	253	CSSM_DL_DB_HANDLE dlDbHandle() { return mDlDbHandle; }
	254	void dlDbHandle(CSSM_DL_DB_HANDLE hand)
	255	{ mDlDbHandle = hand; }
	256	CSSM_DB_UNIQUE_RECORD_PTR uniqueRecord()
	257	{ return mUniqueRecord; }
	258	void uniqueRecord(CSSM_DB_UNIQUE_RECORD_PTR rec)
	259	{ mUniqueRecord = rec; }
df0e469f A	260	CSSM_KEY_PTR pubKey() { return mPublicKey; }
	261	bool used() { return mUsed; }
	262	void used(bool u) { mUsed = u; }
	263	bool isLeaf() { return mIsLeaf; }
	264	void isLeaf(bool l) { mIsLeaf = l; }
	265	/*
	266	* Am I the issuer of the specified subject item? Returns true if so.
	267	* Works for subject certs as well as CRLs.
bac41a7b	268	*/
df0e469f A	269	bool isIssuerOf(
df0e469f A	270	const TPClItemInfo &subject);
bac41a7b	271
df0e469f A	272	void addStatusCode(
	273	CSSM_RETURN code);
	274
	275	/*
	276	* Indicate whether this cert's public key is a CSSM_KEYATTR_PARTIAL
	277	* key.
	278	*/
	279	bool hasPartialKey();
	280
bac41a7b	281	private:
df0e469f	282	/* obtained from CL at construction */
bac41a7b	283	CSSM_DATA_PTR mSubjectName; // always valid
df0e469f	284	CSSM_KEY_PTR mPublicKey;
bac41a7b	285
29654253	286	/* maintained by caller, default at constructor 0/false */
29654253 A	287	bool mIsAnchor;
29654253 A	288	bool mIsFromDb;
df0e469f	289	bool mIsFromNet;
29654253 A	290	unsigned mNumStatusCodes;
	291	CSSM_RETURN *mStatusCodes;
	292	CSSM_DL_DB_HANDLE mDlDbHandle;
	293	CSSM_DB_UNIQUE_RECORD_PTR mUniqueRecord;
df0e469f A	294	bool mUsed; // e.g., used in current loop
	295	bool mIsLeaf; // first in chain
	296	TPRootState mIsRoot; // subject == issuer
29654253	297
df0e469f	298	void releaseResources();
bac41a7b A	299	};
bac41a7b A	300
df0e469f A	301	/* Describe who owns the items in a TP{Cert,Crl}Group */
	302	typedef enum {
	303	TGO_None = 0, // not used
	304	TGO_Group, // TP{Cert,Crl}Group owns the items
	305	TGO_Caller // caller owns the items
	306	} TPGroupOwner;
	307
bac41a7b	308	/*
df0e469f A	309	* TP's private Cert Group class. Provides a list of TPCertInfo pointers,
	310	* to which caller can append additional elements, access an element at
	311	* an arbitrary position, and remover an element at an arbitrrary position.
bac41a7b A	312	*/
	313	class TPCertGroup
	314	{
df0e469f	315	NOCOPY(TPCertGroup)
bac41a7b A	316	public:
bac41a7b A	317	/*
df0e469f A	318	* No default constructor.
df0e469f A	319	* This one creates an empty TPCertGroup.
bac41a7b A	320	*/
	321	TPCertGroup(
	322	CssmAllocator &alloc,
df0e469f	323	TPGroupOwner whoOwns); // if TGO_Group, we delete
bac41a7b	324
df0e469f A	325	/*
	326	* Construct from unordered, untrusted CSSM_CERTGROUP. Resulting
	327	* TPCertInfos are more or less in the same order as the incoming
	328	* certs, though incoming certs are discarded if they don't parse.
	329	* No verification of any sort is performed.
	330	*/
	331	TPCertGroup(
	332	const CSSM_CERTGROUP &CertGroupFrag,
	333	CSSM_CL_HANDLE clHand,
	334	CSSM_CSP_HANDLE cspHand,
	335	CssmAllocator &alloc,
	336	const char *verifyString, // may be NULL
	337	bool firstCertMustBeValid,
	338	TPGroupOwner whoOwns);
	339
bac41a7b A	340	/*
	341	* Deletes all TPCertInfo's.
	342	*/
	343	~TPCertGroup();
	344
df0e469f A	345	/*
	346	* Construct ordered, verified cert chain from a variety of inputs.
	347	* Time validity is ignored and needs to be checked by caller (it's
	348	* stored in each TPCertInfo we add to ourself during construction).
	349	* The only error returned is CSSMERR_APPLETP_INVALID_ROOT, meaning
	350	* we verified back to a supposed root cert which did not in fact
	351	* self-verify. Other interesting status is returned via the
	352	* verifiedToRoot and verifiedToAnchor flags.
	353	*
	354	* NOTE: is it the caller's responsibility to call setAllUnused()
	355	* for both incoming cert groups (inCertGroup and gatheredCerts).
	356	* We don't do that here because we may call ourself recursively.
	357	*
	358	* subjectItem may or may not be in the cert group (currently, it
	359	* is in the group if it's a cert and it's not if it's a CRL, but
	360	* we don't rely on that).
	361	*/
	362	CSSM_RETURN buildCertGroup(
	363	const TPClItemInfo &subjectItem, // Cert or CRL
	364	TPCertGroup *inCertGroup, // optional
	365	const CSSM_DL_DB_LIST *dbList, // optional
	366	CSSM_CL_HANDLE clHand,
	367	CSSM_CSP_HANDLE cspHand,
	368	const char *verifyString, // optional, for establishing
	369	// validity of new TPCertInfos
	370	/* trusted anchors, optional */
	371	/* FIXME - maybe this should be a TPCertGroup */
	372	uint32 numAnchorCerts,
	373	const CSSM_DATA *anchorCerts,
	374
	375	/*
	376	* Certs to be freed by caller (i.e., TPCertInfo which we allocate
	377	* as a result of using a cert from anchorCerts or dbList) are added
	378	* to this group.
	379	*/
	380	TPCertGroup &certsToBeFreed,
	381
	382	/*
	383	* Other certificates gathered during the course of this operation,
	384	* currently consisting of certs fetched from DBs and from the net.
	385	* This is not used when called by AppleTPSession::CertGroupConstructPriv;
	386	* it's an optimization for the case when we're building a cert group
	387	* for TPCrlInfo::verifyWithContext - we avoid re-fetching certs from
	388	* the net which are needed to verify both the subject cert and a CRL.
	389	*/
	390	TPCertGroup *gatheredCerts,
	391
	392	/*
	393	* Indicates that subjectItem is the last element in this cert group.
	394	* If true, that cert will be tested for "root-ness", including
	395	* -- subject/issuer compare
	396	* -- signature self-verify
	397	* -- anchor compare
	398	*/
	399	CSSM_BOOL subjectIsInGroup,
	400
	401	/* currently, only CSSM_TP_ACTION_FETCH_CERT_FROM_NET is
	402	* interesting */
	403	CSSM_APPLE_TP_ACTION_FLAGS actionFlags,
	404
	405	/* returned */
	406	CSSM_BOOL &verifiedToRoot, // end of chain self-verifies
	407	CSSM_BOOL &verifiedToAnchor); // end of chain in anchors
	408
bac41a7b A	409	/* add/remove/access TPTCertInfo's. */
	410	void appendCert(
	411	TPCertInfo *certInfo); // appends to end of mCertInfo
	412	TPCertInfo *certAtIndex(
	413	unsigned index);
	414	TPCertInfo *removeCertAtIndex(
	415	unsigned index); // doesn't delete the cert, just
	416	// removes it from our list
df0e469f A	417	unsigned numCerts() const // how many do we have?
	418	{ return mNumCerts; }
	419
bac41a7b A	420	/*
	421	* Convenience accessors for first and last cert, only valid when we have
	422	* at least one cert.
	423	*/
29654253 A	424	TPCertInfo *firstCert();
29654253 A	425	TPCertInfo *lastCert();
bac41a7b A	426
bac41a7b A	427	/* build a CSSM_CERTGROUP corresponding with our mCertInfo */
29654253 A	428	CSSM_CERTGROUP_PTR buildCssmCertGroup();
	429
	430	/* build a CSSM_TP_APPLE_EVIDENCE_INFO array corresponding with our
	431	* mCertInfo */
	432	CSSM_TP_APPLE_EVIDENCE_INFO *buildCssmEvidenceInfo();
	433
	434	/* Given a status for basic construction of a cert group and a status
	435	* of (optional) policy verification, plus the implicit notBefore/notAfter
	436	* status in the certs, calculate a global return code. This just
	437	* encapsulates a policy for CertGroupeConstruct and CertGroupVerify.
	438	*/
	439	CSSM_RETURN getReturnCode(
	440	CSSM_RETURN constructStatus,
	441	CSSM_BOOL allowExpired,
5a719ac8	442	CSSM_BOOL allowExpiredRoot,
29654253 A	443	CSSM_RETURN policyStatus = CSSM_OK);
	444
	445	CssmAllocator
	446	&alloc() {return mAlloc; }
bac41a7b	447
df0e469f A	448	/* set all TPCertInfo.mUsed flags false */
	449	void setAllUnused();
	450
bac41a7b	451	private:
df0e469f A	452
	453	/*
	454	* Search unused incoming certs to find an issuer of specified
	455	* cert or CRL.
	456	* WARNING this assumes a valied "used" state for all certs
	457	* in this group.
	458	* If partialIssuerKey is true on return, caller must re-verify signature
	459	* of subject later when sufficient info is available.
	460	*/
	461	TPCertInfo *findIssuerForCertOrCrl(
	462	const TPClItemInfo &subject,
	463	bool &partialIssuerKey);
	464
	465	/*
	466	* Called from buildCertGroup as final processing of a constructed
	467	* group when CSSMERR_CSP_APPLE_PUBLIC_KEY_INCOMPLETE has been
	468	* detected. Perform partial public key processing.
	469	* Returns:
	470	* CSSMERR_TP_CERTIFICATE_CANT_OPERATE - can't complete partial key
	471	* CSSMERR_TP_INVALID_CERT_AUTHORITY - sig verify failed with
	472	* (supposedly) completed partial key
	473	*/
	474	CSSM_RETURN verifyWithPartialKeys(
	475	const TPClItemInfo &subjectItem); // Cert or CRL
	476
bac41a7b A	477	CssmAllocator &mAlloc;
	478	TPCertInfo **mCertInfo; // just an array of pointers
	479	unsigned mNumCerts; // valid certs in certInfo
	480	unsigned mSizeofCertInfo; // mallocd space in certInfo
df0e469f A	481	TPGroupOwner mWhoOwns; // if TGO_Group, we delete certs
df0e469f A	482	// upon destruction
bac41a7b A	483	};
bac41a7b A	484	#endif /* _TP_CERT_INFO_H_ */