sec/Security/SecTrustPriv.h

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