OSX/sec/Security/SecPolicy.h

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