OSX/libsecurity_keychain/lib/Trust.h

   1 /*
   2  * Copyright (c) 2002-2015 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         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
 115 private:
 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(
 126                                                         bool ocspEnabledOnBestAttempt,
 127                                                         bool crlEnabledOnBestAttempt,
 128                                                         uint32 &numAdded,
 129                                                         Allocator &alloc);
 130         void                            freeAddedRevocationPolicyData(CFArrayRef policies,
 131                                                         uint32 numAdded,
 132                                                         Allocator &alloc);
 133         CFDictionaryRef     defaultRevocationSettings();
 134
 135 public:
 136         bool                            policySpecified(CFArrayRef policies, const CSSM_OID &inOid);
 137         bool                            revocationPolicySpecified(CFArrayRef policies);
 138         void                            orderRevocationPolicies(CFMutableArrayRef policies);
 139         CFMutableArrayRef       convertRevocationPolicy(uint32 &numAdded, Allocator &alloc);
 140         CFMutableArrayRef       forceRevocationPolicies(
 141                                                         bool ocspEnabled,
 142                                                         bool crlEnabled,
 143                                                         uint32 &numAdded,
 144                                                         Allocator &alloc,
 145                                                         bool requirePerCert=false);
 146
 147 private:
 148         TP mTP;                                                 // our TP
 149
 150         // input arguments: set up before evaluate()
 151         CSSM_TP_ACTION mAction;                 // TP action to verify
 152         CFRef<CFDataRef> mActionData;   // action data
 153         CFRef<CFArrayRef> mExceptions;  // trust exceptions
 154         CFRef<CFArrayRef> mResponses;   // array of OCSP response data (optional)
 155         CFRef<CFDateRef> mVerifyTime;   // verification "now"
 156         CFRef<CFArrayRef> mCerts;               // certificates to verify (item 1 is subject)
 157         CFRef<CFArrayRef> mPolicies;    // array of policy objects to control verification
 158         CFRef<CFArrayRef> mAnchors;             // array of anchor certs
 159         StorageManager::KeychainList *mSearchLibs; // array of databases to search
 160         bool mSearchLibsSet;                    // true if mSearchLibs has been initialized
 161
 162         // evaluation results: set as a result of evaluate()
 163         SecTrustResultType mResult;             // result classification
 164         uint32 mResultIndex;                    // which result cert made the decision?
 165         OSStatus mTpReturn;                             // return code from TP Verify
 166         TPVerifyResult mTpResult;               // result of latest TP verify
 167
 168         vector< SecPointer<Certificate> > mCertChain; // distilled certificate chain
 169
 170         // information returned to caller but owned by us
 171         CFRef<CFArrayRef> mEvidenceReturned;    // evidence chain returned
 172         CFRef<CFArrayRef> mAllowedAnchors;              // array of permitted anchor certificates
 173         CFRef<CFArrayRef> mFilteredCerts;               // array of certificates to verify, post-filtering
 174         CFRef<CFDictionaryRef> mExtendedResult; // dictionary of extended results
 175
 176         bool mUsingTrustSettings;       // true if built-in anchors will be trusted
 177         AnchorPolicy mAnchorPolicy;     // policy for trusting passed-in and/or built-in anchors
 178         NetworkPolicy mNetworkPolicy;   // policy for allowing network use during evaluation
 179
 180 public:
 181         static ModuleNexus<TrustStore> gStore;
 182
 183 private:
 184         Mutex mMutex;
 185 };
 186
 187 //
 188 // TrustKeychains maintains a global reference to standard system keychains,
 189 // to avoid having them be opened anew for each Trust instance.
 190 //
 191 static const CSSM_DL_DB_HANDLE nullCSSMDLDBHandle = {0,};
 192
 193 class TrustKeychains
 194 {
 195     public:
 196     TrustKeychains();
 197     ~TrustKeychains();
 198     CSSM_DL_DB_HANDLE   rootStoreHandle()       { return mRootStoreHandle; }
 199     CSSM_DL_DB_HANDLE   systemKcHandle()        { return mSystem ? mSystem->database()->handle() : nullCSSMDLDBHandle; }
 200     Keychain                    &systemKc()                     { return mSystem; }
 201     Keychain                    &rootStore()            { return *mRootStore; }
 202
 203     private:
 204     DL*                                 mRootStoreDL;
 205     Db*                                 mRootStoreDb;
 206     Keychain*                   mRootStore;
 207     CSSM_DL_DB_HANDLE   mRootStoreHandle;
 208     Keychain                    mSystem;
 209 };
 210
 211 } // end namespace KeychainCore
 212
 213 } // end namespace Security
 214
 215 #endif // !_SECURITY_TRUST_H_