sec/Security/SecTrust.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 SecTrust
  26         The functions and data types in SecTrust implement trust computation
  27     and allow the user to apply trust decisions to the trust configuration.
  28 */
  29
  30 #ifndef _SECURITY_SECTRUST_H_
  31 #define _SECURITY_SECTRUST_H_
  32
  33 #include <Security/SecBase.h>
  34 #include <CoreFoundation/CFArray.h>
  35 #include <CoreFoundation/CFData.h>
  36 #include <CoreFoundation/CFDate.h>
  37
  38 #if defined(__cplusplus)
  39 extern "C" {
  40 #endif
  41
  42 /*!
  43         @typedef SecTrustResultType
  44         @abstract Specifies the trust result type.
  45     @discussion SecTrustResultType results have two dimensions.  They specify
  46     both whether evaluation suceeded and whether this is because of a user
  47     decision.  In practice the commonly expected result is kSecTrustResultUnspecified,
  48     which indicates a positive result that wasn't decided by the user.  The
  49     common failure is kSecTrustResultRecoverableTrustFailure, which means a
  50     negative result.  kSecTrustResultProceed and kSecTrustResultDeny are the
  51     positive and negative result respectively when decided by the user.  User
  52     decisions are persisted through the use of SecTrustCopyExceptions() and
  53     SecTrustSetExceptions().  Finally kSecTrustResultFatalTrustFailure is a
  54     negative result that should not be circumvented.  In fact only in the case
  55     of kSecTrustResultRecoverableTrustFailure should a user ever be asked.
  56         @constant kSecTrustResultInvalid Indicates an invalid setting or result.
  57         @constant kSecTrustResultProceed Indicates you may proceed.  This value
  58     may be returned by the SecTrustEvaluate function or stored as part of
  59     the user trust settings.
  60         @constant kSecTrustResultConfirm Indicates confirmation with the user
  61     is required before proceeding.  This value may be returned by the
  62     SecTrustEvaluate function or stored as part of the user trust settings.
  63         @constant kSecTrustResultDeny Indicates a user-configured deny; do not
  64     proceed. This value may be returned by the SecTrustEvaluate function
  65     or stored as part of the user trust settings.
  66         @constant kSecTrustResultUnspecified Indicates user intent is unknown.
  67     This value may be returned by the SecTrustEvaluate function or stored
  68     as part of the user trust settings.
  69         @constant kSecTrustResultRecoverableTrustFailure Indicates a trust
  70     framework failure; retry after fixing inputs. This value may be returned
  71     by the SecTrustEvaluate function but not stored as part of the user
  72     trust settings.
  73         @constant kSecTrustResultFatalTrustFailure Indicates a trust framework
  74     failure; no "easy" fix. This value may be returned by the
  75     SecTrustEvaluate function but not stored as part of the user trust
  76     settings.
  77         @constant kSecTrustResultOtherError Indicates a failure other than that
  78     of trust evaluation. This value may be returned by the SecTrustEvaluate
  79     function but not stored as part of the user trust settings.
  80  */
  81 typedef UInt32 SecTrustResultType;
  82 enum {
  83     kSecTrustResultInvalid,
  84     kSecTrustResultProceed,
  85     kSecTrustResultConfirm,
  86     kSecTrustResultDeny,
  87     kSecTrustResultUnspecified,
  88     kSecTrustResultRecoverableTrustFailure,
  89     kSecTrustResultFatalTrustFailure,
  90     kSecTrustResultOtherError
  91 };
  92
  93
  94 /*!
  95         @typedef SecTrustRef
  96         @abstract CFType used for performing X.509 certificate trust evaluations.
  97 */
  98 typedef struct __SecTrust *SecTrustRef;
  99
 100 /*!
 101         @function SecTrustGetTypeID
 102         @abstract Returns the type identifier of SecTrust instances.
 103         @result The CFTypeID of SecTrust instances.
 104 */
 105 CFTypeID SecTrustGetTypeID(void)
 106     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 107
 108 /*!
 109         @function SecTrustCreateWithCertificates
 110         @abstract Creates a trust object based on the given certificates and
 111     policies.
 112     @param certificates The group of certificates to verify.  This can either
 113     be a CFArrayRef of SecCertificateRef objects or a single SecCertificateRef
 114     @param policies An array of one or more policies. You may pass a
 115     SecPolicyRef to represent a single policy.
 116         @param trustRef On return, a pointer to the trust management reference.
 117         @result A result code.  See "Security Error Codes" (SecBase.h).
 118     @discussion If multiple policies are passed in, all policies must verify
 119     for the chain to be considered valid.
 120 */
 121 OSStatus SecTrustCreateWithCertificates(CFTypeRef certificates,
 122     CFTypeRef policies, SecTrustRef *trustRef)
 123     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 124
 125 /*!
 126         @function SecTrustSetAnchorCertificates
 127         @abstract Sets the anchor certificates for a given trust.
 128         @param trust A reference to a trust object.
 129         @param anchorCertificates An array of anchor certificates.
 130         @result A result code.  See "Security Error Codes" (SecBase.h).
 131     @discussion Calling this function without also calling
 132     SecTrustSetAnchorCertificatesOnly() will disable trusting any
 133     anchors other than the ones in anchorCertificates.
 134 */
 135 OSStatus SecTrustSetAnchorCertificates(SecTrustRef trust,
 136     CFArrayRef anchorCertificates)
 137     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 138
 139 /*!
 140         @function SecTrustSetAnchorCertificatesOnly
 141         @abstract Reenables trusting anchor certificates in addition to those
 142     passed in via the SecTrustSetAnchorCertificates API.
 143         @param trust A reference to a trust object.
 144         @param anchorCertificatesOnly If true, disables trusting any anchors other
 145     than the ones passed in via SecTrustSetAnchorCertificates().  If false,
 146     the built in anchor certificates are also trusted.
 147         @result A result code.  See "Security Error Codes" (SecBase.h).
 148 */
 149 OSStatus SecTrustSetAnchorCertificatesOnly(SecTrustRef trust,
 150     Boolean anchorCertificatesOnly)
 151     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 152
 153 /*!
 154         @function SecTrustSetVerifyDate
 155         @abstract Set the date on which the trust should be verified.
 156         @param trust A reference to a trust object.
 157         @param verifyDate The date on which to verify trust.
 158         @result A result code.  See "Security Error Codes" (SecBase.h).
 159     @discussion If this function is not called the time at which
 160     SecTrustEvaluate() is called is used implicitly as the verification time.
 161 */
 162 OSStatus SecTrustSetVerifyDate(SecTrustRef trust, CFDateRef verifyDate)
 163     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 164
 165 /*!
 166         @function SecTrustGetVerifyTime
 167         @abstract Returns the verify time.
 168         @param trust A reference to the trust object to verify.
 169         @result A CFAbsoluteTime value representing the time at which certificates
 170         should be checked for validity.
 171 */
 172 CFAbsoluteTime SecTrustGetVerifyTime(SecTrustRef trust)
 173     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
 174
 175 /*!
 176         @function SecTrustEvaluate
 177         @abstract Evaluates a trust.
 178         @param trust A reference to the trust object to evaluate.
 179         @param result A pointer to a result type.
 180         @result A result code.  See "Security Error Codes" (SecBase.h).
 181 */
 182 OSStatus SecTrustEvaluate(SecTrustRef trust, SecTrustResultType *result)
 183     __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
 184
 185 /*!
 186         @function SecTrustCopyPublicKey
 187         @abstract Return the public key for a leaf certificate after it has
 188         been evaluated.
 189         @param trust A reference to the trust object which has been evaluated.
 190         @result The certificate's public key, or NULL if it the public key could
 191         not be extracted (this can happen with DSA certificate chains if the
 192         parameters in the chain cannot be found).  The caller is responsible
 193         for calling CFRelease on the returned key when it is no longer needed.
 194 */
 195 SecKeyRef SecTrustCopyPublicKey(SecTrustRef trust)
 196     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 197
 198 /*!
 199         @function SecTrustGetCertificateCount
 200         @abstract Returns the number of certificates in an evaluated certificate
 201     chain.
 202         @param trust Reference to a trust object.
 203         @result The number of certificates in the trust chain.  This function will
 204     return 1 if the trust has not been evaluated, and the number of
 205     certificates in the chain including the anchor if it has.
 206 */
 207 CFIndex SecTrustGetCertificateCount(SecTrustRef trust)
 208     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 209
 210 /*!
 211         @function SecTrustGetCertificateAtIndex
 212         @abstract Returns a certificate from the trust chain.
 213         @param trust Reference to a trust object.
 214         @param ix The index of the requested certificate.  Indices run from 0
 215     (leaf) to the anchor (or last certificate found if no anchor was found).
 216     The leaf cert (index 0) is always present regardless of whether the trust
 217     reference has been evaluated or not.
 218         @result A SecCertificateRef for the requested certificate.
 219 */
 220 SecCertificateRef SecTrustGetCertificateAtIndex(SecTrustRef trust, CFIndex ix)
 221     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_2_0);
 222
 223 /*!
 224         @function SecTrustCopyExceptions
 225         @abstract Returns an opauqe cookie which will allow future evaluations
 226     of the current certificate to succeed.
 227         @param trust A reference to an evaluated trust object.
 228         @result An opaque cookie which when passed to SecTrustSetExceptions() will
 229     cause a call to SecTrustEvaluate() return kSecTrustResultProceed.  This
 230     will happen upon subsequent evaluation of the current certificate unless
 231     some new error starts happening that wasn't being reported when the cookie
 232     was returned from this function, for example if the certificate expires
 233     evaluation will start failing again.
 234     @discussion Normally this API should only be called once the errors have
 235     been presented to the user and the user decided to trust the current
 236     certificate chain regardless of the errors being presented, for the
 237     current application/server/protocol/etc.
 238 */
 239 CFDataRef SecTrustCopyExceptions(SecTrustRef trust)
 240     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 241
 242 /*!
 243         @function SecTrustSetExceptions
 244         @abstract Set a trust cookie to be used for evaluating this certificate chain.
 245         @param trust A reference to an not yet evaluated trust object.
 246     @param exceptions An exceptions cookie as returned by a call to
 247     SecTrustCopyExceptions() in the past.
 248         @result Upon calling SecTrustEvaluate(), any failures that where present at the
 249     time the exceptions object was created are ignored, and instead of returning
 250     kSecTrustResultRecoverableTrustFailure, kSecTrustResultProceed will be returned
 251     (if the certificate for which exceptions was created matches the current leaf
 252     certificate).
 253     @discussion Clients of this interface will need to establish the context of this
 254     exception to later decide when this exception cookie is to be used.
 255     Examples of elements of this context would be the server we are connecting to, the
 256     ssid of the network this cert is for the account for which this cert should be
 257     considered valid, etc.
 258     @result true if the exceptions cookies was valid and matches the current leaf
 259     certificate, false otherwise.  Note that this function returning true doesn't
 260     mean the caller can skip calling SecTrustEvaluate(), as something could have
 261     changed causing the evaluation to fail after all.
 262 */
 263 bool SecTrustSetExceptions(SecTrustRef trust, CFDataRef exceptions)
 264     __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_4_0);
 265
 266 #if defined(__cplusplus)
 267 }
 268 #endif
 269
 270 #endif /* !_SECURITY_SECTRUST_H_ */