Keychain/SecTrust.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 /*!
  19         @header SecTrust
  20         The functions and data types in SecTrust implement trust computation and allows the user to apply trust decisions to the trust configuration.
  21 */
  22
  23 #ifndef _SECURITY_SECTRUST_H_
  24 #define _SECURITY_SECTRUST_H_
  25
  26 #include <Security/SecBase.h>
  27 #include <Security/cssmtype.h>
  28 #include <Security/cssmapple.h>
  29 #include <CoreFoundation/CoreFoundation.h>
  30
  31
  32 #if defined(__cplusplus)
  33 extern "C" {
  34 #endif
  35
  36 /*!
  37         @typedef SecTrustResultType
  38         @abstract Specifies the trust result type.
  39         @constant kSecTrustResultInvalid Indicates an invalid setting or result.
  40         @constant kSecTrustResultProceed Indicates you may proceed.  This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings.
  41         @constant kSecTrustResultConfirm Indicates confirmation with the user is required before proceeding.  This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings.
  42         @constant kSecTrustResultDeny Indicates a user-configured deny; do not proceed. This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings.
  43         @constant kSecTrustResultUnspecified Indicates user intent is unknown. This value may be returned by the SecTrustEvaluate function or stored as part of the user trust settings.
  44         @constant kSecTrustResultRecoverableTrustFailure Indicates a trust framework failure; retry after fixing inputs. This value may be returned by the SecTrustEvaluate function but not stored as part of the user trust settings.
  45         @constant kSecTrustResultFatalTrustFailure Indicates a trust framework failure; no "easy" fix. This value may be returned by the SecTrustEvaluate function but not stored as part of the user trust settings.
  46         @constant kSecTrustResultOtherError Indicates a failure other than that of trust evaluation. This value may be returned by the SecTrustEvaluate function but not stored as part of the user trust settings.
  47  */
  48 typedef enum {
  49     kSecTrustResultInvalid,
  50     kSecTrustResultProceed,
  51     kSecTrustResultConfirm,
  52     kSecTrustResultDeny,
  53     kSecTrustResultUnspecified,
  54     kSecTrustResultRecoverableTrustFailure,
  55     kSecTrustResultFatalTrustFailure,
  56     kSecTrustResultOtherError
  57 } SecTrustResultType;
  58
  59 /*!
  60         @typedef SecTrustUserSetting
  61         @abstract Specifies user-specified trust settings.
  62 */
  63 typedef SecTrustResultType SecTrustUserSetting;
  64
  65 /*!
  66         @typedef SecTrustRef
  67         @abstract A pointer to an opaque trust management structure.
  68 */
  69 typedef struct OpaqueSecTrustRef *SecTrustRef;
  70
  71 /*!
  72         @function SecTrustGetTypeID
  73         @abstract Returns the type identifier of SecTrust instances.
  74         @result The CFTypeID of SecTrust instances.
  75 */
  76 CFTypeID SecTrustGetTypeID(void);
  77
  78 /*!
  79         @function SecTrustCreateWithCertificates
  80         @abstract Creates a trust based on the given certificates and policies.
  81     @param certificates The group of certificates to verify.
  82     @param policies An array of one or more policies.
  83         @param trustRef On return, a pointer to the trust management reference.
  84         @result A result code.  See "Security Error Codes" (SecBase.h).
  85 */
  86 OSStatus SecTrustCreateWithCertificates(CFArrayRef certificates, CFTypeRef policies, SecTrustRef *trustRef);
  87
  88 /*!
  89         @function SecTrustSetParameters
  90         @abstract Sets the action and action data for a trust.
  91         @param trustRef The reference to the trust to change.
  92         @param action A CSSM trust action.
  93         @param actionData A reference to action data.
  94         @result A result code.  See "Security Error Codes" (SecBase.h).
  95  */
  96 OSStatus SecTrustSetParameters(SecTrustRef trustRef, CSSM_TP_ACTION action, CFDataRef actionData);
  97
  98 /*!
  99         @function SecTrustSetAnchorCertificates
 100         @abstract Sets the anchor certificates for a given trust.
 101         @param trust A reference to a trust.
 102         @param anchorCertificates An array of anchor certificates.
 103         @result A result code.  See "Security Error Codes" (SecBase.h).
 104 */
 105 OSStatus SecTrustSetAnchorCertificates(SecTrustRef trust, CFArrayRef anchorCertificates);
 106
 107 /*!
 108         @function SecTrustSetKeychains
 109         @abstract Sets the keychains for a given trust.
 110         @param trust A reference to a trust.
 111     @param keychainOrArray An reference to an array of keychains to search, a single keychain or NULL to search the user's default keychain search list.
 112         @result A result code.  See "Security Error Codes" (SecBase.h).
 113 */
 114 OSStatus SecTrustSetKeychains(SecTrustRef trust, CFTypeRef keychainOrArray);
 115
 116 /*!
 117         @function SecTrustSetVerifyDate
 118         @abstract Verifies the date of a given trust.
 119         @param trust A reference to the trust to verify.
 120         @param verifyDate The date to verify.
 121         @result A result code.  See "Security Error Codes" (SecBase.h).
 122 */
 123 OSStatus SecTrustSetVerifyDate(SecTrustRef trust, CFDateRef verifyDate);
 124
 125 /*!
 126         @function SecTrustEvaluate
 127         @abstract Evaluates a trust.
 128         @param trust A reference to the trust to evaluate.
 129         @param result A pointer to a result type.
 130         @result A result code.  See "Security Error Codes" (SecBase.h).
 131 */
 132 OSStatus SecTrustEvaluate(SecTrustRef trust, SecTrustResultType *result);
 133
 134 /*!
 135         @function SecTrustGetResult
 136         @abstract Returns detail information on the outcome of a call to SecTrustEvaluate.
 137         @param trustRef A reference to a trust.
 138         @param result A pointer to the result from the call to SecTrustEvaluate.
 139         @param certChain On return, a pointer to the certificate chain used to validate the input certificate.
 140         @param statusChain On return, a pointer to the status of the certificate chain.  Do not attempt to free this pointer; it remains valid until the trust is destroyed or the next call to SecTrustEvaluate.
 141         @result A result code.  See "Security Error Codes" (SecBase.h).
 142 */
 143 OSStatus SecTrustGetResult(SecTrustRef trustRef, SecTrustResultType *result, CFArrayRef *certChain, CSSM_TP_APPLE_EVIDENCE_INFO **statusChain);
 144
 145 /*!
 146         @function SecTrustGetCssmResult
 147         @abstract Gets the CSSM trust result.
 148         @param trust A reference to a trust.
 149         @param result On return, a pointer to the CSSM trust result.
 150         @result A result code.  See "Security Error Codes" (SecBase.h).
 151 */
 152 OSStatus SecTrustGetCssmResult(SecTrustRef trust, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR *result);
 153
 154 /*!
 155         @function SecTrustGetTPHandle
 156         @abstract Gets the CSSM trust handle
 157         @param trust A reference to a trust.
 158         @param handle On return, a pointer to a CSSM trust handle.
 159         @result A result code.  See "Security Error Codes" (SecBase.h).
 160 */
 161 OSStatus SecTrustGetTPHandle(SecTrustRef trust, CSSM_TP_HANDLE *handle);
 162
 163 /*!
 164         @function SecTrustCopyAnchorCertificates
 165         @abstract Returns the anchor (root) certificates.
 166     @param anchors On return, a pointer to the anchors (roots).  This may be used with the function SecCertificateGroupVerify.  Call the CFRelease function to release this pointer.
 167     @result A result code.  See "Security Error Codes" (SecBase.h).
 168 */
 169 OSStatus SecTrustCopyAnchorCertificates(CFArrayRef* anchors);
 170
 171 /*!
 172         @function SecTrustGetCSSMAnchorCertificates
 173         @abstract Retrieves the CSSM anchor certificates.
 174         @param cssmAnchors A pointer to an array of anchor certificates.
 175         @param cssmAnchorCount A pointer to the number of certificates in anchors.
 176         @result A result code.  See "Security Error Codes" (SecBase.h).
 177 */
 178 OSStatus SecTrustGetCSSMAnchorCertificates(const CSSM_DATA **cssmAnchors, uint32 *cssmAnchorCount);
 179
 180 /*!
 181         @function SecTrustGetUserTrust
 182         @abstract Gets the user-specified trust settings of a certificate and policy.
 183         @param certificate A reference to a certificate.
 184         @param policy A reference to a policy.
 185         @param trustSetting On return, a pointer to the user specified trust settings.
 186         @result A result code.  See "Security Error Codes" (SecBase.h).
 187 */
 188 OSStatus SecTrustGetUserTrust(SecCertificateRef certificate, SecPolicyRef policy, SecTrustUserSetting *trustSetting);
 189
 190 /*!
 191         @function SecTrustSetUserTrust
 192         @abstract Sets the user-specified trust settings of a certificate and policy.
 193         @param certificate A reference to a certificate.
 194         @param policy A reference to a policy.
 195         @param trustSetting The user-specified trust settings.
 196         @result A result code.  See "Security Error Codes" (SecBase.h).
 197 */
 198 OSStatus SecTrustSetUserTrust(SecCertificateRef certificate, SecPolicyRef policy, SecTrustUserSetting trustSetting);
 199
 200
 201 #if defined(__cplusplus)
 202 }
 203 #endif
 204
 205 #endif /* !_SECURITY_SECTRUST_H_ */