protocol/SecProtocolMetadata.h

   1 /*
   2  * Copyright (c) 2018 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef SecProtocolMetadata_h
  25 #define SecProtocolMetadata_h
  26
  27 #include <Security/SecProtocolObject.h>
  28 #include <Security/SecProtocolTypes.h>
  29 #include <Security/SecProtocolOptions.h>
  30
  31 #include <dispatch/dispatch.h>
  32 #include <os/object.h>
  33
  34 /*!
  35  * The following diagram shows how clients interact with sec_protocol_options
  36  * and sec_protocol_metadata when configuring and using network security protocols.
  37  *
  38  *                    +--------+
  39  *                    | Client |
  40  *                    +-+---/ \+
  41  *                      |    |
  42  *        +-------------+    +-------------+
  43  *        | (1) set             (2) get    |
  44  *        | options             metadata   |
  45  * +-----\ /---------------+  +------------+----------+
  46  * | sec_protocol_options  |  | sec_protocol_metadata |
  47  * +-----------------------+  +-----------------------+
  48  *
  49  * Clients configure security protocols with `sec_protocol_options` instances.
  50  * And they inspect protocol instances using `sec_protocol_metadata` instances.
  51  */
  52
  53 #ifndef SEC_OBJECT_IMPL
  54 /*!
  55  * A `sec_protocol_metadata` instance conatins read-only properties of a connected and configured
  56  * security protocol. Clients use this object to read information about a protocol instance. Properties
  57  * include, for example, the negotiated TLS version, ciphersuite, and peer certificates.
  58  */
  59 SEC_OBJECT_DECL(sec_protocol_metadata);
  60 #endif // !SEC_OBJECT_IMPL
  61
  62 __BEGIN_DECLS
  63
  64 SEC_ASSUME_NONNULL_BEGIN
  65
  66 /*!
  67  * @function sec_protocol_metadata_get_negotiated_protocol
  68  *
  69  * @abstract
  70  *      Get the application protocol negotiated, e.g., via the TLS ALPN extension.
  71  *
  72  * @param metadata
  73  *      A `sec_protocol_metadata_t` instance.
  74  *
  75  * @return A NULL-terminated string carrying the negotiated protocol.
  76  */
  77 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  78 const char * _Nullable
  79 sec_protocol_metadata_get_negotiated_protocol(sec_protocol_metadata_t metadata);
  80
  81 /*!
  82  * @function sec_protocol_metadata_copy_peer_public_key
  83  *
  84  * @abstract
  85  *      Get the protocol instance peer's public key.
  86  *
  87  * @param metadata
  88  *      A `sec_protocol_metadata_t` instance.
  89  *
  90  * @return A `dispatch_data_t` containing the peer's raw public key.
  91  */
  92 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  93 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
  94 sec_protocol_metadata_copy_peer_public_key(sec_protocol_metadata_t metadata);
  95
  96 /*!
  97  * @function sec_protocol_metadata_get_negotiated_tls_protocol_version
  98  *
  99  * @abstract
 100  *      Get the negotiated TLS version.
 101  *
 102  * @param metadata
 103  *      A `sec_protocol_metadata_t` instance.
 104  *
 105  * @return A `tls_protocol_version_t` value.
 106  */
 107 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 108 tls_protocol_version_t
 109 sec_protocol_metadata_get_negotiated_tls_protocol_version(sec_protocol_metadata_t metadata);
 110
 111 /*!
 112  * @function sec_protocol_metadata_get_negotiated_protocol_version
 113  *
 114  * @abstract
 115  *      Get the negotiated TLS version.
 116  *
 117  * @param metadata
 118  *      A `sec_protocol_metadata_t` instance.
 119  *
 120  * @return A SSLProtocol enum of the TLS version.
 121  */
 122 API_DEPRECATED_WITH_REPLACEMENT("sec_protocol_metadata_get_negotiated_tls_protocol_version",
 123                                 macos(10.14, 10.15), ios(12.0, 13.0), watchos(5.0, 6.0), tvos(12.0, 13.0))
 124 SSLProtocol
 125 sec_protocol_metadata_get_negotiated_protocol_version(sec_protocol_metadata_t metadata);
 126
 127 /*!
 128  * @function sec_protocol_metadata_get_negotiated_tls_ciphersuite
 129  *
 130  * @abstract
 131  *      Get the negotiated TLS ciphersuite.
 132  *
 133  * @param metadata
 134  *      A `sec_protocol_metadata_t` instance.
 135  *
 136  * @return A `tls_ciphersuite_t`.
 137  */
 138 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 139 tls_ciphersuite_t
 140 sec_protocol_metadata_get_negotiated_tls_ciphersuite(sec_protocol_metadata_t metadata);
 141
 142 /*!
 143  * @function sec_protocol_metadata_get_negotiated_ciphersuite
 144  *
 145  * @abstract
 146  *      Get the negotiated TLS ciphersuite.
 147  *
 148  * @param metadata
 149  *      A `sec_protocol_metadata_t` instance.
 150  *
 151  * @return A SSLCipherSuite.
 152  */
 153 API_DEPRECATED_WITH_REPLACEMENT("sec_protocol_metadata_get_negotiated_tls_ciphersuite",
 154                                 macos(10.14, 10.15), ios(12.0, 13.0), watchos(5.0, 6.0), tvos(12.0, 13.0), macCatalyst(13.0, 13.0))
 155 SSLCipherSuite
 156 sec_protocol_metadata_get_negotiated_ciphersuite(sec_protocol_metadata_t metadata);
 157
 158 /*!
 159  * @function sec_protocol_metadata_get_early_data_accepted
 160  *
 161  * @abstract
 162  *      Determine if early data was accepted by the peer.
 163  *
 164  * @param metadata
 165  *      A `sec_protocol_metadata_t` instance.
 166  *
 167  * @return A bool indicating if early data was accepted.
 168  */
 169 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 170 bool
 171 sec_protocol_metadata_get_early_data_accepted(sec_protocol_metadata_t metadata);
 172
 173 #ifdef __BLOCKS__
 174 /*!
 175  * @function sec_protocol_metadata_access_peer_certificate_chain
 176  *
 177  * @abstract
 178  *      Get the certificate chain of the protocol instance peer.
 179  *
 180  * @param metadata
 181  *      A `sec_protocol_metadata_t` instance.
 182  *
 183  * @param handler
 184  *      A block to invoke one or more times with sec_certificate_t objects
 185  *
 186  * @return Returns true if the peer certificates were accessible, false otherwise.
 187  */
 188 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 189 bool
 190 sec_protocol_metadata_access_peer_certificate_chain(sec_protocol_metadata_t metadata,
 191                                                     void (^handler)(sec_certificate_t certificate));
 192
 193 /*!
 194  * @function sec_protocol_metadata_copy_ocsp_response
 195  *
 196  * @abstract
 197  *      Get the OCSP response from the protocol instance peer.
 198  *
 199  * @param metadata
 200  *      A `sec_protocol_metadata_t` instance.
 201  *
 202  * @param handler
 203  *      A block to invoke one or more times with OCSP data
 204  *
 205  * @return Returns true if the OSCP response was accessible, false otherwise.
 206  */
 207 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 208 bool
 209 sec_protocol_metadata_access_ocsp_response(sec_protocol_metadata_t metadata,
 210                                            void (^handler)(dispatch_data_t ocsp_data));
 211
 212 /*!
 213  * @function sec_protocol_metadata_access_supported_signature_algorithms
 214  *
 215  * @abstract
 216  *      Get the signature algorithms supported by the peer. Clients may call this
 217  *      in response to a challenge block.
 218  *
 219  * @param metadata
 220  *      A `sec_protocol_metadata_t` instance.
 221  *
 222  * @param handler
 223  *      A block to invoke one or more times with OCSP data
 224  *
 225  * @return Returns true if the supported signature list was accessible, false otherwise.
 226  */
 227 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 228 bool
 229 sec_protocol_metadata_access_supported_signature_algorithms(sec_protocol_metadata_t metadata,
 230                                                             void (^handler)(uint16_t signature_algorithm));
 231
 232 /*!
 233  * @function sec_protocol_metadata_access_distinguished_names
 234  *
 235  * @abstract
 236  *      Get the X.509 Distinguished Names from the protocol instance peer.
 237  *
 238  * @param metadata
 239  *      A `sec_protocol_metadata_t` instance.
 240  *
 241  * @param handler
 242  *      A block to invoke one or more times with distinguished_name data
 243  *
 244  * @return Returns true if the distinguished names were accessible, false otherwise.
 245  */
 246 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 247 bool
 248 sec_protocol_metadata_access_distinguished_names(sec_protocol_metadata_t metadata,
 249                                                  void (^handler)(dispatch_data_t distinguished_name));
 250
 251 /*!
 252  * @function sec_protocol_metadata_access_pre_shared_keys
 253  *
 254  * @abstract
 255  *      Get the PSKs supported by the local instance.
 256  *
 257  * @param metadata
 258  *      A `sec_protocol_metadata_t` instance.
 259  *
 260  * @param handler
 261  *      A block to invoke one or more times with tuples of dispatch_data_t objects carrying PSKs and their corresponding identities.
 262  *
 263  * @return Returns true if the PSKs were accessible, false otherwise.
 264  */
 265 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 266 bool
 267 sec_protocol_metadata_access_pre_shared_keys(sec_protocol_metadata_t metadata, void (^handler)(dispatch_data_t psk, dispatch_data_t psk_identity));
 268
 269 #endif // __BLOCKS__
 270
 271 /*!
 272  * @function sec_protocol_metadata_get_server_name
 273  *
 274  * @abstract
 275  *      Obtain the server name offered by a client or server during
 276  *      connection establishmet. This is the value commonly carried
 277  *      in the TLS SNI extesion.
 278  *
 279  * @param metadata
 280  *      A `sec_protocol_metadata_t` instance.
 281  *
 282  * @return Returns A NULL-terminated string carrying the server name, or NULL
 283  *      if none was provided.
 284  */
 285 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 286 const char * _Nullable
 287 sec_protocol_metadata_get_server_name(sec_protocol_metadata_t metadata);
 288
 289 /*!
 290  * @function sec_protocol_metadata_peers_are_equal
 291  *
 292  * @abstract
 293  *      Compare peer information for two `sec_protocol_metadata` instances.
 294  *      This comparison does not include protocol configuration options, e.g., ciphersuites.
 295  *
 296  * @param metadataA
 297  *      A `sec_protocol_metadata_t` instance.
 298  *
 299  * @param metadataB
 300  *      A `sec_protocol_metadata_t` instance.
 301  *
 302  * @return Returns true if both metadata values refer to the same peer, and false otherwise.
 303  */
 304 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 305 bool
 306 sec_protocol_metadata_peers_are_equal(sec_protocol_metadata_t metadataA, sec_protocol_metadata_t metadataB);
 307
 308 /*!
 309  * @function sec_protocol_metadata_challenge_parameters_are_equal
 310  *
 311  * @abstract
 312  *      Compare challenge-relevant information for two `sec_protocol_metadata` instances.
 313  *
 314  *      This comparison includes all information relevant to a challenge request, including:
 315  *      distinguished names, signature algorithms, and supported certificate types.
 316  *      See Section 7.4.4 of RFC5246 for more details.
 317  *
 318  * @param metadataA
 319  *      A `sec_protocol_metadata_t` instance.
 320  *
 321  * @param metadataB
 322  *      A `sec_protocol_metadata_t` instance.
 323  *
 324  * @return Returns true if both metadata values have the same challenge parameters.
 325  */
 326 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 327 bool
 328 sec_protocol_metadata_challenge_parameters_are_equal(sec_protocol_metadata_t metadataA, sec_protocol_metadata_t metadataB);
 329
 330 /*!
 331  * @function sec_protocol_metadata_create_secret
 332  *
 333  * @abstract
 334  *      Export a secret, e.g., a cryptographic key, derived from the protocol metadata using a label string.
 335  *
 336  * @param metadata
 337  *      A `sec_protocol_metadata_t` instance.
 338  *
 339  * @param label_len
 340  *      Length of the KDF label string.
 341  *
 342  * @param label
 343  *      KDF label string.
 344  *
 345  * @param exporter_length
 346  *      Length of the secret to be exported.
 347  *
 348  * @return Returns a dispatch_data_t object carrying the exported secret.
 349  */
 350 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 351 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
 352 sec_protocol_metadata_create_secret(sec_protocol_metadata_t metadata, size_t label_len,
 353                                     const char *label, size_t exporter_length);
 354
 355 /*!
 356  * @function sec_protocol_metadata_create_secret_with_context
 357  *
 358  * @abstract
 359  *      Export a secret, e.g., a cryptographic key, derived from the protocol metadata using a label and context string.
 360  *
 361  * @param metadata
 362  *      A `sec_protocol_metadata_t` instance.
 363  *
 364  * @param label_len
 365  *      Length of the KDF label string.
 366  *
 367  * @param label
 368  *      KDF label string.
 369  *
 370  * @param context_len
 371  *      Length of the KDF context string.
 372  *
 373  * @param context
 374  *      Constant opaque context value
 375  *
 376  * @param exporter_length
 377  *      Length of the secret to be exported.
 378  *
 379  * @return Returns a dispatch_data_t object carrying the exported secret.
 380  */
 381 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 382 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
 383 sec_protocol_metadata_create_secret_with_context(sec_protocol_metadata_t metadata, size_t label_len,
 384                                                  const char *label, size_t context_len,
 385                                                  const uint8_t *context, size_t exporter_length);
 386
 387 SEC_ASSUME_NONNULL_END
 388
 389 __END_DECLS
 390
 391 #endif // SecProtocolMetadata_h