cipher.ssl

The Core4 system includes a copy of mbed TLS.

This function creates a new SSL configuration object.

The object stores certificate, key and other information necessary to establish a SSL connection.

After the configuration has been set up, it can be used to make any file handle use SSL. This would usually be a TCP socket.

Following is a list of configuration data that can be used. Not every setting is useful or required in all cases. See examples section below.

Connection mode

In each SSL connection, one peer must act the role of server while the other peer is the client.

This setting is not optional and must be configured by the application before establishing a SSL connection.

To set the connection mode, call ssl:setMode(). The current mode is returned by ssl:getMode().

Peer Verification Level

There are three levels of verification against a peer: (1) do not require identification from a peer, (2) optionally verify the peer certificate if the peer presents one and finally (3) require the peer to properly identify with a certificate.

This setting is not optional and must be configured by the application before establishing a SSL connection.

Set the verification level with ssl:setVerify() and query it with ssl:getVerify().

Local Certificate

The local certificate is the identification of this machine. During connection, it is presented to the peer. The peer can the decide whether to accept or reject the connection.

The certificate data is public and does not need to be kept secure.

The system can load a certificate in X509 PEM or BER format.

For web applications, typically only servers use a local certificate and private key.

The local certificate is set with one of the methods ssl:loadCertData() or ssl:loadCertFile(). To query information about a loaded certificate use ssl:getCertInfo().

Private key

The private key goes together with the local certificate. It is used to establish a secure connection.

This SSL implementation supports RSA encryption only, DSA is not supported.

The key must be kept secure and must never become public, as this compromises security.

The system can load a key in X509 PEM or BER format.

For web applications, typically only servers use a local certificate and private key.

The private key is set with one of the methods ssl:loadKeyData() or ssl:loadKeyFile().

Certificate Authority List

To verify the identification of a peer, it is necessary to have one or more verification certificates.

The certificate authority data is public and does not need to be kept secure.

The system can load certificates in X509 PEM or BER format.

Certificates are loaded with ssl:loadCAData(), ssl:loadCAFile() or ssl:loadCADir(). To query information about a loaded certificate use ssl:getCAInfo().

Expected server name

Note: Only few actual servers support the ServerName feature. It is currently untested in the Core4 implementation.

When connecting to a server, it is possible to tell the server what name the client expects the server to have. This allows running multiple virtual servers on a single IP address.

Set the expected server name with ssl:setHostName(), query with ssl:getHostName().

This setting is only used if the connection mode is client.

List of cipher suites

Note: There is seldom need to change this.

On connect, both server and client together chose a way how data is encrypted. Both sides have a list of encryption methods they can use, and they will pick one from the combined list that both support.

Note that on the Core4 system, AES is the fastest cipher supported, all other ciphers have much slower implementations. The Core4 is set up in a way that it automatically prefers AES if the other side supports it.

To change the list of supported ciphers for this connection, use ssl:setCipherSuites(), query with ssl:getCipherSuites(). The method ssl:defaultCipherSuites() returns a list of suites that are used when no specific list has been configured.