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/SecProtocolTypes.h>
  29 #include <Security/SecProtocolMetadata.h>
  30 #include <Security/SecTrust.h>
  31 #include <Security/SecCertificate.h>
  32 #include <Security/SecIdentity.h>
  33
  34 #include <dispatch/dispatch.h>
  35 #include <os/object.h>
  36
  37 /*!
  38  * The following diagram shows how clients interact with sec_protocol_options
  39  * and sec_protocol_metadata when configuring and using network security protocols.
  40  *
  41  *                    +--------+
  42  *                    | Client |
  43  *                    +-+---/ \+
  44  *                      |    |
  45  *        +-------------+    +-------------+
  46  *        | (1) set             (2) get    |
  47  *        | options             metadata   |
  48  * +-----\ /---------------+  +------------+----------+
  49  * | sec_protocol_options  |  | sec_protocol_metadata |
  50  * +-----------------------+  +-----------------------+
  51  *
  52  * Clients configure security protocols with `sec_protocol_options` instances.
  53  * And they inspect protocol instances using `sec_protocol_metadata` instances.
  54  */
  55
  56 #ifndef SEC_OBJECT_IMPL
  57 /*!
  58  * A `sec_protocol_options` instance is a container of options for security protocol instances,
  59  * such as TLS. Protocol options are used to configure security protocols in the network stack.
  60  * For example, clients may set the maximum and minimum allowed TLS versions through protocol
  61  * options.
  62  */
  63 SEC_OBJECT_DECL(sec_protocol_options);
  64 #endif // !SEC_OBJECT_IMPL
  65
  66 __BEGIN_DECLS
  67
  68 SEC_ASSUME_NONNULL_BEGIN
  69
  70 /*!
  71  * @function sec_protocol_options_are_equal
  72  *
  73  * @abstract
  74  *      Compare two `sec_protocol_options_t` instances.
  75  *
  76  * @param optionsA
  77  *      A `sec_protocol_options_t` instance.
  78  *
  79  * @param optionsB
  80  *      A `sec_protocol_options_t` instance.
  81  *
  82  * @return True if equal, and false otherwise.
  83  */
  84 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  85 bool
  86 sec_protocol_options_are_equal(sec_protocol_options_t optionsA, sec_protocol_options_t optionsB);
  87
  88 /*!
  89  * @function sec_protocol_options_set_local_identity
  90  *
  91  * @abstract
  92  *      Set the local identity to be used for this protocol instance.
  93  *
  94  * @param options
  95  *      A `sec_protocol_options_t` instance.
  96  *
  97  * @param identity
  98  *      A `sec_identity_t` instance carrying the private key and certificate.
  99  */
 100 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 101 void
 102 sec_protocol_options_set_local_identity(sec_protocol_options_t options, sec_identity_t identity);
 103
 104 /*!
 105  * @function sec_protocol_options_append_tls_ciphersuite
 106  *
 107  * @abstract
 108  *      Append a TLS ciphersuite to the set of enabled ciphersuites.
 109  *
 110  * @param options
 111  *      A `sec_protocol_options_t` instance.
 112  *
 113  * @param ciphersuite
 114  *      A `tls_ciphersuite_t` value.
 115  */
 116 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 117 void
 118 sec_protocol_options_append_tls_ciphersuite(sec_protocol_options_t options, tls_ciphersuite_t ciphersuite);
 119
 120 /*!
 121  * @function sec_protocol_options_add_tls_ciphersuite
 122  *
 123  * @abstract
 124  *      Add a TLS ciphersuite to the set of enabled ciphersuites.
 125  *
 126  * @param options
 127  *      A `sec_protocol_options_t` instance.
 128  *
 129  * @param ciphersuite
 130  *      A SSLCipherSuite value.
 131  */
 132 API_DEPRECATED("Use sec_protocol_options_append_tls_ciphersuite", macos(10.14, 10.15), ios(12.0, 13.0), watchos(5.0, 6.0), tvos(12.0, 13.0), macCatalyst(13.0, 13.0))
 133 void
 134 sec_protocol_options_add_tls_ciphersuite(sec_protocol_options_t options, SSLCipherSuite ciphersuite);
 135
 136 /*!
 137  * @function sec_protocol_options_append_tls_ciphersuite_group
 138  *
 139  * @abstract
 140  *      Append a TLS ciphersuite group to the set of enabled ciphersuites.
 141  *
 142  * @param options
 143  *      A `sec_protocol_options_t` instance.
 144  *
 145  * @param group
 146  *      A SSLCipherSuiteGroup value.
 147  */
 148 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 149 void
 150 sec_protocol_options_append_tls_ciphersuite_group(sec_protocol_options_t options, tls_ciphersuite_group_t group);
 151
 152 /*!
 153  * @function sec_protocol_options_add_tls_ciphersuite_group
 154  *
 155  * @abstract
 156  *      Add a TLS ciphersuite group to the set of enabled ciphersuites.
 157  *
 158  * @param options
 159  *      A `sec_protocol_options_t` instance.
 160  *
 161  * @param group
 162  *      A SSLCipherSuiteGroup value.
 163  */
 164 API_DEPRECATED("Use sec_protocol_options_append_tls_ciphersuite_group", macos(10.14, 10.15), ios(12.0, 13.0), watchos(5.0, 6.0), tvos(12.0, 13.0), macCatalyst(13.0, 13.0))
 165 void
 166 sec_protocol_options_add_tls_ciphersuite_group(sec_protocol_options_t options, SSLCiphersuiteGroup group);
 167
 168 /*!
 169  * @function sec_protocol_options_set_tls_min_version
 170  *
 171  * @abstract
 172  *      Set the minimum support TLS version.
 173  *
 174  * @param options
 175  *      A `sec_protocol_options_t` instance.
 176  *
 177  * @param version
 178  *      A SSLProtocol enum value.
 179  */
 180 API_DEPRECATED_WITH_REPLACEMENT("sec_protocol_options_set_min_tls_protocol_version",
 181                                 macos(10.14, 10.15), ios(12.0, 13.0), watchos(5.0, 6.0), tvos(12.0, 13.0), macCatalyst(13.0, 13.0))
 182 void
 183 sec_protocol_options_set_tls_min_version(sec_protocol_options_t options, SSLProtocol version);
 184
 185 /*!
 186  * @function sec_protocol_options_set_min_tls_protocol_version
 187  *
 188  * @abstract
 189  *      Set the minimum support TLS version.
 190  *
 191  * @param options
 192  *      A `sec_protocol_options_t` instance.
 193  *
 194  * @param version
 195  *      A tls_protocol_version_t enum value.
 196  */
 197 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 198 void
 199 sec_protocol_options_set_min_tls_protocol_version(sec_protocol_options_t options, tls_protocol_version_t version);
 200
 201 /*!
 202  * @function sec_protocol_options_get_default_min_tls_protocol_version
 203  *
 204  * @abstract
 205  *      Get the system default minimum TLS protocol version.
 206  *
 207  * @return The default minimum TLS version.
 208  */
 209 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 210 tls_protocol_version_t
 211 sec_protocol_options_get_default_min_tls_protocol_version(void);
 212
 213 /*!
 214  * @function sec_protocol_options_get_default_min_dtls_protocol_version
 215  *
 216  * @abstract
 217  *      Get the system default minimum DTLS protocol version.
 218  *
 219  * @return The default minimum DTLS version.
 220  */
 221 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 222 tls_protocol_version_t
 223 sec_protocol_options_get_default_min_dtls_protocol_version(void);
 224
 225 /*!
 226  * @function sec_protocol_options_set_tls_max_version
 227  *
 228  * @abstract
 229  *      Set the maximum support TLS version.
 230  *
 231  * @param options
 232  *      A `sec_protocol_options_t` instance.
 233  *
 234  * @param version
 235  *      A SSLProtocol enum value.
 236  */
 237 API_DEPRECATED_WITH_REPLACEMENT("sec_protocol_options_set_max_tls_protocol_version",
 238                                 macos(10.14, 10.15), ios(12.0, 13.0), watchos(5.0, 6.0), tvos(12.0, 13.0), macCatalyst(13.0, 13.0))
 239 void
 240 sec_protocol_options_set_tls_max_version(sec_protocol_options_t options, SSLProtocol version);
 241
 242 /*!
 243  * @function sec_protocol_options_set_max_tls_protocol_version
 244  *
 245  * @abstract
 246  *      Set the maximum support TLS version.
 247  *
 248  * @param options
 249  *      A `sec_protocol_options_t` instance.
 250  *
 251  * @param version
 252  *      A tls_protocol_version_t enum value.
 253  */
 254 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 255 void
 256 sec_protocol_options_set_max_tls_protocol_version(sec_protocol_options_t options, tls_protocol_version_t version);
 257
 258 /*!
 259  * @function sec_protocol_options_get_default_max_tls_protocol_version
 260  *
 261  * @abstract
 262  *      Get the system default maximum TLS protocol version.
 263  *
 264  * @return The default maximum TLS version.
 265  */
 266 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 267 tls_protocol_version_t
 268 sec_protocol_options_get_default_max_tls_protocol_version(void);
 269
 270 /*!
 271  * @function sec_protocol_options_get_default_max_tls_protocol_version
 272  *
 273  * @abstract
 274  *      Get the system default maximum DTLS protocol version.
 275  *
 276  * @return The default maximum DTLS version.
 277  */
 278 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 279 tls_protocol_version_t
 280 sec_protocol_options_get_default_max_dtls_protocol_version(void);
 281
 282 /*!
 283  * @function sec_protocol_options_add_tls_application_protocol
 284  *
 285  * @abstract
 286  *      Add an application protocol supported by clients of this protocol instance.
 287  *
 288  * @param options
 289  *      A `sec_protocol_options_t` instance.
 290  *
 291  * @param application_protocol
 292  *      A NULL-terminated string defining the application protocol.
 293  */
 294 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 295 void
 296 sec_protocol_options_add_tls_application_protocol(sec_protocol_options_t options, const char *application_protocol);
 297
 298 /*!
 299  * @function sec_protocol_options_set_tls_server_name
 300  *
 301  * @abstract
 302  *      Set the server name to be used when verifying the peer's certificate. This will override
 303  *      the server name obtained from the endpoint.
 304  *
 305  * @param options
 306  *      A `sec_protocol_options_t` instance.
 307  *
 308  * @param server_name
 309  *      A NULL-terminated string carrying the server name.
 310  */
 311 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 312 void
 313 sec_protocol_options_set_tls_server_name(sec_protocol_options_t options, const char *server_name);
 314
 315 /*!
 316  * @function sec_protocol_options_set_tls_diffie_hellman_parameters
 317  *
 318  * @abstract
 319  *      Set the supported Diffie-Hellman parameters.
 320  *
 321  * @param options
 322  *      A `sec_protocol_options_t` instance.
 323  *
 324  * @param params
 325  *      A dispatch_data_t containing legacy Diffie-Hellman parameters.
 326  */
 327 API_DEPRECATED("DHE ciphersuites are no longer supported", macos(10.14, 10.15), ios(12.0, 13.0), watchos(5.0, 6.0), tvos(12.0, 13.0))
 328 void
 329 sec_protocol_options_set_tls_diffie_hellman_parameters(sec_protocol_options_t options, dispatch_data_t params);
 330
 331 /*!
 332  * @function sec_protocol_options_add_pre_shared_key
 333  *
 334  * @abstract
 335  *      Add a pre-shared key (PSK) and its identity to the options.
 336  *
 337  * @param options
 338  *      A `sec_protocol_options_t` instance.
 339  *
 340  * @param psk
 341  *      A dispatch_data_t containing a PSK blob.
 342  *
 343  * @param psk_identity
 344  *      A dispatch_data_t containing a PSK identity blob.
 345  */
 346 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 347 void
 348 sec_protocol_options_add_pre_shared_key(sec_protocol_options_t options, dispatch_data_t psk, dispatch_data_t psk_identity);
 349
 350 /*!
 351  * @function sec_protocol_options_set_tls_pre_shared_key_identity_hint
 352  *
 353  * @abstract
 354  *      Set the PSK identity hint to use by servers when negotiating a PSK ciphersuite.
 355  *      See https://tools.ietf.org/html/rfc4279 for more details.
 356  *
 357  * @param options
 358  *      A `sec_protocol_options_t` instance.
 359  *
 360  * @param psk_identity_hint
 361  *      A dispatch_data_t containing a PSK identity hint.
 362  */
 363 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 364 void
 365 sec_protocol_options_set_tls_pre_shared_key_identity_hint(sec_protocol_options_t options, dispatch_data_t psk_identity_hint);
 366
 367 #ifdef __BLOCKS__
 368
 369 /*!
 370  * @block sec_protocol_pre_shared_key_selection_complete_t
 371  *
 372  * @abstract
 373  *      Block to be invoked when a PSK selection event is complete and a PSK identity is chosen.
 374  *
 375  * @param psk_identity
 376  *      A `dispatch_data_t` instance carrying the chosen PSK identity, or nil if one does not match.
 377  */
 378 typedef void (^sec_protocol_pre_shared_key_selection_complete_t)(dispatch_data_t _Nullable psk_identity);
 379
 380 /*!
 381  * @block sec_protocol_pre_shared_key_selection_t
 382  *
 383  * @abstract
 384  *      Block to be invoked when the client must choose a PSK identity given a hint from its peer.
 385  *
 386  * @param metadata
 387  *      A `sec_protocol_metadata_t` instance.
 388  *
 389  * @param psk_identity_hint
 390  *      A `dispatch_data_t` object carrying the peer's (optional) PSK identity hint.
 391  *
 392  * @param complete
 393  *      A `sec_protocol_pre_shared_key_selection_complete_t` block to be invoked when PSK selection is complete.
 394  */
 395 typedef void (^sec_protocol_pre_shared_key_selection_t)(sec_protocol_metadata_t metadata, dispatch_data_t _Nullable psk_identity_hint, sec_protocol_pre_shared_key_selection_complete_t complete);
 396
 397 /*!
 398  * @function sec_protocol_options_set_pre_shared_key_selection_block
 399  *
 400  * @abstract
 401  *      Set the PSK selection block.
 402  *
 403  * @param options
 404  *      A `sec_protocol_options_t` instance.
 405  *
 406  * @param psk_selection_block
 407  *      A `sec_protocol_pre_shared_key_selection_t` block.
 408  *
 409  * @params psk_selection_queue
 410  *      A `dispatch_queue_t` on which the PSK selection block should be called.
 411  */
 412 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 413 void
 414 sec_protocol_options_set_pre_shared_key_selection_block(sec_protocol_options_t options, sec_protocol_pre_shared_key_selection_t psk_selection_block, dispatch_queue_t psk_selection_queue);
 415
 416 #endif // __BLOCKS__
 417
 418 /*!
 419  * @function sec_protocol_options_set_tls_tickets_enabled
 420  *
 421  * @abstract
 422  *      Enable or disable TLS session ticket support.
 423  *
 424  * @param options
 425  *      A `sec_protocol_options_t` instance.
 426  *
 427  * @param tickets_enabled
 428  *      Flag to enable or disable TLS session ticket support.
 429  */
 430 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 431 void
 432 sec_protocol_options_set_tls_tickets_enabled(sec_protocol_options_t options, bool tickets_enabled);
 433
 434 /*!
 435  * @function sec_protocol_options_set_tls_is_fallback_attempt
 436  *
 437  * @abstract
 438  *      Signal if this is a TLS fallback attempt.
 439  *
 440  *      A fallback attempt is one following a previously failed TLS connection
 441  *      due to version or parameter incompatibility, e.g., when speaking to a server
 442  *      that does not support a client-offered ciphersuite.
 443  *
 444  *      Clients MUST NOT enable fallback for fresh connections.
 445  *
 446  * @param options
 447  *      A `sec_protocol_options_t` instance.
 448  *
 449  * @param is_fallback_attempt
 450  *      Set a flag indicating that this is a TLS fallback attempt.
 451  */
 452 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 453 void
 454 sec_protocol_options_set_tls_is_fallback_attempt(sec_protocol_options_t options, bool is_fallback_attempt);
 455
 456 /*!
 457  * @function sec_protocol_options_set_tls_resumption_enabled
 458  *
 459  * @abstract
 460  *      Enable or disable TLS session resumption.
 461  *
 462  * @param options
 463  *      A `sec_protocol_options_t` instance.
 464  *
 465  * @param resumption_enabled
 466  *      Flag to enable or disable TLS session resumption.
 467  */
 468 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 469 void
 470 sec_protocol_options_set_tls_resumption_enabled(sec_protocol_options_t options, bool resumption_enabled);
 471
 472 /*!
 473  * @function sec_protocol_options_set_tls_false_start_enabled
 474  *
 475  * @abstract
 476  *      Enable or disable TLS False Start.
 477  *
 478  * @param options
 479  *      A `sec_protocol_options_t` instance.
 480  *
 481  * @param false_start_enabled
 482  *      Flag to enable or disable TLS False Start.
 483  */
 484 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 485 void
 486 sec_protocol_options_set_tls_false_start_enabled(sec_protocol_options_t options, bool false_start_enabled);
 487
 488 /*!
 489  * @function nw_protocol_options_set_tls_ocsp_enabled
 490  *
 491  * @abstract
 492  *      Enable or disable OCSP support.
 493  *
 494  * @param options
 495  *      A `sec_protocol_options_t` instance.
 496  *
 497  * @param ocsp_enabled
 498  *      Flag to enable or disable OCSP support.
 499  */
 500 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 501 void
 502 sec_protocol_options_set_tls_ocsp_enabled(sec_protocol_options_t options, bool ocsp_enabled);
 503
 504 /*!
 505  * @function sec_protocol_options_set_tls_sct_enabled
 506  *
 507  * @abstract
 508  *      Enable or disable SCT (signed certificate timestamp) support.
 509  *
 510  * @param options
 511  *      A `sec_protocol_options_t` instance.
 512  *
 513  * @param sct_enabled
 514  *      Flag to enable or disable SCT support.
 515  */
 516 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 517 void
 518 sec_protocol_options_set_tls_sct_enabled(sec_protocol_options_t options, bool sct_enabled);
 519
 520 /*!
 521  * @function sec_protocol_options_set_tls_renegotiation_enabled
 522  *
 523  * @abstract
 524  *      Enable or disable TLS (1.2 and prior) session renegotiation. This defaults to `true`.
 525  *
 526  * @param options
 527  *      A `sec_protocol_options_t` instance.
 528  *
 529  * @param renegotiation_enabled
 530  *      Flag to enable or disable TLS (1.2 and prior) session renegotiation.
 531  */
 532 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 533 void
 534 sec_protocol_options_set_tls_renegotiation_enabled(sec_protocol_options_t options, bool renegotiation_enabled);
 535
 536 /*!
 537  * @function sec_protocol_options_set_peer_authentication_required
 538  *
 539  * @abstract
 540  *      Enable or disable peer authentication. Clients default to true, whereas servers default to false.
 541  *
 542  * @param options
 543  *      A `sec_protocol_options_t` instance.
 544  *
 545  * @param peer_authentication_required
 546  *      Flag to enable or disable mandatory peer authentication.
 547  */
 548 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 549 void
 550 sec_protocol_options_set_peer_authentication_required(sec_protocol_options_t options, bool peer_authentication_required);
 551
 552 /*!
 553  * @function sec_protocol_options_set_peer_authentication_optional
 554  *
 555  * @abstract
 556  *      When this is enabled, the endpoint requests the peer certificate, but if none is provided, the
 557  *      endpoint still proceeds with the connection. Default false for servers; always false for clients (this
 558  *      function is a no-op for clients). If peer_authentication_required is set to true via
 559  *      sec_protocol_options_set_peer_authentication_required(), peer_authentication_optional will be disregarded
 560  *      and the peer certificate will be required.
 561  *
 562  * @param options
 563  *      A `sec_protocol_options_t` instance.
 564  *
 565  * @param peer_authentication_optional
 566  *      Flag to enable or disable requested peer authentication.
 567  */
 568 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 569 void
 570 sec_protocol_options_set_peer_authentication_optional(sec_protocol_options_t options, bool peer_authentication_optional);
 571
 572 #ifdef __BLOCKS__
 573
 574 /*!
 575  * @block sec_protocol_key_update_complete_t
 576  *
 577  * @abstract
 578  *      Block to be invoked when a key update event is handled.
 579  */
 580 typedef void (^sec_protocol_key_update_complete_t)(void);
 581
 582 /*!
 583  * @block sec_protocol_key_update_t
 584  *
 585  * @abstract
 586  *      Block to be invoked when the protocol key MUST be updated.
 587  *
 588  * @param metadata
 589  *      A `sec_protocol_metadata_t` instance.
 590  *
 591  * @param complete
 592  *      A `sec_protocol_key_update_complete_t` to be invoked when the key update is complete.
 593  */
 594 typedef void (^sec_protocol_key_update_t)(sec_protocol_metadata_t metadata, sec_protocol_key_update_complete_t complete);
 595
 596 /*!
 597  * @block sec_protocol_challenge_complete_t
 598  *
 599  * @abstract
 600  *      Block to be invoked when an identity (authentication) challenge is complete.
 601  *
 602  *      Note: prior to macOS 10.15, iOS 13.0, watchOS 6.0, and tvOS 13.0, calling this
 603  *      block with a NULL `identity` argument was prohibited.
 604  *
 605  * @param identity
 606  *      A `sec_identity_t` containing the identity to use for this challenge.
 607  */
 608 typedef void (^sec_protocol_challenge_complete_t)(sec_identity_t __nullable identity);
 609
 610 /*!
 611  * @block sec_protocol_challenge_t
 612  *
 613  * @abstract
 614  *      Block to be invoked when the protocol instance is issued a challenge (e.g., a TLS certificate request).
 615  *
 616  * @param metadata
 617  *      A `sec_protocol_metadata_t` instance.
 618  *
 619  * @param complete
 620  *      A `sec_protocol_challenge_complete_t` to be invoked when the challenge is complete.
 621  */
 622 typedef void (^sec_protocol_challenge_t)(sec_protocol_metadata_t metadata, sec_protocol_challenge_complete_t complete);
 623
 624 /*!
 625  * @block sec_protocol_verify_complete_t
 626  *
 627  * @abstract
 628  *      Block to be invoked when verification is complete.
 629  *
 630  * @param result
 631  *      A `bool` indicating if verification succeeded or failed.
 632  */
 633 typedef void (^sec_protocol_verify_complete_t)(bool result);
 634
 635 /*!
 636  * @block sec_protocol_verify_t
 637  *
 638  * @abstract
 639  *      Block to be invoked when the protocol instance must verify the peer.
 640  *
 641  *      NOTE: this may be called one or more times for a given connection.
 642  *
 643  * @param metadata
 644  *      A `sec_protocol_metadata_t` instance.
 645  *
 646  * @param trust_ref
 647  *      A `sec_trust_t` instance.
 648  *
 649  * @param complete
 650  *      A `sec_protocol_verify_finish_t` to be invoked when verification is complete.
 651  */
 652 typedef void (^sec_protocol_verify_t)(sec_protocol_metadata_t metadata, sec_trust_t trust_ref, sec_protocol_verify_complete_t complete);
 653
 654 /*!
 655  * @function sec_protocol_options_set_key_update_block
 656  *
 657  * @abstract
 658  *      Set the key update block.
 659  *
 660  * @param options
 661  *      A `sec_protocol_options_t` instance.
 662  *
 663  * @param key_update_block
 664  *      A `sec_protocol_key_update_t` block.
 665  *
 666  * @params key_update_queue
 667  *      A `dispatch_queue_t` on which the key update block should be called.
 668  */
 669 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 670 void
 671 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);
 672
 673 /*!
 674  * @function sec_protocol_options_set_challenge_block
 675  *
 676  * @abstract
 677  *      Set the challenge block.
 678  *
 679  * @param options
 680  *      A `sec_protocol_options_t` instance.
 681  *
 682  * @params challenge_block
 683  *      A `sec_protocol_challenge_t` block.
 684  *
 685  * @params challenge_queue
 686  *      A `dispatch_queue_t` on which the challenge block should be called.
 687  */
 688 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 689 void
 690 sec_protocol_options_set_challenge_block(sec_protocol_options_t options, sec_protocol_challenge_t challenge_block, dispatch_queue_t challenge_queue);
 691
 692 /*!
 693  * @function sec_protocol_options_set_verify_block
 694  *
 695  * @abstract
 696  *      Set the verify block.
 697  *
 698  * @param options
 699  *      A `sec_protocol_options_t` instance.
 700  *
 701  * @params verify_block
 702  *      A `sec_protocol_verify_t` block.
 703  *
 704  * @params verify_block_queue
 705  *      A `dispatch_queue_t` on which the verify block should be called.
 706  */
 707 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 708 void
 709 sec_protocol_options_set_verify_block(sec_protocol_options_t options, sec_protocol_verify_t verify_block, dispatch_queue_t verify_block_queue);
 710
 711 #endif // __BLOCKS__
 712
 713 SEC_ASSUME_NONNULL_END
 714
 715 __END_DECLS
 716
 717 #endif // SecProtocolOptions_h