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_tls_encryption_level_t
 236  *
 237  * @abstract An enumeration of the different TLS encryption levels.
 238  */
 239 typedef enum {
 240     sec_protocol_tls_encryption_level_initial = 0,
 241     sec_protocol_tls_encryption_level_early_data,
 242     sec_protocol_tls_encryption_level_handshake,
 243     sec_protocol_tls_encryption_level_application,
 244 } sec_protocol_tls_encryption_level_t;
 245
 246 /*!
 247  * @block sec_protocol_tls_encryption_secret_update_t
 248  *
 249  * @abstract
 250  *      Block to be invoked when a new session is established and ready.
 251  *
 252  * @param level
 253  *      The `sec_protocol_tls_encryption_level_t` for this secret.
 254  *
 255  * @param is_write
 256  *      True if this secret is for writing, and false if it's for reading.
 257  *
 258  * @param secret
 259  *      Secret wrapped in a `dispatch_data_t`
 260  */
 261 typedef void (^sec_protocol_tls_encryption_secret_update_t)(sec_protocol_tls_encryption_level_t level, bool is_write, dispatch_data_t secret);
 262
 263 /*!
 264  * @function sec_protocol_options_set_tls_encryption_secret_update_block
 265  *
 266  * @abstract
 267  *      Set the TLS secret update block. This is fired whenever a new TLS secret is
 268  *      available.
 269  *
 270  * @param options
 271  *      A `sec_protocol_options_t` instance.
 272  *
 273  * @param update_block
 274  *      A `sec_protocol_tls_encryption_secret_update_t` instance.
 275  *
 276  * @params update_queue
 277  *      A `dispatch_queue_t` on which the update block should be called.
 278  */
 279 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 280 void
 281 sec_protocol_options_set_tls_encryption_secret_update_block(sec_protocol_options_t options,
 282                                                             sec_protocol_tls_encryption_secret_update_t update_block,
 283                                                             dispatch_queue_t update_queue);
 284
 285 /*!
 286  * @block sec_protocol_private_key_complete_t
 287  *
 288  * @abstract
 289  *      Block to be invoked when a private key operation is complete.
 290  *
 291  * @param result
 292  *      A `dispatch_data_t` object containing the private key result.
 293  */
 294 typedef void (^sec_protocol_private_key_complete_t)(dispatch_data_t result);
 295
 296 /*!
 297  * @block sec_protocol_private_key_sign_t
 298  *
 299  * @abstract
 300  *      Block to be invoked when a private key signature operation is required.
 301  *
 302  * @param algorithm
 303  *      The signature algorithm to use for the signature.
 304  *
 305  * @param input
 306  *      The input to be signed.
 307  *
 308  * @param complete
 309  *      The `sec_protocol_private_key_complete_t` block to invoke when the operation is complete.
 310  */
 311 typedef void (^sec_protocol_private_key_sign_t)(uint16_t algorithm, dispatch_data_t input, sec_protocol_private_key_complete_t complete);
 312
 313 /*!
 314  * @block sec_protocol_private_key_decrypt_t
 315  *
 316  * @abstract
 317  *      Block to be invoked when a private key decryption operation is required.
 318  *
 319  * @param input
 320  *      The input to be decrypted.
 321  *
 322  * @param complete
 323  *      The `sec_protocol_private_key_complete_t` block to invoke when the operation is complete.
 324  */
 325 typedef void (^sec_protocol_private_key_decrypt_t)(dispatch_data_t input, sec_protocol_private_key_complete_t complete);
 326
 327 /*!
 328  * @block sec_protocol_options_set_private_key_blocks
 329  *
 330  * @abstract
 331  *      Set the private key operation blocks for this connection.
 332  *
 333  * @param options
 334  *      A `sec_protocol_options_t` instance.
 335  *
 336  * @param sign_block
 337  *      A `sec_protocol_private_key_sign_t` block.
 338  *
 339  * @param decrypt_block
 340  *      A `sec_protocol_private_key_decrypt_t` block.
 341  *
 342  * @param operation_queue
 343  *      The `dispatch_queue_t` queue on which each private key operation is invoked.
 344  */
 345 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 346 void
 347 sec_protocol_options_set_private_key_blocks(sec_protocol_options_t options,
 348                                             sec_protocol_private_key_sign_t sign_block,
 349                                             sec_protocol_private_key_decrypt_t decrypt_block,
 350                                             dispatch_queue_t operation_queue);
 351
 352 /*!
 353  * @block sec_protocol_options_set_local_certificates
 354  *
 355  * @abstract
 356  *      Set the local certificates to be used for this protocol instance.
 357  *
 358  * @param options
 359  *      A `sec_protocol_options_t` instance.
 360  *
 361  * @param certificates
 362  *      A `sec_array_t` instance of `sec_certifiate_t` instances.
 363  */
 364 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 365 void
 366 sec_protocol_options_set_local_certificates(sec_protocol_options_t options, sec_array_t certificates);
 367
 368 /*!
 369  * @block sec_protocol_options_set_tls_certificate_compression_enabled
 370  *
 371  * @abstract
 372  *      Enable or disable TLS 1.3 certificate compression.
 373  *
 374  *      See: https://tools.ietf.org/html/draft-ietf-tls-certificate-compression-04
 375  *
 376  * @param options
 377  *      A `sec_protocol_options_t` instance.
 378  *
 379  * @param certificate_compression_enabled
 380  *      Flag to determine if certificate compression is enabled.
 381  */
 382 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 383 void
 384 sec_protocol_options_set_tls_certificate_compression_enabled(sec_protocol_options_t options, bool certificate_compression_enabled);
 385
 386 /*!
 387  * @block sec_protocol_options_tls_handshake_message_callback
 388  *
 389  * @abstract
 390  *      Set a callback to process each TLS handshake message. This function may be invoked at any point during
 391  *      the TLS handshake, if at all. Clients MUST NOT rely on any behavior aspect of this function as they
 392  *      risk breaking.
 393  *
 394  * @param options
 395  *      A `sec_protocol_options_t` instance.
 396  *
 397  * @param handler
 398  *      A `sec_protocol_tls_handshake_message_handler_t`.
 399  *
 400  * @param queue
 401  *      The queue upon which to invoke the callback.
 402  */
 403 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 404 void
 405 sec_protocol_options_tls_handshake_message_callback(sec_protocol_options_t options, sec_protocol_tls_handshake_message_handler_t handler, dispatch_queue_t queue);
 406
 407 /*!
 408  * @block sec_protocol_options_append_tls_key_exchange_group
 409  *
 410  * @abstract
 411  *      Append a TLS key exchange group to the set of enabled groups.
 412  *
 413  * @param options
 414  *      A `sec_protocol_options_t` instance.
 415  *
 416  * @param group
 417  *      A `tls_key_exchange_group_t` value.
 418  */
 419 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 420 void
 421 sec_protocol_options_append_tls_key_exchange_group(sec_protocol_options_t options, tls_key_exchange_group_t group);
 422
 423 /*!
 424  * @block sec_protocol_options_add_tls_key_exchange_group
 425  *
 426  * @abstract
 427  *      Add a TLS key exchange group to the set of enabled groups.
 428  *
 429  * @param options
 430  *      A `sec_protocol_options_t` instance.
 431  *
 432  * @param group
 433  *      A SSLKeyExchangeGroup value.
 434  */
 435 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 436 void
 437 sec_protocol_options_add_tls_key_exchange_group(sec_protocol_options_t options, SSLKeyExchangeGroup group);
 438
 439 /*!
 440  * @block sec_protocol_options_append_tls_key_exchange_group_set
 441  *
 442  * @abstract
 443  *      Append a TLS key exchange group set to the set of enabled groups.
 444  *
 445  * @param options
 446  *      A `sec_protocol_options_t` instance.
 447  *
 448  * @param set
 449  *      A `tls_key_exchange_group_set_t` value.
 450  */
 451 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 452 void
 453 sec_protocol_options_append_tls_key_exchange_group_set(sec_protocol_options_t options, tls_key_exchange_group_set_t set);
 454
 455 /*!
 456  * @block sec_protocol_options_tls_key_exchange_group_set
 457  *
 458  * @abstract
 459  *      Add a TLS key exchange group set to the set of enabled groups.
 460  *
 461  * @param options
 462  *      A `sec_protocol_options_t` instance.
 463  *
 464  * @param set
 465  *      A SSLKeyExchangeGroupSet value.
 466  */
 467 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 468 void
 469 sec_protocol_options_add_tls_key_exchange_group_set(sec_protocol_options_t options, SSLKeyExchangeGroupSet set);
 470
 471 /*!
 472  * @function sec_protocol_options_set_tls_SIKE503_exchange_enabled
 473  *
 474  * @abstract
 475  *      Enable SIKE using P503 for TLS 1.3 key exchange.
 476  *
 477  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 478  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 479  *
 480  * @param options
 481  *      A `sec_protocol_options_t` instance.
 482  *
 483  * @param tls_SIKE503_exchange_enabled
 484  *      Flag to enable SIKE with P503.
 485  */
 486 #define SEC_PROTOCOL_HAS_PQ_TLS_HANDLES 1
 487 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 488 void
 489 sec_protocol_options_set_tls_SIKE503_exchange_enabled(sec_protocol_options_t options, bool tls_SIKE503_exchange_enabled);
 490
 491 /*!
 492  * @function sec_protocol_options_set_tls_HRSS_exchange_enabled
 493  *
 494  * @abstract
 495  *      Enable HRSS for TLS 1.3 key exchange.
 496  *
 497  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 498  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 499  *
 500  * @param options
 501  *      A `sec_protocol_options_t` instance.
 502  *
 503  * @param tls_HRSS_exchange_enabled
 504  *      Flag to enable HRSS.
 505  */
 506 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 507 void
 508 sec_protocol_options_set_tls_HRSS_exchange_enabled(sec_protocol_options_t options, bool tls_HRSS_exchange_enabled);
 509
 510 /*!
 511  * @function sec_protocol_options_set_eddsa_enabled
 512  *
 513  * @abstract
 514  *      Enable EDDSA support (for TLS 1.3).
 515  *
 516  * @param options
 517  *      A `sec_protocol_options_t` instance.
 518  *
 519  * @param eddsa_enabled
 520  *      Flag to enable EDDSA.
 521  */
 522 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 523 void
 524 sec_protocol_options_set_eddsa_enabled(sec_protocol_options_t options, bool eddsa_enabled);
 525
 526 /*!
 527  * @function sec_protocol_options_set_tls_delegated_credentials_enabled
 528  *
 529  * @abstract
 530  *      Enable TLS delegated credentials support. See https://tools.ietf.org/html/draft-ietf-tls-subcerts-02.
 531  *
 532  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 533  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 534  *
 535  * @param options
 536  *      A `sec_protocol_options_t` instance.
 537  *
 538  * @param tls_delegated_credentials_enabled
 539  *      Flag to enable TLS delegated credentials.
 540  */
 541 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 542 void
 543 sec_protocol_options_set_tls_delegated_credentials_enabled(sec_protocol_options_t options, bool tls_delegated_credentials_enabled);
 544
 545 /*!
 546  * @function sec_protocol_options_set_tls_ticket_request_count
 547  *
 548  * @abstract
 549  *      Enable TLS ticket request support, and specify the count of tickets. Ticket support
 550  *      must also be explicitly enabled by `sec_protocol_options_set_tls_tickets_enabled`.
 551  *
 552  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 553  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 554  *
 555  * @param options
 556  *      A `sec_protocol_options_t` instance.
 557  *
 558  * @param tls_ticket_request_count
 559  *      Set the amount of tickets to request from the server.
 560  */
 561 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 562 void
 563 sec_protocol_options_set_tls_ticket_request_count(sec_protocol_options_t options, uint8_t tls_ticket_request_count);
 564
 565 /*!
 566  * @function sec_protocol_options_set_tls_grease_enabled
 567  *
 568  * @abstract
 569  *      Enable TLS GREASE support. See https://tools.ietf.org/html/draft-ietf-tls-grease-02.
 570  *
 571  *      DO NOT DEPEND ON THIS SPI. IT IS FOR EXPERIMENTAL PURPOSES AND SUBJECT TO REMOVAL WITHOUT ADVANCE NOTICE.
 572  *      BUILD BREAKAGE ISSUES WILL BE SENT TO THE CALLING PROJECT.
 573  *
 574  * @param options
 575  *      A `sec_protocol_options_t` instance.
 576  *
 577  * @param tls_grease_enabled
 578  *      Flag to enable TLS GREASE.
 579  */
 580 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 581 void
 582 sec_protocol_options_set_tls_grease_enabled(sec_protocol_options_t options, bool tls_grease_enabled);
 583
 584 /*!
 585  * @function sec_protocol_options_set_experiment_identifier
 586  *
 587  * @abstract
 588  *      Set the SecExperiment identifier for a given connection.
 589  *
 590  *      Note: this SPI is meant to be called by libnetcore. It should not be called in any other circumstances.
 591  *
 592  * @param options
 593  *      A `sec_protocol_options_t` instance.
 594  *
 595  * @param experiment_identifier
 596  *      The identifier for a secure connection experiment.
 597  */
 598 #define SEC_PROTOCOL_HAS_EXPERIMENT_IDENTIFIER 1
 599 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 600 void
 601 sec_protocol_options_set_experiment_identifier(sec_protocol_options_t options, const char *experiment_identifier);
 602
 603 /*!
 604  * @function sec_protocol_options_set_connection_id
 605  *
 606  * @abstract
 607  *      Set the explciit connection identifier. If not set, one will be populated internally.
 608  *
 609  * @param options
 610  *      A `sec_protocol_options_t` instance.
 611  *
 612  * @param connection_id
 613  *      The `uuid_t`` connection identifier.
 614  */
 615 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 616 void
 617 sec_protocol_options_set_connection_id(sec_protocol_options_t options, uuid_t _Nonnull connection_id);
 618
 619 /*!
 620  * @function sec_protocol_options_create_config
 621  *
 622  * @abstract
 623  *      Create a `xpc_object_t` instance carrying a configuration for the given `sec_protocol_options_t` instance.
 624  *
 625  * @param options
 626  *      A `sec_protocol_options_t` instance.
 627  *
 628  * @return A `xpc_object_t` instance carrying a configuration, or nil on failure.
 629  */
 630 #define SEC_PROTOCOL_HAS_EXPERIMENT_HOOKS 1
 631 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 632 SEC_RETURNS_RETAINED __nullable xpc_object_t
 633 sec_protocol_options_create_config(sec_protocol_options_t options);
 634
 635 /*!
 636  * @function sec_protocol_options_matches_config
 637  *
 638  * @abstract
 639  *      Determine if a `sec_protocol_options_t` instance matches a given configuration.
 640  *
 641  * @param options
 642  *      A `sec_protocol_options_t` instance.
 643  *
 644  * @param config
 645  *      A `xpc_object_t` instance carrying a SecExperiment config.
 646  *
 647  * @return True if the parameters in `config` match that of `options`, and false otherwise.
 648  */
 649 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 650 bool
 651 sec_protocol_options_matches_config(sec_protocol_options_t options, xpc_object_t config);
 652
 653 /*!
 654  * @function sec_protocol_options_apply_config
 655  *
 656  * @abstract
 657  *      Transform the given `sec_protocol_options_t` instance using the provided config.
 658  *
 659  * @param options
 660  *      A `sec_protocol_options_t` instance.
 661  *
 662  * @param config
 663  *      A `xpc_object_t` instance carrying a SecExperiment config.
 664  *
 665  * @return True if the options were applied successfully, and false otherwise.
 666  */
 667 bool
 668 sec_protocol_options_apply_config(sec_protocol_options_t options, xpc_object_t config);
 669
 670 /*!
 671  * @function sec_protocol_metadata_get_tls_negotiated_group
 672  *
 673  * @abstract
 674  *      Get a human readable representation of the negotiated key exchange group.
 675  *
 676  * @param metadata
 677  *      A `sec_protocol_metadata_t` instance.
 678  *
 679  * @return A string representation of the negotiated group, or NULL if it does not exist.
 680  */
 681 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 682 const char * __nullable
 683 sec_protocol_metadata_get_tls_negotiated_group(sec_protocol_metadata_t metadata);
 684
 685 /*!
 686  * @function sec_protocol_metadata_get_experiment_identifier
 687  *
 688  * @abstract
 689  *      Get the SecExperiment identifier for a given connection.
 690  *
 691  *      Note: this SPI is meant to be called by libnetcore. It should not be called in any other circumstances.
 692  *
 693  * @param options
 694  *      A `sec_protocol_metadata_t` instance.
 695  *
 696  * @return The identifier for a secure connection experiment, or NULL if none was specified.
 697  */
 698 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 699 const char * __nullable
 700 sec_protocol_metadata_get_experiment_identifier(sec_protocol_metadata_t metadata);
 701
 702 /*!
 703  * @function sec_protocol_metadata_copy_connection_id
 704  *
 705  * @abstract
 706  *      Copy the secure connection identifier.
 707  *
 708  * @param metadata
 709  *      A `sec_protocol_metadata_t` instance.
 710  *
 711  * @param output_uuid
 712  *      A `uuid_t` into which the connection identifier is written.
 713  */
 714 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 715 void
 716 sec_protocol_metadata_copy_connection_id(sec_protocol_metadata_t metadata, uuid_t _Nonnull output_uuid);
 717
 718 /*!
 719  * @function sec_protocol_metadata_get_tls_false_start_used
 720  *
 721  * @abstract
 722  *      Determine if False Start was used.
 723  *
 724  * @param metadata
 725  *      A `sec_protocol_metadata_t` instance.
 726  *
 727  * @return True if False Start was used, and false otherwise.
 728  */
 729 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 730 bool
 731 sec_protocol_metadata_get_tls_false_start_used(sec_protocol_metadata_t metadata);
 732
 733 /*!
 734  * @function sec_protocol_metadata_get_ticket_offered
 735  *
 736  * @abstract
 737  *      Determine if a ticket was offered for session resumption.
 738  *
 739  * @param metadata
 740  *      A `sec_protocol_metadata_t` instance.
 741  *
 742  * @return True if a ticket was offered for resumption, and false otherwise.
 743  */
 744 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 745 bool
 746 sec_protocol_metadata_get_ticket_offered(sec_protocol_metadata_t metadata);
 747
 748 /*!
 749  * @function sec_protocol_metadata_get_ticket_received
 750  *
 751  * @abstract
 752  *      Determine if a ticket was received upon completing the new connection.
 753  *
 754  * @param metadata
 755  *      A `sec_protocol_metadata_t` instance.
 756  *
 757  * @return True if a ticket was received from the peer (server), and false otherwise.
 758  */
 759 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 760 bool
 761 sec_protocol_metadata_get_ticket_received(sec_protocol_metadata_t metadata);
 762
 763 /*!
 764  * @function sec_protocol_metadata_get_session_resumed
 765  *
 766  * @abstract
 767  *      Determine if this new connection was a session resumption.
 768  *
 769  * @param metadata
 770  *      A `sec_protocol_metadata_t` instance.
 771  *
 772  * @return True if this new connection was resumed, and false otherwise.
 773  */
 774 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 775 bool
 776 sec_protocol_metadata_get_session_resumed(sec_protocol_metadata_t metadata);
 777
 778 /*!
 779  * @function sec_protocol_metadata_get_session_renewed
 780  *
 781  * @abstract
 782  *      Determine if this resumed connection was renewed with a new ticket.
 783  *
 784  * @param metadata
 785  *      A `sec_protocol_metadata_t` instance.
 786  *
 787  * @return True if this resumed connection was renewed with a new ticket, and false otherwise.
 788  */
 789 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 790 bool
 791 sec_protocol_metadata_get_session_renewed(sec_protocol_metadata_t metadata);
 792
 793 /*!
 794  * @function sec_protocol_metadata_get_connection_strength
 795  *
 796  * @abstract
 797  *      Determine the TLS connection strength.
 798  *
 799  * @param metadata
 800  *      A `sec_protocol_metadata_t` instance.
 801  *
 802  * @return An `SSLConnectionStrength` enum.
 803  */
 804 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 805 SSLConnectionStrength
 806 sec_protocol_metadata_get_connection_strength(sec_protocol_metadata_t metadata);
 807
 808 /*!
 809  * @function sec_protocol_metadata_copy_serialized_session
 810  *
 811  * @abstract
 812  *      Copy a serialized representation of a session.
 813  *
 814  * @param metadata
 815  *      A `sec_protocol_metadata_t` instance.
 816  *
 817  * @return A `dispatch_data_t` object containing a serialized session.
 818  */
 819 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 820 SEC_RETURNS_RETAINED __nullable dispatch_data_t
 821 sec_protocol_metadata_copy_serialized_session(sec_protocol_metadata_t metadata);
 822
 823 /*!
 824  * @function sec_protocol_metadata_access_handle
 825  *
 826  * @abstract
 827  *      Access the internal handle of a `sec_protocol_metadata` object.
 828  *
 829  * @param metadata
 830  *      A `sec_protocol_metadata_t` instance.
 831  *
 832  * @param access_block
 833  *      A block to invoke with access to the internal handle.
 834  *
 835  * @return True if the access was successful
 836  */
 837 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 838 bool
 839 sec_protocol_metadata_access_handle(sec_protocol_metadata_t metadata, sec_access_block_t access_block);
 840
 841 /*!
 842  * @function sec_protocol_metadata_serialize_with_options
 843  *
 844  * @abstract
 845  *      Serialize a `sec_protocol_metadata_t` to an `xpc_object_t` dictionary using information
 846  *      contained in the `metadata` and `options` objects.
 847  *
 848  * @param metadata
 849  *      A `sec_protocol_metadata_t` instance.
 850  *
 851  * @return A xpc_object_t carrying the serialized metadata.
 852  */
 853 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 854 SEC_RETURNS_RETAINED __nullable xpc_object_t
 855 sec_protocol_metadata_serialize_with_options(sec_protocol_metadata_t metadata, sec_protocol_options_t options);
 856
 857 /*!
 858  * @function sec_protocol_metadata_get_tls_certificate_compression_used
 859  *
 860  * @abstract
 861  *      Determine if certificate compression was used for a given connection.
 862  *
 863  *      See: https://tools.ietf.org/html/draft-ietf-tls-certificate-compression-04
 864  *
 865  * @param metadata
 866  *      A `sec_protocol_metadata_t` instance.
 867  *
 868  * @return True if certificate compression was negotiated and used.
 869  */
 870 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 871 bool
 872 sec_protocol_metadata_get_tls_certificate_compression_used(sec_protocol_metadata_t metadata);
 873
 874 /*!
 875  * @function sec_protocol_metadata_get_tls_certificate_compression_algorithm
 876  *
 877  * @abstract
 878  *      Return the certificate compression algorithm used. This will return 0
 879  *      if `sec_protocol_metadata_get_tls_certificate_compression_used` is false.
 880  *
 881  *      See: https://tools.ietf.org/html/draft-ietf-tls-certificate-compression-04
 882  *
 883  * @param metadata
 884  *      A `sec_protocol_metadata_t` instance.
 885  *
 886  * @return IANA codepoint for the certificate compression algorithm.
 887  */
 888 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 889 uint16_t
 890 sec_protocol_metadata_get_tls_certificate_compression_algorithm(sec_protocol_metadata_t metadata);
 891
 892 /*!
 893  * @function sec_protocol_metadata_copy_quic_transport_parameters
 894  *
 895  * @abstract
 896  *      Copy the peer's QUIC transport parameters.
 897  *
 898  * @param metadata
 899  *      A `sec_protocol_metadata_t` instance.
 900  *
 901  * @return A dispatch_data_t carrying the connection peer's opaque QUIC tranport parameters.
 902  */
 903 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 904 SEC_RETURNS_RETAINED __nullable dispatch_data_t
 905 sec_protocol_metadata_copy_quic_transport_parameters(sec_protocol_metadata_t metadata);
 906
 907 /*!
 908  * @function sec_protocol_metadata_get_handshake_time_ms
 909  *
 910  * @abstract
 911  *      Get the TLS handshake time in miliseconds. The result is undefined
 912  *      for connections not yet connected.
 913  *
 914  * @param metadata
 915  *      A `sec_protocol_metadata_t` instance.
 916  *
 917  * @return A millisecond measurement of the TLS handshake time from start to finish.
 918  */
 919 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 920 #define SEC_PROTOCOL_HAS_METRIC_SPI_V1
 921 uint64_t
 922 sec_protocol_metadata_get_handshake_time_ms(sec_protocol_metadata_t metadata);
 923
 924 /*!
 925  * @function sec_protocol_metadata_get_handshake_rtt
 926  *
 927  * @abstract
 928  *      Get the observed TLS handshake RTT. This function must only be
 929  *      called after the connection is established. Calling this before
 930  *      the connection completes will yields an undefined result.
 931  *
 932  *      This is computed as the average RTT across all 1-RTT exchanges.
 933  *      For TLS 1.3, this will be the time for the normal exchange. For prior
 934  *      versions, or TLS 1.3 with HRR, this will be the average RTT across
 935  *      multiple message flights.
 936  *
 937  * @param metadata
 938  *      A `sec_protocol_metadata_t` instance.
 939  *
 940  * @return A millisecond measurement of the TLS handshake RTT.
 941  */
 942 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 943 uint64_t
 944 sec_protocol_metadata_get_handshake_rtt(sec_protocol_metadata_t metadata);
 945
 946 /*!
 947  * @function sec_protocol_metadata_get_handshake_byte_count
 948  *
 949  * @abstract
 950  *      Get the total number of bytes sent and received for the handshake.
 951  *
 952  * @param metadata
 953  *      A `sec_protocol_metadata_t` instance.
 954  *
 955  * @return Number of bytes sent and received for the handshake.
 956  */
 957 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 958 uint64_t
 959 sec_protocol_metadata_get_handshake_byte_count(sec_protocol_metadata_t metadata);
 960
 961 /*!
 962  * @function sec_protocol_metadata_get_handshake_sent_byte_count
 963  *
 964  * @abstract
 965  *      Get the total number of bytes sent for the handshake.
 966  *
 967  * @param metadata
 968  *      A `sec_protocol_metadata_t` instance.
 969  *
 970  * @return Number of bytes sent for the handshake.
 971  */
 972 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 973 uint64_t
 974 sec_protocol_metadata_get_handshake_sent_byte_count(sec_protocol_metadata_t metadata);
 975
 976 /*!
 977  * @function sec_protocol_metadata_get_handshake_received_byte_count
 978  *
 979  * @abstract
 980  *      Get the total number of bytes received for the handshake.
 981  *
 982  * @param metadata
 983  *      A `sec_protocol_metadata_t` instance.
 984  *
 985  * @return Number of bytes received for the handshake.
 986  */
 987 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 988 uint64_t
 989 sec_protocol_metadata_get_handshake_received_byte_count(sec_protocol_metadata_t metadata);
 990
 991 /*!
 992  * @function sec_protocol_metadata_get_handshake_read_stall_count
 993  *
 994  * @abstract
 995  *      Get the total number of read stalls during the handshake.
 996  *
 997  * @param metadata
 998  *      A `sec_protocol_metadata_t` instance.
 999  *
1000  * @return Number of read stalls.
1001  */
1002 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1003 size_t
1004 sec_protocol_metadata_get_handshake_read_stall_count(sec_protocol_metadata_t metadata);
1005
1006 /*!
1007  * @function sec_protocol_metadata_get_handshake_write_stall_count
1008  *
1009  * @abstract
1010  *      Get the total number of write stalls during the handshake.
1011  *
1012  * @param metadata
1013  *      A `sec_protocol_metadata_t` instance.
1014  *
1015  * @return Number of write stalls.
1016  */
1017 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1018 size_t
1019 sec_protocol_metadata_get_handshake_write_stall_count(sec_protocol_metadata_t metadata);
1020
1021 /*!
1022  * @function sec_protocol_metadata_get_handshake_async_call_count
1023  *
1024  * @abstract
1025  *      Get the total number of asynchronous callbacks invoked during the handshake.
1026  *
1027  * @param metadata
1028  *      A `sec_protocol_metadata_t` instance.
1029  *
1030  * @return Number of asynchronous callbacks.
1031  */
1032 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1033 size_t
1034 sec_protocol_metadata_get_handshake_async_call_count(sec_protocol_metadata_t metadata);
1035
1036 /*!
1037  * @function sec_protocol_metadata_copy_sec_trust
1038  *
1039  * @abstract
1040  *      Copy the `sec_trust_t` associated with a connection.
1041  *
1042  * @param metadata
1043  *      A `sec_protocol_metadata_t` instance.
1044  *
1045  * @return A `sec_trust_t` instance.
1046  */
1047 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1048 SEC_RETURNS_RETAINED __nullable sec_trust_t
1049 sec_protocol_metadata_copy_sec_trust(sec_protocol_metadata_t metadata);
1050
1051 /*!
1052  * @function sec_protocol_metadata_copy_sec_identity
1053  *
1054  * @abstract
1055  *      Copy the `sec_identity_t` associated with a connection.
1056  *
1057  * @param metadata
1058  *      A `sec_protocol_metadata_t` instance.
1059  *
1060  * @return A `sec_identity_t` instance.
1061  */
1062 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1063 SEC_RETURNS_RETAINED __nullable sec_identity_t
1064 sec_protocol_metadata_copy_sec_identity(sec_protocol_metadata_t metadata);
1065
1066 /*!
1067  * @function sec_protocol_metadata_access_sent_certificates
1068  *
1069  * @abstract
1070  *      Access the certificates which were sent to the peer on this connection.
1071  *
1072  * @param metadata
1073  *      A `sec_protocol_metadata_t` instance.
1074  *
1075  * @param handler
1076  *      A block to invoke one or more times with `sec_certificate_t` instances.
1077  *
1078  * @return Returns true if the peer certificates were accessible, false otherwise.
1079  */
1080 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1081 bool
1082 sec_protocol_metadata_access_sent_certificates(sec_protocol_metadata_t metadata,
1083                                                void (^handler)(sec_certificate_t certificate));
1084
1085 /*!
1086  * @function sec_protocol_metadata_get_tls_negotiated_group
1087  *
1088  * @abstract
1089  *      Get a human readable representation of the negotiated key exchange group.
1090  *
1091  * @param metadata
1092  *      A `sec_protocol_metadata_t` instance.
1093  *
1094  * @return A string representation of the negotiated group, or NULL if it does not exist.
1095  */
1096 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1097 const char * __nullable
1098 sec_protocol_metadata_get_tls_negotiated_group(sec_protocol_metadata_t metadata);
1099
1100 /*!
1101  * @function sec_protocol_configuration_copy_singleton
1102  *
1103  * @abstract
1104  *      Copy the per-process `sec_protocol_configuration_t` object.
1105  *
1106  * @return A non-nil `sec_protocol_configuration_t` instance.
1107  */
1108 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1109 SEC_RETURNS_RETAINED sec_protocol_configuration_t
1110 sec_protocol_configuration_copy_singleton(void);
1111
1112 #ifndef SEC_OBJECT_IMPL
1113 SEC_OBJECT_DECL(sec_protocol_configuration_builder);
1114 #endif // !SEC_OBJECT_IMPL
1115
1116 /*!
1117  * @function sec_protocol_configuration_builder_create
1118  *
1119  * @abstract
1120  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1121  */
1122 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1123 SEC_RETURNS_RETAINED sec_protocol_configuration_builder_t
1124 sec_protocol_configuration_builder_create(CFDictionaryRef dictionary, bool is_apple);
1125
1126 /*!
1127  * @function sec_protocol_configuration_create_with_builder
1128  *
1129  * @abstract
1130  *      This function is exposed for testing purposes only. It MUST NOT be called by clients.
1131  */
1132 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1133 SEC_RETURNS_RETAINED __nullable sec_protocol_configuration_t
1134 sec_protocol_configuration_create_with_builder(sec_protocol_configuration_builder_t builder);
1135
1136 /*!
1137  * @block sec_protocol_output_handler_access_block_t
1138  *
1139  * @abstract
1140  *      Block to be invoked to obtain the output handler for a given encryption level.
1141  */
1142 typedef void *_Nullable(^sec_protocol_output_handler_access_block_t)(sec_protocol_tls_encryption_level_t level);
1143
1144 /*!
1145  * @function sec_protocol_options_set_output_handler_access_block
1146  *
1147  * @abstract
1148  *      Set a block used to access output handler instances identified by encryption level.
1149  */
1150 #define SEC_PROTOCOL_HAS_QUIC_OUTPUT_HANDLER_ACCESS_BLOCK 1
1151 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1152 void
1153 sec_protocol_options_set_output_handler_access_block(sec_protocol_options_t options,
1154                                                      sec_protocol_output_handler_access_block_t access_block);
1155
1156 /*!
1157  * @function sec_protocol_helper_ciphersuite_group_to_ciphersuite_list
1158  *
1159  * @abstract
1160  *      Return a pointer to a statically allocated list of ciphersuites corresponding to `group`.
1161  *
1162  * @param group
1163  *      A `tls_ciphersuite_group_t` instance.
1164  *
1165  * @param list_count
1166  *      Pointer to storage for the ciphersuite list length.
1167  *
1168  * @return Pointer to a statically allocated list, or NULL if an error occurred.
1169  */
1170 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
1171 const tls_ciphersuite_t * __nullable
1172 sec_protocol_helper_ciphersuite_group_to_ciphersuite_list(tls_ciphersuite_group_t group, size_t *list_count);
1173
1174 #define SEC_PROTOCOL_HAS_MULTI_PSK_SUPPORT 1
1175
1176 struct sec_protocol_options_content {
1177     SSLProtocol min_version;
1178     SSLProtocol max_version;
1179
1180     char *server_name;
1181     char *experiment_identifier;
1182     uuid_t connection_id;
1183     __nullable xpc_object_t ciphersuites;
1184     xpc_object_t application_protocols;
1185     sec_identity_t identity;
1186     sec_array_t certificates;
1187     xpc_object_t pre_shared_keys;
1188     dispatch_data_t psk_identity_hint;
1189     sec_protocol_key_update_t key_update_block;
1190     dispatch_queue_t key_update_queue;
1191     sec_protocol_challenge_t challenge_block;
1192     dispatch_queue_t challenge_queue;
1193     sec_protocol_verify_t verify_block;
1194     dispatch_queue_t verify_queue;
1195     dispatch_data_t quic_transport_parameters;
1196     sec_protocol_tls_encryption_secret_update_t tls_secret_update_block;
1197     dispatch_queue_t tls_secret_update_queue;
1198     sec_protocol_session_update_t session_update_block;
1199     dispatch_queue_t session_update_queue;
1200     dispatch_data_t session_state;
1201     sec_protocol_private_key_sign_t private_key_sign_block;
1202     sec_protocol_private_key_decrypt_t private_key_decrypt_block;
1203     dispatch_queue_t private_key_queue;
1204     dispatch_data_t dh_params;
1205     xpc_object_t key_exchange_groups;
1206     sec_protocol_tls_handshake_message_handler_t handshake_message_callback;
1207     dispatch_queue_t handshake_message_callback_queue;
1208     sec_protocol_pre_shared_key_selection_t psk_selection_block;
1209     dispatch_queue_t psk_selection_queue;
1210
1211     // ATS minimums
1212     size_t minimum_rsa_key_size;
1213     size_t minimum_ecdsa_key_size;
1214     SecSignatureHashAlgorithm minimum_signature_algorithm;
1215
1216     // Non-boolean options
1217     uint8_t tls_ticket_request_count;
1218
1219     // QUIC-specific access block
1220     sec_protocol_output_handler_access_block_t output_handler_access_block;
1221
1222     // Boolean flags
1223     unsigned ats_required : 1;
1224     unsigned ats_minimum_tls_version_allowed : 1;
1225     unsigned ats_non_pfs_ciphersuite_allowed : 1;
1226     unsigned trusted_peer_certificate : 1;
1227     unsigned trusted_peer_certificate_override : 1;
1228     unsigned disable_sni : 1;
1229     unsigned disable_sni_override : 1;
1230     unsigned enable_fallback_attempt : 1;
1231     unsigned enable_fallback_attempt_override : 1;
1232     unsigned enable_false_start : 1;
1233     unsigned enable_false_start_override : 1;
1234     unsigned enable_tickets : 1;
1235     unsigned enable_tickets_override : 1;
1236     unsigned enable_sct : 1;
1237     unsigned enable_sct_override : 1;
1238     unsigned enable_ocsp : 1;
1239     unsigned enable_ocsp_override : 1;
1240     unsigned enforce_ev : 1;
1241     unsigned enforce_ev_override : 1;
1242     unsigned enable_resumption : 1;
1243     unsigned enable_resumption_override : 1;
1244     unsigned enable_renegotiation : 1;
1245     unsigned enable_renegotiation_override : 1;
1246     unsigned enable_early_data : 1;
1247     unsigned enable_early_data_override : 1;
1248     unsigned peer_authentication_required : 1;
1249     unsigned peer_authentication_override : 1;
1250     unsigned certificate_compression_enabled : 1;
1251     unsigned tls_SIKE503_exchange_enabled : 1;
1252     unsigned tls_HRSS_exchange_enabled : 1;
1253     unsigned eddsa_enabled : 1;
1254     unsigned tls_delegated_credentials_enabled : 1;
1255     unsigned tls_grease_enabled : 1;
1256 };
1257
1258 struct sec_protocol_metadata_content {
1259     void *exporter_context; // Opaque context for the exporter function
1260     sec_protocol_metadata_exporter exporter_function; // Exporter function pointer. This MUST be set by the metadata allocator.
1261     void *session_exporter_context; // Opaque context for the session exporter function
1262     sec_protocol_metadata_session_exporter session_exporter_function;
1263
1264     SSLProtocol negotiated_protocol_version;
1265     SSLCipherSuite negotiated_ciphersuite;
1266     const char *negotiated_protocol;
1267     const char *server_name;
1268     const char *experiment_identifier;
1269     uuid_t connection_id;
1270
1271     sec_array_t sent_certificate_chain;
1272     sec_array_t peer_certificate_chain;
1273     xpc_object_t pre_shared_keys;
1274     dispatch_data_t peer_public_key;
1275     xpc_object_t supported_signature_algorithms;
1276     dispatch_data_t request_certificate_types;
1277     sec_array_t signed_certificate_timestamps;
1278     sec_array_t ocsp_response;
1279     sec_array_t distinguished_names;
1280     dispatch_data_t quic_transport_parameters;
1281     sec_identity_t identity;
1282     sec_trust_t trust_ref;
1283     const char *negotiated_curve;
1284     const char *peer_public_key_type;
1285     const char *certificate_request_type;
1286     uint64_t ticket_lifetime;
1287     uint64_t max_early_data_supported;
1288     uint64_t alert_type;
1289     uint64_t alert_code;
1290     uint64_t handshake_state;
1291     uint64_t stack_error;
1292     uint64_t handshake_rtt;
1293     uint16_t certificate_compression_algorithm;
1294     uint64_t handshake_time;
1295     uint64_t total_byte_count;
1296     uint64_t sent_byte_count;
1297     uint64_t received_byte_count;
1298     size_t read_stall_count;
1299     size_t write_stall_count;
1300     size_t async_call_count;
1301
1302     unsigned failure : 1;
1303     unsigned sct_enabled : 1;
1304     unsigned ocsp_enabled : 1;
1305     unsigned early_data_accepted : 1;
1306     unsigned false_start_used : 1;
1307     unsigned ticket_offered : 1;
1308     unsigned ticket_received : 1;
1309     unsigned session_resumed : 1;
1310     unsigned session_renewed : 1;
1311     unsigned resumption_attempted : 1;
1312     unsigned alpn_used : 1;
1313     unsigned npn_used : 1;
1314     unsigned early_data_sent : 1;
1315     unsigned certificate_compression_used : 1;
1316 };
1317
1318 SEC_ASSUME_NONNULL_END
1319
1320 __END_DECLS
1321
1322 #endif /* SecProtocolPriv_h */