As of A-Shell build 1180 of 20 April 2010, the STARTTLS protocol is supported via a new opcode and flag (in ashell.def).
Symbol |
Value |
Meaning |
|---|---|---|
TCPOP_STARTTLS |
12 |
TCPX opcode to initiate STARTTLS |
TCPXFLG_STARTTLS |
&h00200000 |
Use with TCPOP_CONNECT |
Limitations: As with TLS connections (introduced in 1179.0), currently only client connections (TCPOP_CONNECT) are supported. Also, the TIMER option seems to interfere with the TLS handshaking. If having problems, turn that off and just use blocking mode, in conjunction with TCPOP_CHECK to check for data.
To initiate a STARTTLS connection, use the TCPOP_CONNECT opcode, along with the TCPXFLG_TLS and TCPXFLG_STARTTLS flags to initiate the unencrypted connection. When you want to start the TLS negotiation, use whatever unencrypted means are required to inform the server that you are about to start negotiating TLS, and then call TCPX with opcode TCPOP_STARTTLS. After the successful return (STATUS=0), you will be in encrypted mode, and the TCPXFLG_STARTTLS flag will no longer be needed. (However, as mentioned in the 1179 notes, TCPXFLG_TLS is required with EVERY call to TCPX if you are using TLS or STARTTLS protocol, including those calls prior to using TCPOP_STARTTLS.)
Note: EMAILX 5.1(121) uses this new feature to support the STARTTLS protocol extension to SMTP, permitting, for example, the use of the GMAIL SMTP server.
Unix installation requirements:
| • | Standard installation of the GnuTLS package, preferably version 2.8.6 (from www.gnu.org). |
| • | Copy the latest libashtls.so.1.0.xxx (xxx currently at 204) into the $MIAME/bin directory (where the ashell executable is). |
| • | Create /usr/lib/libashtls.so.1 as a symbolic link to the libashtls library in the $MIAME/bin directory, e.g.: |
# ln -s $MIAME/bin/libashtls.so.1.0.204 /usr/lib/libashtls.so.1
Windows installation requirements:
| • | Download http://www.microsabio.net/dist/other/gnutls/gnutls-2.8.6.zip and unzip the contents into the bin directory (where ashw32.exe is located). |
| • | Download http://www.microsabio.net/dist/51dev/bin-win/libashtls-204.zip and unzip the contents (libashtls.zip) into that same bin directory. |
Debugging notes: Use the "SOCKS" trace option (SET TRACE SOCKS ON) to record many details about the operation of the TLS library. For even more detail (particularparticularly about the handshaking process), also set the XDEBUG trace option.
