X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/80e2389990082500d76eb566d4946be3e786c3ef..d8f41ccd20de16f8ebe2ccc84d47bf1cb2b26bbb:/Security/libsecurity_keychain/lib/SecPolicy.h diff --git a/Security/libsecurity_keychain/lib/SecPolicy.h b/Security/libsecurity_keychain/lib/SecPolicy.h new file mode 100644 index 00000000..3a42320a --- /dev/null +++ b/Security/libsecurity_keychain/lib/SecPolicy.h @@ -0,0 +1,408 @@ +/* + * Copyright (c) 2002-2014 Apple Inc. All Rights Reserved. + * + * @APPLE_LICENSE_HEADER_START@ + * + * This file contains Original Code and/or Modifications of Original Code + * as defined in and that are subject to the Apple Public Source License + * Version 2.0 (the 'License'). You may not use this file except in + * compliance with the License. Please obtain a copy of the License at + * http://www.opensource.apple.com/apsl/ and read it before using this + * file. + * + * The Original Code and all software distributed under the License are + * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER + * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, + * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. + * Please see the License for the specific language governing rights and + * limitations under the License. + * + * @APPLE_LICENSE_HEADER_END@ + */ + +/*! + @header SecPolicy + The functions provided in SecPolicy.h provide an interface to various + X.509 certificate trust policies. +*/ + +#ifndef _SECURITY_SECPOLICY_H_ +#define _SECURITY_SECPOLICY_H_ + +#include +#include +#include + +#if defined(__cplusplus) +extern "C" { +#endif + +/*! + @enum Policy Constants + @discussion Predefined constants used to specify a policy. + @constant kSecPolicyAppleX509Basic + @constant kSecPolicyAppleSSL + @constant kSecPolicyAppleSMIME + @constant kSecPolicyAppleEAP + @constant kSecPolicyAppleIPsec + @constant kSecPolicyAppleiChat + @constant kSecPolicyApplePKINITClient + @constant kSecPolicyApplePKINITServer + @constant kSecPolicyAppleCodeSigning + @constant kSecPolicyMacAppStoreReceipt + @constant kSecPolicyAppleIDValidation + @constant kSecPolicyAppleTimeStamping + @constant kSecPolicyAppleRevocation + @constant kSecPolicyApplePassbookSigning +*/ +extern CFTypeRef kSecPolicyAppleX509Basic + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyAppleSSL + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyAppleSMIME + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyAppleEAP + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyAppleIPsec + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyAppleiChat + __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA); +extern CFTypeRef kSecPolicyApplePKINITClient + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyApplePKINITServer + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyAppleCodeSigning + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyMacAppStoreReceipt + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyAppleIDValidation + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyAppleTimeStamping + __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_7_0); +extern CFTypeRef kSecPolicyAppleRevocation + __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); +extern CFTypeRef kSecPolicyApplePassbookSigning + __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); + +/*! + @enum Policy Value Constants + @abstract Predefined property key constants used to get or set values in + a dictionary for a policy instance. + @discussion + All policies will have the following read-only value: + kSecPolicyOid (the policy object identifier) + + Additional policy values which your code can optionally set: + kSecPolicyName (name which must be matched) + kSecPolicyClient (evaluate for client, rather than server) + kSecPolicyRevocationFlags (only valid for a revocation policy) + + @constant kSecPolicyOid Specifies the policy OID (value is a CFStringRef) + @constant kSecPolicyName Specifies a CFStringRef (or CFArrayRef of same) + containing a name which must be matched in the certificate to satisfy + this policy. For SSL/TLS, EAP, and IPSec policies, this specifies the + server name which must match the common name of the certificate. + For S/MIME, this specifies the RFC822 email address. + For Passbook signing, this specifies the pass signer. + @constant kSecPolicyClient Specifies a CFBooleanRef value that indicates + this evaluation should be for a client certificate. If not set (or + false), the policy evaluates the certificate as a server certificate. + @constant kSecPolicyRevocationFlags Specifies a CFNumberRef that holds a + kCFNumberCFIndexType bitmask value. See "Revocation Policy Constants" + for a description of individual bits in this value. + @constant kSecPolicyTeamIdentifier Specifies a CFStringRef containing a + team identifier which must be matched in the certificate to satisfy + this policy. For the Passbook signing policy, this string must match + the Organizational Unit field of the certificate subject. + */ +extern CFTypeRef kSecPolicyOid + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyName + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyClient + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); +extern CFTypeRef kSecPolicyRevocationFlags + __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); +extern CFTypeRef kSecPolicyTeamIdentifier + __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); + + +/*! + @function SecPolicyGetTypeID + @abstract Returns the type identifier of SecPolicy instances. + @result The CFTypeID of SecPolicy instances. +*/ +CFTypeID SecPolicyGetTypeID(void) + __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0); + +/*! + @function SecPolicyCopyProperties + @abstract Returns a dictionary of this policy's properties. + @param policyRef A policy reference. + @result A properties dictionary. See "Policy Value Constants" for a list + of currently defined property keys. It is the caller's responsibility to + CFRelease this reference when it is no longer needed. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function returns the properties for a policy, as set by the + policy's construction function or by a prior call to SecPolicySetProperties. +*/ +CFDictionaryRef SecPolicyCopyProperties(SecPolicyRef policyRef) + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0); + +/*! + @function SecPolicyCreateBasicX509 + @abstract Returns a policy object for the default X.509 policy. + @result A policy object. The caller is responsible for calling CFRelease + on this when it is no longer needed. +*/ +SecPolicyRef SecPolicyCreateBasicX509(void) + __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0); + +/*! + @function SecPolicyCreateSSL + @abstract Returns a policy object for evaluating SSL certificate chains. + @param server Passing true for this parameter creates a policy for SSL + server certificates. + @param hostname (Optional) If present, the policy will require the specified + hostname to match the hostname in the leaf certificate. + @result A policy object. The caller is responsible for calling CFRelease + on this when it is no longer needed. +*/ +SecPolicyRef SecPolicyCreateSSL(Boolean server, CFStringRef hostname) + __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0); + +/*! + @enum Revocation Policy Constants + @abstract Predefined constants which allow you to specify how revocation + checking will be performed for a trust evaluation. + @constant kSecRevocationOCSPMethod If this flag is set, perform revocation + checking using OCSP (Online Certificate Status Protocol). + @constant kSecRevocationCRLMethod If this flag is set, perform revocation + checking using the CRL (Certificate Revocation List) method. + @constant kSecRevocationPreferCRL If this flag is set, then CRL revocation + checking will be preferred over OCSP (by default, OCSP is preferred.) + Note that this flag only matters if both revocation methods are specified. + @constant kSecRevocationRequirePositiveResponse If this flag is set, then + the policy will fail unless a verified positive response is obtained. If + the flag is not set, revocation checking is done on a "best attempt" basis, + where failure to reach the server is not considered fatal. + @constant kSecRevocationNetworkAccessDisabled If this flag is set, then + no network access is performed; only locally cached replies are consulted. + @constant kSecRevocationUseAnyAvailableMethod Specifies that either + OCSP or CRL may be used, depending on the method(s) specified in the + certificate and the value of kSecRevocationPreferCRL. + */ +enum { + kSecRevocationOCSPMethod = (1 << 0), + kSecRevocationCRLMethod = (1 << 1), + kSecRevocationPreferCRL = (1 << 2), + kSecRevocationRequirePositiveResponse = (1 << 3), + kSecRevocationNetworkAccessDisabled = (1 << 4), + kSecRevocationUseAnyAvailableMethod = (kSecRevocationOCSPMethod | + kSecRevocationCRLMethod) +}; + +/*! + @function SecPolicyCreateRevocation + @abstract Returns a policy object for checking revocation of certificates. + @result A policy object. The caller is responsible for calling CFRelease + on this when it is no longer needed. + @param revocationFlags Flags to specify revocation checking options. + @discussion Use this function to create a revocation policy with behavior + specified by revocationFlags. See the "Revocation Policy Constants" section + for a description of these flags. Note: it is usually not necessary to + create a revocation policy yourself unless you wish to override default + system behavior (e.g. to force a particular method, or to disable + revocation checking entirely.) +*/ +SecPolicyRef SecPolicyCreateRevocation(CFOptionFlags revocationFlags) + __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); + +/*! + @function SecPolicyCreateWithProperties + @abstract Returns a policy object based on an object identifier for the + policy type. See the "Policy Constants" section for a list of defined + policy object identifiers. + @param policyIdentifier The identifier for the desired policy type. + @param properties (Optional) A properties dictionary. See "Policy Value + Constants" for a list of currently defined property keys. + @result The returned policy reference, or NULL if the policy could not be + created. +*/ +SecPolicyRef SecPolicyCreateWithProperties(CFTypeRef policyIdentifier, + CFDictionaryRef properties) + __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); + + +/* + * Legacy functions (OS X only) + */ +#if TARGET_OS_MAC && !TARGET_OS_IPHONE +#include + +/*! + @enum Policy Value Constants (OS X) + @discussion Predefined property key constants used to get or set values in + a dictionary for a policy instance. + + Some policy values may specify CFBooleanRef key usage constraints: + kSecPolicyKU_DigitalSignature + kSecPolicyKU_NonRepudiation + kSecPolicyKU_KeyEncipherment + kSecPolicyKU_DataEncipherment + kSecPolicyKU_KeyAgreement + kSecPolicyKU_KeyCertSign + kSecPolicyKU_CRLSign + kSecPolicyKU_EncipherOnly + kSecPolicyKU_DecipherOnly + + kSecPolicyKU policy values define certificate-level key purposes, + in contrast to the key-level definitions in SecItem.h + + For example, a key in a certificate might be acceptable to use for + signing a CRL, but not for signing another certificate. In either + case, this key would have the ability to sign (i.e. kSecAttrCanSign + is true), but may only sign for specific purposes allowed by these + policy constants. Similarly, a public key might have the capability + to perform encryption or decryption, but the certificate in which it + resides might have a decipher-only certificate policy. + + These constants correspond to values defined in RFC 5280, section + 4.2.1.3 (Key Usage) which define the purpose of a key contained in a + certificate, in contrast to section 4.1.2.7 which define the uses that + a key is capable of. + + Note: these constants are not available on iOS. Your code should + avoid direct reliance on these values for making policy decisions + and use higher level policies where possible. + + @constant kSecPolicyKU_DigitalSignature Specifies that the certificate must + have a key usage that allows it to be used for signing. + @constant kSecPolicyKU_NonRepudiation Specifies that the certificate must + have a key usage that allows it to be used for non-repudiation. + @constant kSecPolicyKU_KeyEncipherment Specifies that the certificate must + have a key usage that allows it to be used for key encipherment. + @constant kSecPolicyKU_DataEncipherment Specifies that the certificate must + have a key usage that allows it to be used for data encipherment. + @constant kSecPolicyKU_KeyAgreement Specifies that the certificate must + have a key usage that allows it to be used for key agreement. + @constant kSecPolicyKU_KeyCertSign Specifies that the certificate must + have a key usage that allows it to be used for signing certificates. + @constant kSecPolicyKU_CRLSign Specifies that the certificate must + have a key usage that allows it to be used for signing CRLs. + @constant kSecPolicyKU_EncipherOnly Specifies that the certificate must + have a key usage that permits it to be used for encryption only. + @constant kSecPolicyKU_DecipherOnly Specifies that the certificate must + have a key usage that permits it to be used for decryption only. + */ +extern CFTypeRef kSecPolicyKU_DigitalSignature + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_NonRepudiation + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_KeyEncipherment + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_DataEncipherment + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_KeyAgreement + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_KeyCertSign + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_CRLSign + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_EncipherOnly + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); +extern CFTypeRef kSecPolicyKU_DecipherOnly + __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); + +/*! + @function SecPolicyCreateWithOID + @abstract Returns a policy object based on an object identifier for the + policy type. See the "Policy Constants" section for a list of defined + policy object identifiers. + @param policyOID The OID of the desired policy. + @result The returned policy reference, or NULL if the policy could not be + created. + @discussion This function is deprecated in Mac OS X 10.9 and later; + use SecPolicyCreateWithProperties (or a more specific policy creation + function) instead. +*/ +SecPolicyRef SecPolicyCreateWithOID(CFTypeRef policyOID) + __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA); + +/*! + @function SecPolicyGetOID + @abstract Returns a policy's object identifier. + @param policyRef A policy reference. + @param oid On return, a pointer to the policy's object identifier. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later; + use SecPolicyCopyProperties instead. +*/ +OSStatus SecPolicyGetOID(SecPolicyRef policyRef, CSSM_OID *oid) + __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); + +/*! + @function SecPolicyGetValue + @abstract Returns a policy's value. + @param policyRef A policy reference. + @param value On return, a pointer to the policy's value. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later; + use SecPolicyCopyProperties instead. +*/ +OSStatus SecPolicyGetValue(SecPolicyRef policyRef, CSSM_DATA *value) + __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); + +/*! + @function SecPolicySetValue + @abstract Sets a policy's value. + @param policyRef A policy reference. + @param value The value to be set into the policy object, replacing any + previous value. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later. Policy + instances should be considered read-only; in cases where your code would + consider changing properties of a policy, it should instead create a new + policy instance with the desired properties. +*/ +OSStatus SecPolicySetValue(SecPolicyRef policyRef, const CSSM_DATA *value) + __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); + +/*! + @function SecPolicySetProperties + @abstract Sets a policy's properties. + @param policyRef A policy reference. + @param properties A properties dictionary. See "Policy Value Constants" + for a list of currently defined property keys. This dictionary replaces the + policy's existing properties, if any. Note that the policy OID (specified + by kSecPolicyOid) is a read-only property of the policy and cannot be set. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.9 and later. Policy + instances should be considered read-only; in cases where your code would + consider changing properties of a policy, it should instead create a new + policy instance with the desired properties. +*/ +OSStatus SecPolicySetProperties(SecPolicyRef policyRef, + CFDictionaryRef properties) + __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA); + +/*! + @function SecPolicyGetTPHandle + @abstract Returns the CSSM trust policy handle for the given policy. + @param policyRef A policy reference. + @param tpHandle On return, a pointer to a value of type CSSM_TP_HANDLE. + @result A result code. See "Security Error Codes" (SecBase.h). + @discussion This function is deprecated in Mac OS X 10.7 and later. +*/ +OSStatus SecPolicyGetTPHandle(SecPolicyRef policyRef, CSSM_TP_HANDLE *tpHandle) + __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA); + +#endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */ + + +#if defined(__cplusplus) +} +#endif + +#endif /* !_SECURITY_SECPOLICY_H_ */