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