1/* 2 * Copyright (c) 2002-2010,2012-2013 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 SecPolicy 26 The functions provided in SecPolicy.h provide an interface to various 27 X.509 certificate trust policies. 28*/ 29 30#ifndef _SECURITY_SECPOLICY_H_ 31#define _SECURITY_SECPOLICY_H_ 32 33#include <CoreFoundation/CFBase.h> 34#include <CoreFoundation/CFDictionary.h> 35#include <Security/SecBase.h> 36 37__BEGIN_DECLS 38 39/*! 40 @enum Policy Constants 41 @discussion Predefined constants used to specify a policy. 42 @constant kSecPolicyAppleX509Basic 43 @constant kSecPolicyAppleSSL 44 @constant kSecPolicyAppleSMIME 45 @constant kSecPolicyAppleEAP 46 @constant kSecPolicyAppleIPsec 47 @constant kSecPolicyApplePKINITClient 48 @constant kSecPolicyApplePKINITServer 49 @constant kSecPolicyAppleCodeSigning 50 @constant kSecPolicyMacAppStoreReceipt 51 @constant kSecPolicyAppleIDValidation 52 @constant kSecPolicyAppleTimeStamping 53 @constant kSecPolicyAppleRevocation 54*/ 55extern CFTypeRef kSecPolicyAppleX509Basic 56 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 57extern CFTypeRef kSecPolicyAppleSSL 58 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 59extern CFTypeRef kSecPolicyAppleSMIME 60 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 61extern CFTypeRef kSecPolicyAppleEAP 62 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 63extern CFTypeRef kSecPolicyAppleIPsec 64 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 65extern CFTypeRef kSecPolicyApplePKINITClient 66 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 67extern CFTypeRef kSecPolicyApplePKINITServer 68 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 69extern CFTypeRef kSecPolicyAppleCodeSigning 70 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 71extern CFTypeRef kSecPolicyMacAppStoreReceipt 72 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 73extern CFTypeRef kSecPolicyAppleIDValidation 74 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 75extern CFTypeRef kSecPolicyAppleTimeStamping 76 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_7_0); 77extern CFTypeRef kSecPolicyAppleRevocation 78 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 79 80/*! 81 @enum Policy Value Constants 82 @abstract Predefined property key constants used to get or set values in 83 a dictionary for a policy instance. 84 @discussion 85 All policies will have the following read-only value: 86 kSecPolicyOid (the policy object identifier) 87 88 Additional policy values which your code can optionally set: 89 kSecPolicyName (name which must be matched) 90 kSecPolicyClient (evaluate for client, rather than server) 91 kSecPolicyRevocationFlags (only valid for a revocation policy) 92 93 @constant kSecPolicyOid Specifies the policy OID (value is a CFStringRef) 94 @constant kSecPolicyName Specifies a CFStringRef (or CFArrayRef of same) 95 containing a name which must be matched in the certificate to satisfy 96 this policy. For SSL/TLS, EAP, and IPSec policies, this specifies the 97 server name which must match the common name of the certificate. 98 For S/MIME, this specifies the RFC822 email address. 99 @constant kSecPolicyClient Specifies a CFBooleanRef value that indicates 100 this evaluation should be for a client certificate. If not set (or 101 false), the policy evaluates the certificate as a server certificate. 102 @constant kSecPolicyRevocationFlags Specifies a CFNumberRef that holds a 103 kCFNumberCFIndexType bitmask value. See "Revocation Policy Constants" 104 for a description of individual bits in this value. 105 */ 106extern CFTypeRef kSecPolicyOid 107 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 108extern CFTypeRef kSecPolicyName 109 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 110extern CFTypeRef kSecPolicyClient 111 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 112extern CFTypeRef kSecPolicyRevocationFlags 113 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 114 115 116/*! 117 @function SecPolicyGetTypeID 118 @abstract Returns the type identifier of SecPolicy instances. 119 @result The CFTypeID of SecPolicy instances. 120*/ 121CFTypeID SecPolicyGetTypeID(void) 122 __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); 123 124/*! 125 @function SecPolicyCopyProperties 126 @abstract Returns a dictionary of this policy's properties. 127 @param policyRef A policy reference. 128 @result A properties dictionary. See "Policy Value Constants" for a list 129 of currently defined property keys. It is the caller's responsibility to 130 CFRelease this reference when it is no longer needed. 131 @result A result code. See "Security Error Codes" (SecBase.h). 132 @discussion This function returns the properties for a policy, as set by the 133 policy's construction function or by a prior call to SecPolicySetProperties. 134*/ 135CFDictionaryRef SecPolicyCopyProperties(SecPolicyRef policyRef) 136 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); 137 138/*! 139 @function SecPolicyCreateBasicX509 140 @abstract Returns a policy object for the default X.509 policy. 141 @result A policy object. The caller is responsible for calling CFRelease 142 on this when it is no longer needed. 143*/ 144SecPolicyRef SecPolicyCreateBasicX509(void) 145 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0); 146 147/*! 148 @function SecPolicyCreateSSL 149 @abstract Returns a policy object for evaluating SSL certificate chains. 150 @param server Passing true for this parameter creates a policy for SSL 151 server certificates. 152 @param hostname (Optional) If present, the policy will require the specified 153 hostname to match the hostname in the leaf certificate. 154 @result A policy object. The caller is responsible for calling CFRelease 155 on this when it is no longer needed. 156*/ 157SecPolicyRef SecPolicyCreateSSL(Boolean server, CFStringRef hostname) 158 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0); 159 160/*! 161 @enum Revocation Policy Constants 162 @abstract Predefined constants which allow you to specify how revocation 163 checking will be performed for a trust evaluation. 164 @constant kSecRevocationOCSPMethod If this flag is set, perform revocation 165 checking using OCSP (Online Certificate Status Protocol). 166 @constant kSecRevocationCRLMethod If this flag is set, perform revocation 167 checking using the CRL (Certificate Revocation List) method. 168 @constant kSecRevocationPreferCRL If this flag is set, then CRL revocation 169 checking will be preferred over OCSP (by default, OCSP is preferred.) 170 Note that this flag only matters if both revocation methods are specified. 171 @constant kSecRevocationRequirePositiveResponse If this flag is set, then 172 the policy will fail unless a verified positive response is obtained. If 173 the flag is not set, revocation checking is done on a "best attempt" basis, 174 where failure to reach the server is not considered fatal. 175 @constant kSecRevocationNetworkAccessDisabled If this flag is set, then 176 no network access is performed; only locally cached replies are consulted. 177 @constant kSecRevocationUseAnyAvailableMethod Specifies that either 178 OCSP or CRL may be used, depending on the method(s) specified in the 179 certificate and the value of kSecRevocationPreferCRL. 180 */ 181enum { 182 kSecRevocationOCSPMethod = (1 << 0), 183 kSecRevocationCRLMethod = (1 << 1), 184 kSecRevocationPreferCRL = (1 << 2), 185 kSecRevocationRequirePositiveResponse = (1 << 3), 186 kSecRevocationNetworkAccessDisabled = (1 << 4), 187 kSecRevocationUseAnyAvailableMethod = (kSecRevocationOCSPMethod | 188 kSecRevocationCRLMethod) 189}; 190 191/*! 192 @function SecPolicyCreateRevocation 193 @abstract Returns a policy object for checking revocation of certificates. 194 @result A policy object. The caller is responsible for calling CFRelease 195 on this when it is no longer needed. 196 @param revocationFlags Flags to specify revocation checking options. 197 @discussion Use this function to create a revocation policy with behavior 198 specified by revocationFlags. See the "Revocation Policy Constants" section 199 for a description of these flags. Note: it is usually not necessary to 200 create a revocation policy yourself unless you wish to override default 201 system behavior (e.g. to force a particular method, or to disable 202 revocation checking entirely.) 203*/ 204SecPolicyRef SecPolicyCreateRevocation(CFOptionFlags revocationFlags) 205 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 206 207/*! 208 @function SecPolicyCreateWithProperties 209 @abstract Returns a policy object based on an object identifier for the 210 policy type. See the "Policy Constants" section for a list of defined 211 policy object identifiers. 212 @param policyIdentifier The identifier for the desired policy type. 213 @param properties (Optional) A properties dictionary. See "Policy Value 214 Constants" for a list of currently defined property keys. 215 @result The returned policy reference, or NULL if the policy could not be 216 created. 217*/ 218SecPolicyRef SecPolicyCreateWithProperties(CFTypeRef policyIdentifier, 219 CFDictionaryRef properties) 220 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 221 222 223/* 224 * Legacy functions (OS X only) 225 */ 226#if TARGET_OS_MAC && !TARGET_OS_IPHONE 227#include <Security/cssmtype.h> 228 229/*! 230 @enum Policy Value Constants (OS X) 231 @discussion Predefined property key constants used to get or set values in 232 a dictionary for a policy instance. 233 234 Some policy values may specify CFBooleanRef key usage constraints: 235 kSecPolicyKU_DigitalSignature 236 kSecPolicyKU_NonRepudiation 237 kSecPolicyKU_KeyEncipherment 238 kSecPolicyKU_DataEncipherment 239 kSecPolicyKU_KeyAgreement 240 kSecPolicyKU_KeyCertSign 241 kSecPolicyKU_CRLSign 242 kSecPolicyKU_EncipherOnly 243 kSecPolicyKU_DecipherOnly 244 245 kSecPolicyKU policy values define certificate-level key purposes, 246 in contrast to the key-level definitions in SecItem.h 247 248 For example, a key in a certificate might be acceptable to use for 249 signing a CRL, but not for signing another certificate. In either 250 case, this key would have the ability to sign (i.e. kSecAttrCanSign 251 is true), but may only sign for specific purposes allowed by these 252 policy constants. Similarly, a public key might have the capability 253 to perform encryption or decryption, but the certificate in which it 254 resides might have a decipher-only certificate policy. 255 256 These constants correspond to values defined in RFC 5280, section 257 4.2.1.3 (Key Usage) which define the purpose of a key contained in a 258 certificate, in contrast to section 4.1.2.7 which define the uses that 259 a key is capable of. 260 261 Note: these constants are not available on iOS. Your code should 262 avoid direct reliance on these values for making policy decisions 263 and use higher level policies where possible. 264 265 @constant kSecPolicyKU_DigitalSignature Specifies that the certificate must 266 have a key usage that allows it to be used for signing. 267 @constant kSecPolicyKU_NonRepudiation Specifies that the certificate must 268 have a key usage that allows it to be used for non-repudiation. 269 @constant kSecPolicyKU_KeyEncipherment Specifies that the certificate must 270 have a key usage that allows it to be used for key encipherment. 271 @constant kSecPolicyKU_DataEncipherment Specifies that the certificate must 272 have a key usage that allows it to be used for data encipherment. 273 @constant kSecPolicyKU_KeyAgreement Specifies that the certificate must 274 have a key usage that allows it to be used for key agreement. 275 @constant kSecPolicyKU_KeyCertSign Specifies that the certificate must 276 have a key usage that allows it to be used for signing certificates. 277 @constant kSecPolicyKU_CRLSign Specifies that the certificate must 278 have a key usage that allows it to be used for signing CRLs. 279 @constant kSecPolicyKU_EncipherOnly Specifies that the certificate must 280 have a key usage that permits it to be used for encryption only. 281 @constant kSecPolicyKU_DecipherOnly Specifies that the certificate must 282 have a key usage that permits it to be used for decryption only. 283 */ 284extern CFTypeRef kSecPolicyKU_DigitalSignature 285 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 286extern CFTypeRef kSecPolicyKU_NonRepudiation 287 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 288extern CFTypeRef kSecPolicyKU_KeyEncipherment 289 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 290extern CFTypeRef kSecPolicyKU_DataEncipherment 291 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 292extern CFTypeRef kSecPolicyKU_KeyAgreement 293 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 294extern CFTypeRef kSecPolicyKU_KeyCertSign 295 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 296extern CFTypeRef kSecPolicyKU_CRLSign 297 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 298extern CFTypeRef kSecPolicyKU_EncipherOnly 299 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 300extern CFTypeRef kSecPolicyKU_DecipherOnly 301 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 302 303/*! 304 @function SecPolicyCreateWithOID 305 @abstract Returns a policy object based on an object identifier for the 306 policy type. See the "Policy Constants" section for a list of defined 307 policy object identifiers. 308 @param policyOID The OID of the desired policy. 309 @result The returned policy reference, or NULL if the policy could not be 310 created. 311 @discussion This function is deprecated in Mac OS X 10.9 and later; 312 use SecPolicyCreateWithProperties (or a more specific policy creation 313 function) instead. 314*/ 315SecPolicyRef SecPolicyCreateWithOID(CFTypeRef policyOID) 316 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA); 317 318/*! 319 @function SecPolicyGetOID 320 @abstract Returns a policy's object identifier. 321 @param policyRef A policy reference. 322 @param oid On return, a pointer to the policy's object identifier. 323 @result A result code. See "Security Error Codes" (SecBase.h). 324 @discussion This function is deprecated in Mac OS X 10.7 and later; 325 use SecPolicyCopyProperties instead. 326*/ 327OSStatus SecPolicyGetOID(SecPolicyRef policyRef, CSSM_OID *oid) 328 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); 329 330/*! 331 @function SecPolicyGetValue 332 @abstract Returns a policy's value. 333 @param policyRef A policy reference. 334 @param value On return, a pointer to the policy's value. 335 @result A result code. See "Security Error Codes" (SecBase.h). 336 @discussion This function is deprecated in Mac OS X 10.7 and later; 337 use SecPolicyCopyProperties instead. 338*/ 339OSStatus SecPolicyGetValue(SecPolicyRef policyRef, CSSM_DATA *value) 340 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); 341 342/*! 343 @function SecPolicySetValue 344 @abstract Sets a policy's value. 345 @param policyRef A policy reference. 346 @param value The value to be set into the policy object, replacing any 347 previous value. 348 @result A result code. See "Security Error Codes" (SecBase.h). 349 @discussion This function is deprecated in Mac OS X 10.7 and later. Policy 350 instances should be considered read-only; in cases where your code would 351 consider changing properties of a policy, it should instead create a new 352 policy instance with the desired properties. 353*/ 354OSStatus SecPolicySetValue(SecPolicyRef policyRef, const CSSM_DATA *value) 355 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); 356 357/*! 358 @function SecPolicySetProperties 359 @abstract Sets a policy's properties. 360 @param policyRef A policy reference. 361 @param properties A properties dictionary. See "Policy Value Constants" 362 for a list of currently defined property keys. This dictionary replaces the 363 policy's existing properties, if any. Note that the policy OID (specified 364 by kSecPolicyOid) is a read-only property of the policy and cannot be set. 365 @result A result code. See "Security Error Codes" (SecBase.h). 366 @discussion This function is deprecated in Mac OS X 10.9 and later. Policy 367 instances should be considered read-only; in cases where your code would 368 consider changing properties of a policy, it should instead create a new 369 policy instance with the desired properties. 370*/ 371OSStatus SecPolicySetProperties(SecPolicyRef policyRef, 372 CFDictionaryRef properties) 373 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA); 374 375/*! 376 @function SecPolicyGetTPHandle 377 @abstract Returns the CSSM trust policy handle for the given policy. 378 @param policyRef A policy reference. 379 @param tpHandle On return, a pointer to a value of type CSSM_TP_HANDLE. 380 @result A result code. See "Security Error Codes" (SecBase.h). 381 @discussion This function is deprecated in Mac OS X 10.7 and later. 382*/ 383OSStatus SecPolicyGetTPHandle(SecPolicyRef policyRef, CSSM_TP_HANDLE *tpHandle) 384 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); 385 386#endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */ 387 388 389__END_DECLS 390 391#endif /* !_SECURITY_SECPOLICY_H_ */ 392