Support s2n-tls on macOS (#990)

Author: sfod

.github/workflows/ci.yml

@@ -238,6 +238,46 @@ jobs:
         ./builder build -p ${{ env.PACKAGE_NAME }} --spec=downstream
         python3 codebuild/macos_compatibility_check.py
 
+  macos-s2n:
+    runs-on: macos-15 #latest
+    env:
+      AWS_CRT_USE_NON_FIPS_TLS_13: 1
+    steps:
+    - uses: aws-actions/configure-aws-credentials@v4
+      with:
+        role-to-assume: ${{ env.CRT_CI_ROLE }}
+        aws-region: ${{ env.AWS_DEFAULT_REGION }}
+    - name: Checkout Sources
+      uses: actions/checkout@v4
+      with:
+        submodules: true
+    - name: Build ${{ env.PACKAGE_NAME }} + consumers
+      run: |
+        python3 -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder')"
+        chmod a+x builder
+        ./builder build -p ${{ env.PACKAGE_NAME }} --spec=downstream
+        python3 codebuild/macos_compatibility_check.py
+
+  macos-x64-s2n:
+    runs-on: macos-15-large #latest
+    env:
+      AWS_CRT_USE_NON_FIPS_TLS_13: 1
+    steps:
+    - uses: aws-actions/configure-aws-credentials@v4
+      with:
+        role-to-assume: ${{ env.CRT_CI_ROLE }}
+        aws-region: ${{ env.AWS_DEFAULT_REGION }}
+    - name: Checkout Sources
+      uses: actions/checkout@v4
+      with:
+        submodules: true
+    - name: Build ${{ env.PACKAGE_NAME }} + consumers
+      run: |
+        python3 -c "from urllib.request import urlretrieve; urlretrieve('${{ env.BUILDER_HOST }}/${{ env.BUILDER_SOURCE }}/${{ env.BUILDER_VERSION }}/builder.pyz?run=${{ env.RUN }}', 'builder')"
+        chmod a+x builder
+        ./builder build -p ${{ env.PACKAGE_NAME }} --spec=downstream
+        python3 codebuild/macos_compatibility_check.py
+
   # check that docs can still build
   check-docs:
     runs-on: ubuntu-22.04 # use same version as docs.yml

CMakeLists.txt

@@ -29,7 +29,9 @@ if (BUILD_DEPS)
     set(IN_SOURCE_BUILD ON)
     set(BUILD_TESTING OFF)
     add_subdirectory(crt/aws-c-common)
-    if (UNIX AND NOT APPLE)
+    # Build s2n-tls and aws-lc on all Unix platforms except non-macOS Apple (iOS, tvOS).
+    # On macOS (Darwin), both Secure Transport and s2n are built; the TLS backend is selected at runtime.
+    if (UNIX AND (NOT APPLE OR CMAKE_SYSTEM_NAME STREQUAL "Darwin"))
         include(AwsPrebuildDependency)
 
         set(AWSLC_CMAKE_ARGUMENTS
@@ -72,7 +74,18 @@ if (BUILD_DEPS)
         )
 
         set(UNSAFE_TREAT_WARNINGS_AS_ERRORS OFF CACHE BOOL "Disable warnings-as-errors when building S2N")
+        # On Intel Macs, Homebrew installs to /usr/local which is in the default header search path.
+        # Without this, s2n's libcrypto detection picks up Homebrew's OpenSSL instead of bundled aws-lc.
+        # ARM Macs use /opt/homebrew (not in default search paths) so they don't need this.
+        if(APPLE AND CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "x86_64")
+            set(_AWS_CRT_PREV_NO_SYSTEM_FROM_IMPORTED ${CMAKE_NO_SYSTEM_FROM_IMPORTED})
+            set(CMAKE_NO_SYSTEM_FROM_IMPORTED ON)
+        endif()
         add_subdirectory(crt/s2n)
+        if(APPLE AND CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "x86_64")
+            set(CMAKE_NO_SYSTEM_FROM_IMPORTED ${_AWS_CRT_PREV_NO_SYSTEM_FROM_IMPORTED})
+            unset(_AWS_CRT_PREV_NO_SYSTEM_FROM_IMPORTED)
+        endif()
     endif()
     add_subdirectory(crt/aws-c-sdkutils)
     add_subdirectory(crt/aws-c-io)

README.md

@@ -188,10 +188,11 @@ In this way, it reduces the native image size around 30% (142 MB to 101 MB for a
 
 The CRT uses native libraries for TLS, rather than Java's typical
 Secure Socket Extension (JSSE), KeyStore, and TrustStore.
-On [Windows](https://learn.microsoft.com/en-us/windows/win32/security) and
-[Apple](https://developer.apple.com/documentation/security) devices,
-the built-in OS libraries are used.
+On [Windows](https://learn.microsoft.com/en-us/windows/win32/security),
+the built-in OS library (Schannel) is used.
 On Linux/Unix/etc [s2n-tls](https://github.com/aws/s2n-tls) is used.
+On macOS, the default TLS backend is Apple Secure Transport, but an
+alternative backend (s2n-tls) can be selected at runtime (see below).
 
 If you need to add certificates to the trust store, add them to your OS trust store.
 The CRT does not use the Java TrustStore. For more customization options, see
@@ -200,7 +201,25 @@ The CRT does not use the Java TrustStore. For more customization options, see
 
 ### Mac-Only TLS Behavior
 
-Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically.  Beginning in v0.6.6, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
+#### `AWS_CRT_USE_NON_FIPS_TLS_13` environment variable
+
+On macOS, both Apple Secure Transport and s2n-tls are compiled into the binary.
+The TLS backend is selected at runtime based on this environment variable:
+
+* **Not set (default):** Apple Secure Transport is used.
+* **Set (e.g. `AWS_CRT_USE_NON_FIPS_TLS_13=1`):** s2n-tls with aws-lc is used.
+
+This variable has no effect on Linux (always uses s2n-tls) or Windows (always uses Schannel).
+
+| | Secure Transport (default) | s2n-tls (`AWS_CRT_USE_NON_FIPS_TLS_13=1`) |
+|---|---|---|
+| TLS versions | Up to TLS 1.2 | Up to TLS 1.3 |
+| FIPS compliance | Yes | No |
+| macOS Keychain integration | Yes (PKCS#12, system certs) | No |
+
+#### Keychain behavior
+
+Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. This applies when using the default Secure Transport backend. Beginning in v0.6.6, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
 
 ```
 static: certificate has an existing certificate-key pair that was previously imported into the Keychain.  Using key from Keychain instead of the one provided.

crt/aws-c-io

@@ -3425,6 +3425,9 @@ public void ConnDC_Cred_UC2() throws Exception {
         Assume.assumeNotNull(
             AWS_TEST_MQTT5_IOT_CORE_HOST, AWS_TEST_MQTT5_IOT_CORE_PKCS12_KEY,
             AWS_TEST_MQTT5_IOT_CORE_PKCS12_KEY_PASSWORD);
+        // When set, TLS backend on macOS switches from Secure Transport to s2n-tls, which doesn't support PKCS#12.
+        Assume.assumeTrue("Skipped: AWS_CRT_USE_NON_FIPS_TLS_13 is set",
+            System.getenv("AWS_CRT_USE_NON_FIPS_TLS_13") == null);
 
         TestUtils.doRetryableTest(this::doConnDC_Cred_UC2Test, TestUtils::isRetryableTimeout, MAX_TEST_RETRIES, TEST_RETRY_SLEEP_MILLIS);
 
@@ -3647,4 +3650,44 @@ public void ConnWS_Cred_UC4() throws Exception {
 
         CrtResource.waitForNoResources();
     }
+
+    /**
+     * ============================================================
+     * TLS 1.3 TEST CASES
+     * ============================================================
+     */
+
+    private void doConnDC_TLS13Test() {
+        try (TlsContextOptions tlsOptions = TlsContextOptions.createWithMtlsFromPath(
+                AWS_TEST_MQTT5_IOT_CORE_RSA_CERT, AWS_TEST_MQTT5_IOT_CORE_RSA_KEY);
+            TlsContext tlsContext = new TlsContext(tlsOptions)) {
+            LifecycleEvents_Futured events = new LifecycleEvents_Futured();
+            Mqtt5ClientOptionsBuilder builder = new Mqtt5ClientOptionsBuilder(AWS_TEST_MQTT5_IOT_CORE_TLS13_HOST, 8883l);
+            builder.withLifecycleEvents(events);
+            builder.withTlsContext(tlsContext);
+
+            try (Mqtt5Client client = new Mqtt5Client(builder.build())) {
+                client.start();
+                events.connectedFuture.get(OPERATION_TIMEOUT_TIME, TimeUnit.SECONDS);
+                client.stop();
+            }
+        } catch (Exception ex) {
+            throw new RuntimeException(ex);
+        }
+    }
+
+    /* Direct connection to TLS 1.3-only host with mTLS */
+    @Test
+    public void ConnDC_TLS13() throws Exception {
+        skipIfNetworkUnavailable();
+        Assume.assumeNotNull(
+            AWS_TEST_MQTT5_IOT_CORE_TLS13_HOST, AWS_TEST_MQTT5_IOT_CORE_RSA_CERT, AWS_TEST_MQTT5_IOT_CORE_RSA_KEY);
+        // macOS does not support TLS 1.3 unless AWS_CRT_USE_NON_FIPS_TLS_13 is set
+        Assume.assumeFalse("Skipped: macOS with Secure Transport does not support TLS 1.3",
+            CRT.getOSIdentifier().equals("osx") && System.getenv("AWS_CRT_USE_NON_FIPS_TLS_13") == null);
+
+        TestUtils.doRetryableTest(this::doConnDC_TLS13Test, TestUtils::isRetryableTimeout, MAX_TEST_RETRIES, TEST_RETRY_SLEEP_MILLIS);
+
+        CrtResource.waitForNoResources();
+    }
 }

src/test/java/software/amazon/awssdk/crt/test/Mqtt5ClientTest.java

@@ -82,6 +82,8 @@ public class Mqtt5ClientTestFixture extends CrtTestFixture {
     // MQTT5 Windows Cert Store
     static final String AWS_TEST_MQTT5_IOT_CORE_WINDOWS_PFX_CERT_NO_PASS = System.getProperty("AWS_TEST_MQTT5_IOT_CORE_WINDOWS_PFX_CERT_NO_PASS");
     static final String AWS_TEST_MQTT5_IOT_CORE_WINDOWS_CERT_STORE = System.getProperty("AWS_TEST_MQTT5_IOT_CORE_WINDOWS_CERT_STORE");
+    // MQTT5 TLS 1.3
+    static final String AWS_TEST_MQTT5_IOT_CORE_TLS13_HOST = System.getProperty("AWS_TEST_MQTT5_IOT_CORE_TLS13_HOST");
 
     protected int OPERATION_TIMEOUT_TIME = 30;
 

src/test/java/software/amazon/awssdk/crt/test/Mqtt5ClientTestFixture.java

@@ -113,6 +113,9 @@ public void ConnDC_Cred_UC2() throws Exception {
         Assume.assumeNotNull(
             AWS_TEST_MQTT311_IOT_CORE_HOST, AWS_TEST_MQTT311_IOT_CORE_PKCS12_KEY,
             AWS_TEST_MQTT311_IOT_CORE_PKCS12_KEY_PASSWORD);
+        // When set, TLS backend on macOS switches from Secure Transport to s2n-tls, which doesn't support PKCS#12.
+        Assume.assumeTrue("Skipped: AWS_CRT_USE_NON_FIPS_TLS_13 is set",
+            System.getenv("AWS_CRT_USE_NON_FIPS_TLS_13") == null);
 
         TestUtils.doRetryableTest(this::doConnDC_Cred_UC2Test, TestUtils::isRetryableTimeout, MAX_TEST_RETRIES, TEST_RETRY_SLEEP_MILLIS);