# STARTTLS

> [HTML Version](starttls.htm)

The STARTTLS protocol is supported via a an opcode and flag (in [ashell.def](ashell_def.md)).

| **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](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](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.