protocol/SecProtocolConfiguration.h

   1 /*
   2  * Copyright (c) 2018 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 #ifndef SecProtocolConfiguration_h
  25 #define SecProtocolConfiguration_h
  26
  27 #include <Security/SecProtocolObject.h>
  28 #include <Security/SecureTransport.h>
  29
  30 #include <dispatch/dispatch.h>
  31 #include <xpc/xpc.h>
  32
  33 #ifndef SEC_OBJECT_IMPL
  34 /*!
  35  * A `sec_protocol_configuration` is an object that encapsulates App Transport Security
  36  * information and vends `sec_protocol_options` to clients for creating new connections.
  37  * It may also be queried to determine for what domains TLS is required.
  38  */
  39 SEC_OBJECT_DECL(sec_protocol_configuration);
  40 #endif // !SEC_OBJECT_IMPL
  41
  42 __BEGIN_DECLS
  43
  44 SEC_ASSUME_NONNULL_BEGIN
  45
  46 /*!
  47  * @function sec_protocol_configuration_copy_singleton
  48  *
  49  * @abstract
  50  *      Copy the per-process `sec_protocol_configuration_t` object.
  51  *
  52  * @return A non-nil `sec_protocol_configuration_t` instance.
  53  */
  54 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  55 SEC_RETURNS_RETAINED sec_protocol_configuration_t
  56 sec_protocol_configuration_copy_singleton(void);
  57
  58 /*!
  59  * @function sec_protocol_configuration_set_ats_overrides
  60  *
  61  * @abstract
  62  *      Set ATS overrides
  63  *
  64  * @param config
  65  *      A `sec_protocol_configuration_t` instance.
  66  *
  67  * @param override_dictionary
  68  *      A `CFDictionaryRef` dictionary containing the ATS overrides as
  69  *      documented here: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33
  70  *
  71  * @return True if successful, and false otherwise.
  72  */
  73 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  74 bool
  75 sec_protocol_configuration_set_ats_overrides(sec_protocol_configuration_t config, CFDictionaryRef override_dictionary);
  76
  77 /*!
  78  * @function sec_protocol_configuration_copy_transformed_options
  79  *
  80  * @abstract
  81  *      Transform an existing `sec_protocol_options_t` instance with a `sec_protocol_configuration_t` instance.
  82  *
  83  * @param config
  84  *      A `sec_protocol_configuration_t` instance.
  85  *
  86  * @param options
  87  *      A `sec_protocol_options_t` instance.
  88  *
  89  * @return The transformed `sec_protocol_options` instance.
  90  */
  91 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  92 SEC_RETURNS_RETAINED __nullable sec_protocol_options_t
  93 sec_protocol_configuration_copy_transformed_options(sec_protocol_configuration_t config, sec_protocol_options_t options);
  94
  95 /*!
  96  * @function sec_protocol_configuration_copy_transformed_options_for_host
  97  *
  98  * @abstract
  99  *      Transform an existing `sec_protocol_options_t` instance with a `sec_protocol_configuration_t` instance
 100  *      using a specific host endpoint. Note that the service (port) is omitted from this formula.
 101  *
 102  * @param config
 103  *      A `sec_protocol_configuration_t` instance.
 104  *
 105  * @param options
 106  *      A `sec_protocol_options_t` instance.
 107  *
 108  * @param host
 109  *      A NULL-terminated C string containing the host in question.
 110  *
 111  * @return The transformed `sec_protocol_options` instance.
 112  */
 113 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 114 SEC_RETURNS_RETAINED __nullable sec_protocol_options_t
 115 sec_protocol_configuration_copy_transformed_options_for_host(sec_protocol_configuration_t config, sec_protocol_options_t options, const char *host);
 116
 117 /*!
 118  * @function sec_protocol_configuration_tls_required
 119  *
 120  * @abstract
 121  *      Determine if TLS is required by policy for a generic connection. Note that the service (port) is omitted
 122  *      from this formula.
 123  *
 124  * @param config
 125  *      A `sec_protocol_configuration_t` instance.
 126  *
 127  * @return True if connections require TLS, and false otherwise.
 128  */
 129 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 130 bool
 131 sec_protocol_configuration_tls_required(sec_protocol_configuration_t config);
 132
 133 /*!
 134  * @function sec_protocol_configuration_tls_required_for_host
 135  *
 136  * @abstract
 137  *      Determine if TLS is required -- by policy -- for the given host endpoint. Note that the service (port) is
 138  *      omitted from this formula.
 139  *
 140  * @param config
 141  *      A `sec_protocol_configuration_t` instance.
 142  *
 143  * @param host
 144  *      A NULL-terminated C string containing the host endpoint to examine.
 145  *
 146  * @param is_direct
 147  *      A flag which indicates if the given hostname is local (direct).
 148  *
 149  * @return True if connections to the endpoint require TLS, and false otherwise.
 150  */
 151 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 152 bool
 153 sec_protocol_configuration_tls_required_for_host(sec_protocol_configuration_t config, const char *host, bool is_direct);
 154
 155 /*!
 156  * @function sec_protocol_configuration_tls_required_for_address
 157  *
 158  * @abstract
 159  *      Determine if TLS is required -- by policy -- for the given address endpoint.
 160  *
 161  * @param config
 162  *      A `sec_protocol_configuration_t` instance.
 163  *
 164  * @param address
 165  *      A NULL-terminated C string containing the address endpoint to examine.
 166  *
 167  * @return True if connections to the endpoint require TLS, and false otherwise.
 168  */
 169 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 170 bool
 171 sec_protocol_configuration_tls_required_for_address(sec_protocol_configuration_t config, const char *address);
 172
 173 SEC_ASSUME_NONNULL_END
 174
 175 __END_DECLS
 176
 177 #endif // SecProtocolConfiguration_h