OSX/libsecurity_keychain/lib/SecTrustPriv.h

   1 /*
   2  * Copyright (c) 2003-2012,2014-2015 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 SecTrustPriv
  26         Private part of SecTrust.h
  27 */
  28
  29 #ifndef _SECURITY_SECTRUST_PRIV_H_
  30 #define _SECURITY_SECTRUST_PRIV_H_
  31
  32 #include <Security/SecTrust.h>
  33 #include <CoreFoundation/CFString.h>
  34 #include <CoreFoundation/CFDictionary.h>
  35
  36
  37 #if defined(__cplusplus)
  38 extern "C" {
  39 #endif
  40
  41 /*
  42         unique keychain item attributes for user trust records.
  43 */
  44 enum {
  45     kSecTrustCertAttr                            = 'tcrt',
  46     kSecTrustPolicyAttr                          = 'tpol',
  47         /* Leopard and later */
  48         kSecTrustPubKeyAttr                              = 'tpbk',
  49         kSecTrustSignatureAttr                   = 'tsig'
  50 };
  51
  52 /*!
  53         @function SecTrustGetUserTrust
  54         @abstract Gets the user-specified trust settings of a certificate and policy.
  55         @param certificate A reference to a certificate.
  56         @param policy A reference to a policy.
  57         @param trustSetting On return, a pointer to the user specified trust settings.
  58         @result A result code. See "Security Error Codes" (SecBase.h).
  59         @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
  60 */
  61 OSStatus SecTrustGetUserTrust(SecCertificateRef certificate, SecPolicyRef policy, SecTrustUserSetting *trustSetting)
  62         /*DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER*/;
  63
  64 /*!
  65         @function SecTrustSetUserTrust
  66         @abstract Sets the user-specified trust settings of a certificate and policy.
  67         @param certificate A reference to a certificate.
  68         @param policy A reference to a policy.
  69         @param trustSetting The user-specified trust settings.
  70         @result A result code. See "Security Error Codes" (SecBase.h).
  71         @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
  72         @discussion as of Mac OS version 10.5, this will result in a call to
  73          SecTrustSettingsSetTrustSettings().
  74 */
  75 OSStatus SecTrustSetUserTrust(SecCertificateRef certificate, SecPolicyRef policy, SecTrustUserSetting trustSetting)
  76         /*DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER*/;
  77
  78 /*!
  79         @function SecTrustSetUserTrustLegacy
  80         @abstract Sets the user-specified trust settings of a certificate and policy.
  81         @param certificate A reference to a certificate.
  82         @param policy A reference to a policy.
  83         @param trustSetting The user-specified trust settings.
  84         @result A result code.  See "Security Error Codes" (SecBase.h).
  85
  86         @This is the private version of what used to be SecTrustSetUserTrust(); it operates
  87          on UserTrust entries as that function used to. The current SecTrustSetUserTrust()
  88          function operated on Trust Settings.
  89 */
  90 OSStatus SecTrustSetUserTrustLegacy(SecCertificateRef certificate, SecPolicyRef policy, SecTrustUserSetting trustSetting);
  91
  92 /*!
  93         @function SecTrustGetCSSMAnchorCertificates
  94         @abstract Retrieves the CSSM anchor certificates.
  95         @param cssmAnchors A pointer to an array of anchor certificates.
  96         @param cssmAnchorCount A pointer to the number of certificates in anchors.
  97         @result A result code. See "Security Error Codes" (SecBase.h).
  98         @availability Mac OS X version 10.4. Deprecated in Mac OS X version 10.5.
  99 */
 100 OSStatus SecTrustGetCSSMAnchorCertificates(const CSSM_DATA **cssmAnchors, uint32 *cssmAnchorCount)
 101         /*DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER*/;
 102
 103 /*!
 104         @function SecTrustCopyExtendedResult
 105         @abstract Gets the extended trust result after an evaluation has been performed.
 106         @param trust A trust reference.
 107         @param result On return, result points to a CFDictionaryRef containing extended trust results (if no error occurred).
 108         The caller is responsible for releasing this dictionary with CFRelease when finished with it.
 109         @result A result code. See "Security Error Codes" (SecBase.h).
 110         @discussion This function may only be used after SecTrustEvaluate has been called for the trust reference, otherwise
 111         errSecTrustNotAvailable is returned. If the certificate is not an extended validation certificate, there is
 112         no extended result data and errSecDataNotAvailable is returned. Currently, only one dictionary key is defined
 113         (kSecEVOrganizationName).
 114
 115         Note: this function will be deprecated in a future release of OS X. Your
 116         code should use SecTrustCopyResult to obtain the trust results dictionary.
 117 */
 118 OSStatus SecTrustCopyExtendedResult(SecTrustRef trust, CFDictionaryRef *result)
 119         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 120
 121
 122 /*!
 123     @enum Trust Result Constants
 124     @discussion Predefined key constants used to obtain values in a
 125         dictionary of trust evaluation results for a certificate chain,
 126         as retrieved from a call to SecTrustCopyResult.
 127
 128     @constant kSecTrustResultDetails
 129         This key will be present if a trust evaluation has been performed.
 130         Its value is a CFArrayRef of CFDictionaryRef representing detailed
 131         status info for each certificate in the completed chain.
 132     @constant kSecTrustRevocationReason
 133         This key will be present iff this chain had its revocation checked,
 134         and a "revoked" response was received. The value of this key will
 135         be a CFNumberRef indicating the reason for revocation. The possible
 136         reason code values are described in RFC 5280, section 5.3.1.
 137  */
 138 extern const CFStringRef kSecTrustResultDetails;
 139     /*__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_NA);*/
 140 extern const CFStringRef kSecTrustRevocationReason;
 141     /*__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);*/
 142
 143 /*
 144  * Preference-related strings for Revocation policies.
 145  */
 146
 147 /*
 148  * Preference domain, i.e., the name of a plist in ~/Library/Preferences or in
 149  * /Library/Preferences
 150  */
 151 #define kSecRevocationDomain            "com.apple.security.revocation"
 152
 153 /* OCSP and CRL style keys, followed by values used for both of them */
 154 #define kSecRevocationOcspStyle                         CFSTR("OCSPStyle")
 155 #define kSecRevocationCrlStyle                          CFSTR("CRLStyle")
 156   #define kSecRevocationOff                                     CFSTR("None")
 157   #define kSecRevocationBestAttempt                     CFSTR("BestAttempt")
 158   #define kSecRevocationRequireIfPresent        CFSTR("RequireIfPresent")
 159   #define kSecRevocationRequireForAll           CFSTR("RequireForAll")
 160
 161 /* Which first if both enabled? */
 162 #define kSecRevocationWhichFirst                        CFSTR("RevocationFirst")
 163   #define kSecRevocationOcspFirst                       CFSTR("OCSP")
 164   #define kSecRevocationCrlFirst                        CFSTR("CRL")
 165
 166 /* boolean: A "this policy is sufficient per cert" for each */
 167 #define kSecRevocationOCSPSufficientPerCert     CFSTR("OCSPSufficientPerCert")
 168 #define kSecRevocationCRLSufficientPerCert      CFSTR("CRLSufficientPerCert")
 169
 170 /* local OCSP responder URI, value arbitrary string value */
 171 #define kSecOCSPLocalResponder                          CFSTR("OCSPLocalResponder")
 172
 173 /* Extended trust result keys (now in public API) */
 174 #define kSecEVOrganizationName                          kSecTrustOrganizationName
 175 #define kSecTrustExpirationDate                         kSecTrustRevocationValidUntilDate
 176
 177 #if defined(__cplusplus)
 178 }
 179 #endif
 180
 181 #endif /* !_SECURITY_SECTRUST_PRIV_H_ */