AcornSSL provides a BSD-like socket interface for communication through the
TCP/IP protocol stack to resources that require a secure connection. It uses
the mbedTLS library for the majority of its implementation; the module
itself calls the corresponding mbedTLS functions and wraps them into a set
of SWIs that mirror the equivalent calls provided by the Internet module's
BSD sockets interface.
At the time of writing, AcornSSL supports all current TLS standards:
- TLS version 1.0
- TLS version 1.1
- TLS version 1.2
The earlier SSL version 2 and 3 standards are considered too insecure and
are not supported at all, and TLS version 1.0 is likely to be withdrawn in
future. The client SWI interface offers no mechanism to select which
protocol version is used; attempting to connect to a server that only
offers one of the insecure methods will fail.
Application authors who need a network resource protected by TLS, most
commonly for the https: URL scheme handled by
AcornHTTP, use AcornSSL either directly through its SWI interface, or
indirectly through a higher-level fetcher module that already knows how to
drive it. Because untrusted or unexpected certificates may need to be
approved by a person before a connection can proceed, AcornSSL also
provides a desktop user interface: a small Wimp task that displays a
certificate confirmation dialogue whenever a session's server certificate
cannot be verified automatically.
Every AcornSSL SWI operates on an ssl handle, obtained
from or
. This handle is
superficially similar to a socket handle from
, 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:
Socket_Creat -- get a handle
Socket_Connect -- connect to the remote host
Socket_Read / Socket_Write -- insecure dialogue
AcornSSL_CreateSession -- associate the handle
AcornSSL_Read / AcornSSL_Write -- secure dialogue
AcornSSL_Close then Socket_Close
is the SWI used to
upgrade an existing, already-open socket (typically one obtained from
and already connected) into a
secure session, without needing to close and reopen the connection.
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.
,
, and
all use the same
address structure as the corresponding Socket_
SWIs. For the IPv4 sessions AcornSSL currently supports, this is the
16-byte sockaddr_in block:
Length of the structure, in bytes (16)
AF_INET (2); no other address family is currently supported
Port number, in network byte order
IPv4 address, in network byte order
Padding; must be zero
On the caller supplies this
structure to describe the remote host to connect to. On
and
the SWI fills it in to
describe the remote or local end of the connection respectively.
fills in the same
struct stat block as
, defined in
C:TCPIPLibs.sys.h.stat. Because this
structure was designed to describe files rather than sockets, most of its
fields are not meaningful for an ssl handle and should be ignored; only
st_mode, which identifies the handle as a socket,
and st_blksize, which gives a hint of the optimal
I/O size for the connection, are populated with useful values.
Not meaningful for a socket
Not meaningful for a socket
File type and mode; S_IFSOCK is set to identify the handle as a socket
Not meaningful for a socket
Not meaningful for a socket
Not meaningful for a socket
Not meaningful for a socket
Not meaningful for a socket
Not meaningful for a socket
Not meaningful for a socket
Not meaningful for a socket
Optimal block size for reads and writes on this connection
Not meaningful for a socket
Not meaningful for a socket
Not meaningful for a socket
The buffer passed in R1 must be large enough to hold the whole structure
(64 bytes).
An application that wants to use select() semantics
cannot select directly on an ssl handle. The semantics of
select() require a set of bitmaps with bits relating
to each socket number, but ssl handles are opaque values that do not
contain small incrementing integers, so the FD_SET,
FD_CLR, and FD_ISSET macros
cannot be used with them.
If an application's structure requires select(), the
recommended approach is to create the underlying socket with
and then associate it with an
ssl handle using .
Because 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
or
returning nothing.
can be used to mark an ssl
handle as non-blocking, by applying the FIONBIO
command with a pointer to an integer value of 1 (to enable non-blocking
operation) or 0 (to disable it).
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: ,
,
,
, and
.
A session can be configured by calling
or
after
or
, but before
, 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:
SO_ACORNSSL_HOSTNAME -- associates the expected
name of the remote host with the current session. Because name resolution
is performed by the client, and a single peer can present several alias
names, there would otherwise be no way to cross-check, from the IP
address alone, whether the certificate presented by the server was issued
to the expected name. The expected host name is also required if the
server administrator has enabled SNI (Server Name Identification); without
it no name is sent during handshaking, and the connection is likely to be
refused. A name pointer of NULL (the default, if
this option is never set) skips checking the peer's name and does not
send an expected name while handshaking.
Unlike most options, the value of this option is itself a pointer, so it
does not follow the usual pattern of R3 pointing at a buffer that holds
the value:
To set the option, R3 (optval) must itself
be the address of a nul-terminated host name string -- not the address
of a variable that holds that address. AcornSSL does not dereference R3
an extra time; it uses the value of R3 directly as a
const char *. R4
(optlen) is passed by value and must be 4 (the
size of a pointer); it is not the length of the host name string.
To read the option back, R3 (optval) is
the address of a 4-byte word; AcornSSL writes the address of its own
internally-held copy of the host name into that word (so a second level
of indirection is needed to reach the string itself: R3 points to the
word, and the word holds the string's address). R4
(optlen) is a pointer to a word that must hold 4
on entry; AcornSSL does not alter it.
SO_ACORNSSL_PROMPTTIME -- defines how long, in
centiseconds, the certificate confirmation dialogue will wait for a
response if a certificate is flagged as bad. A value of zero displays no
prompt and fails the connection immediately. To set the option,
optval is a pointer to the value in centiseconds
and optlen is 4 (the size of an integer); to read
it back, optval is a pointer to receive the
integer, and optlen is a pointer to an integer
holding 4.
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.
When AcornSSL cannot fully verify a server's certificate chain against its
trusted root certificates, or the certificate presented fails one of its
other checks, the connection does not fail outright. Instead, provided the
desktop is running and
SO_ACORNSSL_PROMPTTIME has not been set to zero for
that session, AcornSSL asks the user whether the connection should be
allowed to proceed. While this confirmation is pending, and while any
handshaking that requires it is in progress, calls such as
and
report the connection's status
as ENOTCONN.
The certificate confirmation dialogue is presented by a small Wimp task,
started automatically as
when the desktop starts. This task is separate from the AcornSSL module
itself: the module runs the TLS handshake and evaluates the certificate
chain in the background, and communicates with the task only to display a
dialogue and collect the user's decision.
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.
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.
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.
AcornSSL's own errors are allocated the range
&813F20 to &813F3F.
These are used for failures that are specific to the module, or that arise
from a SWI that has no direct BSD sockets equivalent (such as
).
Most errors from the socket-like SWIs are instead mapped onto Unix errors
in the DCI4 error range, for maximum compatibility with the BSD sockets
API used by the Internet module. The full list of these errors can be found
in C:TCPIPLibs.sys.h.errno, and macros to
recognise and extract them from a RISC OS error are in
C:TCPIPLibs.sys.h.dcistructs. Errors
propagated from a component AcornSSL relies on (for example, a
‘File not found’ error while reading a certificate file) are
passed back unchanged.
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;
This example shows a protocol that starts with a plain-text exchange over a
socket created with , 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;