Skip to content

Configuring TLS

Ioto supports the TLS / SSL protocol for authenticating systems and encrypting data. Use of this protocol enables secure data transmission to and from clients in a standards-based manner.

This document provides step-by-step instructions for configuring TLS in the Ioto web server. If you are unfamiliar with TLS, please read the TLS Overview first.

TLS Quick Start

The default source build of Ioto will support TLS for use by the Ioto web server. You can immediately test TLS access to documents by using the https:// scheme. For example, to access the home page using TLS, use this URL in your browser:

1
https://localhost/

TLS Providers

Ioto employs an open architecture TLS Provider interface so that customers can select or create an TLS provider for their needs.

Ioto provides multiple TLS implementations:

The default source build will use the OpenSSL provider by default. See the README.md file for details about how to build with MbedTLS.

SSL Configuration Directives

Ioto uses several configuration TLS properties to control TLS and manage secure access to the web server.

The relevant TLS properties are:

There are some additional properties that are necessary should you wish to have Ioto verify client certificates. These :

TLS Configuration Example

Consider the default Ioto TLS configuration in the web.json5 configuration file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
web: {
    listen: [ "https://:443" ]
},
redirect: [
    { status: 302, to: "https://" },
},
tls: {
    certificate: "server.crt",
    key: "server.key",
    verify: {
        issuer: true
    }
}

This set of properties enables TLS on port 443 for all network interfaces and uses the default supplied self-signed certificate to identify the server.

The listen property instructs Ioto to process requests from all interfaces on port 443 using TLS.

The certificate property specifies the server certificate to use and the key property specifies the server private key for signing.

SECURITY WARNING: You must obtain or generate a SSL certificate before using this example in a production environment.

The server key file is a PEM encoded private key. You may supply either an encrypted private key or a decrypted private key. If you use an encrypted private key, the server will prompt you for a pass-phrase to decrypt the key when the server boots.

Self-Signed Certificate

Ioto is shipped with a self-signed certificate to identify the web server.

SECURITY WARNING: This certificate is suitable for testing purposes only and your browser will issue a warning when you access the server. For production use, you should obtain your own service certificate from signing authorities such as Verisign.

Generating Keys and Certificates

To generate a request file that you can send to a certificate issuing authority such as Verisign, use the following openssl command or equivalent command from your TLS provider:

1
2
openssl genrsa -des3 -out server.key 1024
openssl req -new -key server.key -out server.csr

This will generate a server key in the file "server.key" and will generate a certificate request in the file "server.csr" that you can send to the issuing authority. The issuing authority will generate a server certificate for your server and they will sign it with their private key. Subsequently, clients will be able to use the signing authorities public key to decrypt your server certificate and thus verify the identity of your server when negotiating a SSL session. When running these commands, you will be prompted to enter a pass-phrase password to decrypt the server private key. REMEMBER this password.

SECURITY WARNING: Safeguard the "server.key" private key jealously. If this falls into malicious hands, then your server identity may be hijacked by another site.