OSX/libsecurity_keychain/lib/SecPolicy.h

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