sec/Security/SecPolicy.h

   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 */
  55 extern CFTypeRef kSecPolicyAppleX509Basic
  56     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  57 extern CFTypeRef kSecPolicyAppleSSL
  58     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  59 extern CFTypeRef kSecPolicyAppleSMIME
  60     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  61 extern CFTypeRef kSecPolicyAppleEAP
  62     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  63 extern CFTypeRef kSecPolicyAppleIPsec
  64     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  65 extern CFTypeRef kSecPolicyApplePKINITClient
  66     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  67 extern CFTypeRef kSecPolicyApplePKINITServer
  68     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  69 extern CFTypeRef kSecPolicyAppleCodeSigning
  70     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  71 extern CFTypeRef kSecPolicyMacAppStoreReceipt
  72     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  73 extern CFTypeRef kSecPolicyAppleIDValidation
  74     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  75 extern CFTypeRef kSecPolicyAppleTimeStamping
  76     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_7_0);
  77 extern 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  */
 106 extern CFTypeRef kSecPolicyOid
 107         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 108 extern CFTypeRef kSecPolicyName
 109         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 110 extern CFTypeRef kSecPolicyClient
 111         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 112 extern 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 */
 121 CFTypeID 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 */
 135 CFDictionaryRef 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 */
 144 SecPolicyRef 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 */
 157 SecPolicyRef 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  */
 181 enum {
 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 */
 204 SecPolicyRef 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 */
 218 SecPolicyRef 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  */
 284 extern CFTypeRef kSecPolicyKU_DigitalSignature
 285         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 286 extern CFTypeRef kSecPolicyKU_NonRepudiation
 287         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 288 extern CFTypeRef kSecPolicyKU_KeyEncipherment
 289         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 290 extern CFTypeRef kSecPolicyKU_DataEncipherment
 291         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 292 extern CFTypeRef kSecPolicyKU_KeyAgreement
 293         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 294 extern CFTypeRef kSecPolicyKU_KeyCertSign
 295         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 296 extern CFTypeRef kSecPolicyKU_CRLSign
 297         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 298 extern CFTypeRef kSecPolicyKU_EncipherOnly
 299         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 300 extern 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 */
 315 SecPolicyRef 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 */
 327 OSStatus 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 */
 339 OSStatus 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 */
 354 OSStatus 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 */
 371 OSStatus 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 */
 383 OSStatus 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_ */