TLS (SecureSocket)

Copyright 2017-2022 Moddable Tech, Inc.
Revised: November 11, 2022

Table of Contents

• SecureSocket
  • Use with HTTP client (https:)
  • Use with WebSocket client (wss:)
  • Use with MQTT client (mqtts:)
  • TLS Certificates
    • Using a Built-in Certificate
    • Providing a Certificate
    • Converting PEM to DER
    • Updating Certificate Store
  • Memory
• Configuration

class SecureSocket

• Source code: securesocket
• Relevant Examples: socketsecure, httpsget, mqttsecure

The SecureSocket class implements TLS. At this time, there is no Listener in SecureSocket; there is only the Socket, which is TCP-only (no UDP).

import SecureSocket from "securesocket";

constructor(dictionary)

The SecureSocket constructor takes a single argument, a object dictionary of initialization parameters. The dictionary is a super-set of the Socket dictionary (see the documentation of the Socket class in the network documentation for details).

SecureSocket extends the dictionary of the constructor with an additional property named secure which is itself a dictionary used to configure the TLS connection.

The secure dictionary may contain the following properties:

In the following example, the TLS socket is created with support for version 0x303 of TLS, which corresponds to TLS 1.2.

let socket = new SecureSocket({
	host: "www.example.com",
	port: 443,
	secure: {
		protocolVersion: 0x303
	}
});

Use with HTTP client (https:)

The HTTP Client class accepts an optional Socket property in the dictionary of its constructor. Set this property to SecureSocket to make an HTTPS request. The secure property may be provided to configure the TLS connection:

let request = new Request({
	host: "www.howsmyssl.com",
	path: "/",
	response: String,
	Socket: SecureSocket,
	port: 443,
	secure: {
		trace: true,
		protocolVersion: 0x303
	}
});

Use with WebSocket client (wss:)

The WebSocket Client class accepts an optional Socket property in the dictionary of its constructor. Set this property to SecureSocket to make an WSS request. The secure property may be provided to configure the TLS connection:

let ws = new Client({
	host: "echo.websocket.org",
	port: 443,
	Socket: SecureSocket,
	secure: {
		protocolVersion: 0x302
	}
});

Use with MQTT client (mqtts:)

The MQTT Client class accepts an optional Socket property in the dictionary of its constructor. Set this property to SecureSocket to establish a secure MQTT connection. The secure property may be provided to configure the TLS connection:

const mqtt = new MQTT({
	host: "iot.aws.com,
	id: "unique mqtt client id",
	port: 8883,
	Socket: SecureSocket,
	secure: {
		protocolVersion: 0x303,
		applicationLayerProtocolNegotiation: "mqtt",
		certificate: new Resource("AmazonRootCA1.der"),
		clientKey: new Resource("device.key.der"),
		clientCertificates: [new Resource("device.crt.a.der")]
	},
});

TLS Certificates

TLS Certificates are used to encrypt the data you send to a server. SecureSocket objects use certificates in DER (binary) format.

Using a Built-in Certificate

The certificate store is located in the modules/crypt/data directory of the Moddable SDK. Not every certificate is used by every application, so it would be a waste of limited flash memory to include all of them by default. Instead, certificates are explicitly included in the resources section of manifests.

"resources": {
    "*": [
        "$(MODULES)/crypt/data/ca9",
    ]
}

If you are unsure which certificate you need to include, just run your application that tries to access a website and see what certificate fails to load. The application will throw an exception like the following:

In this case, ca109.der needs to be included, so it should be added in the manifest’s resources object.

"resources": {
    "*": [
        "$(MODULES)/crypt/data/ca109"
    ]
}

As an alternative to the certificate store, you can put the certificates needed in your application and pass the appropriate certificate in the secure dictionary.

let request = new Request({
	host: "www.howsmyssl.com",
	path: "/",
	response: String,
	Socket: SecureSocket,
	port: 443,
	secure: {
		certificate: new Resource("ca109.der")
	}
});

Providing a Certificate

You do not have to use the certificates included in the Moddable SDK. You may pass any valid certificate in DER format in the SecureSocket’s dictionary:

let request = new Request({
    ...
    secure: {
    	certificate: new Resource("mycert.der")
    }
});

Converting PEM to DER

The SecureSocket implementation requires certificates to be provided in DER (binary) format. If you have a certificate in PEM (a Base64 encoded) format, you need to convert it to DER.

Whenever possible, convert the PEM file to DER format before adding it to your project. There are many tools that can perform the conversion. A reliable choice is openssl. The following command line works for many certificates (substitute your PEM file path for data.pem and the desired output file path for data.der):

openssl x509 -inform pem -in data.pem -out data.der -outform der

Sometimes there is no choices but to convert the PEM to DER at runtime. For example, during provisioning you might receive a certificate in PEM format from a service, and later you need to use that certificate to establish a TLS connection. The Moddable SDK provides the pemtoDER and privateKeyToPrivateKeyInfo functions for these situations. These functions are part of the Crypt Transform class.

Updating Certificate Store

The certificate store may be updated with new and revised certificates in $MODDABLE/modules/crypt/data. Certificates are numbered sequentially starting with ca0.der. The certificate store index ca.ski must be rebuilt after adding or updating certificates . To update the index, run the mcprintski tool with no arguments. The ca.ski index file is updated in place. (This tool is currently only available on macOS. Windows and Linux could be supported with updates to their tool makefiles.)

Memory

The TLS handshake requires a fair amount of memory. The exact amount required varies depending on the site you are connecting to. As a rough guideline, the following should be free:

• 4 KB of stack
• 10 KB in the chunk heap
• 6 KB in the slot heap
• 2 KB in the system heap

Once the handshake is complete (e.g. once the secure connection is established), memory use drops considerably.

However, if the server sends large fragments (e.g. apple.com sends 16 KB fragments), there may not be enough free RAM on your microcontroller to buffer them. The requests will fail. Secure web servers designed to work with IoT devices will use smaller fragments by default and/or will support the tls_max_fragment_length extension.

When working with HTTPS, it is best to use streaming mode to retrieve the response body as it arrives rather than having the HTTP client buffer the entire response body in memory. See the httpsgetstreaming example for an example of this.

Configuration

The TLS implementation defaults to enabling cipher suites that use DHE and ECDHE. These modes are computationally complex and therefore can take a long time to run on slower microcontrollers. The use of these suites is controlled by the config section of the manifest. To disable these suites, include the following in your project manifest:

"config": {
	"tls": {
		"DHE_RSA": false,
		"ECDHE_RSA": false
	}
}