Handles and sessions

Every AcornSSL SWI operates on an ssl handle, obtained from SWI AcornSSL_Creat or SWI AcornSSL_CreateSession. This handle is superficially similar to a socket handle from SWI Socket_Creat, but it is not a socket handle and must be treated as an opaque value: it must not be used with the Internet module's socket SWIs, and a socket handle must not be used with the AcornSSL SWIs.

The AcornSSL SWIs are deliberately close analogues of the corresponding socket SWIs, so that code already written against a BSD-like sockets API can be adapted to use secure connections with minimal change. Which SWIs are needed depends on whether an insecure exchange is required before the connection becomes secure. Some protocols need an initial plain-text exchange to negotiate whether, or how, to proceed to a secure connection; others are secure from the first byte:

SWI AcornSSL_CreateSession is the SWI used to upgrade an existing, already-open socket (typically one obtained from SWI Socket_Creat and already connected) into a secure session, without needing to close and reopen the connection.

Data structures

Several AcornSSL SWIs operate on fixed-format data blocks that are shared with the Internet module's socket SWIs. These are documented here so that the individual SWI definitions below can refer to them, rather than repeating the field layout at every point of use.

Blocking versus non-blocking operation

If an application's structure requires select(), the recommended approach is to create the underlying socket with SWI Socket_Creat and then associate it with an ssl handle using SWI AcornSSL_CreateSession. Because SWI Socket_Creat does return small incrementing socket numbers, those can be used with select() as normal.

A successful select() does not necessarily mean application data is available. Data that appears ready for reading or writing on the underlying socket may in fact be the security library handling an alert, or updating a session ticket, so a successful select() can still be followed by SWI AcornSSL_Recv or SWI AcornSSL_Send returning nothing.

If this is done before connecting, the connect operation also becomes non-blocking and returns EINPROGRESS. Since it is not possible to select() on an ssl handle directly, there is no convenient way to discover when such a connection becomes ready for writing. The simplest workaround is to leave the connection as blocking (the default) until after it has connected, and only then use FIONBIO before performing reads and writes. Alternatively, an application may proceed regardless and expect ENOTCONN from any SWI that needs an established connection: SWI AcornSSL_Recv, SWI AcornSSL_Send, SWI AcornSSL_Read, SWI AcornSSL_Write, and SWI AcornSSL_Getpeername.

Extension socket options

A session can be configured by calling SWI AcornSSL_Getsockopt or SWI AcornSSL_Setsockopt after SWI AcornSSL_Creat or SWI AcornSSL_CreateSession, but before SWI AcornSSL_Connect, to alter parameters relating to that specific session. Two extension options are defined, in addition to the standard socket options recognised by the Internet module:

Loading the module

Application authors who want to be sure the AcornSSL SWIs are available should use *RMEnsure in the usual manner, for example:

RMEnsure AcornSSL 1.23 RMLoad System:Modules.Network.URL.AcornSSL

RMEnsure AcornSSL 1.23 Error Application requires AcornSSL 1.23 or later

A more comprehensive series of *RMEnsure commands would be needed if an earlier AcornSSL is already loaded with active clients, because loading a second copy of the module would end those sessions. When tracking security enhancements it can be assumed that the latest available version is always preferable, even at the expense of terminating existing sessions.

The System: path variable should be used, as shown above, rather than a reference to a specific RISC OS version's directory inside !System; the module may in future be shipped with builds tailored to different RISC OS versions.

What the dialogue shows

The dialogue is shown once for each certificate in the chain that needs the user's attention, starting with the certificate presented by the remote server (the subject) and, where the user chooses to inspect it, working back towards the root of trust (the issuer). Each certificate's dialogue shows:

• the certificate's issuer
• the certificate's subject
• the period for which the certificate is valid
• the certificate's serial number
• the certificate's signature

Where a check on the certificate has failed, the corresponding field is marked to draw attention to the specific problem: an expired, not-yet-valid, revoked, or otherwise unacceptable validity period; a signature the module could not verify; or an issuer that is not among the trusted roots. The final certificate in the chain is the root; it has no further issuer to inspect, so its dialogue omits the button used to move up the chain.

Responding to the dialogue

For the certificate at the top of the chain (the one the server presented), the dialogue offers three responses:

• Reject refuses the connection. Rejecting any certificate in the chain rejects the whole chain, and the corresponding SWI call fails.
• Accept allows the connection to proceed this time only; the same certificate will be queried again on a future connection.
• Accept always allows the connection to proceed, and records an exception so that the same certificate is accepted automatically in future without prompting again.

Dialogues for certificates further up the chain (the issuers) only offer Accept and Reject, since the decision to trust the chain permanently is made once, at the top level, after the intervening issuers have been reviewed.

Each certificate's dialogue also offers a View certificate button, which writes the certificate to a pipe file in PEM form and opens it in the user's default text viewer, so the certificate's contents can be inspected in detail before a decision is made.

Timing out

SWI AcornSSL_Setsockopt with SO_ACORNSSL_PROMPTTIME controls how long, in centiseconds, a session will wait for the user to respond before the connection attempt fails. A value of zero suppresses the dialogue entirely for that session and fails the connection as soon as the certificate check fails, which is appropriate for background or unattended connections where no user is available to respond.

Connecting with certificate name checking

This example shows the minimum sequence of calls needed to open a secure connection directly, associating an expected host name with the session so that the peer's certificate is checked against it, in the same way a web browser checks a server's certificate against the name in the URL.

int ssl, err;
const char *hostname = "example.com";

/* Get a handle, and check the peer's name during handshaking */
ssl = call AcornSSL_Creat, get ssl handle;
call AcornSSL_Setsockopt, SO_ACORNSSL_HOSTNAME, hostname, 4;

/* Connect; this may trigger the certificate confirmation dialogue */
err = call AcornSSL_Connect, address, addresslen;

/* Read and write the secure connection as usual */
call AcornSSL_Write, ...;
call AcornSSL_Read, ...;

/* Finished */
call AcornSSL_Close;

Upgrading an existing socket

This example shows a protocol that starts with a plain-text exchange over a socket created with SWI Socket_Creat, and only switches to a secure session partway through the conversation, as is typical for protocols such as STARTTLS-style negotiations.

int sock, ssl;

/* Open and connect an ordinary socket, and talk to it in plain text */
sock = call Socket_Creat, get socket handle;
call Socket_Connect, address, addresslen;
negotiate whether to go secure, in plain text;

/* Hand the socket over to AcornSSL and continue securely */
ssl = call AcornSSL_CreateSession, sock, CreateSession_New;
call AcornSSL_Write, ...;
call AcornSSL_Read, ...;

/* Finished; close the secure session, then the underlying socket */
call AcornSSL_Close;
call Socket_Close, sock;