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