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/SecBase.h>
  30 #include <Security/SecureTransport.h>
  31
  32 #include <dispatch/dispatch.h>
  33 #include <os/object.h>
  34
  35 /*!
  36  * The following diagram shows how clients interact with sec_protocol_options
  37  * and sec_protocol_metadata when configuring and using network security protocols.
  38  *
  39  *                    +--------+
  40  *                    | Client |
  41  *                    +-+---/ \+
  42  *                      |    |
  43  *        +-------------+    +-------------+
  44  *        | (1) set             (2) get    |
  45  *        | options             metadata   |
  46  * +-----\ /---------------+  +------------+----------+
  47  * | sec_protocol_options  |  | sec_protocol_metadata |
  48  * +-----------------------+  +-----------------------+
  49  *
  50  * Clients configure security protocols with `sec_protocol_options` instances.
  51  * And they inspect protocol instances using `sec_protocol_metadata` instances.
  52  */
  53
  54 #ifndef SEC_OBJECT_IMPL
  55 /*!
  56  * A `sec_protocol_metadata` instance conatins read-only properties of a connected and configured
  57  * security protocol. Clients use this object to read information about a protocol instance. Properties
  58  * include, for example, the negotiated TLS version, ciphersuite, and peer certificates.
  59  */
  60 SEC_OBJECT_DECL(sec_protocol_metadata);
  61 #endif // !SEC_OBJECT_IMPL
  62
  63 __BEGIN_DECLS
  64
  65 SEC_ASSUME_NONNULL_BEGIN
  66
  67 /*!
  68  * @function sec_protocol_metadata_get_negotiated_protocol
  69  *
  70  * @abstract
  71  *      Get the application protocol negotiated, e.g., via the TLS ALPN extension.
  72  *
  73  * @param metadata
  74  *      A `sec_protocol_metadata_t` instance.
  75  *
  76  * @return A NULL-terminated string carrying the negotiated protocol.
  77  */
  78 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  79 const char * _Nullable
  80 sec_protocol_metadata_get_negotiated_protocol(sec_protocol_metadata_t metadata);
  81
  82 /*!
  83  * @function sec_protocol_metadata_copy_peer_public_key
  84  *
  85  * @abstract
  86  *      Get the protocol instance peer's public key.
  87  *
  88  * @param metadata
  89  *      A `sec_protocol_metadata_t` instance.
  90  *
  91  * @return A `dispatch_data_t` containing the peer's raw public key.
  92  */
  93 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
  94 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
  95 sec_protocol_metadata_copy_peer_public_key(sec_protocol_metadata_t metadata);
  96
  97 /*!
  98  * @function sec_protocol_metadata_get_negotiated_protocol_version
  99  *
 100  * @abstract
 101  *      Get the negotiated TLS version.
 102  *
 103  * @param metadata
 104  *      A `sec_protocol_metadata_t` instance.
 105  *
 106  * @return A SSLProtocol enum of the TLS version.
 107  */
 108 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 109 SSLProtocol
 110 sec_protocol_metadata_get_negotiated_protocol_version(sec_protocol_metadata_t metadata);
 111
 112 /*!
 113  * @function sec_protocol_metadata_get_negotiated_ciphersuite
 114  *
 115  * @abstract
 116  *      Get the negotiated TLS ciphersuite.
 117  *
 118  * @param metadata
 119  *      A `sec_protocol_metadata_t` instance.
 120  *
 121  * @return A SSLCipherSuite.
 122  */
 123 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 124 SSLCipherSuite
 125 sec_protocol_metadata_get_negotiated_ciphersuite(sec_protocol_metadata_t metadata);
 126
 127 /*!
 128  * @function sec_protocol_metadata_get_early_data_accepted
 129  *
 130  * @abstract
 131  *      Determine if early data was accepted by the peer.
 132  *
 133  * @param metadata
 134  *      A `sec_protocol_metadata_t` instance.
 135  *
 136  * @return A bool indicating if early data was accepted.
 137  */
 138 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 139 bool
 140 sec_protocol_metadata_get_early_data_accepted(sec_protocol_metadata_t metadata);
 141
 142 #ifdef __BLOCKS__
 143 /*!
 144  * @function sec_protocol_metadata_access_peer_certificate_chain
 145  *
 146  * @abstract
 147  *      Get the certificate chain of the protocol instance peer.
 148  *
 149  * @param metadata
 150  *      A `sec_protocol_metadata_t` instance.
 151  *
 152  * @param handler
 153  *      A block to invoke one or more times with sec_certificate_t objects
 154  *
 155  * @return Returns true if the peer certificates were accessible, false otherwise.
 156  */
 157 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 158 bool
 159 sec_protocol_metadata_access_peer_certificate_chain(sec_protocol_metadata_t metadata,
 160                                                     void (^handler)(sec_certificate_t certificate));
 161
 162 /*!
 163  * @function sec_protocol_metadata_copy_ocsp_response
 164  *
 165  * @abstract
 166  *      Get the OCSP response from the protocol instance peer.
 167  *
 168  * @param metadata
 169  *      A `sec_protocol_metadata_t` instance.
 170  *
 171  * @param handler
 172  *      A block to invoke one or more times with OCSP data
 173  *
 174  * @return Returns true if the OSCP response was accessible, false otherwise.
 175  */
 176 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 177 bool
 178 sec_protocol_metadata_access_ocsp_response(sec_protocol_metadata_t metadata,
 179                                            void (^handler)(dispatch_data_t ocsp_data));
 180
 181 /*!
 182  * @function sec_protocol_metadata_access_supported_signature_algorithms
 183  *
 184  * @abstract
 185  *      Get the signature algorithms supported by the peer. Clients may call this
 186  *      in response to a challenge block.
 187  *
 188  * @param metadata
 189  *      A `sec_protocol_metadata_t` instance.
 190  *
 191  * @param handler
 192  *      A block to invoke one or more times with OCSP data
 193  *
 194  * @return Returns true if the supported signature list was accessible, false otherwise.
 195  */
 196 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 197 bool
 198 sec_protocol_metadata_access_supported_signature_algorithms(sec_protocol_metadata_t metadata,
 199                                                             void (^handler)(uint16_t signature_algorithm));
 200
 201 /*!
 202  * @function sec_protocol_metadata_access_distinguished_names
 203  *
 204  * @abstract
 205  *      Get the X.509 Distinguished Names from the protocol instance peer.
 206  *
 207  * @param metadata
 208  *      A `sec_protocol_metadata_t` instance.
 209  *
 210  * @param handler
 211  *      A block to invoke one or more times with distinguished_name data
 212  *
 213  * @return Returns true if the distinguished names were accessible, false otherwise.
 214  */
 215 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 216 bool
 217 sec_protocol_metadata_access_distinguished_names(sec_protocol_metadata_t metadata,
 218                                                  void (^handler)(dispatch_data_t distinguished_name));
 219 #endif // __BLOCKS__
 220
 221 /*!
 222  * @function sec_protocol_metadata_peers_are_equal
 223  *
 224  * @abstract
 225  *      Compare peer information for two `sec_protocol_metadata` instances.
 226  *      This comparison does not include protocol configuration options, e.g., ciphersuites.
 227  *
 228  * @param metadataA
 229  *      A `sec_protocol_metadata_t` instance.
 230  *
 231  * @param metadataB
 232  *      A `sec_protocol_metadata_t` instance.
 233  *
 234  * @return Returns true if both metadata values refer to the same peer, and false otherwise.
 235  */
 236 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 237 bool
 238 sec_protocol_metadata_peers_are_equal(sec_protocol_metadata_t metadataA, sec_protocol_metadata_t metadataB);
 239
 240 /*!
 241  * @function sec_protocol_metadata_challenge_parameters_are_equal
 242  *
 243  * @abstract
 244  *      Compare challenge-relevant information for two `sec_protocol_metadata` instances.
 245  *
 246  *      This comparison includes all information relevant to a challenge request, including:
 247  *      distinguished names, signature algorithms, and supported certificate types.
 248  *      See Section 7.4.4 of RFC5246 for more details.
 249  *
 250  * @param metadataA
 251  *      A `sec_protocol_metadata_t` instance.
 252  *
 253  * @param metadataB
 254  *      A `sec_protocol_metadata_t` instance.
 255  *
 256  * @return Returns true if both metadata values have the same challenge parameters.
 257  */
 258 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 259 bool
 260 sec_protocol_metadata_challenge_parameters_are_equal(sec_protocol_metadata_t metadataA, sec_protocol_metadata_t metadataB);
 261
 262 /*!
 263  * @function sec_protocol_metadata_create_secret
 264  *
 265  * @abstract
 266  *      Export a secret, e.g., a cryptographic key, derived from the protocol metadata using a label string.
 267  *
 268  * @param metadata
 269  *      A `sec_protocol_metadata_t` instance.
 270  *
 271  * @param label_len
 272  *      Length of the KDF label string.
 273  *
 274  * @param label
 275  *      KDF label string.
 276  *
 277  * @param exporter_length
 278  *      Length of the secret to be exported.
 279  *
 280  * @return Returns a dispatch_data_t object carrying the exported secret.
 281  */
 282 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 283 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
 284 sec_protocol_metadata_create_secret(sec_protocol_metadata_t metadata, size_t label_len,
 285                                     const char *label, size_t exporter_length);
 286
 287 /*!
 288  * @function sec_protocol_metadata_create_secret_with_context
 289  *
 290  * @abstract
 291  *      Export a secret, e.g., a cryptographic key, derived from the protocol metadata using a label and context string.
 292  *
 293  * @param metadata
 294  *      A `sec_protocol_metadata_t` instance.
 295  *
 296  * @param label_len
 297  *      Length of the KDF label string.
 298  *
 299  * @param label
 300  *      KDF label string.
 301  *
 302  * @param context_len
 303  *      Length of the KDF context string.
 304  *
 305  * @param context
 306  *      Constant opaque context value
 307  *
 308  * @param exporter_length
 309  *      Length of the secret to be exported.
 310  *
 311  * @return Returns a dispatch_data_t object carrying the exported secret.
 312  */
 313 API_AVAILABLE(macos(10.14), ios(12.0), watchos(5.0), tvos(12.0))
 314 SEC_RETURNS_RETAINED _Nullable dispatch_data_t
 315 sec_protocol_metadata_create_secret_with_context(sec_protocol_metadata_t metadata, size_t label_len,
 316                                                  const char *label, size_t context_len,
 317                                                  const uint8_t *context, size_t exporter_length);
 318
 319 SEC_ASSUME_NONNULL_END
 320
 321 __END_DECLS
 322
 323 #endif // SecProtocolMetadata_h