TLS - Amazon IoT Core
Happy PathCipher SuitesLarger Size Server CertificateTLS Unsecure Server CertTLS Expired Server Certificate
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

TLS

Use these tests to determine if the transport layer security protocol (TLS) between your devices and Amazon IoT is secure.

Note

Device Advisor now supports TLS 1.3.

Happy Path

TLS Connect

Validates if the device under test can complete the TLS handshake to Amazon IoT. This test doesn't validate the MQTT implementation of the client device.

Example API test case definition:
Note

EXECUTION_TIMEOUT has a default value of 5 minutes. For best results, we recommend a timeout value of 2 minutes. 

"tests":[
   {
      "name":"my_tls_connect_test",
      "configuration": {
         // optional:
         "EXECUTION_TIMEOUT":"300",  //in seconds
      },
      "test":{
         "id":"TLS_Connect",
         "version":"0.0.0"
      }
   }
]
Example Test case outputs:

  • Pass — The device under test completed TLS handshake with Amazon IoT.

  • Pass with warnings — The device under test completed TLS handshake with Amazon IoT, but there were TLS warning messages from the device or Amazon IoT.

  • Fail — The device under test failed to complete TLS handshake with Amazon IoT due to handshake error.

TLS Receive Maximum Size Fragments

This test case validates that your device can receive and process TLS maximum size fragments. Your test device must subscribe to a pre-configured topic with QoS 1 to receive a large payload. You can customize the payload with the configuration ${payload}.

Example API test case definition:
Note

EXECUTION_TIMEOUT has a default value of 5 minutes. For best results, we recommend a timeout value of 2 minutes. 

"tests":[
   {
      "name":"TLS Receive Maximum Size Fragments",
      "configuration": {
         // optional:
         "EXECUTION_TIMEOUT":"300",  //in seconds
         "PAYLOAD_FORMAT":"{"message":"${payload}"}", // A string with a placeholder ${payload}, or leave it empty to receive a plain string.
         "TRIGGER_TOPIC": "test_1" // A topic to which a device will subscribe, and to which a test case will publish a large payload.
      },
      "test":{
         "id":"TLS_Receive_Maximum_Size_Fragments",
         "version":"0.0.0"
      }
   }
]

Cipher Suites

TLS Device Support for Amazon IoT recommended Cipher Suites

Validates that the cipher suites in the TLS Client Hello message from the device under test contains the recommended Amazon IoT cipher suites. It provides more insights into cipher suites supported by the device.

Example API test case definition:
Note

EXECUTION_TIMEOUT has a default value of 5 minutes. We recommend a timeout value of 2 minutes.

"tests":[
   {
      "name":"my_tls_support_aws_iot_cipher_suites_test",
      "configuration": {
         // optional:
         "EXECUTION_TIMEOUT":"300",  // in seconds
      },
      "test":{
         "id":"TLS_Support_AWS_IoT_Cipher_Suites",
         "version":"0.0.0"
      }
   }
]
Example Test case outputs:

  • Pass — The device under test cipher suites contain at least one of the recommended Amazon IoT cipher suite and don't contain any unsupported cipher suites.

  • Pass with warnings — The device cipher suites contain at least one Amazon IoT cipher suite but:

    1. It doesn't contain any of the recommended cipher suites

    2. It contains cipher suites that aren't supported by Amazon IoT.

    We suggest that you verify that any unsupported cipher suites are safe.

  • Fail — The device under test cipher suites doesn't contain any of the Amazon IoT supported cipher suites.

Larger Size Server Certificate

TLS large Size Server Certificate

Validates at your device can complete the TLS handshake with Amazon IoT when it receives and processes a larger size server certificate. The size of the server certificate (in bytes) used by this test is larger than what is currently used in the TLS Connect test case and IoT Core by 20 During this test case, Amazon IoT tests your device’s buffer space for TLS If the buffer space is large enough, the TLS handshake ompletes without errors. This test esn't validate the MQTT implementation of the device. The test case ds after the TLS handshake process completes.

Example API test case definition:
Note

EXECUTION_TIMEOUT has a default value of 5 minutes. For best results, we recommend a timeout value of 2 minutes. If this test case fails but the TLS Connect test case passes, we recommend you increase your device’s buffer space limit for TLS Increasing the buffer space limit sures that your device can process a larger size server certificate in case the size increases.

"tests":[
   {
      "name":"my_tls_large_size_server_cert_test",
      "configuration": {
         // optional:
         "EXECUTION_TIMEOUT":"300",  // in seconds
      },
      "test":{
         "id":"TLS_Large_Size_Server_Cert",
         "version":"0.0.0"
      }
   }
]
Example Test case outputs:

  • Pass — The device under test completed the TLS handshake with Amazon IoT.

  • Pass with warnings — The device under test completed the TLS handshake with Amazon IoT, but there are TLS warning messages either from the device or Amazon IoT.

  • Fail — The device under test failed to complete the TLS handshake with Amazon IoT because of an error during the handshake process.

TLS Unsecure Server Cert

Not Signed By Recognized CA

Validates that the device under test closes the connection if it's presented with a server certificate without a valid signature from the ATS CA. A device should only connect to an endpoint that presents a valid certificate.

Example API test case definition:
Note

EXECUTION_TIMEOUT has a default value of 5 minutes. We recommend a timeout value of 2 minutes. 

"tests":[
   {
      "name":"my_tls_unsecure_server_cert_test",
      "configuration": {
         // optional:
         "EXECUTION_TIMEOUT":"300",  //in seconds
      },
      "test":{
         "id":"TLS_Unsecure_Server_Cert",
         "version":"0.0.0"
      }
   }
]
Example Test case outputs:

  • Pass — The device under test closed the connection.

  • Fail — The device under test completed TLS handshake with Amazon IoT.

TLS Incorrect Subject Name Server Cert / Incorrect Subject Common Name (CN) / Subject Alternative Name (SAN)

Validates that the device under test closes the connection if it's presented with a server certificate for a domain name that is different than the one requested.

Example API test case definition:
Note

EXECUTION_TIMEOUT has a default value of 5 minutes. We recommend a timeout value of 2 minutes. 

"tests":[
   {
      "name":"my_tls_incorrect_subject_name_cert_test",
      "configuration": {
         // optional:
         "EXECUTION_TIMEOUT":"300",   // in seconds
      },
      "test":{
         "id":"TLS_Incorrect_Subject_Name_Server_Cert",
         "version":"0.0.0"
      }
   }
]
Example Test case outputs:

  • Pass — The device under test closed the connection.

  • Fail — The device under test completed the TLS handshake with Amazon IoT.

TLS Expired Server Certificate

Expired server certificate

Validates that the device under test closes the connection if it's presented with an expired server certificate.

Example API test case definition:
Note

EXECUTION_TIMEOUT has a default value of 5 minutes. We recommend a timeout value of 2 minutes. 

"tests":[
   {
      "name":"my_tls_expired_cert_test",
      "configuration": {
         // optional:
         "EXECUTION_TIMEOUT":"300",  //in seconds
      },
      "test":{
         "id":"TLS_Expired_Server_Cert",
         "version":"0.0.0"
      }
   }
]
Example Test case outputs:

  • Pass — The device under test refuses to complete the TLS handshake with Amazon IoT. The device sends a TLS alert message before it closes the connection.

  • Pass with warnings — The device under test refuses to complete the TLS handshake with Amazon IoT. However, it doesn’t send a TLS alert message before it closes the connection.

  • Fail — The device under test completes the TLS handshake with Amazon IoT.