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 an atomic pre-decrement operation */
 115 unsigned int SecPathBuilderDecrementAsyncJobCount(SecPathBuilderRef builder);
 116 void SecPathBuilderSetAsyncJobCount(SecPathBuilderRef builder, unsigned int jobCount);
 117 unsigned int SecPathBuilderGetAsyncJobCount(SecPathBuilderRef builder);
 118
 119 CFMutableDictionaryRef SecPathBuilderGetInfo(SecPathBuilderRef builder);
 120
 121 /* Enable revocation checking if the rest of the policy checks succeed. */
 122 CFStringRef SecPathBuilderGetRevocationMethod(SecPathBuilderRef builder);
 123 void SecPathBuilderSetRevocationMethod(SecPathBuilderRef builder, CFStringRef method);
 124
 125 /* Require a online revocation response for the chain. */
 126 bool SecPathBuilderGetCheckRevocationOnline(SecPathBuilderRef builder);
 127 void SecPathBuilderSetCheckRevocationOnline(SecPathBuilderRef builder);
 128
 129 /* Only do networking for revocation if the chain is trusted */
 130 bool SecPathBuilderGetCheckRevocationIfTrusted(SecPathBuilderRef builder);
 131 void SecPathBuilderSetCheckRevocationIfTrusted(SecPathBuilderRef builder);
 132
 133 /* Core of the trust evaluation engine, this will invoke the completed
 134    callback and return false if the evaluation completed, or return true if
 135    the evaluation is still waiting for some external event (usually the
 136    network). */
 137 bool SecPathBuilderStep(SecPathBuilderRef builder);
 138
 139 /* Return the dispatch queue to be used by this builder. */
 140 dispatch_queue_t SecPathBuilderGetQueue(SecPathBuilderRef builder);
 141
 142 /* Return the client audit token associated with this path builder,
 143    which caller must release, or NULL if there is no external client. */
 144 CFDataRef SecPathBuilderCopyClientAuditToken(SecPathBuilderRef builder);
 145
 146 /* Evaluate trust and call evaluated when done. */
 147 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));
 148
 149 /* Synchronously invoke SecTrustServerEvaluateBlock. */
 150 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);
 151
 152 /* TrustAnalytics builder types */
 153 typedef CF_OPTIONS(uint8_t, TA_SCTSource) {
 154     TA_SCTEmbedded  = 1 << 0,
 155     TA_SCT_OCSP     = 1 << 1,
 156     TA_SCT_TLS      = 1 << 2,
 157 };
 158
 159 typedef CF_ENUM(uint8_t, TA_CTFailureReason) {
 160     TA_CTNoFailure = 0,
 161     TA_CTNoSCTs = 1,
 162     TA_CTMissingLogs = 2,
 163     TA_CTNoCurrentSCTsUnknownLog = 3,
 164     TA_CTNoCurrentSCTsDisqualifiedLog = 4,
 165     TA_CTPresentedNotEnoughUnknown = 5,
 166     TA_CTPresentedNotEnoughDisqualified = 6,
 167     TA_CTPresentedNotEnough = 7,
 168     TA_CTEmbeddedNotEnoughUnknown = 8,
 169     TA_CTEmbeddedNotEnoughDisqualified = 9,
 170     TA_CTEmbeddedNotEnough = 10,
 171 };
 172
 173 typedef CF_OPTIONS(uint8_t, TAValidStatus) {
 174     TAValidDefinitelyOK          = 1 << 0,
 175     TAValidProbablyOK            = 1 << 1,
 176     TAValidProbablyRevoked       = 1 << 2,
 177     TAValidDefinitelyRevoked     = 1 << 3,
 178     TAValidDateConstrainedOK     = 1 << 4,
 179     TAValidDateContrainedRevoked = 1 << 5,
 180 };
 181
 182 typedef struct {
 183     uint64_t start_time;
 184     // Certificate Transparency
 185     TA_SCTSource sct_sources;
 186     uint32_t number_scts;
 187     uint32_t number_trusted_scts;
 188     TA_CTFailureReason ct_failure_reason;
 189     bool ct_one_current;
 190     // CAIssuer
 191     bool ca_issuer_cache_hit;
 192     bool ca_issuer_network;
 193     uint32_t ca_issuer_fetches;
 194     uint64_t ca_issuer_fetch_time;
 195     uint32_t ca_issuer_fetch_failed;
 196     bool ca_issuer_unsupported_data;
 197     bool ca_issuer_multiple_certs;
 198     // OCSP
 199     bool ocsp_no_check;
 200     bool ocsp_cache_hit;
 201     bool ocsp_network;
 202     uint32_t ocsp_fetches;
 203     uint64_t ocsp_fetch_time;
 204     uint32_t ocsp_fetch_failed;
 205     bool ocsp_validation_failed;
 206 #if ENABLE_CRLS
 207     // CRLs
 208     bool crl_client;
 209     bool crl_cert;
 210     uint32_t crl_fetches;
 211     uint64_t crl_fetch_time;
 212     uint32_t crl_fetch_failed;
 213 #endif
 214     // Valid
 215     TAValidStatus valid_status;
 216     bool valid_trigger_ocsp;
 217     bool valid_require_ct;
 218     bool valid_known_intermediates_only;
 219     bool valid_unknown_intermediate;
 220 } TrustAnalyticsBuilder;
 221
 222 TrustAnalyticsBuilder *SecPathBuilderGetAnalyticsData(SecPathBuilderRef builder);
 223
 224 __END_DECLS
 225
 226 #endif /* !_SECURITY_SECTRUSTSERVER_H_ */