OSX/sec/securityd/SecTrustServer.h

   1 /*
   2  * Copyright (c) 2008-2009,2012-2014,2017 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  * SecTrustServer.h - certificate trust evaluation engine
  24  *
  25  *
  26  */
  27
  28 #ifndef _SECURITY_SECTRUSTSERVER_H_
  29 #define _SECURITY_SECTRUSTSERVER_H_
  30
  31 #include <CoreFoundation/CFString.h>
  32
  33 #include <Security/SecTrust.h>
  34 #include <Security/SecBasePriv.h> /* For errSecWaitForCallback. */
  35 #include <securityd/SecCertificateServer.h>
  36 #include <securityd/SecCertificateSource.h>
  37 #include <mach/port.h>
  38
  39 __BEGIN_DECLS
  40
  41 /* CRLs only implemented for macOS for legacy compatibility purposes using
  42  * ocspd's (legacy) interfaces */
  43 #define ENABLE_CRLS TARGET_OS_OSX
  44
  45 typedef struct SecPathBuilder *SecPathBuilderRef;
  46
  47 typedef struct OpaqueSecPVC *SecPVCRef;
  48
  49 struct OpaqueSecPVC {
  50     SecPathBuilderRef builder;
  51     CFArrayRef policies;
  52     CFDictionaryRef callbacks;
  53     CFIndex policyIX;
  54     bool require_revocation_response;
  55
  56     CFArrayRef leafDetails;
  57     SecTrustResultType leafResult;
  58
  59     CFArrayRef details;
  60     SecTrustResultType result;
  61 };
  62
  63 /* Completion callback. */
  64 typedef void(*SecPathBuilderCompleted)(const void *userData,
  65     CFArrayRef chain, CFArrayRef details, CFDictionaryRef info,
  66     SecTrustResultType result);
  67
  68 /* Returns a new trust path builder and policy evaluation engine instance. */
  69 SecPathBuilderRef SecPathBuilderCreate(CFDataRef clientAuditToken,
  70     CFArrayRef certificates, CFArrayRef anchors, bool anchorsOnly,
  71     bool keychainsAllowed, CFArrayRef policies, CFArrayRef ocspResponse,
  72     CFArrayRef signedCertificateTimestamps, CFArrayRef trustedLogs,
  73     CFAbsoluteTime verifyTime, CFArrayRef accessGroups, CFArrayRef exceptions,
  74     SecPathBuilderCompleted completed, const void *userData);
  75
  76 /* Returns true if it's ok to perform network operations for this builder. */
  77 bool SecPathBuilderCanAccessNetwork(SecPathBuilderRef builder);
  78
  79 /* Disable or enable network access for this builder if allow is false
  80    network access will be disabled. */
  81 void SecPathBuilderSetCanAccessNetwork(SecPathBuilderRef builder, bool allow);
  82
  83 /* Get the stapled SCTs */
  84 CFArrayRef SecPathBuilderCopySignedCertificateTimestamps(SecPathBuilderRef builder);
  85 CFArrayRef SecPathBuilderCopyOCSPResponses(SecPathBuilderRef builder);
  86 CFArrayRef SecPathBuilderCopyTrustedLogs(SecPathBuilderRef builder);
  87
  88 CFSetRef SecPathBuilderGetAllPaths(SecPathBuilderRef builder);
  89 SecCertificatePathVCRef SecPathBuilderGetPath(SecPathBuilderRef builder);
  90 SecCertificatePathVCRef SecPathBuilderGetBestPath(SecPathBuilderRef builder);
  91 CFAbsoluteTime SecPathBuilderGetVerifyTime(SecPathBuilderRef builder);
  92 CFIndex SecPathBuilderGetCertificateCount(SecPathBuilderRef builder);
  93 SecCertificateRef SecPathBuilderGetCertificateAtIndex(SecPathBuilderRef builder, CFIndex ix);
  94 CFArrayRef SecPathBuilderGetExceptions(SecPathBuilderRef builder);
  95 bool SecPathBuilderHasTemporalParentChecks(SecPathBuilderRef builder);
  96
  97 /* Returns the isAnchored status of the path. The path builder sets isAnchored
  98  * based solely on whether the terminating cert has some sort of trust setting
  99  * on it. This check does NOT reflect whether that anchor is actually trusted,
 100  * as trust in an anchor is contextual to the policy being validated. */
 101 bool SecPathBuilderIsAnchored(SecPathBuilderRef builder);
 102 bool SecPathBuilderIsAnchorSource(SecPathBuilderRef builder, SecCertificateSourceRef source);
 103 SecCertificateSourceRef SecPathBuilderGetAppAnchorSource(SecPathBuilderRef builder);
 104
 105 CFIndex SecPathBuilderGetPVCCount(SecPathBuilderRef builder);
 106 SecPVCRef SecPathBuilderGetPVCAtIndex(SecPathBuilderRef builder, CFIndex ix);
 107
 108 /* Returns the first PVC that passed */
 109 SecPVCRef SecPathBuilderGetResultPVC(SecPathBuilderRef builder);
 110
 111 void SecPathBuilderSetResultInPVCs(SecPathBuilderRef builder, CFStringRef key,
 112                                    CFIndex ix, CFTypeRef result, bool force);
 113
 114 /* This is a pre-decrement operation */
 115 unsigned int SecPathBuilderDecrementAsyncJobCount(SecPathBuilderRef builder);
 116 void SecPathBuilderSetAsyncJobCount(SecPathBuilderRef builder, unsigned int jobCount);
 117
 118 CFMutableDictionaryRef SecPathBuilderGetInfo(SecPathBuilderRef builder);
 119
 120 /* Enable revocation checking if the rest of the policy checks succeed. */
 121 CFStringRef SecPathBuilderGetRevocationMethod(SecPathBuilderRef builder);
 122 void SecPathBuilderSetRevocationMethod(SecPathBuilderRef builder, CFStringRef method);
 123
 124 /* Require a online revocation response for the chain. */
 125 bool SecPathBuilderGetCheckRevocationOnline(SecPathBuilderRef builder);
 126 void SecPathBuilderSetCheckRevocationOnline(SecPathBuilderRef builder);
 127
 128 /* Core of the trust evaluation engine, this will invoke the completed
 129    callback and return false if the evaluation completed, or return true if
 130    the evaluation is still waiting for some external event (usually the
 131    network). */
 132 bool SecPathBuilderStep(SecPathBuilderRef builder);
 133
 134 /* Return the dispatch queue to be used by this builder. */
 135 dispatch_queue_t SecPathBuilderGetQueue(SecPathBuilderRef builder);
 136
 137 /* Return the client audit token associated with this path builder,
 138    which caller must release, or NULL if there is no external client. */
 139 CFDataRef SecPathBuilderCopyClientAuditToken(SecPathBuilderRef builder);
 140
 141 /* Evaluate trust and call evaluated when done. */
 142 void SecTrustServerEvaluateBlock(CFDataRef clientAuditToken, CFArrayRef certificates, CFArrayRef anchors, bool anchorsOnly, bool keychainsAllowed, CFArrayRef policies, CFArrayRef responses, CFArrayRef SCTs, CFArrayRef trustedLogs, CFAbsoluteTime verifyTime, __unused CFArrayRef accessGroups, CFArrayRef exceptions, void (^evaluated)(SecTrustResultType tr, CFArrayRef details, CFDictionaryRef info, CFArrayRef chain, CFErrorRef error));
 143
 144 /* Synchronously invoke SecTrustServerEvaluateBlock. */
 145 SecTrustResultType SecTrustServerEvaluate(CFArrayRef certificates, CFArrayRef anchors, bool anchorsOnly, bool keychainsAllowed, CFArrayRef policies, CFArrayRef responses, CFArrayRef SCTs, CFArrayRef trustedLogs, CFAbsoluteTime verifyTime, __unused CFArrayRef accessGroups, CFArrayRef exceptions, CFArrayRef *details, CFDictionaryRef *info, CFArrayRef *chain, CFErrorRef *error);
 146
 147 /* TrustAnalytics builder types */
 148 typedef CF_OPTIONS(uint8_t, TA_SCTSource) {
 149     TA_SCTEmbedded  = 1 << 0,
 150     TA_SCT_OCSP     = 1 << 1,
 151     TA_SCT_TLS      = 1 << 2,
 152 };
 153
 154 typedef CF_OPTIONS(uint8_t, TAValidStatus) {
 155     TAValidDefinitelyOK          = 1 << 0,
 156     TAValidProbablyOK            = 1 << 1,
 157     TAValidProbablyRevoked       = 1 << 2,
 158     TAValidDefinitelyRevoked     = 1 << 3,
 159     TAValidDateConstrainedOK     = 1 << 4,
 160     TAValidDateContrainedRevoked = 1 << 5,
 161 };
 162
 163 typedef struct {
 164     uint64_t start_time;
 165     // Certificate Transparency
 166     TA_SCTSource sct_sources;
 167     uint32_t number_scts;
 168     uint32_t number_trusted_scts;
 169     size_t total_sct_size;
 170     // CAIssuer
 171     bool ca_issuer_cache_hit;
 172     bool ca_issuer_network;
 173     uint32_t ca_issuer_fetches;
 174     uint64_t ca_issuer_fetch_time;
 175     uint32_t ca_issuer_fetch_failed;
 176     bool ca_issuer_unsupported_data;
 177     bool ca_issuer_multiple_certs;
 178     // OCSP
 179     bool ocsp_no_check;
 180     bool ocsp_cache_hit;
 181     bool ocsp_network;
 182     uint32_t ocsp_fetches;
 183     uint64_t ocsp_fetch_time;
 184     uint32_t ocsp_fetch_failed;
 185     bool ocsp_validation_failed;
 186 #if ENABLE_CRLS
 187     // CRLs
 188     bool crl_client;
 189     bool crl_cert;
 190     uint32_t crl_fetches;
 191     uint64_t crl_fetch_time;
 192     uint32_t crl_fetch_failed;
 193 #endif
 194     // Valid
 195     TAValidStatus valid_status;
 196     bool valid_trigger_ocsp;
 197     bool valid_require_ct;
 198 } TrustAnalyticsBuilder;
 199
 200 TrustAnalyticsBuilder *SecPathBuilderGetAnalyticsData(SecPathBuilderRef builder);
 201
 202 __END_DECLS
 203
 204 #endif /* !_SECURITY_SECTRUSTSERVER_H_ */