1.\" $OpenBSD: starttls.8,v 1.22 2015/12/24 16:54:37 mmcc Exp $ 2.\" 3.\" Copyright (c) 2001 Jose Nazario <jose@monkey.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 16.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 17.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 18.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd $Mdocdate: December 24 2015 $ 27.Dt STARTTLS 8 28.Os 29.Sh NAME 30.Nm starttls 31.Nd ESMTP over TLS/SSL 32.Sh DESCRIPTION 33STARTTLS is an ESMTP option, defined in RFC 3207, which is used to conduct 34ESMTP transactions over TLS circuits. 35This is used to increase the security of mail server transactions. 36.Pp 37STARTTLS allows for the combination of several security solutions for MTA 38(mail transport agent) level services through the TLS suite. 39These security features include: 40.Bl -tag -width Ds 41.It Confidentiality 42Encryption is used to protect data from passive monitoring. 43An attacker would have to recover the encryption key used to 44decode the transmitted data. 45.It Integrity 46Hash algorithms are used to ensure the integrity of the 47transmitted data, and alternatively the timestamp, protecting against a 48replay attack. 49This protects data from modification in transit. 50.It Authentication 51The use of public key encryption allows for the strong authentication of 52either, or both, communicating parties. 53This can be used to allow for select features, such as relaying, 54to be controlled more securely. 55.El 56.Pp 57A new ESMTP option, STARTTLS, has been added. 58This is presented by the server when an ESMTP session is initiated. 59The client then begins the TLS portion of the ESMTP session by issuing 60the command 61.Dq STARTTLS . 62The remaining portion of the ESMTP session occurs over a TLS channel. 63.Ss Creating a private key and certificate for an MTA 64This example assumes you are creating your own self-signed certificates 65for use with 66.Xr smtpd 8 67and STARTTLS. 68If you have an existing private key and you simply wish to generate 69a new certificate (for example, if your old certificate has expired), 70see the section entitled 71.Sx Creating a certificate with an existing private key . 72.Pp 73For the purposes of this example the certificates will be stored in 74.Pa /etc/ssl , 75though it is possible to use a different directory if needed. 76.Pp 77Next, you must generate an 78.Ar RSA 79private key: 80.Pp 81.Dl # openssl genrsa -out /etc/ssl/private/mail.example.com.key 4096 82.Pp 83This would generate a 4096-bit 84.Ar RSA 85key stored in the file 86.Pa mail.example.com.key . 87.Pp 88Once you have generated the 89.Ar RSA 90key, you can generate a certificate from it using the command: 91.Bd -literal -offset indent 92# openssl req -x509 -new -key /etc/ssl/private/mail.example.com.key \e 93 -out /etc/ssl/mail.example.com.crt -days 365 94.Ed 95.Pp 96You may adjust the lifetime of the certificate via the 97.Fl days 98parameter (one year in this example). 99.Pp 100You can verify that the newly-generated certificate has correct information 101with the following command: 102.Pp 103.Dl # openssl x509 -in /etc/ssl/mail.example.com.crt -text 104.Pp 105If you don't intend to use TLS for authentication (and if you are using 106self-signed certificates you probably don't) you can simply link 107your new certificate to 108.Pa CAcert.pem . 109.Pp 110.Dl # ln -s /etc/ssl/mail.example.com.crt /etc/ssl/CAcert.pem 111.Pp 112If, on the other hand, you intend to use TLS for authentication 113you should install your certificate authority bundle as 114.Pa /etc/ssl/CAcert.pem . 115.Pp 116Because the private key files are unencrypted, 117MTAs 118can be picky about using tight permissions on those files. 119The certificate directory and the files therein should be 120readable and writable only by the owner (root). 121A simple way to ensure this is to run the following: 122.Pp 123.Dl # chmod -R go-rwx /etc/ssl/private 124.Ss Creating a certificate with an existing private key 125This example assumes you already have an existing private key, 126.Pa /etc/ssl/private/mail.example.com.key . 127You can generate a new certificate based on this key using the command: 128.Bd -literal -offset indent 129# openssl req -x509 -new -key /etc/ssl/private/mail.example.com.key \e 130 -out /etc/ssl/mail.example.com.crt -days 365 131# chmod 600 /etc/ssl/mycert.pem 132.Ed 133.Pp 134You may adjust the lifetime of the certificate via the 135.Fl days 136parameter (one year in this example). 137.Pp 138After having installed the certificates 139the mail server needs to be configured to accept TLS sessions 140and use the key and certificate. 141For 142.Xr smtpd 8 , 143it's as simple as adding pki configuration to 144.Xr smtpd.conf 5 : 145.Bd -literal -offset indent 146pki mail.example.com certificate "/etc/ssl/mail.example.com.crt" 147pki mail.example.com key "/etc/ssl/private/mail.example.com.key" 148 149listen on [...] tls pki mail.example.com auth 150.Ed 151.Pp 152After restarting the mail server, a new option should be presented for ESMTP 153transactions, STARTTLS. 154You can test this by connecting to the local host and issuing the 155.Dq EHLO 156command. 157.Bd -literal -offset indent 158# telnet localhost 25 159Trying 127.0.0.1... 160Connected to localhost. 161Escape character is '^]'. 162220 localhost ESMTP OpenSMTPD 163EHLO localhost 164.Ed 165.Pp 166After typing 167.Em EHLO localhost 168you should receive something like the following back. 169.Bd -literal -offset indent 170250-localhost Hello localhost [127.0.0.1], pleased to meet you 171250-8BITMIME 172250-ENHANCEDSTATUSCODES 173250-SIZE 36700160 174250-DSN 175250-STARTTLS 176250 HELP 177.Ed 178.Pp 179You should see 180.Dq STARTTLS 181listed along with the other options. 182If so, congratulations, the MTA will now use TLS to encrypt your mail 183traffic when the remote server supports it. 184If not, check 185.Pa /var/log/maillog 186to see whether the MTA has reported any security problems or other errors. 187.Ss Uses for TLS equipped MTAs 188The most obvious use of a cryptographically enabled MTA 189is for confidentiality of the electronic mail transaction and the 190integrity checking provided by the cipher suite. 191All traffic between the two mail servers is encrypted, including the 192sender and recipient addresses. 193TLS also allows for authentication of either or both systems in the transaction. 194.Pp 195One use of public key cryptography is for strong authentication. 196We can use this authentication to selectively relay clients, including 197other mail servers and mobile clients like laptops. 198However, there have been some problems getting some mail clients to work using 199certificate-based authentication. 200Note that your clients will have to generate certificates and have them 201signed (for trust validation) by a CA (certificate authority) you also trust, 202if you configure your server to do client certificate checking. 203Two new entries are available for TLS options: 204.Bl -tag -width Ds -offset indent 205.It VERIFY 206contains the status of the level of verification (held in the macro {verify}) 207.It ENCR 208the strength of the encryption (in the macro {cipher_bits}) 209.El 210.Pp 211VERIFY can also accept the argument for {cipher_bits}. 212Here are a few example entries that illustrate these features, and 213the role based granularity as well: 214.Pp 215Require strong (256-bit) encryption for communication with this server: 216.Pp 217.Dl TLS_Srv:server1.example.net ENCR:256 218.Pp 219For a TLS client, 220require verification and a minimum of 128-bit encryption: 221.Pp 222.Dl TLS_Clt:desktop.example.net VERIFY:128 223.Pp 224Much more complicated access maps are possible, and error conditions (such 225as permanent or temporary, PERM+ or TEMP+) can be set on the basis of 226various criteria. 227This allows you fine-grained control over the types of connections you 228can allow. 229.Pp 230Note that it is unwise to force all SMTP clients to use TLS, as it is not 231yet widespread. 232The RFC document notes that publicly referenced SMTP servers, such as the 233MX servers for a domain, must not refuse non-TLS connections. 234However, restricted access SMTP servers, such as those for a corporate 235intranet, can use TLS as an access control mechanism. 236.Sh SEE ALSO 237.Xr mail 1 , 238.Xr openssl 1 , 239.Xr smtpd 8 , 240.Xr ssl 8 241.Sh STANDARDS 242.Rs 243.%A P. Hoffman 244.%D February 2002 245.%R RFC 3207 246.%T SMTP Service Extension for Secure SMTP over Transport Layer Security 247.Re 248.Sh CAVEATS 249One often forgotten limitation of using TLS on a mail server is the 250payload of the mail message and the resulting security there. 251Many virus and worm files are now distributed via electronic mail. 252While the mail may be encrypted and the servers authenticated, the payload 253can still be malicious. 254The use of a good content protection program on the desktop is 255therefore still of value even with TLS at the MTA level. 256.Pp 257Because TLS can only authenticate at the server level, true 258end-to-end authentication of the mail message cannot be performed with 259only the use of STARTLS on the server. 260The use of S/MIME or PGP email and trustworthy key hierarchies can guarantee 261full confidentiality and integrity of the entire message path. 262.Pp 263Furthermore, if a mail message traverses more than just the starting and 264ending servers, there is no way to control interactions between the intervening 265mail servers, which may use non-secure connections. 266This introduces a point of vulnerability in the chain. 267.Pp 268Additionally, SMTP over TLS is not yet widely implemented. 269The standard, in fact, doesn't require it, leaving it only as an option, though 270specific sites can configure their servers to force it for specific clients. 271As such, it is difficult to foresee the widespread use of SMTP using TLS, 272despite the fact that the standard is, at the date of this writing, 273over two years old. 274.Pp 275Lastly, interoperability problems can appear between different implementations. 276