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_get_enable_encrypted_client_hello 284 * 285 * @abstract 286 * For experimental use only. Find out whether Encrypted Client Hello has been enabled. 287 * 288 * @return A boolean that indicates whether or not Encrypted Client Hello has been enabled. 289 */ 290 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0)) 291 bool 292 sec_protocol_options_get_enable_encrypted_client_hello(sec_protocol_options_t options); 293 294 /*! 295 * @function sec_protocol_options_add_tls_application_protocol 296 * 297 * @abstract 298 * Add an application protocol supported by clients of this protocol instance. 299 * 300 * @param options 301 * A `sec_protocol_options_t` instance. 302 * 303 * @param application_protocol 304 * A NULL-terminated string defining the application protocol. 305 */ 306 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 307 void 308 sec_protocol_options_add_tls_application_protocol(sec_protocol_options_t options, const char *application_protocol); 309 310 /*! 311 * @function sec_protocol_options_set_tls_server_name 312 * 313 * @abstract 314 * Set the server name to be used when verifying the peer's certificate. This will override 315 * the server name obtained from the endpoint. 316 * 317 * @param options 318 * A `sec_protocol_options_t` instance. 319 * 320 * @param server_name 321 * A NULL-terminated string carrying the server name. 322 */ 323 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 324 void 325 sec_protocol_options_set_tls_server_name(sec_protocol_options_t options, const char *server_name); 326 327 /*! 328 * @function sec_protocol_options_set_tls_diffie_hellman_parameters 329 * 330 * @abstract 331 * Set the supported Diffie-Hellman parameters. 332 * 333 * @param options 334 * A `sec_protocol_options_t` instance. 335 * 336 * @param params 337 * A dispatch_data_t containing legacy Diffie-Hellman parameters. 338 */ 339 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)) 340 void 341 sec_protocol_options_set_tls_diffie_hellman_parameters(sec_protocol_options_t options, dispatch_data_t params); 342 343 /*! 344 * @function sec_protocol_options_add_pre_shared_key 345 * 346 * @abstract 347 * Add a pre-shared key (PSK) and its identity to the options. 348 * 349 * @param options 350 * A `sec_protocol_options_t` instance. 351 * 352 * @param psk 353 * A dispatch_data_t containing a PSK blob. 354 * 355 * @param psk_identity 356 * A dispatch_data_t containing a PSK identity blob. 357 */ 358 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 359 void 360 sec_protocol_options_add_pre_shared_key(sec_protocol_options_t options, dispatch_data_t psk, dispatch_data_t psk_identity); 361 362 /*! 363 * @function sec_protocol_options_set_tls_pre_shared_key_identity_hint 364 * 365 * @abstract 366 * Set the PSK identity hint to use by servers when negotiating a PSK ciphersuite. 367 * See https://tools.ietf.org/html/rfc4279 for more details. 368 * 369 * @param options 370 * A `sec_protocol_options_t` instance. 371 * 372 * @param psk_identity_hint 373 * A dispatch_data_t containing a PSK identity hint. 374 */ 375 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0)) 376 void 377 sec_protocol_options_set_tls_pre_shared_key_identity_hint(sec_protocol_options_t options, dispatch_data_t psk_identity_hint); 378 379 #ifdef __BLOCKS__ 380 381 /*! 382 * @block sec_protocol_pre_shared_key_selection_complete_t 383 * 384 * @abstract 385 * Block to be invoked when a PSK selection event is complete and a PSK identity is chosen. 386 * 387 * @param psk_identity 388 * A `dispatch_data_t` instance carrying the chosen PSK identity, or nil if one does not match. 389 */ 390 typedef void (^sec_protocol_pre_shared_key_selection_complete_t)(dispatch_data_t _Nullable psk_identity); 391 392 /*! 393 * @block sec_protocol_pre_shared_key_selection_t 394 * 395 * @abstract 396 * Block to be invoked when the client must choose a PSK identity given a hint from its peer. 397 * 398 * @param metadata 399 * A `sec_protocol_metadata_t` instance. 400 * 401 * @param psk_identity_hint 402 * A `dispatch_data_t` object carrying the peer's (optional) PSK identity hint. 403 * 404 * @param complete 405 * A `sec_protocol_pre_shared_key_selection_complete_t` block to be invoked when PSK selection is complete. 406 */ 407 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); 408 409 /*! 410 * @function sec_protocol_options_set_pre_shared_key_selection_block 411 * 412 * @abstract 413 * Set the PSK selection block. 414 * 415 * @param options 416 * A `sec_protocol_options_t` instance. 417 * 418 * @param psk_selection_block 419 * A `sec_protocol_pre_shared_key_selection_t` block. 420 * 421 * @params psk_selection_queue 422 * A `dispatch_queue_t` on which the PSK selection block should be called. 423 */ 424 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0)) 425 void 426 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); 427 428 #endif // __BLOCKS__ 429 430 /*! 431 * @function sec_protocol_options_set_tls_tickets_enabled 432 * 433 * @abstract 434 * Enable or disable TLS session ticket support. 435 * 436 * @param options 437 * A `sec_protocol_options_t` instance. 438 * 439 * @param tickets_enabled 440 * Flag to enable or disable TLS session ticket support. 441 */ 442 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 443 void 444 sec_protocol_options_set_tls_tickets_enabled(sec_protocol_options_t options, bool tickets_enabled); 445 446 /*! 447 * @function sec_protocol_options_set_tls_is_fallback_attempt 448 * 449 * @abstract 450 * Signal if this is a TLS fallback attempt. 451 * 452 * A fallback attempt is one following a previously failed TLS connection 453 * due to version or parameter incompatibility, e.g., when speaking to a server 454 * that does not support a client-offered ciphersuite. 455 * 456 * Clients MUST NOT enable fallback for fresh connections. 457 * 458 * @param options 459 * A `sec_protocol_options_t` instance. 460 * 461 * @param is_fallback_attempt 462 * Set a flag indicating that this is a TLS fallback attempt. 463 */ 464 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 465 void 466 sec_protocol_options_set_tls_is_fallback_attempt(sec_protocol_options_t options, bool is_fallback_attempt); 467 468 /*! 469 * @function sec_protocol_options_set_tls_resumption_enabled 470 * 471 * @abstract 472 * Enable or disable TLS session resumption. 473 * 474 * @param options 475 * A `sec_protocol_options_t` instance. 476 * 477 * @param resumption_enabled 478 * Flag to enable or disable TLS session resumption. 479 */ 480 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 481 void 482 sec_protocol_options_set_tls_resumption_enabled(sec_protocol_options_t options, bool resumption_enabled); 483 484 /*! 485 * @function sec_protocol_options_set_tls_false_start_enabled 486 * 487 * @abstract 488 * Enable or disable TLS False Start. 489 * 490 * @param options 491 * A `sec_protocol_options_t` instance. 492 * 493 * @param false_start_enabled 494 * Flag to enable or disable TLS False Start. 495 */ 496 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 497 void 498 sec_protocol_options_set_tls_false_start_enabled(sec_protocol_options_t options, bool false_start_enabled); 499 500 /*! 501 * @function nw_protocol_options_set_tls_ocsp_enabled 502 * 503 * @abstract 504 * Enable or disable OCSP support. 505 * 506 * @param options 507 * A `sec_protocol_options_t` instance. 508 * 509 * @param ocsp_enabled 510 * Flag to enable or disable OCSP support. 511 */ 512 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 513 void 514 sec_protocol_options_set_tls_ocsp_enabled(sec_protocol_options_t options, bool ocsp_enabled); 515 516 /*! 517 * @function sec_protocol_options_set_tls_sct_enabled 518 * 519 * @abstract 520 * Enable or disable SCT (signed certificate timestamp) support. 521 * 522 * @param options 523 * A `sec_protocol_options_t` instance. 524 * 525 * @param sct_enabled 526 * Flag to enable or disable SCT support. 527 */ 528 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 529 void 530 sec_protocol_options_set_tls_sct_enabled(sec_protocol_options_t options, bool sct_enabled); 531 532 /*! 533 * @function sec_protocol_options_set_tls_renegotiation_enabled 534 * 535 * @abstract 536 * Enable or disable TLS (1.2 and prior) session renegotiation. This defaults to `true`. 537 * 538 * @param options 539 * A `sec_protocol_options_t` instance. 540 * 541 * @param renegotiation_enabled 542 * Flag to enable or disable TLS (1.2 and prior) session renegotiation. 543 */ 544 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 545 void 546 sec_protocol_options_set_tls_renegotiation_enabled(sec_protocol_options_t options, bool renegotiation_enabled); 547 548 /*! 549 * @function sec_protocol_options_set_peer_authentication_required 550 * 551 * @abstract 552 * Enable or disable peer authentication. Clients default to true, whereas servers default to false. 553 * 554 * @param options 555 * A `sec_protocol_options_t` instance. 556 * 557 * @param peer_authentication_required 558 * Flag to enable or disable mandatory peer authentication. 559 */ 560 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 561 void 562 sec_protocol_options_set_peer_authentication_required(sec_protocol_options_t options, bool peer_authentication_required); 563 564 /*! 565 * @function sec_protocol_options_set_peer_authentication_optional 566 * 567 * @abstract 568 * When this is enabled, the endpoint requests the peer certificate, but if none is provided, the 569 * endpoint still proceeds with the connection. Default false for servers; always false for clients (clients ignore 570 * this option). If peer_authentication_required is set to true via 571 * sec_protocol_options_set_peer_authentication_required(), peer_authentication_optional will be disregarded 572 * and the peer certificate will be required. 573 * 574 * @param options 575 * A `sec_protocol_options_t` instance. 576 * 577 * @param peer_authentication_optional 578 * Flag to enable or disable requested peer authentication. 579 */ 580 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0)) 581 void 582 sec_protocol_options_set_peer_authentication_optional(sec_protocol_options_t options, bool peer_authentication_optional); 583 584 /*! 585 * @function sec_protocol_options_set_enable_encrypted_client_hello 586 * 587 * @abstract 588 * For experimental use only. When this is enabled, the Encrypted Client Hello extension will be sent on the Client 589 * Hello if TLS 1.3 is among the supported TLS versions. Default false for clients; always false for servers (servers 590 * ignore this option). 591 * 592 * @param options 593 * A `sec_protocol_options_t` instance. 594 * 595 * @param peer_authentication_optional 596 * Flag to enable or disable Encrypted Client Hello. 597 */ 598 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0)) 599 void 600 sec_protocol_options_set_enable_encrypted_client_hello(sec_protocol_options_t options, bool enable_encrypted_client_hello); 601 602 #ifdef __BLOCKS__ 603 604 /*! 605 * @block sec_protocol_key_update_complete_t 606 * 607 * @abstract 608 * Block to be invoked when a key update event is handled. 609 */ 610 typedef void (^sec_protocol_key_update_complete_t)(void); 611 612 /*! 613 * @block sec_protocol_key_update_t 614 * 615 * @abstract 616 * Block to be invoked when the protocol key MUST be updated. 617 * 618 * @param metadata 619 * A `sec_protocol_metadata_t` instance. 620 * 621 * @param complete 622 * A `sec_protocol_key_update_complete_t` to be invoked when the key update is complete. 623 */ 624 typedef void (^sec_protocol_key_update_t)(sec_protocol_metadata_t metadata, sec_protocol_key_update_complete_t complete); 625 626 /*! 627 * @block sec_protocol_challenge_complete_t 628 * 629 * @abstract 630 * Block to be invoked when an identity (authentication) challenge is complete. 631 * 632 * Note: prior to macOS 10.15, iOS 13.0, watchOS 6.0, and tvOS 13.0, calling this 633 * block with a NULL `identity` argument was prohibited. 634 * 635 * @param identity 636 * A `sec_identity_t` containing the identity to use for this challenge. 637 */ 638 typedef void (^sec_protocol_challenge_complete_t)(sec_identity_t __nullable identity); 639 640 /*! 641 * @block sec_protocol_challenge_t 642 * 643 * @abstract 644 * Block to be invoked when the protocol instance is issued a challenge (e.g., a TLS certificate request). 645 * 646 * @param metadata 647 * A `sec_protocol_metadata_t` instance. 648 * 649 * @param complete 650 * A `sec_protocol_challenge_complete_t` to be invoked when the challenge is complete. 651 */ 652 typedef void (^sec_protocol_challenge_t)(sec_protocol_metadata_t metadata, sec_protocol_challenge_complete_t complete); 653 654 /*! 655 * @block sec_protocol_verify_complete_t 656 * 657 * @abstract 658 * Block to be invoked when verification is complete. 659 * 660 * @param result 661 * A `bool` indicating if verification succeeded or failed. 662 */ 663 typedef void (^sec_protocol_verify_complete_t)(bool result); 664 665 /*! 666 * @block sec_protocol_verify_t 667 * 668 * @abstract 669 * Block to be invoked when the protocol instance must verify the peer. 670 * 671 * NOTE: this may be called one or more times for a given connection. 672 * 673 * @param metadata 674 * A `sec_protocol_metadata_t` instance. 675 * 676 * @param trust_ref 677 * A `sec_trust_t` instance. 678 * 679 * @param complete 680 * A `sec_protocol_verify_finish_t` to be invoked when verification is complete. 681 */ 682 typedef void (^sec_protocol_verify_t)(sec_protocol_metadata_t metadata, sec_trust_t trust_ref, sec_protocol_verify_complete_t complete); 683 684 /*! 685 * @function sec_protocol_options_set_key_update_block 686 * 687 * @abstract 688 * Set the key update block. 689 * 690 * @param options 691 * A `sec_protocol_options_t` instance. 692 * 693 * @param key_update_block 694 * A `sec_protocol_key_update_t` block. 695 * 696 * @params key_update_queue 697 * A `dispatch_queue_t` on which the key update block should be called. 698 */ 699 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 700 void 701 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); 702 703 /*! 704 * @function sec_protocol_options_set_challenge_block 705 * 706 * @abstract 707 * Set the challenge block. 708 * 709 * @param options 710 * A `sec_protocol_options_t` instance. 711 * 712 * @params challenge_block 713 * A `sec_protocol_challenge_t` block. 714 * 715 * @params challenge_queue 716 * A `dispatch_queue_t` on which the challenge block should be called. 717 */ 718 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 719 void 720 sec_protocol_options_set_challenge_block(sec_protocol_options_t options, sec_protocol_challenge_t challenge_block, dispatch_queue_t challenge_queue); 721 722 /*! 723 * @function sec_protocol_options_set_verify_block 724 * 725 * @abstract 726 * Set the verify block. 727 * 728 * @param options 729 * A `sec_protocol_options_t` instance. 730 * 731 * @params verify_block 732 * A `sec_protocol_verify_t` block. 733 * 734 * @params verify_block_queue 735 * A `dispatch_queue_t` on which the verify block should be called. 736 */ 737 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0)) 738 void 739 sec_protocol_options_set_verify_block(sec_protocol_options_t options, sec_protocol_verify_t verify_block, dispatch_queue_t verify_block_queue); 740 741 #endif // __BLOCKS__ 742 743 SEC_ASSUME_NONNULL_END 744 745 __END_DECLS 746 747 #endif // SecProtocolOptions_h