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.14), ios(12.0), watchos(5.0), tvos(12.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))
 155 API_UNAVAILABLE(iosmac)
 156 SSLCipherSuite
 157 sec_protocol_metadata_get_negotiated_ciphersuite(sec_protocol_metadata_t metadata);
 158
 159 /*!
 160  * @function sec_protocol_metadata_get_early_data_accepted
 161  *
 162  * @abstract
 163  *      Determine if early data was accepted by the peer.
 164  *
 165  * @param metadata
 166  *      A `sec_protocol_metadata_t` instance.
 167  *
 168  * @return A bool indicating if early data was accepted.
 169  */
 170 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 171 bool
 172 sec_protocol_metadata_get_early_data_accepted(sec_protocol_metadata_t metadata);
 173
 174 #ifdef __BLOCKS__
 175 /*!
 176  * @function sec_protocol_metadata_access_peer_certificate_chain
 177  *
 178  * @abstract
 179  *      Get the certificate chain of the protocol instance peer.
 180  *
 181  * @param metadata
 182  *      A `sec_protocol_metadata_t` instance.
 183  *
 184  * @param handler
 185  *      A block to invoke one or more times with sec_certificate_t objects
 186  *
 187  * @return Returns true if the peer certificates were accessible, false otherwise.
 188  */
 189 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 190 bool
 191 sec_protocol_metadata_access_peer_certificate_chain(sec_protocol_metadata_t metadata,
 192                                                     void (^handler)(sec_certificate_t certificate));
 193
 194 /*!
 195  * @function sec_protocol_metadata_copy_ocsp_response
 196  *
 197  * @abstract
 198  *      Get the OCSP response from the protocol instance peer.
 199  *
 200  * @param metadata
 201  *      A `sec_protocol_metadata_t` instance.
 202  *
 203  * @param handler
 204  *      A block to invoke one or more times with OCSP data
 205  *
 206  * @return Returns true if the OSCP response was accessible, false otherwise.
 207  */
 208 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 209 bool
 210 sec_protocol_metadata_access_ocsp_response(sec_protocol_metadata_t metadata,
 211                                            void (^handler)(dispatch_data_t ocsp_data));
 212
 213 /*!
 214  * @function sec_protocol_metadata_access_supported_signature_algorithms
 215  *
 216  * @abstract
 217  *      Get the signature algorithms supported by the peer. Clients may call this
 218  *      in response to a challenge block.
 219  *
 220  * @param metadata
 221  *      A `sec_protocol_metadata_t` instance.
 222  *
 223  * @param handler
 224  *      A block to invoke one or more times with OCSP data
 225  *
 226  * @return Returns true if the supported signature list was accessible, false otherwise.
 227  */
 228 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 229 bool
 230 sec_protocol_metadata_access_supported_signature_algorithms(sec_protocol_metadata_t metadata,
 231                                                             void (^handler)(uint16_t signature_algorithm));
 232
 233 /*!
 234  * @function sec_protocol_metadata_access_distinguished_names
 235  *
 236  * @abstract
 237  *      Get the X.509 Distinguished Names from the protocol instance peer.
 238  *
 239  * @param metadata
 240  *      A `sec_protocol_metadata_t` instance.
 241  *
 242  * @param handler
 243  *      A block to invoke one or more times with distinguished_name data
 244  *
 245  * @return Returns true if the distinguished names were accessible, false otherwise.
 246  */
 247 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 248 bool
 249 sec_protocol_metadata_access_distinguished_names(sec_protocol_metadata_t metadata,
 250                                                  void (^handler)(dispatch_data_t distinguished_name));
 251
 252 /*!
 253  * @function sec_protocol_metadata_access_pre_shared_keys
 254  *
 255  * @abstract
 256  *      Get the PSKs supported by the local instance.
 257  *
 258  * @param metadata
 259  *      A `sec_protocol_metadata_t` instance.
 260  *
 261  * @param handler
 262  *      A block to invoke one or more times with tuples of dispatch_data_t objects carrying PSKs and their corresponding identities.
 263  *
 264  * @return Returns true if the PSKs were accessible, false otherwise.
 265  */
 266 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 267 bool
 268 sec_protocol_metadata_access_pre_shared_keys(sec_protocol_metadata_t metadata, void (^handler)(dispatch_data_t psk, dispatch_data_t psk_identity));
 269
 270 #endif // __BLOCKS__
 271
 272 /*!
 273  * @function sec_protocol_metadata_get_server_name
 274  *
 275  * @abstract
 276  *      Obtain the server name offered by a client or server during
 277  *      connection establishmet. This is the value commonly carried
 278  *      in the TLS SNI extesion.
 279  *
 280  * @param metadata
 281  *      A `sec_protocol_metadata_t` instance.
 282  *
 283  * @return Returns A NULL-terminated string carrying the server name, or NULL
 284  *      if none was provided.
 285  */
 286 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 287 const char * _Nullable
 288 sec_protocol_metadata_get_server_name(sec_protocol_metadata_t metadata);
 289
 290 /*!
 291  * @function sec_protocol_metadata_peers_are_equal
 292  *
 293  * @abstract
 294  *      Compare peer information for two `sec_protocol_metadata` instances.
 295  *      This comparison does not include protocol configuration options, e.g., ciphersuites.
 296  *
 297  * @param metadataA
 298  *      A `sec_protocol_metadata_t` instance.
 299  *
 300  * @param metadataB
 301  *      A `sec_protocol_metadata_t` instance.
 302  *
 303  * @return Returns true if both metadata values refer to the same peer, and false otherwise.
 304  */
 305 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 306 bool
 307 sec_protocol_metadata_peers_are_equal(sec_protocol_metadata_t metadataA, sec_protocol_metadata_t metadataB);
 308
 309 /*!
 310  * @function sec_protocol_metadata_challenge_parameters_are_equal
 311  *
 312  * @abstract
 313  *      Compare challenge-relevant information for two `sec_protocol_metadata` instances.
 314  *
 315  *      This comparison includes all information relevant to a challenge request, including:
 316  *      distinguished names, signature algorithms, and supported certificate types.
 317  *      See Section 7.4.4 of RFC5246 for more details.
 318  *
 319  * @param metadataA
 320  *      A `sec_protocol_metadata_t` instance.
 321  *
 322  * @param metadataB
 323  *      A `sec_protocol_metadata_t` instance.
 324  *
 325  * @return Returns true if both metadata values have the same challenge parameters.
 326  */
 327 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 328 bool
 329 sec_protocol_metadata_challenge_parameters_are_equal(sec_protocol_metadata_t metadataA, sec_protocol_metadata_t metadataB);
 330
 331 /*!
 332  * @function sec_protocol_metadata_create_secret
 333  *
 334  * @abstract
 335  *      Export a secret, e.g., a cryptographic key, derived from the protocol metadata using a label string.
 336  *
 337  * @param metadata
 338  *      A `sec_protocol_metadata_t` instance.
 339  *
 340  * @param label_len
 341  *      Length of the KDF label string.
 342  *
 343  * @param label
 344  *      KDF label string.
 345  *
 346  * @param exporter_length
 347  *      Length of the secret to be exported.
 348  *
 349  * @return Returns a dispatch_data_t object carrying the exported secret.
 350  */
 351 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 352 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
 353 sec_protocol_metadata_create_secret(sec_protocol_metadata_t metadata, size_t label_len,
 354                                     const char *label, size_t exporter_length);
 355
 356 /*!
 357  * @function sec_protocol_metadata_create_secret_with_context
 358  *
 359  * @abstract
 360  *      Export a secret, e.g., a cryptographic key, derived from the protocol metadata using a label and context string.
 361  *
 362  * @param metadata
 363  *      A `sec_protocol_metadata_t` instance.
 364  *
 365  * @param label_len
 366  *      Length of the KDF label string.
 367  *
 368  * @param label
 369  *      KDF label string.
 370  *
 371  * @param context_len
 372  *      Length of the KDF context string.
 373  *
 374  * @param context
 375  *      Constant opaque context value
 376  *
 377  * @param exporter_length
 378  *      Length of the secret to be exported.
 379  *
 380  * @return Returns a dispatch_data_t object carrying the exported secret.
 381  */
 382 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 383 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
 384 sec_protocol_metadata_create_secret_with_context(sec_protocol_metadata_t metadata, size_t label_len,
 385                                                  const char *label, size_t context_len,
 386                                                  const uint8_t *context, size_t exporter_length);
 387
 388 SEC_ASSUME_NONNULL_END
 389
 390 __END_DECLS
 391
 392 #endif // SecProtocolMetadata_h