1/*
2 * Copyright (c) 2002-2014 Apple Inc. All Rights Reserved.
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// Trust.h - Trust control wrappers
26//
27#ifndef _SECURITY_TRUST_H_
28#define _SECURITY_TRUST_H_
29
30#include <CoreFoundation/CoreFoundation.h>
31#include <security_keychain/StorageManager.h>
32#include <security_cdsa_client/tpclient.h>
33#include <security_utilities/cfutilities.h>
34#include <Security/SecTrust.h>
35#include <security_keychain/Certificate.h>
36#include <security_keychain/Policies.h>
37#include <security_keychain/TrustStore.h>
38#include <vector>
39
40using namespace CssmClient;
41
42namespace Security {
43namespace KeychainCore {
44
45
46//
47// The Trust object manages trust-verification workflow.
48// As such, it represents a somewhat more complex concept than
49// a single "object".
50//
51class Trust : public SecCFObject
52{
53	NOCOPY(Trust)
54public:
55	SECCFFUNCTIONS(Trust, SecTrustRef, errSecInvalidItemRef, gTypes().Trust)
56
57    Trust(CFTypeRef certificates, CFTypeRef policies);
58    virtual ~Trust();
59
60	enum AnchorPolicy {
61		useAnchorsDefault,		// default policy: trust built-in unless passed-in
62		useAnchorsAndBuiltIns,	// SetTrustAnchorCertificatesOnly value = false
63		useAnchorsOnly			// SetTrustAnchorCertificatesOnly value = true
64	};
65
66	enum NetworkPolicy {
67		useNetworkDefault,		// default policy: network fetch enabled only for SSL
68		useNetworkDisabled,		// explicitly disable network use for any policy
69		useNetworkEnabled		// explicitly enable network use for any policy
70	};
71
72	// set (or reset) more input parameters
73	void policies(CFTypeRef policies)			{ mPolicies.take(cfArrayize(policies)); }
74	void action(CSSM_TP_ACTION action)			{ mAction = action; }
75	void actionData(CFDataRef data)				{ mActionData = data; }
76	void time(CFDateRef verifyTime)				{ mVerifyTime = verifyTime; }
77	void anchors(CFArrayRef anchorList)			{ mAnchors.take(cfArrayize(anchorList)); }
78	void anchorPolicy(AnchorPolicy policy)		{ mAnchorPolicy = policy; }
79	void networkPolicy(NetworkPolicy policy)	{ mNetworkPolicy = policy; }
80	void exceptions(CFArrayRef exceptions)		{ mExceptions.take(cfArrayize(exceptions)); }
81	void responses(CFTypeRef responseData)		{ mResponses.take(cfArrayize(responseData)); }
82
83	StorageManager::KeychainList &searchLibs(bool init=true);
84	void searchLibs(StorageManager::KeychainList &libs);
85
86	// perform evaluation
87	void evaluate(bool disableEV=false);
88
89	// update evaluation results
90	void setResult(SecTrustResultType result)	{ mResult = result; }
91
92	// get at evaluation results
93	void buildEvidence(CFArrayRef &certChain, TPEvidenceInfo * &statusChain);
94	CSSM_TP_VERIFY_CONTEXT_RESULT_PTR cssmResult();
95	void extendedResult(CFDictionaryRef &extendedResult);
96	CFArrayRef properties();
97	CFDictionaryRef results();
98
99	SecTrustResultType result() const			{ return mResult; }
100	OSStatus cssmResultCode() const				{ return mTpReturn; }
101	TP getTPHandle() const						{ return mTP; }
102	CFArrayRef evidence() const					{ return mEvidenceReturned; }
103	CFArrayRef policies() const					{ return mPolicies; }
104	CFArrayRef anchors() const					{ return mAnchors; }
105	CFArrayRef certificates() const				{ return mCerts; }
106	CFDateRef time() const						{ return mVerifyTime; }
107	AnchorPolicy anchorPolicy() const			{ return mAnchorPolicy; }
108	NetworkPolicy networkPolicy() const			{ return mNetworkPolicy; }
109	CFArrayRef exceptions() const				{ return mExceptions; }
110
111	// an independent release function for TP evidence results
112	// (yes, we could hand this out to the C layer if desired)
113	static void releaseTPEvidence(TPVerifyResult &result, Allocator &allocator);
114
115private:
116	SecTrustResultType diagnoseOutcome();
117	void evaluateUserTrust(const CertGroup &certs,
118			const CSSM_TP_APPLE_EVIDENCE_INFO *info,
119		CFCopyRef<CFArrayRef> anchors);
120	void clearResults();
121
122	Keychain keychainByDLDb(const CSSM_DL_DB_HANDLE &handle);
123
124	/* revocation policy support */
125	CFMutableArrayRef	addPreferenceRevocationPolicies(uint32 &numAdded,
126							Allocator &alloc);
127	void				freeAddedRevocationPolicyData(CFArrayRef policies,
128							uint32 numAdded,
129							Allocator &alloc);
130	CFDictionaryRef     defaultRevocationSettings();
131
132public:
133	bool				policySpecified(CFArrayRef policies, const CSSM_OID &inOid);
134	bool				revocationPolicySpecified(CFArrayRef policies);
135	void				orderRevocationPolicies(CFMutableArrayRef policies);
136	CFMutableArrayRef	convertRevocationPolicy(uint32 &numAdded, Allocator &alloc);
137	CFMutableArrayRef	forceRevocationPolicies(uint32 &numAdded,
138							Allocator &alloc,
139							bool requirePerCert=false);
140
141private:
142	TP mTP;							// our TP
143
144	// input arguments: set up before evaluate()
145	CSSM_TP_ACTION mAction;			// TP action to verify
146	CFRef<CFDataRef> mActionData;	// action data
147	CFRef<CFArrayRef> mExceptions;	// trust exceptions
148	CFRef<CFArrayRef> mResponses;	// array of OCSP response data (optional)
149	CFRef<CFDateRef> mVerifyTime;	// verification "now"
150	CFRef<CFArrayRef> mCerts;		// certificates to verify (item 1 is subject)
151	CFRef<CFArrayRef> mPolicies;	// array of policy objects to control verification
152	CFRef<CFArrayRef> mAnchors;		// array of anchor certs
153	StorageManager::KeychainList *mSearchLibs; // array of databases to search
154	bool mSearchLibsSet;			// true if mSearchLibs has been initialized
155
156	// evaluation results: set as a result of evaluate()
157	SecTrustResultType mResult;		// result classification
158	uint32 mResultIndex;			// which result cert made the decision?
159	OSStatus mTpReturn;				// return code from TP Verify
160	TPVerifyResult mTpResult;		// result of latest TP verify
161
162	vector< SecPointer<Certificate> > mCertChain; // distilled certificate chain
163
164	// information returned to caller but owned by us
165	CFRef<CFArrayRef> mEvidenceReturned;	// evidence chain returned
166	CFRef<CFArrayRef> mAllowedAnchors;		// array of permitted anchor certificates
167	CFRef<CFArrayRef> mFilteredCerts;		// array of certificates to verify, post-filtering
168	CFRef<CFDictionaryRef> mExtendedResult;	// dictionary of extended results
169
170	bool mUsingTrustSettings;	// true if built-in anchors will be trusted
171	AnchorPolicy mAnchorPolicy;	// policy for trusting passed-in and/or built-in anchors
172	NetworkPolicy mNetworkPolicy;	// policy for allowing network use during evaluation
173
174public:
175	static ModuleNexus<TrustStore> gStore;
176
177private:
178	Mutex mMutex;
179};
180
181} // end namespace KeychainCore
182
183} // end namespace Security
184
185#endif // !_SECURITY_TRUST_H_
186