protocol/SecProtocolOptions.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 SecProtocolOptions_h
  25 #define SecProtocolOptions_h
  26
  27 #include <Security/SecProtocolObject.h>
  28 #include <Security/SecBase.h>
  29 #include <Security/SecureTransport.h>
  30 #include <Security/SecTrust.h>
  31 #include <Security/SecCertificate.h>
  32 #include <Security/SecIdentity.h>
  33 #include <Security/SecProtocolMetadata.h>
  34
  35 #include <dispatch/dispatch.h>
  36 #include <os/object.h>
  37
  38 /*!
  39  * The following diagram shows how clients interact with sec_protocol_options
  40  * and sec_protocol_metadata when configuring and using network security protocols.
  41  *
  42  *                    +--------+
  43  *                    | Client |
  44  *                    +-+---/ \+
  45  *                      |    |
  46  *        +-------------+    +-------------+
  47  *        | (1) set             (2) get    |
  48  *        | options             metadata   |
  49  * +-----\ /---------------+  +------------+----------+
  50  * | sec_protocol_options  |  | sec_protocol_metadata |
  51  * +-----------------------+  +-----------------------+
  52  *
  53  * Clients configure security protocols with `sec_protocol_options` instances.
  54  * And they inspect protocol instances using `sec_protocol_metadata` instances.
  55  */
  56
  57 #ifndef SEC_OBJECT_IMPL
  58 /*!
  59  * A `sec_protocol_options` instance is a container of options for security protocol instances,
  60  * such as TLS. Protocol options are used to configure security protocols in the network stack.
  61  * For example, clients may set the maximum and minimum allowed TLS versions through protocol
  62  * options.
  63  */
  64 SEC_OBJECT_DECL(sec_protocol_options);
  65 #endif // !SEC_OBJECT_IMPL
  66
  67 __BEGIN_DECLS
  68
  69 SEC_ASSUME_NONNULL_BEGIN
  70
  71 /*!
  72  * @function sec_protocol_options_set_local_identity
  73  *
  74  * @abstract
  75  *      Set the local identity to be used for this protocol instance.
  76  *
  77  * @param options
  78  *      A `sec_protocol_options_t` instance.
  79  *
  80  * @param identity
  81  *      A `sec_identity_t` instance carrying the private key and certificate.
  82  */
  83 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  84 void
  85 sec_protocol_options_set_local_identity(sec_protocol_options_t options, sec_identity_t identity);
  86
  87 /*!
  88  * @function sec_protocol_options_add_tls_ciphersuite
  89  *
  90  * @abstract
  91  *      Add a TLS ciphersuite to the set of enabled ciphersuites.
  92  *
  93  * @param options
  94  *      A `sec_protocol_options_t` instance.
  95  *
  96  * @param ciphersuite
  97  *      A SSLCipherSuite value.
  98  */
  99 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 100 void
 101 sec_protocol_options_add_tls_ciphersuite(sec_protocol_options_t options, SSLCipherSuite ciphersuite);
 102
 103 /*!
 104  * @function sec_protocol_options_add_tls_ciphersuite_group
 105  *
 106  * @abstract
 107  *      Add a TLS ciphersuite group to the set of enabled ciphersuites.
 108  *
 109  * @param options
 110  *      A `sec_protocol_options_t` instance.
 111  *
 112  * @param group
 113  *      A SSLCipherSuiteGroup value.
 114  */
 115 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 116 void
 117 sec_protocol_options_add_tls_ciphersuite_group(sec_protocol_options_t options, SSLCiphersuiteGroup group);
 118
 119 /*!
 120  * @function sec_protocol_options_set_tls_min_version
 121  *
 122  * @abstract
 123  *      Set the minimum support TLS version.
 124  *
 125  * @param options
 126  *      A `sec_protocol_options_t` instance.
 127  *
 128  * @param version
 129  *      A SSLProtocol enum value.
 130  */
 131 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 132 void
 133 sec_protocol_options_set_tls_min_version(sec_protocol_options_t options, SSLProtocol version);
 134
 135 /*!
 136  * @function sec_protocol_options_set_tls_max_version
 137  *
 138  * @abstract
 139  *      Set the maximum support TLS version.
 140  *
 141  * @param options
 142  *      A `sec_protocol_options_t` instance.
 143  *
 144  * @param version
 145  *      A SSLProtocol enum value.
 146  */
 147 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 148 void
 149 sec_protocol_options_set_tls_max_version(sec_protocol_options_t options, SSLProtocol version);
 150
 151 /*!
 152  * @function sec_protocol_options_add_tls_application_protocol
 153  *
 154  * @abstract
 155  *      Add an application protocol supported by clients of this protocol instance.
 156  *
 157  * @param options
 158  *      A `sec_protocol_options_t` instance.
 159  *
 160  * @param application_protocol
 161  *      A NULL-terminated string defining the application protocol.
 162  */
 163 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 164 void
 165 sec_protocol_options_add_tls_application_protocol(sec_protocol_options_t options, const char *application_protocol);
 166
 167 /*!
 168  * @function sec_protocol_options_set_tls_server_name
 169  *
 170  * @abstract
 171  *      Set the server (domain) name to be used in the TLS SNI. This will override
 172  *      the server name obtained from the endpoint.
 173  *
 174  * @param options
 175  *      A `sec_protocol_options_t` instance.
 176  *
 177  * @param server_name
 178  *      A NULL-terminated string carrying the server (domain) name.
 179  */
 180 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 181 void
 182 sec_protocol_options_set_tls_server_name(sec_protocol_options_t options, const char *server_name);
 183
 184 /*!
 185  * @function sec_protocol_options_set_tls_diffie_hellman_parameters
 186  *
 187  * @abstract
 188  *      Set the supported Diffie-Hellman parameters.
 189  *
 190  * @param options
 191  *      A `sec_protocol_options_t` instance.
 192  *
 193  * @param params
 194  *      A dispatch_data_t containing legacy Diffie-Hellman parameters.
 195  */
 196 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 197 void
 198 sec_protocol_options_set_tls_diffie_hellman_parameters(sec_protocol_options_t options, dispatch_data_t params);
 199
 200 /*!
 201  * @function sec_protocol_options_add_pre_shared_key
 202  *
 203  * @abstract
 204  *      Add a pre-shared key (PSK) and its identity to the options.
 205  *
 206  * @param options
 207  *      A `sec_protocol_options_t` instance.
 208  *
 209  * @param psk
 210  *      A dispatch_data_t containing a PSK blob.
 211  *
 212  * @param psk_identity
 213  *      A dispatch_data_t containing a PSK identity blob.
 214  */
 215 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 216 void
 217 sec_protocol_options_add_pre_shared_key(sec_protocol_options_t options, dispatch_data_t psk, dispatch_data_t psk_identity);
 218
 219 /*!
 220  * @function sec_protocol_options_set_tls_tickets_enabled
 221  *
 222  * @abstract
 223  *      Enable or disable TLS session ticket support.
 224  *
 225  * @param options
 226  *      A `sec_protocol_options_t` instance.
 227  *
 228  * @param tickets_enabled
 229  *      Flag to enable or disable TLS session ticket support.
 230  */
 231 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 232 void
 233 sec_protocol_options_set_tls_tickets_enabled(sec_protocol_options_t options, bool tickets_enabled);
 234
 235 /*!
 236  * @function sec_protocol_options_set_tls_is_fallback_attempt
 237  *
 238  * @abstract
 239  *      Signal if this is a TLS fallback attempt.
 240  *
 241  *      A fallback attempt is one following a previously failed TLS connection
 242  *      due to version or parameter incompatibility, e.g., when speaking to a server
 243  *      that does not support a client-offered ciphersuite.
 244  *
 245  *      Clients MUST NOT enable fallback for fresh connections.
 246  *
 247  * @param options
 248  *      A `sec_protocol_options_t` instance.
 249  *
 250  * @param is_fallback_attempt
 251  *      Set a flag indicating that this is a TLS fallback attempt.
 252  */
 253 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 254 void
 255 sec_protocol_options_set_tls_is_fallback_attempt(sec_protocol_options_t options, bool is_fallback_attempt);
 256
 257 /*!
 258  * @function sec_protocol_options_set_tls_resumption_enabled
 259  *
 260  * @abstract
 261  *      Enable or disable TLS session resumption.
 262  *
 263  * @param options
 264  *      A `sec_protocol_options_t` instance.
 265  *
 266  * @param resumption_enabled
 267  *      Flag to enable or disable TLS session resumption.
 268  */
 269 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 270 void
 271 sec_protocol_options_set_tls_resumption_enabled(sec_protocol_options_t options, bool resumption_enabled);
 272
 273 /*!
 274  * @function sec_protocol_options_set_tls_false_start_enabled
 275  *
 276  * @abstract
 277  *      Enable or disable TLS False Start.
 278  *
 279  * @param options
 280  *      A `sec_protocol_options_t` instance.
 281  *
 282  * @param false_start_enabled
 283  *      Flag to enable or disable TLS False Start.
 284  */
 285 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 286 void
 287 sec_protocol_options_set_tls_false_start_enabled(sec_protocol_options_t options, bool false_start_enabled);
 288
 289 /*!
 290  * @function nw_protocol_options_set_tls_ocsp_enabled
 291  *
 292  * @abstract
 293  *      Enable or disable OCSP support.
 294  *
 295  * @param options
 296  *      A `sec_protocol_options_t` instance.
 297  *
 298  * @param ocsp_enabled
 299  *      Flag to enable or disable OCSP support.
 300  */
 301 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 302 void
 303 sec_protocol_options_set_tls_ocsp_enabled(sec_protocol_options_t options, bool ocsp_enabled);
 304
 305 /*!
 306  * @function sec_protocol_options_set_tls_sct_enabled
 307  *
 308  * @abstract
 309  *      Enable or disable SCT (signed certificate timestamp) support.
 310  *
 311  * @param options
 312  *      A `sec_protocol_options_t` instance.
 313  *
 314  * @param sct_enabled
 315  *      Flag to enable or disable SCT support.
 316  */
 317 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 318 void
 319 sec_protocol_options_set_tls_sct_enabled(sec_protocol_options_t options, bool sct_enabled);
 320
 321 /*!
 322  * @function sec_protocol_options_set_tls_renegotiation_enabled
 323  *
 324  * @abstract
 325  *      Enable or disable TLS (1.2 and prior) session renegotiation. This defaults to `true`.
 326  *
 327  * @param options
 328  *      A `sec_protocol_options_t` instance.
 329  *
 330  * @param renegotiation_enabled
 331  *      Flag to enable or disable TLS (1.2 and prior) session renegotiation.
 332  */
 333 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 334 void
 335 sec_protocol_options_set_tls_renegotiation_enabled(sec_protocol_options_t options, bool renegotiation_enabled);
 336
 337 /*!
 338  * @function sec_protocol_options_set_peer_authentication_required
 339  *
 340  * @abstract
 341  *      Enable or disable peer authentication. Clients default to true, whereas servers default to false.
 342  *
 343  * @param options
 344  *      A `sec_protocol_options_t` instance.
 345  *
 346  * @param peer_authentication_required
 347  *      Flag to enable or disable mandatory peer authentication.
 348  */
 349 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 350 void
 351 sec_protocol_options_set_peer_authentication_required(sec_protocol_options_t options, bool peer_authentication_required);
 352
 353 #ifdef __BLOCKS__
 354
 355 /*!
 356  * @block sec_protocol_key_update_complete_t
 357  *
 358  * @abstract
 359  *      Block to be invoked when a key update event is handled.
 360  */
 361 typedef void (^sec_protocol_key_update_complete_t)(void);
 362
 363 /*!
 364  * @block sec_protocol_key_update_t
 365  *
 366  * @abstract
 367  *      Block to be invoked when the protocol key MUST be updated.
 368  *
 369  * @param metadata
 370  *      A `sec_protocol_metadata_t` instance.
 371  *
 372  * @param complete
 373  *      A `sec_protocol_key_update_complete_t` to be invoked when the key update is complete.
 374  */
 375 typedef void (^sec_protocol_key_update_t)(sec_protocol_metadata_t metadata, sec_protocol_key_update_complete_t complete);
 376
 377 /*!
 378  * @block sec_protocol_challenge_complete_t
 379  *
 380  * @abstract
 381  *      Block to be invoked when an identity (authentication) challenge is complete.
 382  *
 383  * @param identity
 384  *      A `sec_identity_t` containing the identity to use for this challenge.
 385  */
 386 typedef void (^sec_protocol_challenge_complete_t)(sec_identity_t identity);
 387
 388 /*!
 389  * @block sec_protocol_challenge_t
 390  *
 391  * @abstract
 392  *      Block to be invoked when the protocol instance is issued a challenge (e.g., a TLS certificate request).
 393  *
 394  * @param metadata
 395  *      A `sec_protocol_metadata_t` instance.
 396  *
 397  * @param complete
 398  *      A `sec_protocol_challenge_complete_t` to be invoked when the challenge is complete.
 399  */
 400 typedef void (^sec_protocol_challenge_t)(sec_protocol_metadata_t metadata, sec_protocol_challenge_complete_t complete);
 401
 402 /*!
 403  * @block sec_protocol_verify_complete_t
 404  *
 405  * @abstract
 406  *      Block to be invoked when verification is complete.
 407  *
 408  * @param result
 409  *      A `bool` indicating if verification succeeded or failed.
 410  */
 411 typedef void (^sec_protocol_verify_complete_t)(bool result);
 412
 413 /*!
 414  * @block sec_protocol_verify_t
 415  *
 416  * @abstract
 417  *      Block to be invoked when the protocol instance must verify the peer.
 418  *
 419  *      NOTE: this may be called one or more times for a given connection.
 420  *
 421  * @param metadata
 422  *      A `sec_protocol_metadata_t` instance.
 423  *
 424  * @param trust_ref
 425  *      A `sec_trust_t` instance.
 426  *
 427  * @param complete
 428  *      A `sec_protocol_verify_finish_t` to be invoked when verification is complete.
 429  */
 430 typedef void (^sec_protocol_verify_t)(sec_protocol_metadata_t metadata, sec_trust_t trust_ref, sec_protocol_verify_complete_t complete);
 431
 432 /*!
 433  * @function sec_protocol_options_set_key_update_block
 434  *
 435  * @abstract
 436  *      Set the key update block.
 437  *
 438  * @param options
 439  *      A `sec_protocol_options_t` instance.
 440  *
 441  * @param key_update_block
 442  *      A `sec_protocol_key_update_t` block.
 443  *
 444  * @params key_update_queue
 445  *      A `dispatch_queue_t` on which the key update block should be called.
 446  */
 447 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 448 void
 449 sec_protocol_options_set_key_update_block(sec_protocol_options_t options, sec_protocol_key_update_t key_update_block, dispatch_queue_t key_update_queue);
 450
 451 /*!
 452  * @function sec_protocol_options_set_challenge_block
 453  *
 454  * @abstract
 455  *      Set the challenge block.
 456  *
 457  * @param options
 458  *      A `sec_protocol_options_t` instance.
 459  *
 460  * @params challenge_block
 461  *      A `sec_protocol_challenge_t` block.
 462  *
 463  * @params challenge_queue
 464  *      A `dispatch_queue_t` on which the challenge block should be called.
 465  */
 466 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 467 void
 468 sec_protocol_options_set_challenge_block(sec_protocol_options_t options, sec_protocol_challenge_t challenge_block, dispatch_queue_t challenge_queue);
 469
 470 /*!
 471  * @function sec_protocol_options_set_verify_block
 472  *
 473  * @abstract
 474  *      Set the verify block.
 475  *
 476  * @param options
 477  *      A `sec_protocol_options_t` instance.
 478  *
 479  * @params verify_block
 480  *      A `sec_protocol_verify_t` block.
 481  *
 482  * @params verify_block_queue
 483  *      A `dispatch_queue_t` on which the verify block should be called.
 484  */
 485 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 486 void
 487 sec_protocol_options_set_verify_block(sec_protocol_options_t options, sec_protocol_verify_t verify_block, dispatch_queue_t verify_block_queue);
 488
 489 #endif // __BLOCKS__
 490
 491 SEC_ASSUME_NONNULL_END
 492
 493 __END_DECLS
 494
 495 #endif // SecProtocolOptions_h