Security/libsecurity_keychain/lib/Trust.h

   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
  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(uint32 &numAdded,
 126                                                         Allocator &alloc);
 127         void                            freeAddedRevocationPolicyData(CFArrayRef policies,
 128                                                         uint32 numAdded,
 129                                                         Allocator &alloc);
 130         CFDictionaryRef     defaultRevocationSettings();
 131
 132 public:
 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
 141 private:
 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
 174 public:
 175         static ModuleNexus<TrustStore> gStore;
 176
 177 private:
 178         Mutex mMutex;
 179 };
 180
 181 } // end namespace KeychainCore
 182
 183 } // end namespace Security
 184
 185 #endif // !_SECURITY_TRUST_H_