How to troubleshoot TLS connection issues with your AWS IoT Core endpoint

We have put together a step by step outline on how the troubleshooting process looks like:

Step1: Identify your AWS IoT Endpoint address

Connect to your AWS IoT Core Console, in the region(s) where your devices will connect to. In the left navigation bar, look for Settings. On the Settings page, look for Endpoint. You should see a data field that has a value similar to this:

account-specific-prefix.iot.aws-region.amazonaws.com.

Alternatively, you may also use the AWS CLI as per the documentation here:

aws iot describe-endpoint --endpoint-type iot:Data-ATS

Step 2: Confirm the protocol and ports your device will use to communicate with AWS IoT Core

The destination ports on AWS IoT Core depend on the protocol you intend to use for the connection. Refer to the developer guide to see the updated Port-Protocol mapping, as well as the TLS versions currently supported.

Step 3: Use a TLS client application to initiate a connection with your endpoint

With OpenSSL s_client for example, you can run the following command to initiate a TLS session:

openssl s_client -connect YOUR_ENDPOINT_ADDRESS:YOUR_PORT -servername YOUR_ENDPOINT_ADDRESS:YOUR_PORT -CAfile AmazonRootCA1.pem -msg -alpn tls,mqtt

Your endpoint address and port should be those from previous steps, and the CA file is the Amazon Root CA Certificate 1 that you can obtain in this online repository. You may also want to download the Root CA File directly from here.

With this command, you are starting and maintaining a session by exchanging keyboard inputs with AWS IoT Core, not unlike an SSH tunnel. If the connection is successful, there is no error message displayed and the session stays open. Otherwise, you receive error feedback and the connection is interrupted by the broker.

Sample Successful TLS connection

An output of “Verify return code: 0 (ok)” means that the handshake was successful!

Sample failed TLS connection

An output of “Verify return code: 20 (unable to get local issuer certificate)” indicates that the certificate issuer (Certification Authority - CA) could not be validated against the requested IoT Endpoint domain name. In this example request here, the Root CA provided for the connection is not valid!

Step 4: Tracing live TLS traffic

If you’d like to get a broader view (visualizing live traffic and connection information), you can leverage a utility like ssldump on a test client device to verify the entire TLS negotiation process (tagged by connection number). This helps you ensure that the handshake and application data exchange is successful. Having this tracing capability also helps you identify where the connection or negotiation process is affected.

Here the tag number for the sample connection is “69” and I can trace the connection steps between my Client (C) and Server (S).

From lines 749 you are able to see that the Handshake process is initiated by the Server to the Client with a cipherSuite, compressionMethod and other flags. Any non-nominal log entries will be immediately apparent, which would allow you to further investigate that specific anomaly. ssldump -A can provide some verbose output, and so ssldump -d might be a better starting point.

Key Takeaways and further reading

Migrating from one MQTT broker to another may reveal challenges and friction not readily apparent to your IoT Team, particularly from a security context. In this article, we looked at several quick tips to identify and resolve some aspects of IoT security and TLS connection issues.

To learn more about AWS IoT and IoT Security, explore here!