Security-58286.20.16.tar.gz

[apple/security.git] / OSX / libsecurity_ssl / lib / SecureTransport.h

diff --git a/OSX/libsecurity_ssl/lib/SecureTransport.h b/OSX/libsecurity_ssl/lib/SecureTransport.h
index 061ae594ac77f33a86bb69a1c30511426c8a9368..c753a2789617a8d93b6b08b50ac0db805b95d29a 100644 (file)
--- 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@
  * 
  *
  * @APPLE_LICENSE_HEADER_START@
  * 


@@ -84,19 +84,20 @@ typedef const void *                SSLConnectionRef;
 
 /* SSL Protocol version */
 typedef CF_ENUM(int, SSLProtocol) {
 
 /* 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 */
 };
 
 /* 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 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 */
 };
 
 /* 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
        /*
         * 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.
         * 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
         */
        kSSLClientCertRejected

-} ;
+};

 
 /*
  * R/W functions. The application using this library provides
 
 /*
  * R/W functions. The application using this library provides


@@ -303,6 +311,58 @@ typedef CF_ENUM(int, SSLConnectionType)
     kSSLDatagramType
 };
 
     kSSLDatagramType
 };
 

+/*
+ * 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 ***
 
 /******************
  *** Public API ***


@@ -410,6 +470,19 @@ SSLSetIOFuncs                              (SSLContextRef          context,
                                                         SSLWriteFunc           writeFunc)
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
                                                         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.
 /*
  * Set the minimum SSL protocol version allowed. Optional.
  * The default is the lower supported protocol.


@@ -444,13 +517,13 @@ SSLGetProtocolVersionMin  (SSLContextRef      context,
  *
  * This can only be called when no session is active.
  *
  *
  * 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
  *
  *             kSSLProtocol3
  *             kTLSProtocol1
  *             kTLSProtocol11
  *             kTLSProtocol12
  *

- * For DTLS contexts, legal values for minVersion are :
+ * For DTLS contexts, legal values for maxVersion are :

  *      kDTLSProtocol1
  */
 OSStatus
  *      kDTLSProtocol1
  */
 OSStatus


@@ -576,7 +649,7 @@ SSLGetProtocolVersion               (SSLContextRef          context,
  */
 OSStatus
 SSLSetCertificate                      (SSLContextRef          context,
  */
 OSStatus
 SSLSetCertificate                      (SSLContextRef          context,

-                                                        CFArrayRef                     certRefs)
+                                                        CFArrayRef                     _Nullable certRefs)

        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
 /*
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
 /*


@@ -629,6 +702,25 @@ SSLGetPeerDomainName               (SSLContextRef          context,
                                                         size_t                         *peerNameLen)   // IN/OUT
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
                                                         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.
 /*
  * Specify the Datagram TLS Hello Cookie.
  * This is to be called for server side only and is optional.


@@ -718,18 +810,14 @@ SSLGetEnabledCiphers              (SSLContextRef                  context,
                                                         size_t                                 *numCiphers)    /* IN/OUT */
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
                                                         size_t                                 *numCiphers)    /* IN/OUT */
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 

-
-/* Deprecated, does nothing */
-typedef CF_ENUM(int, SSLSessionStrengthPolicy)
-{
-    kSSLSessionStrengthPolicyDefault,
-    kSSLSessionStrengthPolicyATSv1,
-    kSSLSessionStrengthPolicyATSv1_noPFS,
-};
-
+/*
+ * Forcibly enable or disable session ticket resumption. By default, session tickets
+ * are disabled.
+ */

 OSStatus
 OSStatus

-SSLSetSessionStrengthPolicy(SSLContextRef context,
-                            SSLSessionStrengthPolicy policyStrength);
+SSLSetSessionTicketsEnabled     (SSLContextRef          context,
+                                 Boolean                enabled)
+    __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);

 
 
 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
 
 
 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))


@@ -1088,6 +1176,48 @@ SSLGetNegotiatedCipher           (SSLContextRef          context,
                                                         SSLCipherSuite         *cipherSuite)
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
                                                         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. ***
 
 /********************************************************
  *** Session context configuration, server side only. ***


@@ -1298,6 +1428,17 @@ OSStatus
 SSLHandshake                           (SSLContextRef          context)
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
 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 -
 /*
  * Normal application-level read/write. On both of these, a errSSLWouldBlock
  * return and a partially completed transfer - or even zero bytes transferred -


@@ -1350,6 +1491,15 @@ OSStatus
 SSLClose                                       (SSLContextRef          context)
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 
 SSLClose                                       (SSLContextRef          context)
        __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0);
 

+/*
+ * Set the status of a SSLContextRef. This is to be done after handling 
+ * steps of the SSL handshake such as server certificate validation.
+ */
+OSStatus
+SSLSetError                 (SSLContextRef      context,
+                             OSStatus           status)
+    __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
+

 CF_IMPLICIT_BRIDGING_DISABLED
 CF_ASSUME_NONNULL_END
 
 CF_IMPLICIT_BRIDGING_DISABLED
 CF_ASSUME_NONNULL_END