libsecurity_keychain/lib/SecPolicy.h

   1 /*
   2  * Copyright (c) 2002-2010 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 #include <Security/cssmtype.h>
  37
  38 #if defined(__cplusplus)
  39 extern "C" {
  40 #endif
  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 kSecPolicyAppleiChat
  51         @constant kSecPolicyApplePKINITClient
  52         @constant kSecPolicyApplePKINITServer
  53         @constant kSecPolicyAppleCodeSigning
  54         @constant kSecPolicyMacAppStoreReceipt
  55         @constant kSecPolicyAppleIDValidation
  56         @constant kSecPolicyAppleTimeStamping
  57 */
  58 extern CFTypeRef kSecPolicyAppleX509Basic
  59     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  60 extern CFTypeRef kSecPolicyAppleSSL
  61     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  62 extern CFTypeRef kSecPolicyAppleSMIME
  63     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  64 extern CFTypeRef kSecPolicyAppleEAP
  65     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  66 extern CFTypeRef kSecPolicyAppleIPsec
  67     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  68 extern CFTypeRef kSecPolicyAppleiChat
  69     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  70 extern CFTypeRef kSecPolicyApplePKINITClient
  71     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  72 extern CFTypeRef kSecPolicyApplePKINITServer
  73     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  74 extern CFTypeRef kSecPolicyAppleCodeSigning
  75     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  76 extern CFTypeRef kSecPolicyMacAppStoreReceipt
  77     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  78 extern CFTypeRef kSecPolicyAppleIDValidation
  79     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
  80 extern CFTypeRef kSecPolicyAppleTimeStamping
  81     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_NA);
  82
  83 /*!
  84     @enum Policy Value Constants
  85     @discussion Predefined property key constants used to get or set values in
  86         a dictionary for a policy instance.
  87
  88         All policies will have the following read-only value:
  89             kSecPolicyOid       (the policy object identifier)
  90
  91         Additional policy values which your code can optionally set:
  92             kSecPolicyName      (name which must be matched)
  93             kSecPolicyClient    (evaluate for client, rather than server)
  94
  95         Policy values may also specify CFBooleanRef key usage constraints:
  96             kSecPolicyKU_DigitalSignature
  97             kSecPolicyKU_NonRepudiation
  98             kSecPolicyKU_KeyEncipherment
  99             kSecPolicyKU_DataEncipherment
 100             kSecPolicyKU_KeyAgreement
 101             kSecPolicyKU_KeyCertSign
 102             kSecPolicyKU_CRLSign
 103             kSecPolicyKU_EncipherOnly
 104             kSecPolicyKU_DecipherOnly
 105
 106         Note that these policy values cover certificate-level purpose
 107         definitions, in contrast to the key-level definitions in
 108         SecItem.h. For example, a key in a certificate might be
 109         acceptable for CRL signing, but not NonRepudiation. In either
 110         case, this key would definitely have (via SecItem.h) the ability
 111         to sign; it is the *context* of signing that is defined further
 112         in these policy constants. Similarly, a key might be able to do
 113         both encryption and decryption, but the certificate in which it
 114         resides might have a decipher-only certificate policy in
 115         certificate A, but not in certificate B. These policy values
 116         refine the key's attributes within the context of the
 117         certificate.
 118
 119         They correspond to values defined in RFC 5280, section 4.2.1.3
 120         (Key Usage) which define the purpose of a key contained in a
 121         certificate, in contrast to section 4.1.2.7 which define what a
 122         key is capable of.
 123
 124     @constant kSecPolicyOid Specifies the policy OID (value is a CFStringRef)
 125     @constant kSecPolicyName Specifies a CFStringRef containing a name which
 126         must be matched in the certificate to satisfy this policy. For SSL/TLS,
 127         this specifies the server name which must match the common name of the
 128         certificate. For S/MIME, this specifies the RFC822 email address.
 129     @constant kSecPolicyClient Specifies a CFBooleanRef value that indicates
 130         this evaluation should be for a client certificate. If not set (or
 131         false), the policy evaluates the certificate for the server.
 132     @constant kSecPolicyKU_DigitalSignature Specifies that the certificate must
 133         have a key usage that allows it to be used for signing.
 134     @constant kSecPolicyKU_NonRepudiation Specifies that the certificate must
 135         have a key usage that allows it to be used for non-repudiation.
 136     @constant kSecPolicyKU_KeyEncipherment Specifies that the certificate must
 137         have a key usage that allows it to be used for key encipherment.
 138     @constant kSecPolicyKU_DataEncipherment Specifies that the certificate must
 139         have a key usage that allows it to be used for data encipherment.
 140     @constant kSecPolicyKU_KeyAgreement Specifies that the certificate must
 141         have a key usage that allows it to be used for key agreement.
 142     @constant kSecPolicyKU_KeyCertSign Specifies that the certificate must
 143         have a key usage that allows it to be used for signing certificates.
 144     @constant kSecPolicyKU_CRLSign Specifies that the certificate must
 145         have a key usage that allows it to be used for signing CRLs.
 146     @constant kSecPolicyKU_EncipherOnly Specifies that the certificate must
 147         have a key usage that permits it to be used for encryption only.
 148     @constant kSecPolicyKU_DecipherOnly Specifies that the certificate must
 149         have a key usage that permits it to be used for decryption only.
 150 */
 151 extern CFTypeRef kSecPolicyOid
 152     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 153 extern CFTypeRef kSecPolicyName
 154         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 155 extern CFTypeRef kSecPolicyClient
 156         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 157
 158 extern CFTypeRef kSecPolicyKU_DigitalSignature
 159         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 160 extern CFTypeRef kSecPolicyKU_NonRepudiation
 161         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 162 extern CFTypeRef kSecPolicyKU_KeyEncipherment
 163         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 164 extern CFTypeRef kSecPolicyKU_DataEncipherment
 165         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 166 extern CFTypeRef kSecPolicyKU_KeyAgreement
 167         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 168 extern CFTypeRef kSecPolicyKU_KeyCertSign
 169         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 170 extern CFTypeRef kSecPolicyKU_CRLSign
 171         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 172 extern CFTypeRef kSecPolicyKU_EncipherOnly
 173         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 174 extern CFTypeRef kSecPolicyKU_DecipherOnly
 175         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 176
 177
 178 /*!
 179     @function SecPolicyGetTypeID
 180     @abstract Returns the type identifier of SecPolicy instances.
 181     @result The CFTypeID of SecPolicy instances.
 182 */
 183 CFTypeID SecPolicyGetTypeID(void)
 184     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 185
 186 /*!
 187     @function SecPolicyGetOID
 188     @abstract Returns a policy's object identifier.
 189     @param policyRef A policy reference.
 190     @param oid On return, a pointer to the policy's object identifier.
 191     @result A result code. See "Security Error Codes" (SecBase.h).
 192         @discussion This function is deprecated in Mac OS X 10.7 and later;
 193         use SecPolicyCopyProperties instead.
 194 */
 195 OSStatus SecPolicyGetOID(SecPolicyRef policyRef, CSSM_OID *oid)
 196         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 197
 198 /*!
 199     @function SecPolicyGetValue
 200     @abstract Returns a policy's value.
 201     @param policyRef A policy reference.
 202     @param value On return, a pointer to the policy's value.
 203     @result A result code. See "Security Error Codes" (SecBase.h).
 204         @discussion This function is deprecated in Mac OS X 10.7 and later;
 205         use SecPolicyCopyProperties instead.
 206 */
 207 OSStatus SecPolicyGetValue(SecPolicyRef policyRef, CSSM_DATA *value)
 208         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 209
 210 /*!
 211     @function SecPolicyCopyProperties
 212     @abstract Returns a dictionary of this policy's properties.
 213     @param policyRef A policy reference.
 214     @result A properties dictionary. See "Policy Value Constants" for a list
 215     of currently defined property keys. It is the caller's responsibility to
 216     CFRelease this reference when it is no longer needed.
 217     @result A result code. See "Security Error Codes" (SecBase.h).
 218         @discussion This function returns the properties for a policy, as set by the
 219         policy's construction function or by a prior call to SecPolicySetProperties.
 220 */
 221 CFDictionaryRef SecPolicyCopyProperties(SecPolicyRef policyRef)
 222     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 223
 224 /*!
 225     @function SecPolicySetValue
 226     @abstract Sets a policy's value.
 227     @param policyRef A policy reference.
 228     @param value The value to be set into the policy object, replacing any
 229         previous value.
 230     @result A result code. See "Security Error Codes" (SecBase.h).
 231         @discussion This function is deprecated in Mac OS X 10.7 and later;
 232         use SecPolicySetProperties instead.
 233 */
 234 OSStatus SecPolicySetValue(SecPolicyRef policyRef, const CSSM_DATA *value)
 235         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 236
 237 /*!
 238     @function SecPolicySetProperties
 239     @abstract Sets a policy's properties.
 240     @param policyRef A policy reference.
 241     @param properties A properties dictionary. See "Policy Value Constants"
 242     for a list of currently defined property keys. This dictionary replaces the
 243     policy's existing properties, if any. Note that the policy OID (specified
 244     by kSecPolicyOid) is a read-only property of the policy and cannot be set.
 245     @result A result code. See "Security Error Codes" (SecBase.h).
 246 */
 247 OSStatus SecPolicySetProperties(SecPolicyRef policyRef,
 248         CFDictionaryRef properties)
 249     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 250
 251 /*!
 252     @function SecPolicyGetTPHandle
 253     @abstract Returns the CSSM trust policy handle for the given policy.
 254     @param policyRef A policy reference.
 255     @param tpHandle On return, a pointer to a value of type CSSM_TP_HANDLE.
 256     @result A result code. See "Security Error Codes" (SecBase.h).
 257         @discussion This function is deprecated in Mac OS X 10.7 and later.
 258 */
 259 OSStatus SecPolicyGetTPHandle(SecPolicyRef policyRef, CSSM_TP_HANDLE *tpHandle)
 260         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 261
 262 /*!
 263     @function SecPolicyCreateBasicX509
 264     @abstract Returns a policy object for the default X.509 policy.
 265     @result A policy object. The caller is responsible for calling CFRelease
 266         on this when it is no longer needed.
 267 */
 268 SecPolicyRef SecPolicyCreateBasicX509(void)
 269     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 270
 271 /*!
 272     @function SecPolicyCreateSSL
 273     @abstract Returns a policy object for evaluating SSL certificate chains.
 274         @param server Passing true for this parameter creates a policy for SSL
 275         server certificates.
 276         @param hostname (Optional) If present, the policy will require the specified
 277         hostname to match the hostname in the leaf certificate.
 278     @result A policy object. The caller is responsible for calling CFRelease
 279         on this when it is no longer needed.
 280 */
 281 SecPolicyRef SecPolicyCreateSSL(Boolean server, CFStringRef hostname)
 282     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 283
 284 /*!
 285         @function SecPolicyCreateWithOID
 286         @abstract Returns a policy object based on an object identifier for the
 287         policy type. See the "Policy Constants" section for a list of defined
 288         policy object identifiers.
 289     @param policyOID The OID of the desired policy.
 290         @result The returned policy reference, or NULL if the policy could not be
 291         created.
 292 */
 293 SecPolicyRef SecPolicyCreateWithOID(CFTypeRef policyOID)
 294     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 295
 296
 297 #if defined(__cplusplus)
 298 }
 299 #endif
 300
 301 #endif /* !_SECURITY_SECPOLICY_H_ */