libsecurity_keychain/lib/Trust.h

   1 /*
   2  * Copyright (c) 2002-2010,2012 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
  40 using namespace CssmClient;
  41
  42 namespace Security {
  43 namespace 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 //
  51 class Trust : public SecCFObject
  52 {
  53         NOCOPY(Trust)
  54 public:
  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         CFDateRef time() const                                          { return mVerifyTime; }
 106         AnchorPolicy anchorPolicy() const                       { return mAnchorPolicy; }
 107         NetworkPolicy networkPolicy() const                     { return mNetworkPolicy; }
 108         CFArrayRef exceptions() const                           { return mExceptions; }
 109
 110         // an independent release function for TP evidence results
 111         // (yes, we could hand this out to the C layer if desired)
 112         static void releaseTPEvidence(TPVerifyResult &result, Allocator &allocator);
 113
 114 private:
 115         SecTrustResultType diagnoseOutcome();
 116         void evaluateUserTrust(const CertGroup &certs,
 117                         const CSSM_TP_APPLE_EVIDENCE_INFO *info,
 118                 CFCopyRef<CFArrayRef> anchors);
 119         void clearResults();
 120
 121         Keychain keychainByDLDb(const CSSM_DL_DB_HANDLE &handle);
 122
 123         /* revocation policy support */
 124         CFMutableArrayRef       addPreferenceRevocationPolicies(uint32 &numAdded,
 125                                                         Allocator &alloc);
 126         void                            freeAddedRevocationPolicyData(CFArrayRef policies,
 127                                                         uint32 numAdded,
 128                                                         Allocator &alloc);
 129         CFDictionaryRef     defaultRevocationSettings();
 130
 131 public:
 132         bool                            policySpecified(CFArrayRef policies, const CSSM_OID &inOid);
 133         bool                            revocationPolicySpecified(CFArrayRef policies);
 134         void                            orderRevocationPolicies(CFMutableArrayRef policies);
 135         CFMutableArrayRef       convertRevocationPolicy(uint32 &numAdded, Allocator &alloc);
 136         CFMutableArrayRef       forceRevocationPolicies(uint32 &numAdded,
 137                                                         Allocator &alloc,
 138                                                         bool requirePerCert=false);
 139
 140 private:
 141         TP mTP;                                                 // our TP
 142
 143         // input arguments: set up before evaluate()
 144         CSSM_TP_ACTION mAction;                 // TP action to verify
 145         CFRef<CFDataRef> mActionData;   // action data
 146         CFRef<CFArrayRef> mExceptions;  // trust exceptions
 147         CFRef<CFArrayRef> mResponses;   // array of OCSP response data (optional)
 148         CFRef<CFDateRef> mVerifyTime;   // verification "now"
 149         CFRef<CFArrayRef> mCerts;               // certificates to verify (item 1 is subject)
 150         CFRef<CFArrayRef> mPolicies;    // array of policy objects to control verification
 151         CFRef<CFArrayRef> mAnchors;             // array of anchor certs
 152         StorageManager::KeychainList *mSearchLibs; // array of databases to search
 153         bool mSearchLibsSet;                    // true if mSearchLibs has been initialized
 154
 155         // evaluation results: set as a result of evaluate()
 156         SecTrustResultType mResult;             // result classification
 157         uint32 mResultIndex;                    // which result cert made the decision?
 158         OSStatus mTpReturn;                             // return code from TP Verify
 159         TPVerifyResult mTpResult;               // result of latest TP verify
 160
 161         vector< SecPointer<Certificate> > mCertChain; // distilled certificate chain
 162
 163         // information returned to caller but owned by us
 164         CFRef<CFArrayRef> mEvidenceReturned;    // evidence chain returned
 165         CFRef<CFArrayRef> mAllowedAnchors;              // array of permitted anchor certificates
 166         CFRef<CFArrayRef> mFilteredCerts;               // array of certificates to verify, post-filtering
 167         CFRef<CFDictionaryRef> mExtendedResult; // dictionary of extended results
 168
 169         bool mUsingTrustSettings;       // true if built-in anchors will be trusted
 170         AnchorPolicy mAnchorPolicy;     // policy for trusting passed-in and/or built-in anchors
 171         NetworkPolicy mNetworkPolicy;   // policy for allowing network use during evaluation
 172
 173 public:
 174         static ModuleNexus<TrustStore> gStore;
 175
 176 private:
 177         Mutex mMutex;
 178 };
 179
 180 } // end namespace KeychainCore
 181
 182 } // end namespace Security
 183
 184 #endif // !_SECURITY_TRUST_H_