Web Services Series Part 2: Making Secure Network Requests

May 31, 2018 | Lizzie Prader, Software Engineer

The first article of this series describes how to issue HTTP requests in applications built with the Moddable SDK using information from REST APIs. This article builds on the concepts from the first article and explains how to use the Moddable SDK's TLS stack in applications to make HTTPS requests.

What is TLS?

Transport Layer Security (TLS) is a cryptographic protocol used to encrypt and authenticate HTTPS messages to allow for secure network communication. The source code for Moddable's implementation can be found in the modules/crypt folder of our open source repository.

Note: Earlier versions of TLS were known as SSL, Secure Sockets Layer.

Application Code

The httpsgetjson example application is very short and makes just one request to howsmyssl.com. Here is the code that creates that request:

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

Below are some notes on the parameters related to HTTPS.

`port`

443 is the default TCP port used for HTTPS.

`Socket`

The HTTP Request object is built on the Socket class by default; for HTTPS requests you require the request to use the SecureSocket class instead.

`secure`

The secure parameter is a dictionary passed into the constructor of the SecureSocketobject. You can read about all of the supported properties in the SecureSocket documentation.

The only property specified in this application is protocolVersion, which is the TLS version specified in hex.

0x303 is TLS 1.2
0x302 is TLS 1.1
0x301 is TLS 1.0

Some servers will only accept requests that use newer versions of TLS. This one accepts all versions.

If you use TLS 1.2, the server gives a "Probably Okay" rating:

content-length: 586
access-control-allow-origin: *
connection: close
content-type: application/json
date: Tue, 24 Apr 2018 18:07:22 GMT
strict-transport-security: max-age=631138519; includeSubdomains; preload
Rating: Probably Okay

If you use TLS 1.0, the server gives a "Bad" rating:

content-length: 574
access-control-allow-origin: *
connection: close
content-type: application/json
date: Tue, 24 Apr 2018 18:08:11 GMT
strict-transport-security: max-age=631138519; includeSubdomains; preload
Rating: Bad

Manifest

All applications that issue HTTPS requests typically start with the following manifest.

{
    "include": [
        "$(MODDABLE)/examples/manifest_base.json",
        "$(MODDABLE)/examples/manifest_net.json",
        "$(MODDABLE)/modules/crypt/tls.json"
    ],
    "modules": {
        "*": [
            "./main",
            "$(MODULES)/network/http/*"
        ]
    },
    "preload": [
        "http"
    ],
}

As always, it may be necessary to add other modules and resources or tweak settings to suit your own applications. It is also necessary to include TLS Certificates in applications that make HTTPS requests.

TLS Certificates

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

The certificate store is located in the modules/crypt/data folder of our open source repository. Not every certificate is used by every application. It would be a waste of limited flash memory to include all of them by default. Instead, certificates are explicitly included in manifests. If you are unsure which certificate you need to include, just run your application that tries to access the web site 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 is added in the manifest's resourcesobject.

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

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"), protocolVersion: 0x303 } 
});

Conclusion

Being able to securely communicate with web services is important for many IoT applications. The Moddable SDK's TLS stack is an important, but easy to use, feature that allows you to encrypt the data sent and received in HTTPS requests.

This article is part two of a series about using web services in applications built with the Moddable SDK. Stay tuned for the next post on building custom modules to replace JavaScript SDKs and libraries for the web.