OSX/sec/Security/SecTrustPriv.h

   1 /*
   2  * Copyright (c) 2008-2015 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 const CFStringRef kSecPropertyKeyType;
  48 extern const CFStringRef kSecPropertyKeyLabel;
  49 extern const CFStringRef kSecPropertyKeyLocalizedLabel;
  50 extern const CFStringRef kSecPropertyKeyValue;
  51
  52 extern const CFStringRef kSecPropertyTypeWarning;
  53 extern const CFStringRef kSecPropertyTypeSuccess;
  54 extern const CFStringRef kSecPropertyTypeSection;
  55 extern const CFStringRef kSecPropertyTypeData;
  56 extern const CFStringRef kSecPropertyTypeString;
  57 extern const CFStringRef kSecPropertyTypeURL;
  58 extern const CFStringRef kSecPropertyTypeDate;
  59
  60 /* Constants used as keys in the dictionary returned by SecTrustCopyInfo. */
  61 extern const CFStringRef kSecTrustInfoExtendedValidationKey;
  62 extern const CFStringRef kSecTrustInfoCompanyNameKey;
  63 extern const CFStringRef kSecTrustInfoRevocationKey;
  64 extern const CFStringRef kSecTrustInfoRevocationValidUntilKey;
  65 extern const CFStringRef kSecTrustInfoCertificateTransparencyKey;
  66
  67 /*!
  68     @enum Trust Result Constants
  69     @discussion Predefined key constants used to obtain values in a
  70         dictionary of trust evaluation results for a certificate chain,
  71         as retrieved from a call to SecTrustCopyResult.
  72
  73     @constant kSecTrustResultDetails
  74         This key will be present if a trust evaluation has been performed.
  75         Its value is a CFArrayRef of CFDictionaryRef representing detailed
  76         status info for each certificate in the completed chain.
  77     @constant kSecTrustRevocationReason
  78         This key will be present iff this chain had its revocation checked,
  79         and a "revoked" response was received. The value of this key will
  80         be a CFNumberRef indicating the reason for revocation. The possible
  81         reason code values are described in RFC 5280, section 5.3.1.
  82  */
  83 extern const CFStringRef kSecTrustResultDetails;
  84     /*__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_9_0);*/
  85 extern const CFStringRef kSecTrustRevocationReason;
  86     /*__OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);*/
  87
  88 /*!
  89         @function SecTrustCopySummaryPropertiesAtIndex
  90         @abstract Return a property array for the certificate.
  91         @param trust A reference to the trust object to evaluate.
  92         @param ix The index of the requested certificate.  Indices run from 0
  93     (leaf) to the anchor (or last certificate found if no anchor was found).
  94     @result A property array. It is the caller's responsibility to CFRelease
  95     the returned array when it is no longer needed. This function returns a
  96     short summary description of the certificate in question.  The property
  97     at index 0 of the array might also include general information about the
  98     entire chain's validity in the context of this trust evaluation.
  99
 100         @discussion Returns a property array for this trust certificate. A property
 101     array is an array of CFDictionaryRefs.  Each dictionary (we call it a
 102     property for short) has the following keys:
 103
 104            kSecPropertyKeyType This key's value determines how this property
 105                should be displayed. Its associated value is one of the
 106                following:
 107            kSecPropertyTypeWarning
 108                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 109                            set.  The kSecPropertyKeyValue is a CFStringRef which should
 110                            be displayed in yellow with a warning triangle.
 111            kSecPropertyTypeError
 112                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 113                            set.  The kSecPropertyKeyValue is a CFStringRef which should
 114                            be displayed in red with an error X.
 115            kSecPropertyTypeSuccess
 116                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 117                            set.  The kSecPropertyKeyValue is a CFStringRef which should
 118                            be displayed in green with a checkmark in front of it.
 119            kSecPropertyTypeTitle
 120                        The kSecPropertyKeyLocalizedLabel and kSecPropertyKeyLabel keys are not
 121                            set.  The kSecPropertyKeyValue is a CFStringRef which should
 122                            be displayed in a larger bold font.
 123            kSecPropertyTypeSection
 124                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef with the name
 125                            of the next section to display.  The value of the
 126                            kSecPropertyKeyValue key is a CFArrayRef which is a property
 127                            array as defined here.
 128            kSecPropertyTypeData
 129                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 130                            the localized label for the value for the kSecPropertyKeyValue.
 131                            The type of this value is a CFDataRef.  Its contents should be
 132                            displayed as: "bytes length_of_data : hexdump_of_data". Ideally
 133                            the UI will only show one line of hex dump data and have a
 134                            disclosure arrow to see the remainder.
 135            kSecPropertyTypeString
 136                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 137                            the localized label for the value for the kSecPropertyKeyValue.
 138                            The type of this value is a CFStringRef.  It's contents should be
 139                            displayed in the normal font.
 140            kSecPropertyTypeURL
 141                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 142                            the localized label for the value for the kSecPropertyKeyValue.
 143                            The type of this value is a CFURLRef.  It's contents should be
 144                            displayed as a hyperlink.
 145            kSecPropertyTypeDate
 146                        The optional kSecPropertyKeyLocalizedLabel is a CFStringRef containing
 147                            the localized label for the value for the kSecPropertyKeyValue.
 148                            The type of this value is a CFDateRef.  It's contents should be
 149                            displayed in human readable form (probably in the current
 150                            timezone).
 151            kSecPropertyKeyLocalizedLabel
 152                Human readable localized label for a given property.
 153            kSecPropertyKeyValue
 154                See description of kSecPropertyKeyType to determine what the value
 155                    for this key is.
 156            kSecPropertyKeyLabel
 157            Non localized key (label) for this value.  This is only
 158                    present for properties with fixed label names.
 159         @param certificate A reference to the certificate to evaluate.
 160     @result A property array. It is the caller's responsability to CFRelease
 161     the returned array when it is no longer needed.
 162 */
 163 CFArrayRef SecTrustCopySummaryPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
 164
 165 /*!
 166         @function SecTrustCopyDetailedPropertiesAtIndex
 167         @abstract Return a property array for the certificate.
 168         @param trust A reference to the trust object to evaluate.
 169         @param ix The index of the requested certificate.  Indices run from 0
 170     (leaf) to the anchor (or last certificate found if no anchor was found).
 171     @result A property array. It is the caller's responsibility to CFRelease
 172     the returned array when it is no longer needed.
 173     See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
 174         Unlike that function call this function returns a detailed description
 175     of the certificate in question.
 176 */
 177 CFArrayRef SecTrustCopyDetailedPropertiesAtIndex(SecTrustRef trust, CFIndex ix);
 178
 179 /*!
 180         @function SecTrustCopyProperties
 181         @abstract Return a property array for this trust evaluation.
 182         @param trust A reference to the trust object to evaluate.
 183     @result A property array. It is the caller's responsibility to CFRelease
 184     the returned array when it is no longer needed. See
 185     SecTrustCopySummaryPropertiesAtIndex for a detailed description of this array.
 186     Unlike that function, this function returns a short text string suitable for
 187     display in a sheet explaining to the user why this certificate chain is
 188     not trusted for this operation. This function may return NULL if the
 189     certificate chain was trusted.
 190 */
 191 CFArrayRef SecTrustCopyProperties(SecTrustRef trust);
 192
 193 /*!
 194         @function SecTrustCopyInfo
 195         @abstract Return a dictionary with additional information about the
 196     evaluated certificate chain for use by clients.
 197         @param trust A reference to an evaluated trust object.
 198         @discussion Returns a dictionary for this trust evaluation. This
 199     dictionary may have the following keys:
 200
 201         kSecTrustInfoExtendedValidationKey this key will be present and have
 202             a value of kCFBooleanTrue if this chain was validated for EV.
 203         kSecTrustInfoCompanyNameKey Company name field of subject of leaf
 204             certificate, this field is meant to be displayed to the user
 205             if the kSecTrustInfoExtendedValidationKey is present.
 206         kSecTrustInfoRevocationKey this key will be present iff this chain
 207             had its revocation checked. The value will be a kCFBooleanTrue
 208             if revocation checking was successful and none of the
 209             certificates in the chain were revoked.
 210             The value will be kCFBooleanFalse if no current revocation status
 211             could be obtained for one or more certificates in the chain due
 212             to connection problems or timeouts etc.  This is a hint to a
 213             client to retry revocation checking at a later time.
 214         kSecTrustInfoRevocationValidUntilKey this key will be present iff
 215             kSecTrustInfoRevocationKey has a value of kCFBooleanTrue.
 216             The value will be a CFDateRef representing the earliest date at
 217             which the revocation info for one of the certificates in this chain
 218             might change.
 219
 220         @result A dictionary with various fields that can be displayed to the user,
 221     or NULL if no additional info is available or the trust has not yet been
 222     validated.  The caller is responsible for calling CFRelease on the value
 223     returned when it is no longer needed.
 224 */
 225 CFDictionaryRef SecTrustCopyInfo(SecTrustRef trust);
 226
 227 /* For debugging purposes. */
 228 CFArrayRef SecTrustGetDetails(SecTrustRef trust);
 229
 230 /* For debugging purposes. */
 231 CFStringRef SecTrustCopyFailureDescription(SecTrustRef trust);
 232
 233 /*!
 234         @function SecTrustSetPolicies
 235         @abstract Set the trust policies against which the trust should be verified.
 236         @param trust A reference to a trust object.
 237     @param policies An array of one or more policies. You may pass a
 238     SecPolicyRef to represent a single policy.
 239         @result A result code.  See "Security Error Codes" (SecBase.h).
 240     @discussion This function does not invalidate the trust, but should do so in the future.
 241 */
 242 OSStatus SecTrustSetPolicies(SecTrustRef trust, CFTypeRef policies)
 243    __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_6_0);
 244
 245 OSStatus SecTrustGetOTAPKIAssetVersionNumber(int* versionNumber);
 246
 247 OSStatus SecTrustOTAPKIGetUpdatedAsset(int* didUpdateAsset);
 248
 249 /*!
 250  @function SecTrustSignedCertificateTimestampList
 251  @abstract Attach SignedCertificateTimestampList data to a trust object.
 252  @param trust A reference to a trust object.
 253  @param sctArray is a CFArray of CFData objects each containing a SCT (per RFC 6962).
 254  @result A result code. See "Security Error Codes" (SecBase.h).
 255  @discussion Allows the caller to provide SCT data (which may be
 256  obtained during a TLS/SSL handshake, per RFC 6962) as input to a trust
 257  evaluation.
 258  */
 259 OSStatus SecTrustSetSignedCertificateTimestamps(SecTrustRef trust, CFArrayRef sctArray);
 260
 261 /*!
 262  @function SecTrustSetTrustedLogs
 263  @abstract Sets the trusted CT logs for a given trust.
 264  @param trust A reference to a trust object.
 265  @param trustedLogs An array of trusted logs.
 266  @result A result code.  See "Security Error Codes" (SecBase.h).
 267  @discussion trustedLog is a CFArray of CFData containing the DER-encode SubjectPublicKeyInfo
 268  of the trusted CT logs.
 269  */
 270 OSStatus SecTrustSetTrustedLogs(SecTrustRef trust, CFArrayRef trustedLogs);
 271
 272 __END_DECLS
 273
 274 #endif /* !_SECURITY_SECTRUSTPRIV_H_ */