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. You may pass a SecPolicyRef
  83                 to represent a single policy.
  84         @param trustRef On return, a pointer to the trust management reference.
  85         @result A result code.  See "Security Error Codes" (SecBase.h).
  86 */
  87 OSStatus SecTrustCreateWithCertificates(CFArrayRef certificates, CFTypeRef policies, SecTrustRef *trustRef);
  88
  89 /*!
  90         @function SecTrustSetParameters
  91         @abstract Sets the action and action data for a trust.
  92         @param trustRef The reference to the trust to change.
  93         @param action A CSSM trust action.
  94         @param actionData A reference to action data.
  95         @result A result code.  See "Security Error Codes" (SecBase.h).
  96  */
  97 OSStatus SecTrustSetParameters(SecTrustRef trustRef, CSSM_TP_ACTION action, CFDataRef actionData);
  98
  99 /*!
 100         @function SecTrustSetAnchorCertificates
 101         @abstract Sets the anchor certificates for a given trust.
 102         @param trust A reference to a trust.
 103         @param anchorCertificates An array of anchor certificates.
 104         @result A result code.  See "Security Error Codes" (SecBase.h).
 105 */
 106 OSStatus SecTrustSetAnchorCertificates(SecTrustRef trust, CFArrayRef anchorCertificates);
 107
 108 /*!
 109         @function SecTrustSetKeychains
 110         @abstract Sets the keychains for a given trust.
 111         @param trust A reference to a trust.
 112     @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.
 113         @result A result code.  See "Security Error Codes" (SecBase.h).
 114 */
 115 OSStatus SecTrustSetKeychains(SecTrustRef trust, CFTypeRef keychainOrArray);
 116
 117 /*!
 118         @function SecTrustSetVerifyDate
 119         @abstract Verifies the date of a given trust.
 120         @param trust A reference to the trust to verify.
 121         @param verifyDate The date to verify.
 122         @result A result code.  See "Security Error Codes" (SecBase.h).
 123 */
 124 OSStatus SecTrustSetVerifyDate(SecTrustRef trust, CFDateRef verifyDate);
 125
 126 /*!
 127         @function SecTrustEvaluate
 128         @abstract Evaluates a trust.
 129         @param trust A reference to the trust to evaluate.
 130         @param result A pointer to a result type.
 131         @result A result code.  See "Security Error Codes" (SecBase.h).
 132 */
 133 OSStatus SecTrustEvaluate(SecTrustRef trust, SecTrustResultType *result);
 134
 135 /*!
 136         @function SecTrustGetResult
 137         @abstract Returns detail information on the outcome of a call to SecTrustEvaluate.
 138         @param trustRef A reference to a trust.
 139         @param result A pointer to the result from the call to SecTrustEvaluate.
 140         @param certChain On return, a pointer to the certificate chain used to validate the input certificate.
 141         @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.
 142         @result A result code.  See "Security Error Codes" (SecBase.h).
 143 */
 144 OSStatus SecTrustGetResult(SecTrustRef trustRef, SecTrustResultType *result, CFArrayRef *certChain, CSSM_TP_APPLE_EVIDENCE_INFO **statusChain);
 145
 146 /*!
 147         @function SecTrustGetCssmResult
 148         @abstract Gets the CSSM trust result.
 149         @param trust A reference to a trust.
 150         @param result On return, a pointer to the CSSM trust result.
 151         @result A result code.  See "Security Error Codes" (SecBase.h).
 152 */
 153 OSStatus SecTrustGetCssmResult(SecTrustRef trust, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR *result);
 154
 155 /*!
 156         @function SecTrustGetTPHandle
 157         @abstract Gets the CSSM trust handle
 158         @param trust A reference to a trust.
 159         @param handle On return, a pointer to a CSSM trust handle.
 160         @result A result code.  See "Security Error Codes" (SecBase.h).
 161 */
 162 OSStatus SecTrustGetTPHandle(SecTrustRef trust, CSSM_TP_HANDLE *handle);
 163
 164 /*!
 165         @function SecTrustCopyAnchorCertificates
 166         @abstract Returns the anchor (root) certificates.
 167     @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.
 168     @result A result code.  See "Security Error Codes" (SecBase.h).
 169 */
 170 OSStatus SecTrustCopyAnchorCertificates(CFArrayRef* anchors);
 171
 172 /*!
 173         @function SecTrustGetCSSMAnchorCertificates
 174         @abstract Retrieves the CSSM anchor certificates.
 175         @param cssmAnchors A pointer to an array of anchor certificates.
 176         @param cssmAnchorCount A pointer to the number of certificates in anchors.
 177         @result A result code.  See "Security Error Codes" (SecBase.h).
 178 */
 179 OSStatus SecTrustGetCSSMAnchorCertificates(const CSSM_DATA **cssmAnchors, uint32 *cssmAnchorCount);
 180
 181 /*!
 182         @function SecTrustGetUserTrust
 183         @abstract Gets the user-specified trust settings of a certificate and policy.
 184         @param certificate A reference to a certificate.
 185         @param policy A reference to a policy.
 186         @param trustSetting On return, a pointer to the user specified trust settings.
 187         @result A result code.  See "Security Error Codes" (SecBase.h).
 188 */
 189 OSStatus SecTrustGetUserTrust(SecCertificateRef certificate, SecPolicyRef policy, SecTrustUserSetting *trustSetting);
 190
 191 /*!
 192         @function SecTrustSetUserTrust
 193         @abstract Sets the user-specified trust settings of a certificate and policy.
 194         @param certificate A reference to a certificate.
 195         @param policy A reference to a policy.
 196         @param trustSetting The user-specified trust settings.
 197         @result A result code.  See "Security Error Codes" (SecBase.h).
 198 */
 199 OSStatus SecTrustSetUserTrust(SecCertificateRef certificate, SecPolicyRef policy, SecTrustUserSetting trustSetting);
 200
 201
 202 #if defined(__cplusplus)
 203 }
 204 #endif
 205
 206 #endif /* !_SECURITY_SECTRUST_H_ */