libsecurity_keychain/lib/SecPolicy.h

   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)
  38 extern "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 */
  59 extern CFTypeRef kSecPolicyAppleX509Basic
  60     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  61 extern CFTypeRef kSecPolicyAppleSSL
  62     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  63 extern CFTypeRef kSecPolicyAppleSMIME
  64     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  65 extern CFTypeRef kSecPolicyAppleEAP
  66     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  67 extern CFTypeRef kSecPolicyAppleIPsec
  68     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  69 extern CFTypeRef kSecPolicyAppleiChat
  70     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
  71 extern CFTypeRef kSecPolicyApplePKINITClient
  72     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  73 extern CFTypeRef kSecPolicyApplePKINITServer
  74     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  75 extern CFTypeRef kSecPolicyAppleCodeSigning
  76     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  77 extern CFTypeRef kSecPolicyMacAppStoreReceipt
  78     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  79 extern CFTypeRef kSecPolicyAppleIDValidation
  80     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
  81 extern CFTypeRef kSecPolicyAppleTimeStamping
  82     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_7_0);
  83 extern CFTypeRef kSecPolicyAppleRevocation
  84     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
  85 extern 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  */
 119 extern CFTypeRef kSecPolicyOid
 120         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 121 extern CFTypeRef kSecPolicyName
 122         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 123 extern CFTypeRef kSecPolicyClient
 124         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
 125 extern CFTypeRef kSecPolicyRevocationFlags
 126         __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 127 extern 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 */
 136 CFTypeID 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 */
 150 CFDictionaryRef 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 */
 159 SecPolicyRef 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 */
 172 SecPolicyRef 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  */
 196 enum {
 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 */
 219 SecPolicyRef 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 */
 233 SecPolicyRef 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  */
 299 extern CFTypeRef kSecPolicyKU_DigitalSignature
 300         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 301 extern CFTypeRef kSecPolicyKU_NonRepudiation
 302         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 303 extern CFTypeRef kSecPolicyKU_KeyEncipherment
 304         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 305 extern CFTypeRef kSecPolicyKU_DataEncipherment
 306         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 307 extern CFTypeRef kSecPolicyKU_KeyAgreement
 308         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 309 extern CFTypeRef kSecPolicyKU_KeyCertSign
 310         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 311 extern CFTypeRef kSecPolicyKU_CRLSign
 312         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 313 extern CFTypeRef kSecPolicyKU_EncipherOnly
 314         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 315 extern 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 */
 330 SecPolicyRef 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 */
 342 OSStatus 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 */
 354 OSStatus 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 */
 369 OSStatus 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 */
 386 OSStatus 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 */
 398 OSStatus 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_ */