sec/Security/SecTrustPriv.h

   1 /*
   2  * Copyright (c) 2008-2013 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         The functions and data types in SecTrustPriv implement trust computation
  27         and allow the user to apply trust decisions to the trust configuration.
  28 */
  29
  30 #ifndef _SECURITY_SECTRUSTPRIV_H_
  31 #define _SECURITY_SECTRUSTPRIV_H_
  32
  33 #include <Security/SecTrust.h>
  34 #include <CoreFoundation/CFData.h>
  35 #include <CoreFoundation/CFDictionary.h>
  36
  37 __BEGIN_DECLS
  38
  39 typedef enum {
  40         useNetworkDefault,              // default policy: network fetch enabled only for SSL
  41         useNetworkDisabled,             // explicitly disable network use for any policy
  42         useNetworkEnabled               // explicitly enable network use for any policy
  43 } SecNetworkPolicy;
  44
  45 /* Constants used as keys in property lists.  See
  46    SecTrustCopySummaryPropertiesAtIndex for more information. */
  47 extern CFTypeRef kSecPropertyKeyType;
  48 extern CFTypeRef kSecPropertyKeyLabel;
  49 extern CFTypeRef kSecPropertyKeyLocalizedLabel;
  50 extern CFTypeRef kSecPropertyKeyValue;
  51
  52 extern CFTypeRef kSecPropertyTypeWarning;
  53 extern CFTypeRef kSecPropertyTypeSuccess;
  54 extern CFTypeRef kSecPropertyTypeSection;
  55 extern CFTypeRef kSecPropertyTypeData;
  56 extern CFTypeRef kSecPropertyTypeString;
  57 extern CFTypeRef kSecPropertyTypeURL;
  58 extern CFTypeRef kSecPropertyTypeDate;
  59
  60 /* Constants used as keys in the dictionary returned by SecTrustCopyInfo. */
  61 extern CFTypeRef kSecTrustInfoExtendedValidationKey;
  62 extern CFTypeRef kSecTrustInfoCompanyNameKey;
  63 extern CFTypeRef kSecTrustInfoRevocationKey;
  64 extern CFTypeRef kSecTrustInfoRevocationValidUntilKey;
  65
  66 /*!
  67         @function SecTrustCopySummaryPropertiesAtIndex
  68         @abstract Return a property array for the certificate.
  69         @param trust A reference to the trust object to evaluate.
  70         @param ix The index of the requested certificate.  Indices run from 0
  71     (leaf) to the anchor (or last certificate found if no anchor was found).
  72     @result A property array. It is the caller's responsibility to CFRelease
  73     the returned array when it is no longer needed. This function returns a
  74     short summary description of the certificate in question.  The property
  75     at index 0 of the array might also include general information about the
  76     entire chain's validity in the context of this trust evaluation.
  77
  78         @discussion Returns a property array for this trust certificate. A property
  79     array is an array of CFDictionaryRefs.  Each dictionary (we call it a
  80     property for short) has the following keys:
  81
  82            kSecPropertyKeyType This key's value determines how this property
  83                should be displayed. Its associated value is one of the
  84                following:
  85            kSecPropertyTypeWarning
  86                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
  87                            set.  The kSecPropertyKeyValue is a CFStringRef which should
  88                            be displayed in yellow with a warning triangle.
  89            kSecPropertyTypeError
  90                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
  91                            set.  The kSecPropertyKeyValue is a CFStringRef which should
  92                            be displayed in red with an error X.
  93            kSecPropertyTypeSuccess
  94                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
  95                            set.  The kSecPropertyKeyValue is a CFStringRef which should
  96                            be displayed in green with a checkmark in front of it.
  97            kSecPropertyTypeTitle
  98                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
  99                            set.  The kSecPropertyKeyValue is a CFStringRef which should
 100                            be displayed in a larger bold font.
 101            kSecPropertyTypeSection
 102                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef with the name
 103                            of the next section to display.  The value of the
 104                            kSecPropertyKeyValue key is a CFArrayRef which is a property
 105                            array as defined here.
 106            kSecPropertyTypeData
 107                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 108                            the localized label for the value for the kSecPropertyKeyValue.
 109                            The type of this value is a CFDataRef.  Its contents should be
 110                            displayed as: "bytes length_of_data : hexdump_of_data". Ideally
 111                            the UI will only show one line of hex dump data and have a
 112                            disclosure arrow to see the remainder.
 113            kSecPropertyTypeString
 114                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 115                            the localized label for the value for the kSecPropertyKeyValue.
 116                            The type of this value is a CFStringRef.  It's contents should be
 117                            displayed in the normal font.
 118            kSecPropertyTypeURL
 119                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 120                            the localized label for the value for the kSecPropertyKeyValue.
 121                            The type of this value is a CFURLRef.  It's contents should be
 122                            displayed as a hyperlink.
 123            kSecPropertyTypeDate
 124                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 125                            the localized label for the value for the kSecPropertyKeyValue.
 126                            The type of this value is a CFDateRef.  It's contents should be
 127                            displayed in human readable form (probably in the current
 128                            timezone).
 129            kSecPropertyKeyLocalizedLabel
 130                Human readable localized label for a given property.
 131            kSecPropertyKeyValue
 132                See description of kSecPropertyKeyType to determine what the value
 133                    for this key is.
 134            kSecPropertyKeyLabel
 135            Non localized key (label) for this value.  This is only
 136                    present for properties with fixed label names.
 137         @param certificate A reference to the certificate to evaluate.
 138     @result A property array. It is the caller's responsability to CFRelease
 139     the returned array when it is no longer needed.
 140 */
 141 CFArrayRef SecTrustCopySummaryPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
 142
 143 /*!
 144         @function SecTrustCopyDetailedPropertiesAtIndex
 145         @abstract Return a property array for the certificate.
 146         @param trust A reference to the trust object to evaluate.
 147         @param ix The index of the requested certificate.  Indices run from 0
 148     (leaf) to the anchor (or last certificate found if no anchor was found).
 149     @result A property array. It is the caller's responsibility to CFRelease
 150     the returned array when it is no longer needed.
 151     See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
 152         Unlike that function call this function returns a detailed description
 153     of the certificate in question.
 154 */
 155 CFArrayRef SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
 156
 157 /*!
 158         @function SecTrustCopyProperties
 159         @abstract Return a property array for this trust evaluation.
 160         @param trust A reference to the trust object to evaluate.
 161     @result A property array. It is the caller's responsibility to CFRelease
 162     the returned array when it is no longer needed. See
 163     SecTrustCopySummaryPropertiesAtIndex for a detailed description of this array.
 164     Unlike that function, this function returns a short text string suitable for
 165     display in a sheet explaining to the user why this certificate chain is
 166     not trusted for this operation. This function may return NULL if the
 167     certificate chain was trusted.
 168 */
 169 CFArrayRef SecTrustCopyProperties(SecTrustRef trust);
 170
 171 /*!
 172         @function SecTrustCopyInfo
 173         @abstract Return a dictionary with additional information about the
 174     evaluated certificate chain for use by clients.
 175         @param trust A reference to an evaluated trust object.
 176         @discussion Returns a dictionary for this trust evaluation. This
 177     dictionary may have the following keys:
 178
 179         kSecTrustInfoExtendedValidationKey this key will be present and have
 180             a value of kCFBooleanTrue if this chain was validated for EV.
 181         kSecTrustInfoCompanyNameKey Company name field of subject of leaf
 182             certificate, this field is meant to be displayed to the user
 183             if the kSecTrustInfoExtendedValidationKey is present.
 184         kSecTrustInfoRevocationKey this key will be present iff this chain
 185             had its revocation checked. The value will be a kCFBooleanTrue
 186             if revocation checking was successful and none of the
 187             certificates in the chain were revoked.
 188             The value will be kCFBooleanFalse if no current revocation status
 189             could be obtained for one or more certificates in the chain due
 190             to connection problems or timeouts etc.  This is a hint to a
 191             client to retry revocation checking at a later time.
 192         kSecTrustInfoRevocationValidUntilKey this key will be present iff
 193             kSecTrustInfoRevocationKey has a value of kCFBooleanTrue.
 194             The value will be a CFDateRef representing the earliest date at
 195             which the revocation info for one of the certificates in this chain
 196             might change.
 197
 198         @result A dictionary with various fields that can be displayed to the user,
 199     or NULL if no additional info is available or the trust has not yet been
 200     validated.  The caller is responsible for calling CFRelease on the value
 201     returned when it is no longer needed.
 202 */
 203 CFDictionaryRef SecTrustCopyInfo(SecTrustRef trust);
 204
 205 /* For debugging purposes. */
 206 CFArrayRef SecTrustGetDetails(SecTrustRef trust);
 207
 208 /* For debugging purposes. */
 209 CFStringRef SecTrustCopyFailureDescription(SecTrustRef trust);
 210
 211 /*!
 212         @function SecTrustSetPolicies
 213         @abstract Set the trust policies against which the trust should be verified.
 214         @param trust A reference to a trust object.
 215     @param policies An array of one or more policies. You may pass a
 216     SecPolicyRef to represent a single policy.
 217         @result A result code.  See "Security Error Codes" (SecBase.h).
 218     @discussion This function does not invalidate the trust, but should do so in the future.
 219 */
 220 OSStatus SecTrustSetPolicies(SecTrustRef trust, CFTypeRef policies)
 221    __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_6_0);
 222
 223 OSStatus SecTrustGetOTAPKIAssetVersionNumber(int* versionNumber);
 224
 225 OSStatus SecTrustOTAPKIGetUpdatedAsset(int* didUpdateAsset);
 226
 227 __END_DECLS
 228
 229 #endif /* !_SECURITY_SECTRUSTPRIV_H_ */