OSX/sec/Security/SecPolicyInternal.h

   1 /*
   2  * Copyright (c) 2008-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
  24 /*!
  25     @header SecPolicyPriv
  26     The functions provided in SecPolicyInternal provide the interface to
  27     trust policies used by SecTrust.
  28 */
  29
  30 #ifndef _SECURITY_SECPOLICYINTERNAL_H_
  31 #define _SECURITY_SECPOLICYINTERNAL_H_
  32
  33 #include <Security/SecPolicy.h>
  34 #include <Security/SecTrust.h>
  35 #include <Security/SecCertificatePath.h>
  36 #include <CoreFoundation/CFArray.h>
  37 #include <CoreFoundation/CFString.h>
  38 #include <CoreFoundation/CFRuntime.h>
  39
  40 __BEGIN_DECLS
  41
  42 /********************************************************
  43  ****************** SecPolicy struct ********************
  44  ********************************************************/
  45 struct __SecPolicy {
  46     CFRuntimeBase               _base;
  47     CFStringRef                 _oid;
  48     CFStringRef         _name;
  49         CFDictionaryRef         _options;
  50 };
  51
  52 /*!
  53     @enum Policy Check Keys
  54     @discussion Keys that represent various checks that can be done in a trust
  55         policy.
  56     @constant kSecPolicyCheckCriticalExtensions Ensure that no certificate in the chain has any critical extensions that we do not understand.
  57     @constant kSecPolicyCheckIdLinkage Check that all the certificates in the chain that have a SubjectId, match the AuthorityId of the certificate they sign.  This check is optional, in that if either certificate is missing the required extension the check succeeds.
  58         @constant kSecPolicyCheckBasicConstraints Fails if the basic constraints for the certificate chain are not met, this allows for basic constraints to be non critical and doesn't require every CA certificate to have a basic constraints extension, and allows for leaf certificates to have basic constraints extensions.
  59         @constant kSecPolicyCheckExtendedKeyUsage @@@
  60         @constant kSecPolicyCheckIdLinkage Fails if the AuthorityKeyID -> SubjectKeyID chaining isn't right.
  61         @constant kSecPolicyCheckKeyUsage @@@
  62         @constant kSecPolicyCheckWeakIntermediates Fails if any certificates in the chain (other than the leaf and root) have a too small key size.
  63         @constant kSecPolicyCheckWeakLeaf Fails if the leaf has a too small key size.
  64         @constant kSecPolicyCheckWeakRoot Fails if the root has a too small key size.
  65         @constant kSecPolicyCheckKeySize Fails if any certificates in the chain have key size smaller than the policy allows.
  66         @constant kSecPolicyCheckSignatureHashAlgorithms Fails if any certificates in the chain use a hash algorithm disallowed by the policy.
  67         @constant kSecPolicyCheckNonEmptySubject Perform the following check: RFC 3280, 4.1.2.6, says that an empty subject name can only appear in a leaf cert, and only if subjectAltName is present and marked critical.
  68         @constant kSecPolicyCheckQualifiedCertStatements Perform the following check: RFC 3739: if this cert has a Qualified Cert Statements extension, and it's Critical, make sure we understand all of the extension's statementIds.
  69         @constant kSecPolicyCheckValidIntermediates Fails if any certificates in the chain are not valid at the verify time other than the leaf and the root.
  70         @constant kSecPolicyCheckValidLeaf Fails if the leaf certificate is not valid at the verify time.
  71         @constant kSecPolicyCheckValidRoot Fails if the root certificate is not valid at the verify time.
  72         @constant kSecPolicyCheckAnchorTrusted @@@.
  73         @constant kSecPolicyCheckAnchorSHA1 @@@.
  74         @constant kSecPolicyCheckAnchorSHA256 @@@.
  75         @constant kSecPolicyCheckAnchorApple @@@.
  76         @constant kSecPolicyCheckSSLHostname @@@.
  77         @constant kSecPolicyCheckEmail @@@.
  78         @constant kSecPolicyCheckIssuerCommonName @@@.
  79         @constant kSecPolicyCheckSubjectCommonNamePrefix @@@.
  80         @constant kSecPolicyCheckChainLength @@@.
  81         @constant kSecPolicyCheckNotValidBefore @@@.
  82         @constant kSecPolicyCheckEAPTrustedServerNames @@@.
  83         @constant kSecPolicyCheckBasicCertificateProcessing @@@.
  84         @constant kSecPolicyCheckExtendedValidation @@@.
  85         @constant kSecPolicyCheckRevocation Perform a revocation check.
  86         @constant kSecPolicyCheckRevocationResponseRequired Require positive response for revocation check. Use of thise constant indicates that the policy should "fail closed" in case of missing revocation information.
  87         @constant kSecPolicyCheckRevocationOCSP Use OCSP to perform revocation check.
  88         @constant kSecPolicyCheckRevocationCRL Use CRL to perform revocation check.
  89         @constant kSecPolicyCheckRevocationAny Use any available method (OCSP or CRL) to perform revocation check.
  90         @constant kSecPolicyCheckRevocationOnline Force an "online" OCSP check.
  91         @constant kSecPolicyCheckNoNetworkAccess @@@.
  92     @constant kSecPolicyCheckBlackListedLeaf @@@.
  93     @constant kSecPolicyCheckUsageConstraints @@@.
  94     @constant kSecPolicyCheckSystemTrustedWeakHash Check whether the leaf or intermediates are using a weak hash in chains that end with a system-trusted anchor.
  95     @constant kSecPolicyCheckSystemTrustedWeakKey Check whether the leaf or intermediates are using a weak key in chains that end with a system-trusted anchor.
  96     @constant kSecPolicyCheckIntermediateOrganization Fails if any (non-leaf and non-root) certificates in the chain do not have a matching Organization string.
  97     @constant kSecPolicyCheckIntermediateCountry Fails if any (non-leaf and non-root) certificates in the chain do not have a matching Country string.
  98     @constant kSecPolicyCheckPinningRequired Fails if the binary Info plist required pinning but no pinning policies were used.
  99 */
 100 extern const CFStringRef kSecPolicyCheckBasicConstraints;
 101 extern const CFStringRef kSecPolicyCheckCriticalExtensions;
 102 extern const CFStringRef kSecPolicyCheckExtendedKeyUsage;
 103 extern const CFStringRef kSecPolicyCheckIdLinkage;
 104 extern const CFStringRef kSecPolicyCheckWeakIntermediates;
 105 extern const CFStringRef kSecPolicyCheckWeakLeaf;
 106 extern const CFStringRef kSecPolicyCheckWeakRoot;
 107 extern const CFStringRef kSecPolicyCheckKeySize;
 108 extern const CFStringRef kSecPolicyCheckSignatureHashAlgorithms;
 109 extern const CFStringRef kSecPolicyCheckKeyUsage;
 110 extern const CFStringRef kSecPolicyCheckNonEmptySubject;
 111 extern const CFStringRef kSecPolicyCheckQualifiedCertStatements;
 112 extern const CFStringRef kSecPolicyCheckValidIntermediates;
 113 extern const CFStringRef kSecPolicyCheckValidLeaf;
 114 extern const CFStringRef kSecPolicyCheckValidRoot;
 115 extern const CFStringRef kSecPolicyCheckAnchorTrusted;
 116 extern const CFStringRef kSecPolicyCheckAnchorSHA1;
 117 extern const CFStringRef kSecPolicyCheckAnchorSHA256;
 118 extern const CFStringRef kSecPolicyCheckAnchorApple;
 119 extern const CFStringRef kSecPolicyCheckSSLHostname;
 120 extern const CFStringRef kSecPolicyCheckEmail;
 121 extern const CFStringRef kSecPolicyCheckIssuerCommonName;
 122 extern const CFStringRef kSecPolicyCheckSubjectCommonName;
 123 extern const CFStringRef kSecPolicyCheckSubjectCommonNameTEST;
 124 extern const CFStringRef kSecPolicyCheckSubjectOrganization;
 125 extern const CFStringRef kSecPolicyCheckSubjectOrganizationalUnit;
 126 extern const CFStringRef kSecPolicyCheckSubjectCommonNamePrefix;
 127 extern const CFStringRef kSecPolicyCheckChainLength;
 128 extern const CFStringRef kSecPolicyCheckNotValidBefore;
 129 extern const CFStringRef kSecPolicyCheckEAPTrustedServerNames;
 130 extern const CFStringRef kSecPolicyCheckCertificatePolicy;
 131 extern const CFStringRef kSecPolicyCheckBasicCertificateProcessing;
 132 extern const CFStringRef kSecPolicyCheckExtendedValidation;
 133 extern const CFStringRef kSecPolicyCheckRevocation;
 134 extern const CFStringRef kSecPolicyCheckRevocationResponseRequired;
 135 extern const CFStringRef kSecPolicyCheckRevocationOCSP;
 136 extern const CFStringRef kSecPolicyCheckRevocationCRL;
 137 extern const CFStringRef kSecPolicyCheckRevocationAny;
 138 extern const CFStringRef kSecPolicyCheckRevocationOnline;
 139 extern const CFStringRef kSecPolicyCheckNoNetworkAccess;
 140 extern const CFStringRef kSecPolicyCheckBlackListedLeaf;
 141 extern const CFStringRef kSecPolicyCheckBlackListedKey;
 142 extern const CFStringRef kSecPolicyCheckGrayListedLeaf;
 143 extern const CFStringRef kSecPolicyCheckLeafMarkerOid;
 144 extern const CFStringRef kSecPolicyCheckLeafMarkerOidWithoutValueCheck;
 145 extern const CFStringRef kSecPolicyCheckLeafMarkersProdAndQA;
 146 extern const CFStringRef kSecPolicyCheckIntermediateMarkerOid;
 147 extern const CFStringRef kSecPolicyCheckIntermediateSPKISHA256;
 148 extern const CFStringRef kSecPolicyCheckIntermediateEKU;
 149 extern const CFStringRef kSecPolicyCheckGrayListedKey;
 150 extern const CFStringRef kSecPolicyCheckCertificateTransparency;
 151 extern const CFStringRef kSecPolicyCheckUsageConstraints;
 152 extern const CFStringRef kSecPolicyCheckSystemTrustedWeakHash;
 153 extern const CFStringRef kSecPolicyCheckSystemTrustedWeakKey;
 154 extern const CFStringRef kSecPolicyCheckIntermediateOrganization;
 155 extern const CFStringRef kSecPolicyCheckIntermediateCountry;
 156 extern const CFStringRef kSecPolicyCheckPinningRequired;
 157
 158 /*  Special option for checking Apple Anchors */
 159 extern const CFStringRef kSecPolicyAppleAnchorIncludeTestRoots;
 160
 161 /* Special option for checking Prod and QA Markers */
 162 extern const CFStringRef kSecPolicyLeafMarkerProd;
 163 extern const CFStringRef kSecPolicyLeafMarkerQA;
 164
 165 SecPolicyRef SecPolicyCreate(CFStringRef oid, CFStringRef name, CFDictionaryRef options);
 166
 167 CFDictionaryRef SecPolicyGetOptions(SecPolicyRef policy);
 168 void SecPolicySetOptionsValue(SecPolicyRef policy, CFStringRef key, CFTypeRef value);
 169 void SecPolicySetName(SecPolicyRef policy, CFStringRef policyName);
 170
 171 xpc_object_t SecPolicyArrayCopyXPCArray(CFArrayRef policies, CFErrorRef *error);
 172 CFArrayRef SecPolicyXPCArrayCopyArray(xpc_object_t xpc_policies, CFErrorRef *error);
 173
 174 CFArrayRef SecPolicyArrayCreateDeserialized(CFArrayRef serializedPolicies);
 175 CFArrayRef SecPolicyArrayCreateSerialized(CFArrayRef policies);
 176
 177 /*
 178  * MARK: SecPolicyCheckCert functions
 179  */
 180 bool SecPolicyCheckCertKeyUsage(SecCertificateRef cert, CFTypeRef pvcValue);
 181 bool SecPolicyCheckCertExtendedKeyUsage(SecCertificateRef cert, CFTypeRef pvcValue);
 182 bool SecPolicyCheckCertNonEmptySubject(SecCertificateRef cert, CFTypeRef pvcValue);
 183 bool SecPolicyCheckCertSSLHostname(SecCertificateRef cert, CFTypeRef pvcValue);
 184 bool SecPolicyCheckCertEmail(SecCertificateRef cert, CFTypeRef pvcValue);
 185 bool SecPolicyCheckCertSubjectCommonNamePrefix(SecCertificateRef cert, CFTypeRef pvcValue);
 186 bool SecPolicyCheckCertSubjectCommonName(SecCertificateRef cert, CFTypeRef pvcValue);
 187 bool SecPolicyCheckCertSubjectCommonNameTEST(SecCertificateRef cert, CFTypeRef pvcValue);
 188 bool SecPolicyCheckCertNotValidBefore(SecCertificateRef cert, CFTypeRef pvcValue);
 189 bool SecPolicyCheckCertSubjectOrganization(SecCertificateRef cert, CFTypeRef pvcValue);
 190 bool SecPolicyCheckCertSubjectOrganizationalUnit(SecCertificateRef cert, CFTypeRef pvcValue);
 191 bool SecPolicyCheckCertEAPTrustedServerNames(SecCertificateRef cert, CFTypeRef pvcValue);
 192 bool SecPolicyCheckCertLeafMarkerOid(SecCertificateRef cert, CFTypeRef pvcValue);
 193 bool SecPolicyCheckCertLeafMarkerOidWithoutValueCheck(SecCertificateRef cert, CFTypeRef pvcValue);
 194 bool SecPolicyCheckCertSignatureHashAlgorithms(SecCertificateRef cert, CFTypeRef pvcValue);
 195 bool SecPolicyCheckCertSubjectCountry(SecCertificateRef cert, CFTypeRef pvcValue);
 196
 197
 198 /*
 199  * MARK: SecLeafPVC functions
 200  */
 201
 202 typedef struct OpaqueSecLeafPVC *SecLeafPVCRef;
 203
 204 struct OpaqueSecLeafPVC {
 205     SecCertificateRef leaf;
 206     CFArrayRef policies;
 207     CFAbsoluteTime verifyTime;
 208     CFArrayRef details;
 209     CFMutableDictionaryRef info;
 210     CFDictionaryRef callbacks;
 211     CFIndex policyIX;
 212     bool result;
 213 };
 214
 215 void SecLeafPVCInit(SecLeafPVCRef pvc, SecCertificateRef leaf, CFArrayRef policies, CFAbsoluteTime verifyTime);
 216 void SecLeafPVCDelete(SecLeafPVCRef pvc);
 217 bool SecLeafPVCLeafChecks(SecLeafPVCRef pvc);
 218
 219 __END_DECLS
 220
 221 #endif /* !_SECURITY_SECPOLICYINTERNAL_H_ */