X-Git-Url: https://git.saurik.com/apple/security.git/blobdiff_plain/5c19dc3ae3bd8e40a9c028b0deddd50ff337692c..dd5fb164cf5b32c462296bc65e289e100f74b59a:/OSX/libsecurity_ssl/lib/SecureTransport.h diff --git a/OSX/libsecurity_ssl/lib/SecureTransport.h b/OSX/libsecurity_ssl/lib/SecureTransport.h index f6e5fc6b..c753a278 100644 --- a/OSX/libsecurity_ssl/lib/SecureTransport.h +++ b/OSX/libsecurity_ssl/lib/SecureTransport.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999-2002,2005-2014 Apple Inc. All Rights Reserved. + * Copyright (c) 1999-2002,2005-2016 Apple Inc. All Rights Reserved. * * @APPLE_LICENSE_HEADER_START@ * @@ -84,19 +84,20 @@ typedef const void * SSLConnectionRef; /* SSL Protocol version */ typedef CF_ENUM(int, SSLProtocol) { - kSSLProtocolUnknown = 0, /* no protocol negotiated/specified; use default */ - kSSLProtocol3 = 2, /* SSL 3.0 */ - kTLSProtocol1 = 4, /* TLS 1.0 */ - kTLSProtocol11 = 7, /* TLS 1.1 */ - kTLSProtocol12 = 8, /* TLS 1.2 */ - kDTLSProtocol1 = 9, /* DTLS 1.0 */ - - /* DEPRECATED on iOS */ - kSSLProtocol2 = 1, /* SSL 2.0 */ - kSSLProtocol3Only = 3, /* SSL 3.0 Only */ - kTLSProtocol1Only = 5, /* TLS 1.0 Only */ - kSSLProtocolAll = 6, /* All TLS supported protocols */ - + kSSLProtocolUnknown = 0, /* no protocol negotiated/specified; use default */ + kSSLProtocol3 = 2, /* SSL 3.0 */ + kTLSProtocol1 = 4, /* TLS 1.0 */ + kTLSProtocol11 = 7, /* TLS 1.1 */ + kTLSProtocol12 = 8, /* TLS 1.2 */ + kDTLSProtocol1 = 9, /* DTLS 1.0 */ + kTLSProtocol13 = 10, /* TLS 1.3 */ + + kTLSProtocolMaxSupported = 999, /* Max system-supported version */ + + kSSLProtocol2 = 1, /* SSL 2.0. DEPRECATED on iOS. */ + kSSLProtocol3Only = 3, /* SSL 3.0. DEPRECATED on iOS. */ + kTLSProtocol1Only = 5, /* TLS 1.0 Only. DEPRECATED on iOS. */ + kSSLProtocolAll = 6, /* All TLS supported protocols. DEPRECATED on iOS. */ }; /* SSL session options */ @@ -147,7 +148,14 @@ typedef CF_ENUM(int, SSLSessionOption) { * Set this option to break from a client hello in order to check for SNI */ kSSLSessionOptionBreakOnClientHello = 7, - + /* + * Set this option to Allow renegotations. False by default. + */ + kSSLSessionOptionAllowRenegotiation = 8, + /* + * Set this option to enable session tickets. False by default. + */ + kSSLSessionOptionEnableSessionTickets = 9, }; /* State of an SSLSession */ @@ -171,16 +179,16 @@ typedef CF_ENUM(int, SSLClientCertificateState) { /* * Server side: We asked for a cert, client sent one, we validated * it OK. App can inspect the cert via - * SSLGetPeerCertificates(). + * SSLCopyPeerCertificates(). * Client side: server asked for one, we sent it. */ kSSLClientCertSent, /* * Client sent a cert but failed validation. Server side only. - * Server app can inspect the cert via SSLGetPeerCertificates(). + * Server app can inspect the cert via SSLCopyPeerCertificates(). */ kSSLClientCertRejected -} ; +}; /* * R/W functions. The application using this library provides @@ -303,11 +311,58 @@ typedef CF_ENUM(int, SSLConnectionType) kSSLDatagramType }; -typedef CF_ENUM(int, SSLSessionStrengthPolicy) -{ - kSSLSessionStrengthPolicyDefault, - kSSLSessionStrengthPolicyATSv1 -}; +/* + * Predefined TLS configurations constants + */ + +/* Default configuration (has 3DES, no RC4) */ +extern const CFStringRef kSSLSessionConfig_default +__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0); + +/* ATS v1 Config: TLS v1.2, only PFS ciphersuites */ +extern const CFStringRef kSSLSessionConfig_ATSv1 +__OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* ATS v1 Config without PFS: TLS v1.2, include non PFS ciphersuites */ +extern const CFStringRef kSSLSessionConfig_ATSv1_noPFS +__OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* TLS v1.2 to TLS v1.0, with default ciphersuites (no 3DES, no RC4) */ +extern const CFStringRef kSSLSessionConfig_standard +__OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* TLS v1.2 to TLS v1.0, with default ciphersuites + RC4 + 3DES */ +extern const CFStringRef kSSLSessionConfig_RC4_fallback +__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0); + +/* TLS v1.0 only, with default ciphersuites + fallback SCSV */ +extern const CFStringRef kSSLSessionConfig_TLSv1_fallback +__OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* TLS v1.0, with default ciphersuites + RC4 + 3DES + fallback SCSV */ +extern const CFStringRef kSSLSessionConfig_TLSv1_RC4_fallback +__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0); + +/* TLS v1.2 to TLS v1.0, defaults + RC4 + DHE ciphersuites */ +extern const CFStringRef kSSLSessionConfig_legacy +__OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* TLS v1.2 to TLS v1.0, default + RC4 + DHE ciphersuites */ +extern const CFStringRef kSSLSessionConfig_legacy_DHE +__OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* TLS v1.2, anonymous ciphersuites only */ +extern const CFStringRef kSSLSessionConfig_anonymous +__OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* TLS v1.2 to TLS v1.0, has 3DES, no RC4 */ +extern const CFStringRef kSSLSessionConfig_3DES_fallback +__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0); + +/* TLS v1.0, with default ciphersuites + 3DES, no RC4 */ +extern const CFStringRef kSSLSessionConfig_TLSv1_3DES_fallback +__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_13,__IPHONE_5_0,__IPHONE_11_0); + /****************** *** Public API *** @@ -415,6 +470,19 @@ SSLSetIOFuncs (SSLContextRef context, SSLWriteFunc writeFunc) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* + * Set a predefined configuration for the SSL Session + * + * This currently affect enabled protocol versions, + * enabled ciphersuites, and the kSSLSessionOptionFallback + * session option. + */ +OSStatus +SSLSetSessionConfig(SSLContextRef context, + CFStringRef config) + __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0); + /* * Set the minimum SSL protocol version allowed. Optional. * The default is the lower supported protocol. @@ -449,13 +517,13 @@ SSLGetProtocolVersionMin (SSLContextRef context, * * This can only be called when no session is active. * - * For TLS contexts, legal values for minVersion are : + * For TLS contexts, legal values for maxVersion are : * kSSLProtocol3 * kTLSProtocol1 * kTLSProtocol11 * kTLSProtocol12 * - * For DTLS contexts, legal values for minVersion are : + * For DTLS contexts, legal values for maxVersion are : * kDTLSProtocol1 */ OSStatus @@ -581,7 +649,7 @@ SSLGetProtocolVersion (SSLContextRef context, */ OSStatus SSLSetCertificate (SSLContextRef context, - CFArrayRef certRefs) + CFArrayRef _Nullable certRefs) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* @@ -634,6 +702,25 @@ SSLGetPeerDomainName (SSLContextRef context, size_t *peerNameLen) // IN/OUT __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); + +/* + * Determine the buffer size needed for SSLCopyRequestedPeerNameLength(). + */ +OSStatus +SSLCopyRequestedPeerName (SSLContextRef context, + char *peerName, + size_t *peerNameLen) + __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0); + +/* + * Server Only: obtain the hostname specified by the client in the ServerName extension (SNI) + */ +OSStatus +SSLCopyRequestedPeerNameLength (SSLContextRef ctx, + size_t *peerNameLen) + __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0); + + /* * Specify the Datagram TLS Hello Cookie. * This is to be called for server side only and is optional. @@ -723,6 +810,15 @@ SSLGetEnabledCiphers (SSLContextRef context, size_t *numCiphers) /* IN/OUT */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); +/* + * Forcibly enable or disable session ticket resumption. By default, session tickets + * are disabled. + */ +OSStatus +SSLSetSessionTicketsEnabled (SSLContextRef context, + Boolean enabled) + __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0); + #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* @@ -1080,6 +1176,48 @@ SSLGetNegotiatedCipher (SSLContextRef context, SSLCipherSuite *cipherSuite) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); +/* + * Set the ALPN protocols to be passed in the ALPN negotiation. + * This is the list of supported application-layer protocols supported. + * + * The protocols parameter must be an array of CFStringRef values + * with ASCII-encoded reprensetations of the supported protocols, e.g., "http/1.1". + * + * See RFC 7301 for more information. + */ +OSStatus +SSLSetALPNProtocols (SSLContextRef context, + CFArrayRef protocols) + __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0); + +/* + * Get the ALPN protocols associated with this SSL context. + * This is the list of supported application-layer protocols supported. + * + * The resultant protocols array will contain CFStringRef values containing + * ASCII-encoded representations of the supported protocols, e.g., "http/1.1". + * + * See RFC 7301 for more information. + * + * Note: The `protocols` pointer must be NULL, otherwise the copy will fail. + * This function will allocate memory for the CFArrayRef container + * if there is data to provide. Otherwise, the pointer will remain NULL. + */ +OSStatus +SSLCopyALPNProtocols (SSLContextRef context, + CFArrayRef __nullable * __nonnull protocols) /* RETURNED */ + __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0); + +/* + * Set the OCSP response for the given SSL session. + * + * The response parameter must be a non-NULL CFDataRef containing the + * bytes of the OCSP response. + */ +OSStatus +SSLSetOCSPResponse (SSLContextRef context, + CFDataRef __nonnull response) +__OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0); /******************************************************** *** Session context configuration, server side only. *** @@ -1290,6 +1428,17 @@ OSStatus SSLHandshake (SSLContextRef context) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); +/* + * Server Only: Request renegotation. + * This will return an error if the server is already renegotiating, or if the session is closed. + * After this return without error, the application should call SSLHandshake() and/or SSLRead() as + * for the original handshake. + */ +OSStatus +SSLReHandshake (SSLContextRef context) + __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0); + + /* * Normal application-level read/write. On both of these, a errSSLWouldBlock * return and a partially completed transfer - or even zero bytes transferred - @@ -1343,12 +1492,13 @@ SSLClose (SSLContextRef context) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* - * Set the minimum acceptable strength of policy to be negotiated for an - * ATS session + * Set the status of a SSLContextRef. This is to be done after handling + * steps of the SSL handshake such as server certificate validation. */ OSStatus -SSLSetSessionStrengthPolicy(SSLContextRef context, - SSLSessionStrengthPolicy policyStrength); +SSLSetError (SSLContextRef context, + OSStatus status) + __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0); CF_IMPLICIT_BRIDGING_DISABLED CF_ASSUME_NONNULL_END