OSX/libsecurity_keychain/lib/SecPolicy.h

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