protocol/SecProtocolPriv.h

   1 //
   2 //  SecProtocolPriv.h
   3 //  Security
   4 //
   5
   6 #ifndef SecProtocolPriv_h
   7 #define SecProtocolPriv_h
   8
   9 #include <Security/SecProtocolOptions.h>
  10 #include <Security/SecProtocolMetadata.h>
  11
  12 __BEGIN_DECLS
  13
  14 typedef struct sec_protocol_options_content {
  15     SSLProtocol min_version;
  16     SSLProtocol max_version;
  17
  18     void *ciphersuites; // xpc_object_t (array of uint64)
  19
  20     void *application_protocols; // xpc_object_t (array of strings)
  21
  22     void *identity; // sec_identity_t
  23     char *server_name;
  24
  25     void *pre_shared_keys; // xpc_object_t (array of (data, identity))
  26
  27     void *key_update_block; // sec_protocol_key_update_t
  28     void *key_update_queue; // dispatch_queue_t
  29     void *challenge_block; // sec_protocol_challenge_t
  30     void *challenge_queue; // dispatch_queue_t
  31     void *verify_block; // sec_protocol_verify_t
  32     void *verify_queue; // dispatch_queue_t
  33
  34     void *dh_params; // dispatch_data_t
  35
  36     void *custom_extensions; // sec_array_t of sec_tls_extension_t
  37
  38     unsigned disable_sni : 1;
  39     unsigned enable_fallback_attempt : 1;
  40     unsigned enable_false_start : 1;
  41     unsigned enable_tickets : 1;
  42     unsigned enable_sct : 1;
  43     unsigned enable_ocsp : 1;
  44     unsigned enforce_ev : 1;
  45     unsigned enable_resumption : 1;
  46     unsigned enable_renegotiation : 1;
  47     unsigned enable_early_data : 1;
  48     unsigned peer_authentication_required : 1;
  49     unsigned peer_authentication_override : 1;
  50 } *sec_protocol_options_content_t;
  51
  52 typedef dispatch_data_t (*sec_protocol_metadata_exporter)(void * handle, size_t label_len, const char *label,
  53                                                           size_t context_len, const uint8_t *context, size_t exporter_len);
  54
  55 typedef struct sec_protocol_metadata_content {
  56     void *peer_certificate_chain; // sec_array_t of sec_certificate_t
  57     void *peer_public_key; // dispatch_data_t
  58
  59     const char *negotiated_protocol;
  60
  61     SSLProtocol negotiated_protocol_version;
  62     SSLCipherSuite negotiated_ciphersuite;
  63
  64     void *supported_signature_algorithms; // xpc_object_t (array of uint64)
  65     void *request_certificate_types; // dispatch_data
  66     void *ocsp_response; // sec_array_t of dispatch_data
  67     void *distinguished_names; // sec_array_t of dispatch_data
  68
  69     void *exporter_context; // Opaque context for the exporter function
  70     sec_protocol_metadata_exporter exporter_function; // Exporter function pointer. This MUST be set by the metadata allocator.
  71
  72     unsigned early_data_accepted : 1;
  73     unsigned false_start_used : 1;
  74     unsigned ticket_offered : 1;
  75     unsigned ticket_received : 1;
  76     unsigned session_resumed : 1;
  77     unsigned session_renewed : 1;
  78
  79     // Struct padding
  80     unsigned __pad_bits : 2;
  81 } *sec_protocol_metadata_content_t;
  82
  83 #ifndef SEC_OBJECT_IMPL
  84 SEC_OBJECT_DECL(sec_array);
  85 #endif // !SEC_OBJECT_IMPL
  86
  87 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  88 SEC_RETURNS_RETAINED sec_array_t
  89 sec_array_create(void);
  90
  91 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  92 void
  93 sec_array_append(sec_array_t array, sec_object_t object);
  94
  95 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  96 size_t
  97 sec_array_get_count(sec_array_t array);
  98
  99 #ifdef __BLOCKS__
 100 typedef bool (^sec_array_applier_t) (size_t index, sec_object_t object);
 101
 102 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 103 bool
 104 sec_array_apply(sec_array_t array, sec_array_applier_t applier);
 105
 106 #ifdef __BLOCKS__
 107 /*!
 108  * @block sec_protocol_tls_ext_add_callback
 109  *
 110  * @param metadata
 111  * A valid `sec_protocol_metadata_t` instance.
 112  *
 113  * @param extension_type
 114  *     The 2-byte identifier for the extension.
 115  *
 116  * @param data
 117  *     Pointer to a uint8_t buffer where the encoded extension data is located.
 118  *
 119  * @param data_length
 120  *     Pointer to a variable containing the data length. This should be set to the size of the `data` buffer.
 121  *
 122  * @param error
 123  *     Pointer to a return error code that's populated in the event of an error.
 124  */
 125 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 126 typedef int (^sec_protocol_tls_ext_add_callback)(sec_protocol_metadata_t metadata, uint16_t extension_type,
 127                                                  const uint8_t **data, size_t *data_length, int *error);
 128
 129 /*!
 130  * @block sec_protocol_tls_ext_free_callback
 131  *
 132  * @param metadata
 133  *     A valid `sec_protocol_metadata_t` instance.
 134  *
 135  * @param extension_type
 136  *     The 2-byte identifier for the extension.
 137  *
 138  * @param data
 139  *     Pointer to a uint8_t buffer where the encoded extension data is located.
 140  */
 141 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 142 typedef void (^sec_protocol_tls_ext_free_callback)(sec_protocol_metadata_t metadata, uint16_t extension_type,
 143                                                    const uint8_t *data);
 144
 145 /*!
 146  * @block sec_protocol_tls_ext_parse_callback
 147  *
 148  * @param metadata
 149  *     A valid `sec_protocol_metadata_t` handle.
 150  *
 151  * @param extension_type
 152  *     The 2-byte identifier for the extension.
 153  *
 154  * @param data
 155  *     A buffer where the encoded extension data is stored.
 156  *
 157  * @param data_length
 158  *     Length of the encoded extension data.
 159  *
 160  * @param error
 161  *     Pointer to a return error code that's populated in the event of an error.
 162  */
 163 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 164 typedef int (^sec_protocol_tls_ext_parse_callback)(sec_protocol_metadata_t metadata, uint16_t extension_type,
 165                                                    const uint8_t *data, size_t data_length,
 166                                                    int *error);
 167 #endif // __BLOCKS__
 168
 169 #ifndef SEC_OBJECT_IMPL
 170 SEC_OBJECT_DECL(sec_tls_extension);
 171 #endif // !SEC_OBJECT_IMPL
 172
 173 #ifdef __BLOCKS__
 174 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 175 uint16_t
 176 sec_tls_extension_get_type(sec_tls_extension_t extension);
 177
 178 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 179 SEC_RETURNS_RETAINED sec_protocol_tls_ext_add_callback
 180 sec_tls_extension_copy_add_block(sec_tls_extension_t extension);
 181
 182 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 183 SEC_RETURNS_RETAINED sec_protocol_tls_ext_parse_callback
 184 sec_tls_extension_copy_parse_block(sec_tls_extension_t extension);
 185
 186 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 187 SEC_RETURNS_RETAINED sec_protocol_tls_ext_free_callback
 188 sec_tls_extension_copy_free_block(sec_tls_extension_t extension);
 189
 190 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 191 sec_tls_extension_t
 192 sec_tls_extension_create(uint16_t type, sec_protocol_tls_ext_add_callback add_block,
 193                          sec_protocol_tls_ext_parse_callback parse_block,
 194                          sec_protocol_tls_ext_free_callback free_block);
 195 #endif // __BLOCKS__
 196
 197 /*!
 198  * @function sec_protocol_options_add_tls_extension
 199  *
 200  * @abstract
 201  *      Add support for a custom TLS extension.
 202  *
 203  *      Clients such as QUIC use this when custom TLS extensions are needed.
 204  *
 205  * @param options
 206  *      A `sec_protocol_options_t` instance.
 207  *
 208  * @param extension
 209  *      A `sec_tls_extension_t` instance.
 210  */
 211 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 212 void
 213 sec_protocol_options_add_tls_extension(sec_protocol_options_t options, sec_tls_extension_t extension);
 214
 215 #endif // __BLOCKS__
 216
 217 /*!
 218  * @function sec_protocol_options_set_tls_early_data_enabled
 219  *
 220  * @abstract
 221  *      Enable or disable early (0-RTT) data for TLS.
 222  *
 223  * @param options
 224  *      A `sec_protocol_options_t` instance.
 225  *
 226  * @param early_data_enabled
 227  *      Flag to enable or disable early (0-RTT) data.
 228  */
 229 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 230 void
 231 sec_protocol_options_set_tls_early_data_enabled(sec_protocol_options_t options, bool early_data_enabled);
 232
 233 /*!
 234  * @function sec_protocol_options_set_tls_sni_disabled
 235  *
 236  * @abstract
 237  *      Enable or disable the TLS SNI extension. This defaults to `false`.
 238  *
 239  * @param options
 240  *      A `sec_protocol_options_t` instance.
 241  *
 242  * @param sni_disabled
 243  *      Flag to enable or disable use of the TLS SNI extension.
 244  */
 245 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 246 void
 247 sec_protocol_options_set_tls_sni_disabled(sec_protocol_options_t options, bool sni_disabled);
 248
 249 /*!
 250  * @function sec_protocol_options_set_enforce_ev
 251  *
 252  * @abstract
 253  *      Enable or disable EV enforcement.
 254  *
 255  * @param options
 256  *      A `sec_protocol_options_t` instance.
 257  *
 258  * @param enforce_ev
 259  *      Flag to determine if EV is enforced.
 260  */
 261 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 262 void
 263 sec_protocol_options_set_enforce_ev(sec_protocol_options_t options, bool enforce_ev);
 264
 265 /*!
 266  * @function sec_protocol_metadata_get_tls_false_start_used
 267  *
 268  * @abstract
 269  *      Determine if False Start was used.
 270  *
 271  * @param metadata
 272  *      A `sec_protocol_metadata_t` instance.
 273  *
 274  * @return True if False Start was used, and false otherwise.
 275  */
 276 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 277 bool
 278 sec_protocol_metadata_get_tls_false_start_used(sec_protocol_metadata_t metadata);
 279
 280 /*!
 281  * @function sec_protocol_metadata_get_ticket_offered
 282  *
 283  * @abstract
 284  *      Determine if a ticket was offered for session resumption.
 285  *
 286  * @param metadata
 287  *      A `sec_protocol_metadata_t` instance.
 288  *
 289  * @return True if a ticket was offered for resumption, and false otherwise.
 290  */
 291 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 292 bool
 293 sec_protocol_metadata_get_ticket_offered(sec_protocol_metadata_t metadata);
 294
 295 /*!
 296  * @function sec_protocol_metadata_get_ticket_received
 297  *
 298  * @abstract
 299  *      Determine if a ticket was received upon completing the new connection.
 300  *
 301  * @param metadata
 302  *      A `sec_protocol_metadata_t` instance.
 303  *
 304  * @return True if a ticket was received from the peer (server), and false otherwise.
 305  */
 306 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 307 bool
 308 sec_protocol_metadata_get_ticket_received(sec_protocol_metadata_t metadata);
 309
 310 /*!
 311  * @function sec_protocol_metadata_get_session_resumed
 312  *
 313  * @abstract
 314  *      Determine if this new connection was a session resumption.
 315  *
 316  * @param metadata
 317  *      A `sec_protocol_metadata_t` instance.
 318  *
 319  * @return True if this new connection was resumed, and false otherwise.
 320  */
 321 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 322 bool
 323 sec_protocol_metadata_get_session_resumed(sec_protocol_metadata_t metadata);
 324
 325 /*!
 326  * @function sec_protocol_metadata_get_session_renewed
 327  *
 328  * @abstract
 329  *      Determine if this resumed connection was renewed with a new ticket.
 330  *
 331  * @param metadata
 332  *      A `sec_protocol_metadata_t` instance.
 333  *
 334  * @return True if this resumed connection was renewed with a new ticket, and false otherwise.
 335  */
 336 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 337 bool
 338 sec_protocol_metadata_get_session_renewed(sec_protocol_metadata_t metadata);
 339
 340 __END_DECLS
 341
 342 #endif /* SecProtocolPriv_h */