protocol/SecProtocolPriv.h

   1 //
   2 //  SecProtocolPriv.h
   3 //  Security
   4 //
   5
   6 #ifndef SecProtocolPriv_h
   7 #define SecProtocolPriv_h
   8
   9 #include <Security/SecProtocolOptions.h>
  10 #include <Security/SecProtocolMetadata.h>
  11 #include <Security/SecProtocolConfiguration.h>
  12 #include <Security/SecureTransportPriv.h>
  13 #include <Security/SecCertificatePriv.h>
  14
  15 #include <xpc/xpc.h>
  16
  17 __BEGIN_DECLS
  18
  19 /* See: https://tools.ietf.org/html/rfc8446#section-4.2.7 */
  20 typedef CF_ENUM(uint16_t, tls_key_exchange_group_t) {
  21     tls_key_exchange_group_Secp256r1 = 0x0017,
  22     tls_key_exchange_group_Secp384r1 = 0x0018,
  23     tls_key_exchange_group_Secp521r1 = 0x0019,
  24     tls_key_exchange_group_X25519 = 0x001D,
  25     tls_key_exchange_group_X448 = 0x001E,
  26     tls_key_exchange_group_FFDHE2048 = 0x0100,
  27     tls_key_exchange_group_FFDHE3072 = 0x0101,
  28     tls_key_exchange_group_FFDHE4096 = 0x0102,
  29     tls_key_exchange_group_FFDHE6144 = 0x0103,
  30     tls_key_exchange_group_FFDHE8192 = 0x0104,
  31 };
  32
  33 /*
  34  * Convenience key exchange groups that collate group identifiers of
  35  * comparable security into a single alias.
  36  */
  37 typedef CF_ENUM(uint16_t, tls_key_exchange_group_set_t) {
  38     tls_key_exchange_group_set_default,
  39     tls_key_exchange_group_set_compatibility,
  40     tls_key_exchange_group_set_legacy,
  41 };
  42
  43 SEC_ASSUME_NONNULL_BEGIN
  44
  45 #ifndef SEC_OBJECT_IMPL
  46 SEC_OBJECT_DECL(sec_array);
  47 #endif // !SEC_OBJECT_IMPL
  48
  49 struct sec_protocol_options_content;
  50 typedef struct sec_protocol_options_content *sec_protocol_options_content_t;
  51
  52 struct sec_protocol_metadata_content;
  53 typedef struct sec_protocol_metadata_content *sec_protocol_metadata_content_t;
  54
  55 typedef void (^sec_protocol_tls_handshake_message_handler_t)(uint8_t type, dispatch_data_t message);
  56
  57 typedef dispatch_data_t _Nullable (*sec_protocol_metadata_exporter)(void * handle, size_t label_len, const char *label,
  58                                                           size_t context_len, const uint8_t * __nullable context, size_t exporter_len);
  59
  60 typedef dispatch_data_t _Nullable (*sec_protocol_metadata_session_exporter)(void *handle);
  61
  62 typedef bool (^sec_access_block_t)(void *handle);
  63
  64 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  65 SEC_RETURNS_RETAINED sec_array_t
  66 sec_array_create(void);
  67
  68 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  69 void
  70 sec_array_append(sec_array_t array, sec_object_t object);
  71
  72 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  73 size_t
  74 sec_array_get_count(sec_array_t array);
  75
  76 typedef bool (^sec_array_applier_t) (size_t index, sec_object_t object);
  77
  78 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  79 bool
  80 sec_array_apply(sec_array_t array, sec_array_applier_t applier);
  81
  82 /*!
  83  * @function sec_protocol_options_access_handle
  84  *
  85  * @abstract
  86  *      Access the internal handle of a `sec_protocol_options` object.
  87  *
  88  * @param options
  89  *      A `sec_protocol_options_t` instance.
  90  *
  91  * @param access_block
  92  *      A block to invoke with access to the internal handle.
  93  *
  94  * @return True if the access was successful
  95  */
  96 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  97 bool
  98 sec_protocol_options_access_handle(sec_protocol_options_t options, sec_access_block_t access_block);
  99
 100 /*!
 101  * @function sec_protocol_options_contents_are_equal
 102  *
 103  * @abstract
 104  *      Compare two `sec_protocol_options_content_t` structs for equality.
 105  *
 106  * @param contentA
 107  *      A `sec_protocol_options_t` instance.
 108  *
 109  * @param contentB
 110  *      A `sec_protocol_options_t` instance.
 111  *
 112  * @return True if equal, and false otherwise.
 113  */
 114 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 115 bool
 116 sec_protocol_options_contents_are_equal(sec_protocol_options_content_t contentA, sec_protocol_options_content_t contentB);
 117
 118 /*!
 119  * @function sec_protocol_options_set_tls_early_data_enabled
 120  *
 121  * @abstract
 122  *      Enable or disable early (0-RTT) data for TLS.
 123  *
 124  * @param options
 125  *      A `sec_protocol_options_t` instance.
 126  *
 127  * @param early_data_enabled
 128  *      Flag to enable or disable early (0-RTT) data.
 129  */
 130 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 131 void
 132 sec_protocol_options_set_tls_early_data_enabled(sec_protocol_options_t options, bool early_data_enabled);
 133
 134 /*!
 135  * @function sec_protocol_options_set_tls_sni_disabled
 136  *
 137  * @abstract
 138  *      Enable or disable the TLS SNI extension. This defaults to `false`.
 139  *
 140  * @param options
 141  *      A `sec_protocol_options_t` instance.
 142  *
 143  * @param sni_disabled
 144  *      Flag to enable or disable use of the TLS SNI extension.
 145  */
 146 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 147 void
 148 sec_protocol_options_set_tls_sni_disabled(sec_protocol_options_t options, bool sni_disabled);
 149
 150 /*!
 151  * @function sec_protocol_options_set_enforce_ev
 152  *
 153  * @abstract
 154  *      Enable or disable EV enforcement.
 155  *
 156  * @param options
 157  *      A `sec_protocol_options_t` instance.
 158  *
 159  * @param enforce_ev
 160  *      Flag to determine if EV is enforced.
 161  */
 162 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 163 void
 164 sec_protocol_options_set_enforce_ev(sec_protocol_options_t options, bool enforce_ev);
 165
 166 /*!
 167  * @block sec_protocol_session_update_t
 168  *
 169  * @abstract
 170  *      Block to be invoked when a new session is established and ready.
 171  *
 172  * @param metadata
 173  *      A `sec_protocol_metadata_t` instance.
 174  */
 175 typedef void (^sec_protocol_session_update_t)(sec_protocol_metadata_t metadata);
 176
 177 /*!
 178  * @function sec_protocol_options_set_session_update_block
 179  *
 180  * @abstract
 181  *      Set the session update block. This is fired whenever a new session is
 182  *      created an inserted into the cache.
 183  *
 184  * @param options
 185  *      A `sec_protocol_options_t` instance.
 186  *
 187  * @param update_block
 188  *      A `sec_protocol_session_update_t` instance.
 189  *
 190  * @params update_queue
 191  *      A `dispatch_queue_t` on which the update block should be called.
 192  */
 193 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 194 void
 195 sec_protocol_options_set_session_update_block(sec_protocol_options_t options,
 196                                               sec_protocol_session_update_t update_block,
 197                                               dispatch_queue_t update_queue);
 198
 199 /*!
 200  * @function sec_protocol_options_set_session_state
 201  *
 202  * @abstract
 203  *      Set the session state using a serialized session blob.
 204  *
 205  *      If the session state is invalid or otherwise corrupt, the state is ignored and
 206  *      the connection will proceed as if no state was provided.
 207  *
 208  * @param options
 209  *      A `sec_protocol_options_t` instance.
 210  *
 211  * @param session_state
 212  *      A `dispatch_data_t` carrying serialized session state from a previous.
 213  */
 214 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 215 void
 216 sec_protocol_options_set_session_state(sec_protocol_options_t options, dispatch_data_t session_state);
 217
 218 /*!
 219  * @function sec_protocol_options_set_quic_transport_parameters
 220  *
 221  * @abstract
 222  *      Set the opaque QUIC transport parameters to be used for this connection.
 223  *
 224  * @param options
 225  *      A `sec_protocol_options_t` instance.
 226  *
 227  * @param transport_parameters
 228  *      A `dispatch_data_t` carrying opqaue QUIC transport parameters.
 229  */
 230 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 231 void
 232 sec_protocol_options_set_quic_transport_parameters(sec_protocol_options_t options, dispatch_data_t transport_parameters);
 233
 234 /*!
 235  * @enum sec_protocol_transport_t
 236  *
 237  * @abstract An enumeration of the different transport protocols that can have specific security options.
 238  */
 239 typedef enum {
 240     sec_protocol_transport_any = 0,
 241     sec_protocol_transport_tcp,
 242     sec_protocol_transport_quic,
 243 } sec_protocol_transport_t;
 244
 245 #define SEC_PROTOCOL_HAS_TRANSPORT_SPECIFIC_ALPN 1
 246
 247 /*!
 248  * @function sec_protocol_options_add_transport_specific_application_protocol
 249  *
 250  * @abstract
 251  *      Add an application protocol supported by clients of this protocol instance, specific
 252  *      to a transport protocol.
 253  *
 254  * @param options
 255  *      A `sec_protocol_options_t` instance.
 256  *
 257  * @param application_protocol
 258  *      A NULL-terminated string defining the application protocol.
 259  *
 260  * @param specific_transport
 261  *      A specific transport to which to bind the application protocol.
 262  */
 263 API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 264 void
 265 sec_protocol_options_add_transport_specific_application_protocol(sec_protocol_options_t options, const char *application_protocol, sec_protocol_transport_t specific_transport);
 266
 267 /*!
 268  * @function sec_protocol_options_copy_transport_specific_application_protocol
 269  *
 270  * @abstract
 271  *      Return the application protocols configured by clients of this protocol instance, specific
 272  *      to a transport protocol if applicable.
 273  *
 274  * @param options
 275  *      A `sec_protocol_options_t` instance.
 276  *
 277  * @param specific_transport
 278  *      A specific transport to which to bind the application protocol.
 279  *
 280  * @return An `xpc_object_t` instance carrying an array of application protocol strings, or nil.
 281  */
 282 #define SEC_PROTOCOL_HAS_TRANSPORT_SPECIFIC_ALPN_GETTER 1 /* rdar://problem/63987477 */
 283 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 284 SEC_RETURNS_RETAINED __nullable xpc_object_t
 285 sec_protocol_options_copy_transport_specific_application_protocol(sec_protocol_options_t options, sec_protocol_transport_t specific_transport);
 286
 287 /*!
 288  * @enum sec_protocol_tls_encryption_level_t
 289  *
 290  * @abstract An enumeration of the different TLS encryption levels.
 291  */
 292 typedef enum {
 293     sec_protocol_tls_encryption_level_initial = 0,
 294     sec_protocol_tls_encryption_level_early_data,
 295     sec_protocol_tls_encryption_level_handshake,
 296     sec_protocol_tls_encryption_level_application,
 297 } sec_protocol_tls_encryption_level_t;
 298
 299 /*!
 300  * @block sec_protocol_tls_encryption_secret_update_t
 301  *
 302  * @abstract
 303  *      Block to be invoked when a new session is established and ready.
 304  *
 305  * @param level
 306  *      The `sec_protocol_tls_encryption_level_t` for this secret.
 307  *
 308  * @param is_write
 309  *      True if this secret is for writing, and false if it's for reading.
 310  *
 311  * @param secret
 312  *      Secret wrapped in a `dispatch_data_t`
 313  */
 314 typedef void (^sec_protocol_tls_encryption_secret_update_t)(sec_protocol_tls_encryption_level_t level, bool is_write, dispatch_data_t secret);
 315
 316 /*!
 317  * @function sec_protocol_options_set_tls_encryption_secret_update_block
 318  *
 319  * @abstract
 320  *      Set the TLS secret update block. This is fired whenever a new TLS secret is
 321  *      available.
 322  *
 323  * @param options
 324  *      A `sec_protocol_options_t` instance.
 325  *
 326  * @param update_block
 327  *      A `sec_protocol_tls_encryption_secret_update_t` instance.
 328  *
 329  * @params update_queue
 330  *      A `dispatch_queue_t` on which the update block should be called.
 331  */
 332 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 333 void
 334 sec_protocol_options_set_tls_encryption_secret_update_block(sec_protocol_options_t options,
 335                                                             sec_protocol_tls_encryption_secret_update_t update_block,
 336                                                             dispatch_queue_t update_queue);
 337
 338 /*!
 339  * @block sec_protocol_tls_encryption_level_update_t
 340  *
 341  * @abstract
 342  *      Block to be invoked when the encryption level is updated.
 343  *
 344  * @param level
 345  *      The new `sec_protocol_tls_encryption_level_t`.
 346  *
 347  * @param is_write
 348  *      True if this is a write level and false if it's a read.
 349  *
 350  */
 351 typedef void (^sec_protocol_tls_encryption_level_update_t)(sec_protocol_tls_encryption_level_t level, bool is_write);
 352
 353 /*!
 354  * @function sec_protocol_options_set_tls_encryption_level_update_block
 355  *
 356  * @abstract
 357  *      Set the TLS encryption level update block. It is invoked whenever the encryption level is updated.
 358  *
 359  * @param options
 360  *      A `sec_protocol_options_t` instance.
 361  *
 362  * @param update_block
 363  *      A `sec_protocol_tls_encryption_level_update_t` instance.
 364  *
 365  * @params update_queue
 366  *      A `dispatch_queue_t` on which the update block should be called.
 367  */
 368 #define SEC_PROTOCOL_HAS_TLS_ENCRYPTION_LEVEL_UPDATE_BLOCK 1 /* rdar://problem/63986462 */
 369 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 370 void
 371 sec_protocol_options_set_tls_encryption_level_update_block(sec_protocol_options_t options,
 372                                                             sec_protocol_tls_encryption_level_update_t update_block,
 373                                                             dispatch_queue_t update_queue);
 374
 375 /*!
 376  * @block sec_protocol_private_key_complete_t
 377  *
 378  * @abstract
 379  *      Block to be invoked when a private key operation is complete.
 380  *
 381  * @param result
 382  *      A `dispatch_data_t` object containing the private key result.
 383  */
 384 typedef void (^sec_protocol_private_key_complete_t)(dispatch_data_t result);
 385
 386 /*!
 387  * @block sec_protocol_private_key_sign_t
 388  *
 389  * @abstract
 390  *      Block to be invoked when a private key signature operation is required.
 391  *
 392  * @param algorithm
 393  *      The signature algorithm to use for the signature.
 394  *
 395  * @param input
 396  *      The input to be signed.
 397  *
 398  * @param complete
 399  *      The `sec_protocol_private_key_complete_t` block to invoke when the operation is complete.
 400  */
 401 typedef void (^sec_protocol_private_key_sign_t)(uint16_t algorithm, dispatch_data_t input, sec_protocol_private_key_complete_t complete);
 402
 403 /*!
 404  * @block sec_protocol_private_key_decrypt_t
 405  *
 406  * @abstract
 407  *      Block to be invoked when a private key decryption operation is required.
 408  *
 409  * @param input
 410  *      The input to be decrypted.
 411  *
 412  * @param complete
 413  *      The `sec_protocol_private_key_complete_t` block to invoke when the operation is complete.
 414  */
 415 typedef void (^sec_protocol_private_key_decrypt_t)(dispatch_data_t input, sec_protocol_private_key_complete_t complete);
 416
 417 /*!
 418  * @block sec_protocol_options_set_private_key_blocks
 419  *
 420  * @abstract
 421  *      Set the private key operation blocks for this connection.
 422  *
 423  * @param options
 424  *      A `sec_protocol_options_t` instance.
 425  *
 426  * @param sign_block
 427  *      A `sec_protocol_private_key_sign_t` block.
 428  *
 429  * @param decrypt_block
 430  *      A `sec_protocol_private_key_decrypt_t` block.
 431  *
 432  * @param operation_queue
 433  *      The `dispatch_queue_t` queue on which each private key operation is invoked.
 434  */
 435 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 436 void
 437 sec_protocol_options_set_private_key_blocks(sec_protocol_options_t options,
 438                                             sec_protocol_private_key_sign_t sign_block,
 439                                             sec_protocol_private_key_decrypt_t decrypt_block,
 440                                             dispatch_queue_t operation_queue);
 441
 442 /*!
 443  * @block sec_protocol_options_set_local_certificates
 444  *
 445  * @abstract
 446  *      Set the local certificates to be used for this protocol instance.
 447  *
 448  * @param options
 449  *      A `sec_protocol_options_t` instance.
 450  *
 451  * @param certificates
 452  *      A `sec_array_t` instance of `sec_certifiate_t` instances.
 453  */
 454 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 455 void
 456 sec_protocol_options_set_local_certificates(sec_protocol_options_t options, sec_array_t certificates);
 457
 458 /*!
 459  * @block sec_protocol_options_set_tls_certificate_compression_enabled
 460  *
 461  * @abstract
 462  *      Enable or disable TLS 1.3 certificate compression.
 463  *
 464  *      See: https://tools.ietf.org/html/draft-ietf-tls-certificate-compression-04
 465  *
 466  * @param options
 467  *      A `sec_protocol_options_t` instance.
 468  *
 469  * @param certificate_compression_enabled
 470  *      Flag to determine if certificate compression is enabled.
 471  */
 472 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 473 void
 474 sec_protocol_options_set_tls_certificate_compression_enabled(sec_protocol_options_t options, bool certificate_compression_enabled);
 475
 476 /*!
 477  * @block sec_protocol_options_tls_handshake_message_callback
 478  *
 479  * @abstract
 480  *      Set a callback to process each TLS handshake message. This function may be invoked at any point during
 481  *      the TLS handshake, if at all. Clients MUST NOT rely on any behavior aspect of this function as they
 482  *      risk breaking.
 483  *
 484  * @param options
 485  *      A `sec_protocol_options_t` instance.
 486  *
 487  * @param handler
 488  *      A `sec_protocol_tls_handshake_message_handler_t`.
 489  *
 490  * @param queue
 491  *      The queue upon which to invoke the callback.
 492  */
 493 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 494 void
 495 sec_protocol_options_tls_handshake_message_callback(sec_protocol_options_t options, sec_protocol_tls_handshake_message_handler_t handler, dispatch_queue_t queue);
 496
 497 /*!
 498  * @block sec_protocol_options_append_tls_key_exchange_group
 499  *
 500  * @abstract
 501  *      Append a TLS key exchange group to the set of enabled groups.
 502  *
 503  * @param options
 504  *      A `sec_protocol_options_t` instance.
 505  *
 506  * @param group
 507  *      A `tls_key_exchange_group_t` value.
 508  */
 509 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 510 void
 511 sec_protocol_options_append_tls_key_exchange_group(sec_protocol_options_t options, tls_key_exchange_group_t group);
 512
 513 /*!
 514  * @block sec_protocol_options_add_tls_key_exchange_group
 515  *
 516  * @abstract
 517  *      Add a TLS key exchange group to the set of enabled groups.
 518  *
 519  * @param options
 520  *      A `sec_protocol_options_t` instance.
 521  *
 522  * @param group
 523  *      A SSLKeyExchangeGroup value.
 524  */
 525 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 526 void
 527 sec_protocol_options_add_tls_key_exchange_group(sec_protocol_options_t options, SSLKeyExchangeGroup group);
 528
 529 /*!
 530  * @block sec_protocol_options_append_tls_key_exchange_group_set
 531  *
 532  * @abstract
 533  *      Append a TLS key exchange group set to the set of enabled groups.
 534  *
 535  * @param options
 536  *      A `sec_protocol_options_t` instance.
 537  *
 538  * @param set
 539  *      A `tls_key_exchange_group_set_t` value.
 540  */
 541 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 542 void
 543 sec_protocol_options_append_tls_key_exchange_group_set(sec_protocol_options_t options, tls_key_exchange_group_set_t set);
 544
 545 /*!
 546  * @block sec_protocol_options_tls_key_exchange_group_set
 547  *
 548  * @abstract
 549  *      Add a TLS key exchange group set to the set of enabled groups.
 550  *
 551  * @param options
 552  *      A `sec_protocol_options_t` instance.
 553  *
 554  * @param set
 555  *      A SSLKeyExchangeGroupSet value.
 556  */
 557 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 558 void
 559 sec_protocol_options_add_tls_key_exchange_group_set(sec_protocol_options_t options, SSLKeyExchangeGroupSet set);
 560
 561 /*!
 562  * @function sec_protocol_options_set_eddsa_enabled
 563  *
 564  * @abstract
 565  *      Enable EDDSA support (for TLS 1.3).
 566  *
 567  * @param options
 568  *      A `sec_protocol_options_t` instance.
 569  *
 570  * @param eddsa_enabled
 571  *      Flag to enable EDDSA.
 572  */
 573 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 574 void
 575 sec_protocol_options_set_eddsa_enabled(sec_protocol_options_t options, bool eddsa_enabled);
 576
 577 /*!
 578  * @function sec_protocol_options_set_tls_delegated_credentials_enabled
 579  *
 580  * @abstract
 581  *      Enable TLS delegated credentials support. See https://tools.ietf.org/html/draft-ietf-tls-subcerts-02.
 582  *
 583  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 584  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 585  *
 586  * @param options
 587  *      A `sec_protocol_options_t` instance.
 588  *
 589  * @param tls_delegated_credentials_enabled
 590  *      Flag to enable TLS delegated credentials.
 591  */
 592 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 593 void
 594 sec_protocol_options_set_tls_delegated_credentials_enabled(sec_protocol_options_t options, bool tls_delegated_credentials_enabled);
 595
 596 /*!
 597  * @function sec_protocol_options_set_tls_ticket_request_count
 598  *
 599  * @abstract
 600  *      Enable TLS ticket request support, and specify the count of tickets. Ticket support
 601  *      must also be explicitly enabled by `sec_protocol_options_set_tls_tickets_enabled`.
 602  *
 603  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 604  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 605  *
 606  * @param options
 607  *      A `sec_protocol_options_t` instance.
 608  *
 609  * @param tls_ticket_request_count
 610  *      Set the amount of tickets to request from the server.
 611  */
 612 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 613 void
 614 sec_protocol_options_set_tls_ticket_request_count(sec_protocol_options_t options, uint8_t tls_ticket_request_count);
 615
 616 /*!
 617  * @function sec_protocol_options_set_tls_grease_enabled
 618  *
 619  * @abstract
 620  *      Enable TLS GREASE support. See https://tools.ietf.org/html/draft-ietf-tls-grease-02.
 621  *
 622  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 623  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 624  *
 625  * @param options
 626  *      A `sec_protocol_options_t` instance.
 627  *
 628  * @param tls_grease_enabled
 629  *      Flag to enable TLS GREASE.
 630  */
 631 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 632 void
 633 sec_protocol_options_set_tls_grease_enabled(sec_protocol_options_t options, bool tls_grease_enabled);
 634
 635 /*!
 636  * @function sec_protocol_options_set_allow_unknown_alpn_protos
 637  *
 638  * @abstract
 639  *      Configure clients to accept server ALPN values they did not advertise.
 640  *
 641  * @param options
 642  *      A `sec_protocol_options_t` instance.
 643  *
 644  * @param allow_unknown_alpn_protos
 645  *      Flag to enable or disable the use of unknown ALPN values.
 646  */
 647 #define SEC_PROTOCOL_HAS_ALLOW_UNKNOWN_ALPN_PROTOS_SETTER 1 /* rdar://problem/64449512 */
 648 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 649 void
 650 sec_protocol_options_set_allow_unknown_alpn_protos(sec_protocol_options_t options, bool allow_unknown_alpn_protos);
 651
 652 /*!
 653  * @function sec_protocol_options_set_experiment_identifier
 654  *
 655  * @abstract
 656  *      Set the SecExperiment identifier for a given connection.
 657  *
 658  *      Note: this SPI is meant to be called by libnetcore. It should not be called in any other circumstances.
 659  *
 660  * @param options
 661  *      A `sec_protocol_options_t` instance.
 662  *
 663  * @param experiment_identifier
 664  *      The identifier for a secure connection experiment.
 665  */
 666 #define SEC_PROTOCOL_HAS_EXPERIMENT_IDENTIFIER 1
 667 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 668 void
 669 sec_protocol_options_set_experiment_identifier(sec_protocol_options_t options, const char *experiment_identifier);
 670
 671 /*!
 672  * @function sec_protocol_options_set_connection_id
 673  *
 674  * @abstract
 675  *      Set the explciit connection identifier. If not set, one will be populated internally.
 676  *
 677  * @param options
 678  *      A `sec_protocol_options_t` instance.
 679  *
 680  * @param connection_id
 681  *      The `uuid_t`` connection identifier.
 682  */
 683 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 684 void
 685 sec_protocol_options_set_connection_id(sec_protocol_options_t options, uuid_t _Nonnull connection_id);
 686
 687 /*!
 688  * @function sec_protocol_options_create_config
 689  *
 690  * @abstract
 691  *      Create a `xpc_object_t` instance carrying a configuration for the given `sec_protocol_options_t` instance.
 692  *
 693  * @param options
 694  *      A `sec_protocol_options_t` instance.
 695  *
 696  * @return A `xpc_object_t` instance carrying a configuration, or nil on failure.
 697  */
 698 #define SEC_PROTOCOL_HAS_EXPERIMENT_HOOKS 1
 699 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 700 SEC_RETURNS_RETAINED __nullable xpc_object_t
 701 sec_protocol_options_create_config(sec_protocol_options_t options);
 702
 703 /*!
 704  * @function sec_protocol_options_matches_config
 705  *
 706  * @abstract
 707  *      Determine if a `sec_protocol_options_t` instance matches a given configuration.
 708  *
 709  * @param options
 710  *      A `sec_protocol_options_t` instance.
 711  *
 712  * @param config
 713  *      A `xpc_object_t` instance carrying a SecExperiment config.
 714  *
 715  * @return True if the parameters in `config` match that of `options`, and false otherwise.
 716  */
 717 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 718 bool
 719 sec_protocol_options_matches_config(sec_protocol_options_t options, xpc_object_t config);
 720
 721 /*!
 722  * @function sec_protocol_options_apply_config
 723  *
 724  * @abstract
 725  *      Transform the given `sec_protocol_options_t` instance using the provided config.
 726  *
 727  * @param options
 728  *      A `sec_protocol_options_t` instance.
 729  *
 730  * @param config
 731  *      A `xpc_object_t` instance carrying a SecExperiment config.
 732  *
 733  * @return True if the options were applied successfully, and false otherwise.
 734  */
 735 bool
 736 sec_protocol_options_apply_config(sec_protocol_options_t options, xpc_object_t config);
 737
 738 /*!
 739  * @function sec_protocol_metadata_get_tls_negotiated_group
 740  *
 741  * @abstract
 742  *      Get a human readable representation of the negotiated key exchange group.
 743  *
 744  * @param metadata
 745  *      A `sec_protocol_metadata_t` instance.
 746  *
 747  * @return A string representation of the negotiated group, or NULL if it does not exist.
 748  */
 749 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 750 const char * __nullable
 751 sec_protocol_metadata_get_tls_negotiated_group(sec_protocol_metadata_t metadata);
 752
 753 /*!
 754  * @function sec_protocol_metadata_get_experiment_identifier
 755  *
 756  * @abstract
 757  *      Get the SecExperiment identifier for a given connection.
 758  *
 759  *      Note: this SPI is meant to be called by libnetcore. It should not be called in any other circumstances.
 760  *
 761  * @param metadata
 762  *      A `sec_protocol_metadata_t` instance.
 763  *
 764  * @return The identifier for a secure connection experiment, or NULL if none was specified.
 765  */
 766 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 767 const char * __nullable
 768 sec_protocol_metadata_get_experiment_identifier(sec_protocol_metadata_t metadata);
 769
 770 /*!
 771  * @function sec_protocol_metadata_copy_connection_id
 772  *
 773  * @abstract
 774  *      Copy the secure connection identifier.
 775  *
 776  * @param metadata
 777  *      A `sec_protocol_metadata_t` instance.
 778  *
 779  * @param output_uuid
 780  *      A `uuid_t` into which the connection identifier is written.
 781  */
 782 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 783 void
 784 sec_protocol_metadata_copy_connection_id(sec_protocol_metadata_t metadata, uuid_t _Nonnull output_uuid);
 785
 786 /*!
 787  * @function sec_protocol_metadata_get_tls_false_start_used
 788  *
 789  * @abstract
 790  *      Determine if False Start was used.
 791  *
 792  * @param metadata
 793  *      A `sec_protocol_metadata_t` instance.
 794  *
 795  * @return True if False Start was used, and false otherwise.
 796  */
 797 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 798 bool
 799 sec_protocol_metadata_get_tls_false_start_used(sec_protocol_metadata_t metadata);
 800
 801 /*!
 802  * @function sec_protocol_metadata_get_ticket_offered
 803  *
 804  * @abstract
 805  *      Determine if a ticket was offered for session resumption.
 806  *
 807  * @param metadata
 808  *      A `sec_protocol_metadata_t` instance.
 809  *
 810  * @return True if a ticket was offered for resumption, and false otherwise.
 811  */
 812 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 813 bool
 814 sec_protocol_metadata_get_ticket_offered(sec_protocol_metadata_t metadata);
 815
 816 /*!
 817  * @function sec_protocol_metadata_get_ticket_received
 818  *
 819  * @abstract
 820  *      Determine if a ticket was received upon completing the new connection.
 821  *
 822  * @param metadata
 823  *      A `sec_protocol_metadata_t` instance.
 824  *
 825  * @return True if a ticket was received from the peer (server), and false otherwise.
 826  */
 827 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 828 bool
 829 sec_protocol_metadata_get_ticket_received(sec_protocol_metadata_t metadata);
 830
 831 /*!
 832  * @function sec_protocol_metadata_get_session_resumed
 833  *
 834  * @abstract
 835  *      Determine if this new connection was a session resumption.
 836  *
 837  * @param metadata
 838  *      A `sec_protocol_metadata_t` instance.
 839  *
 840  * @return True if this new connection was resumed, and false otherwise.
 841  */
 842 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 843 bool
 844 sec_protocol_metadata_get_session_resumed(sec_protocol_metadata_t metadata);
 845
 846 /*!
 847  * @function sec_protocol_metadata_get_session_renewed
 848  *
 849  * @abstract
 850  *      Determine if this resumed connection was renewed with a new ticket.
 851  *
 852  * @param metadata
 853  *      A `sec_protocol_metadata_t` instance.
 854  *
 855  * @return True if this resumed connection was renewed with a new ticket, and false otherwise.
 856  */
 857 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 858 bool
 859 sec_protocol_metadata_get_session_renewed(sec_protocol_metadata_t metadata);
 860
 861 /*!
 862  * @function sec_protocol_metadata_get_connection_strength
 863  *
 864  * @abstract
 865  *      Determine the TLS connection strength.
 866  *
 867  * @param metadata
 868  *      A `sec_protocol_metadata_t` instance.
 869  *
 870  * @return An `SSLConnectionStrength` enum.
 871  */
 872 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 873 SSLConnectionStrength
 874 sec_protocol_metadata_get_connection_strength(sec_protocol_metadata_t metadata);
 875
 876 /*!
 877  * @function sec_protocol_metadata_copy_serialized_session
 878  *
 879  * @abstract
 880  *      Copy a serialized representation of a session.
 881  *
 882  * @param metadata
 883  *      A `sec_protocol_metadata_t` instance.
 884  *
 885  * @return A `dispatch_data_t` object containing a serialized session.
 886  */
 887 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 888 SEC_RETURNS_RETAINED __nullable dispatch_data_t
 889 sec_protocol_metadata_copy_serialized_session(sec_protocol_metadata_t metadata);
 890
 891 /*!
 892  * @function sec_protocol_metadata_access_handle
 893  *
 894  * @abstract
 895  *      Access the internal handle of a `sec_protocol_metadata` object.
 896  *
 897  * @param metadata
 898  *      A `sec_protocol_metadata_t` instance.
 899  *
 900  * @param access_block
 901  *      A block to invoke with access to the internal handle.
 902  *
 903  * @return True if the access was successful
 904  */
 905 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 906 bool
 907 sec_protocol_metadata_access_handle(sec_protocol_metadata_t metadata, sec_access_block_t access_block);
 908
 909 /*!
 910  * @function sec_protocol_metadata_serialize_with_options
 911  *
 912  * @abstract
 913  *      Serialize a `sec_protocol_metadata_t` to an `xpc_object_t` dictionary using information
 914  *      contained in the `metadata` and `options` objects.
 915  *
 916  * @param metadata
 917  *      A `sec_protocol_metadata_t` instance.
 918  *
 919  * @return A xpc_object_t carrying the serialized metadata.
 920  */
 921 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 922 SEC_RETURNS_RETAINED __nullable xpc_object_t
 923 sec_protocol_metadata_serialize_with_options(sec_protocol_metadata_t metadata, sec_protocol_options_t options);
 924
 925 /*!
 926  * @function sec_protocol_metadata_get_tls_certificate_compression_used
 927  *
 928  * @abstract
 929  *      Determine if certificate compression was used for a given connection.
 930  *
 931  *      See: https://tools.ietf.org/html/draft-ietf-tls-certificate-compression-04
 932  *
 933  * @param metadata
 934  *      A `sec_protocol_metadata_t` instance.
 935  *
 936  * @return True if certificate compression was negotiated and used.
 937  */
 938 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 939 bool
 940 sec_protocol_metadata_get_tls_certificate_compression_used(sec_protocol_metadata_t metadata);
 941
 942 /*!
 943  * @function sec_protocol_metadata_get_tls_certificate_compression_algorithm
 944  *
 945  * @abstract
 946  *      Return the certificate compression algorithm used. This will return 0
 947  *      if `sec_protocol_metadata_get_tls_certificate_compression_used` is false.
 948  *
 949  *      See: https://tools.ietf.org/html/draft-ietf-tls-certificate-compression-04
 950  *
 951  * @param metadata
 952  *      A `sec_protocol_metadata_t` instance.
 953  *
 954  * @return IANA codepoint for the certificate compression algorithm.
 955  */
 956 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 957 uint16_t
 958 sec_protocol_metadata_get_tls_certificate_compression_algorithm(sec_protocol_metadata_t metadata);
 959
 960 /*!
 961  * @function sec_protocol_metadata_copy_quic_transport_parameters
 962  *
 963  * @abstract
 964  *      Copy the peer's QUIC transport parameters.
 965  *
 966  * @param metadata
 967  *      A `sec_protocol_metadata_t` instance.
 968  *
 969  * @return A dispatch_data_t carrying the connection peer's opaque QUIC tranport parameters.
 970  */
 971 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 972 SEC_RETURNS_RETAINED __nullable dispatch_data_t
 973 sec_protocol_metadata_copy_quic_transport_parameters(sec_protocol_metadata_t metadata);
 974
 975 /*!
 976  * @function sec_protocol_metadata_get_handshake_time_ms
 977  *
 978  * @abstract
 979  *      Get the TLS handshake time in miliseconds. The result is undefined
 980  *      for connections not yet connected.
 981  *
 982  * @param metadata
 983  *      A `sec_protocol_metadata_t` instance.
 984  *
 985  * @return A millisecond measurement of the TLS handshake time from start to finish.
 986  */
 987 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 988 #define SEC_PROTOCOL_HAS_METRIC_SPI_V1
 989 uint64_t
 990 sec_protocol_metadata_get_handshake_time_ms(sec_protocol_metadata_t metadata);
 991
 992 /*!
 993  * @function sec_protocol_metadata_get_handshake_rtt
 994  *
 995  * @abstract
 996  *      Get the observed TLS handshake RTT. This function must only be
 997  *      called after the connection is established. Calling this before
 998  *      the connection completes will yields an undefined result.
 999  *
1000  *      This is computed as the average RTT across all 1-RTT exchanges.
1001  *      For TLS 1.3, this will be the time for the normal exchange. For prior
1002  *      versions, or TLS 1.3 with HRR, this will be the average RTT across
1003  *      multiple message flights.
1004  *
1005  * @param metadata
1006  *      A `sec_protocol_metadata_t` instance.
1007  *
1008  * @return A millisecond measurement of the TLS handshake RTT.
1009  */
1010 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1011 uint64_t
1012 sec_protocol_metadata_get_handshake_rtt(sec_protocol_metadata_t metadata);
1013
1014 /*!
1015  * @function sec_protocol_metadata_get_handshake_byte_count
1016  *
1017  * @abstract
1018  *      Get the total number of bytes sent and received for the handshake.
1019  *
1020  * @param metadata
1021  *      A `sec_protocol_metadata_t` instance.
1022  *
1023  * @return Number of bytes sent and received for the handshake.
1024  */
1025 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1026 uint64_t
1027 sec_protocol_metadata_get_handshake_byte_count(sec_protocol_metadata_t metadata);
1028
1029 /*!
1030  * @function sec_protocol_metadata_get_handshake_sent_byte_count
1031  *
1032  * @abstract
1033  *      Get the total number of bytes sent for the handshake.
1034  *
1035  * @param metadata
1036  *      A `sec_protocol_metadata_t` instance.
1037  *
1038  * @return Number of bytes sent for the handshake.
1039  */
1040 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1041 uint64_t
1042 sec_protocol_metadata_get_handshake_sent_byte_count(sec_protocol_metadata_t metadata);
1043
1044 /*!
1045  * @function sec_protocol_metadata_get_handshake_received_byte_count
1046  *
1047  * @abstract
1048  *      Get the total number of bytes received for the handshake.
1049  *
1050  * @param metadata
1051  *      A `sec_protocol_metadata_t` instance.
1052  *
1053  * @return Number of bytes received for the handshake.
1054  */
1055 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1056 uint64_t
1057 sec_protocol_metadata_get_handshake_received_byte_count(sec_protocol_metadata_t metadata);
1058
1059 /*!
1060  * @function sec_protocol_metadata_get_handshake_read_stall_count
1061  *
1062  * @abstract
1063  *      Get the total number of read stalls during the handshake.
1064  *
1065  * @param metadata
1066  *      A `sec_protocol_metadata_t` instance.
1067  *
1068  * @return Number of read stalls.
1069  */
1070 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1071 size_t
1072 sec_protocol_metadata_get_handshake_read_stall_count(sec_protocol_metadata_t metadata);
1073
1074 /*!
1075  * @function sec_protocol_metadata_get_handshake_write_stall_count
1076  *
1077  * @abstract
1078  *      Get the total number of write stalls during the handshake.
1079  *
1080  * @param metadata
1081  *      A `sec_protocol_metadata_t` instance.
1082  *
1083  * @return Number of write stalls.
1084  */
1085 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1086 size_t
1087 sec_protocol_metadata_get_handshake_write_stall_count(sec_protocol_metadata_t metadata);
1088
1089 /*!
1090  * @function sec_protocol_metadata_get_handshake_async_call_count
1091  *
1092  * @abstract
1093  *      Get the total number of asynchronous callbacks invoked during the handshake.
1094  *
1095  * @param metadata
1096  *      A `sec_protocol_metadata_t` instance.
1097  *
1098  * @return Number of asynchronous callbacks.
1099  */
1100 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1101 size_t
1102 sec_protocol_metadata_get_handshake_async_call_count(sec_protocol_metadata_t metadata);
1103
1104 /*!
1105  * @function sec_protocol_metadata_copy_sec_trust
1106  *
1107  * @abstract
1108  *      Copy the `sec_trust_t` associated with a connection.
1109  *
1110  * @param metadata
1111  *      A `sec_protocol_metadata_t` instance.
1112  *
1113  * @return A `sec_trust_t` instance.
1114  */
1115 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1116 SEC_RETURNS_RETAINED __nullable sec_trust_t
1117 sec_protocol_metadata_copy_sec_trust(sec_protocol_metadata_t metadata);
1118
1119 /*!
1120  * @function sec_protocol_metadata_copy_sec_identity
1121  *
1122  * @abstract
1123  *      Copy the `sec_identity_t` associated with a connection.
1124  *
1125  * @param metadata
1126  *      A `sec_protocol_metadata_t` instance.
1127  *
1128  * @return A `sec_identity_t` instance.
1129  */
1130 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1131 SEC_RETURNS_RETAINED __nullable sec_identity_t
1132 sec_protocol_metadata_copy_sec_identity(sec_protocol_metadata_t metadata);
1133
1134 /*!
1135  * @function sec_protocol_metadata_access_sent_certificates
1136  *
1137  * @abstract
1138  *      Access the certificates which were sent to the peer on this connection.
1139  *
1140  * @param metadata
1141  *      A `sec_protocol_metadata_t` instance.
1142  *
1143  * @param handler
1144  *      A block to invoke one or more times with `sec_certificate_t` instances.
1145  *
1146  * @return Returns true if the peer certificates were accessible, false otherwise.
1147  */
1148 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1149 bool
1150 sec_protocol_metadata_access_sent_certificates(sec_protocol_metadata_t metadata,
1151                                                void (^handler)(sec_certificate_t certificate));
1152
1153 /*!
1154  * @function sec_protocol_metadata_get_tls_negotiated_group
1155  *
1156  * @abstract
1157  *      Get a human readable representation of the negotiated key exchange group.
1158  *
1159  * @param metadata
1160  *      A `sec_protocol_metadata_t` instance.
1161  *
1162  * @return A string representation of the negotiated group, or NULL if it does not exist.
1163  */
1164 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1165 const char * __nullable
1166 sec_protocol_metadata_get_tls_negotiated_group(sec_protocol_metadata_t metadata);
1167
1168 /*!
1169  * @function sec_protocol_configuration_copy_singleton
1170  *
1171  * @abstract
1172  *      Copy the per-process `sec_protocol_configuration_t` object.
1173  *
1174  * @return A non-nil `sec_protocol_configuration_t` instance.
1175  */
1176 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1177 SEC_RETURNS_RETAINED sec_protocol_configuration_t
1178 sec_protocol_configuration_copy_singleton(void);
1179
1180 #ifndef SEC_OBJECT_IMPL
1181 SEC_OBJECT_DECL(sec_protocol_configuration_builder);
1182 #endif // !SEC_OBJECT_IMPL
1183
1184 /*!
1185  * @function sec_protocol_configuration_builder_create
1186  *
1187  * @abstract
1188  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1189  */
1190 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1191 SEC_RETURNS_RETAINED sec_protocol_configuration_builder_t
1192 sec_protocol_configuration_builder_create(CFDictionaryRef dictionary, bool is_apple);
1193
1194 /*!
1195  * @function sec_protocol_configuration_create_with_builder
1196  *
1197  * @abstract
1198  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1199  */
1200 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1201 SEC_RETURNS_RETAINED __nullable sec_protocol_configuration_t
1202 sec_protocol_configuration_create_with_builder(sec_protocol_configuration_builder_t builder);
1203
1204 /*!
1205  * @block sec_protocol_output_handler_access_block_t
1206  *
1207  * @abstract
1208  *      Block to be invoked to obtain the output handler for a given encryption level.
1209  */
1210 typedef void *_Nullable(^sec_protocol_output_handler_access_block_t)(sec_protocol_tls_encryption_level_t level);
1211
1212 /*!
1213  * @function sec_protocol_options_set_output_handler_access_block
1214  *
1215  * @abstract
1216  *      Set a block used to access output handler instances identified by encryption level.
1217  */
1218 #define SEC_PROTOCOL_HAS_QUIC_OUTPUT_HANDLER_ACCESS_BLOCK 1
1219 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1220 void
1221 sec_protocol_options_set_output_handler_access_block(sec_protocol_options_t options,
1222                                                      sec_protocol_output_handler_access_block_t access_block);
1223
1224 /*!
1225  * @function sec_protocol_helper_ciphersuite_group_to_ciphersuite_list
1226  *
1227  * @abstract
1228  *      Return a pointer to a statically allocated list of ciphersuites corresponding to `group`.
1229  *
1230  * @param group
1231  *      A `tls_ciphersuite_group_t` instance.
1232  *
1233  * @param list_count
1234  *      Pointer to storage for the ciphersuite list length.
1235  *
1236  * @return Pointer to a statically allocated list, or NULL if an error occurred.
1237  */
1238 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1239 const tls_ciphersuite_t * __nullable
1240 sec_protocol_helper_ciphersuite_group_to_ciphersuite_list(tls_ciphersuite_group_t group, size_t *list_count);
1241
1242 typedef CF_ENUM(uint16_t, sec_protocol_block_length_padding_t) {
1243     SEC_PROTOCOL_BLOCK_LENGTH_PADDING_NONE = 0,
1244     SEC_PROTOCOL_BLOCK_LENGTH_PADDING_DEFAULT = 16,
1245 };
1246
1247 /*!
1248  * @function sec_protocol_options_set_tls_block_length_padding
1249  *
1250  * @abstract
1251  *      Pad TLS messages to a multiple of the specified block length. By default, padding is disabled.
1252  *
1253  * @param options
1254  *      A `sec_protocol_options_t` instance.
1255  *
1256  * @param block_length_padding
1257  *      A sec_protocol_block_length_padding_t variable specifying the block length padding. Setting the block length padding to 0 disables padding.
1258  *
1259  * @return True if the padding policy has been successfully set, false otherwise.
1260  */
1261 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1262 bool
1263 sec_protocol_options_set_tls_block_length_padding(sec_protocol_options_t options, sec_protocol_block_length_padding_t block_length_padding);
1264
1265 /*!
1266  * @function sec_protocol_helper_ciphersuite_group_contains_ciphersuite
1267  *
1268  * @abstract
1269  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1270  *
1271  * @param group
1272  *      A `tls_ciphersuite_group_t` instance.
1273  *
1274  * @param suite
1275  *      A `tls_ciphersuite_t` instance.
1276  *
1277  * @return True if the ciphersuite group contains the given ciphersuite, false otherwise.
1278 */
1279 API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
1280 bool
1281 sec_protocol_helper_ciphersuite_group_contains_ciphersuite(tls_ciphersuite_group_t group, tls_ciphersuite_t suite);
1282
1283 /*!
1284  * @function sec_protocol_helper_ciphersuite_minimum_TLS_version
1285  *
1286  * @abstract
1287  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1288  *
1289  * @param ciphersuite
1290  *      A `tls_ciphersuite_t` instance.
1291  *
1292  * @return The `tls_protocol_version_t` pertaining to the minimum TLS version designated for the given ciphersuite.
1293 */
1294 API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
1295 tls_protocol_version_t
1296 sec_protocol_helper_ciphersuite_minimum_TLS_version(tls_ciphersuite_t ciphersuite);
1297
1298 /*!
1299  * @function sec_protocol_helper_ciphersuite_maximum_TLS_version
1300  *
1301  * @abstract
1302  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1303  *
1304  * @param ciphersuite
1305  *      A `tls_ciphersuite_t` instance.
1306  *
1307  * @return The `tls_protocol_version_t` pertaining to the maximum TLS version designated for the given ciphersuite.
1308 */
1309 API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
1310 tls_protocol_version_t
1311 sec_protocol_helper_ciphersuite_maximum_TLS_version(tls_ciphersuite_t ciphersuite);
1312
1313 /*!
1314  * @function sec_protocol_helper_get_ciphersuite_name
1315  *
1316  * @abstract
1317  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1318  *
1319  * @param ciphersuite
1320  *      A `tls_ciphersuite_t` instance.
1321  *
1322  * @return A string representation of the given ciphersuite, or NULL if it does not exist.
1323 */
1324 API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
1325 const char * __nullable
1326 sec_protocol_helper_get_ciphersuite_name(tls_ciphersuite_t ciphersuite);
1327
1328 #define SEC_PROTOCOL_HAS_MULTI_PSK_SUPPORT 1
1329
1330 #define SEC_PROTOCOL_HAS_PEER_AUTHENTICATION_OPTIONAL 1
1331
1332 struct sec_protocol_options_content {
1333     SSLProtocol min_version;
1334     SSLProtocol max_version;
1335
1336     char *server_name;
1337     char *experiment_identifier;
1338     uuid_t connection_id;
1339     __nullable xpc_object_t ciphersuites;
1340     xpc_object_t application_protocols;
1341     sec_identity_t identity;
1342     sec_array_t certificates;
1343     xpc_object_t pre_shared_keys;
1344     dispatch_data_t psk_identity_hint;
1345     sec_protocol_key_update_t key_update_block;
1346     dispatch_queue_t key_update_queue;
1347     sec_protocol_challenge_t challenge_block;
1348     dispatch_queue_t challenge_queue;
1349     sec_protocol_verify_t verify_block;
1350     dispatch_queue_t verify_queue;
1351     dispatch_data_t quic_transport_parameters;
1352     sec_protocol_tls_encryption_secret_update_t tls_secret_update_block;
1353     dispatch_queue_t tls_secret_update_queue;
1354     sec_protocol_tls_encryption_level_update_t tls_encryption_level_update_block;
1355     dispatch_queue_t tls_encryption_level_update_queue;
1356     sec_protocol_session_update_t session_update_block;
1357     dispatch_queue_t session_update_queue;
1358     dispatch_data_t session_state;
1359     sec_protocol_private_key_sign_t private_key_sign_block;
1360     sec_protocol_private_key_decrypt_t private_key_decrypt_block;
1361     dispatch_queue_t private_key_queue;
1362     dispatch_data_t dh_params;
1363     xpc_object_t key_exchange_groups;
1364     sec_protocol_tls_handshake_message_handler_t handshake_message_callback;
1365     dispatch_queue_t handshake_message_callback_queue;
1366     sec_protocol_pre_shared_key_selection_t psk_selection_block;
1367     dispatch_queue_t psk_selection_queue;
1368
1369     // ATS minimums
1370     size_t minimum_rsa_key_size;
1371     size_t minimum_ecdsa_key_size;
1372     SecSignatureHashAlgorithm minimum_signature_algorithm;
1373
1374     // Non-boolean options
1375     uint8_t tls_ticket_request_count;
1376
1377     // QUIC-specific access block
1378     sec_protocol_output_handler_access_block_t output_handler_access_block;
1379
1380     // Boolean flags
1381     unsigned ats_required : 1;
1382     unsigned ats_minimum_tls_version_allowed : 1;
1383     unsigned ats_non_pfs_ciphersuite_allowed : 1;
1384     unsigned trusted_peer_certificate : 1;
1385     unsigned trusted_peer_certificate_override : 1;
1386     unsigned disable_sni : 1;
1387     unsigned disable_sni_override : 1;
1388     unsigned enable_fallback_attempt : 1;
1389     unsigned enable_fallback_attempt_override : 1;
1390     unsigned enable_false_start : 1;
1391     unsigned enable_false_start_override : 1;
1392     unsigned enable_tickets : 1;
1393     unsigned enable_tickets_override : 1;
1394     unsigned enable_sct : 1;
1395     unsigned enable_sct_override : 1;
1396     unsigned enable_ocsp : 1;
1397     unsigned enable_ocsp_override : 1;
1398     unsigned enforce_ev : 1;
1399     unsigned enforce_ev_override : 1;
1400     unsigned enable_resumption : 1;
1401     unsigned enable_resumption_override : 1;
1402     unsigned enable_renegotiation : 1;
1403     unsigned enable_renegotiation_override : 1;
1404     unsigned enable_early_data : 1;
1405     unsigned enable_early_data_override : 1;
1406     unsigned peer_authentication_required : 1;
1407     unsigned peer_authentication_optional : 1;
1408     unsigned peer_authentication_override : 1;
1409     unsigned certificate_compression_enabled : 1;
1410     unsigned eddsa_enabled : 1;
1411     unsigned tls_delegated_credentials_enabled : 1;
1412     unsigned tls_grease_enabled : 1;
1413     unsigned allow_unknown_alpn_protos : 1;
1414     unsigned allow_unknown_alpn_protos_override : 1;
1415
1416     sec_protocol_block_length_padding_t tls_block_length_padding;
1417 };
1418
1419 struct sec_protocol_metadata_content {
1420     void *exporter_context; // Opaque context for the exporter function
1421     sec_protocol_metadata_exporter exporter_function; // Exporter function pointer. This MUST be set by the metadata allocator.
1422     void *session_exporter_context; // Opaque context for the session exporter function
1423     sec_protocol_metadata_session_exporter session_exporter_function;
1424
1425     SSLProtocol negotiated_protocol_version;
1426     SSLCipherSuite negotiated_ciphersuite;
1427     const char *negotiated_protocol;
1428     const char *server_name;
1429     const char *experiment_identifier;
1430     uuid_t connection_id;
1431
1432     sec_array_t sent_certificate_chain;
1433     sec_array_t peer_certificate_chain;
1434     xpc_object_t pre_shared_keys;
1435     dispatch_data_t peer_public_key;
1436     xpc_object_t supported_signature_algorithms;
1437     dispatch_data_t request_certificate_types;
1438     sec_array_t signed_certificate_timestamps;
1439     sec_array_t ocsp_response;
1440     sec_array_t distinguished_names;
1441     dispatch_data_t quic_transport_parameters;
1442     sec_identity_t identity;
1443     sec_trust_t trust_ref;
1444     const char *negotiated_curve;
1445     const char *peer_public_key_type;
1446     const char *certificate_request_type;
1447     uint64_t ticket_lifetime;
1448     uint64_t max_early_data_supported;
1449     uint64_t alert_type;
1450     uint64_t alert_code;
1451     uint64_t handshake_state;
1452     uint64_t stack_error;
1453     uint64_t handshake_rtt;
1454     uint16_t certificate_compression_algorithm;
1455     uint64_t handshake_time;
1456     uint64_t total_byte_count;
1457     uint64_t sent_byte_count;
1458     uint64_t received_byte_count;
1459     size_t read_stall_count;
1460     size_t write_stall_count;
1461     size_t async_call_count;
1462
1463     unsigned failure : 1;
1464     unsigned sct_enabled : 1;
1465     unsigned ocsp_enabled : 1;
1466     unsigned early_data_accepted : 1;
1467     unsigned false_start_used : 1;
1468     unsigned ticket_offered : 1;
1469     unsigned ticket_received : 1;
1470     unsigned session_resumed : 1;
1471     unsigned session_renewed : 1;
1472     unsigned resumption_attempted : 1;
1473     unsigned alpn_used : 1;
1474     unsigned npn_used : 1;
1475     unsigned early_data_sent : 1;
1476     unsigned certificate_compression_used : 1;
1477 };
1478
1479 SEC_ASSUME_NONNULL_END
1480
1481 __END_DECLS
1482
1483 #endif /* SecProtocolPriv_h */