1.\" $OpenBSD: starttls.8,v 1.16 2008/09/23 11:03:41 grunk 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: September 23 2008 $ 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. 36As of version 8.11, 37.Xr sendmail 8 38has supported the use of TLS to protect ESMTP communications. 39.Pp 40STARTTLS allows for the combination of several security solutions for MTA 41(mail transport agent) level services through the TLS suite. 42These security features include: 43.Bl -tag -width Ds 44.It Confidentiality 45Encryption is used to protect data from passive monitoring. 46An attacker would have to recover the encryption key used to 47decode the transmitted data. 48.It Integrity 49Hash algorithms are used to ensure the integrity of the 50transmitted data, and alternatively the timestamp, protecting against a 51replay attack. 52This protects data from modification in transit. 53.It Authentication 54The use of public key encryption allows for the strong authentication of 55either, or both, communicating parties. 56This can be used to allow for select features, such as relaying, 57to be controlled more securely. 58.El 59.Pp 60A new ESMTP option, STARTTLS, has been added. 61This is presented by the server when an ESMTP session is initiated. 62The client then begins the TLS portion of the ESMTP session by issuing 63the command 64.Dq STARTTLS . 65The remaining portion of the ESMTP session occurs over a TLS channel. 66.Ss Creating a private key and certificate for sendmail 67This example assumes you are creating your own self-signed certificates 68for use with sendmail and STARTTLS. 69If you have an existing private key and you simply wish to generate 70a new certificate (for example, if your old certificate has expired), 71see the section entitled 72.Sx "Creating a certificate with an existing private key" . 73.Pp 74For the purposes of this example the certificates will be stored in 75.Pa /etc/mail/certs , 76though it is possible to use a different directory if needed. 77If this directory does not already exist, you must create it: 78.Pp 79.Dl # mkdir /etc/mail/certs 80.Pp 81Next, you must generate a 82.Ar DSA 83parameter set with a command like the following: 84.Pp 85.Dl # openssl dsaparam 1024 -out dsa1024.pem 86.Pp 87This would generate 88.Ar DSA 89parameters for 1024-bit 90.Ar DSA 91keys, and save them to the 92file 93.Pa dsa1024.pem . 94.Pp 95Once you have the 96.Ar DSA 97parameters generated, you can generate a certificate 98and unencrypted private key using the command: 99.Bd -literal -offset indent 100# openssl req -x509 -nodes -days 365 -newkey dsa:dsa1024.pem \e 101 -out /etc/mail/certs/mycert.pem -keyout /etc/mail/certs/mykey.pem 102.Ed 103.Pp 104You may adjust the lifetime of the certificate via the 105.Fl days 106parameter (one year in this example). 107.Pp 108Make sure to leave the private key files unencrypted, using the 109.Fl nodes 110option. 111Otherwise, 112.Xr sendmail 8 113will be unable to initiate TLS server functions. 114.Pp 115You can verify that the newly-generated certificate has correct information 116with the following command: 117.Pp 118.Dl # openssl x509 -in /etc/mail/certs/mycert.pem -text 119.Pp 120If you don't intend to use TLS for authentication (and if you are using 121self-signed certificates you probably don't) you can simply link 122your new certificate to 123.Pa CAcert.pem . 124.Pp 125.Dl # ln -s /etc/mail/certs/mycert.pem /etc/mail/certs/CAcert.pem 126.Pp 127If, on the other hand, you intend to use TLS for authentication 128you should install your certificate authority bundle as 129.Pa /etc/mail/certs/CAcert.pem . 130.Pp 131At this point, you no longer need the 132.Pa dsa1024.pem 133file and it can be removed. 134.Pp 135.Dl # rm dsa1024.pem 136.Pp 137Because the private key files are unencrypted, 138.Xr sendmail 8 139is picky about using tight permissions on those files. 140The certificate directory and the files therein should be 141readable and writable only by the owner (root). 142A simple way to ensure this is to run the following: 143.Pp 144.Dl # chmod -R go-rwx /etc/mail/certs 145.Ss Creating a certificate with an existing private key 146This example assumes you already have an existing private key, 147.Pa /etc/mail/certs/mykey.pem . 148You can generate a new certificate based on this key using the command: 149.Bd -literal -offset indent 150# openssl req -x509 -new -days 365 -key /etc/mail/certs/mykey.pem \e 151 -out /etc/mail/certs/mycert.pem 152# chmod 600 /etc/mail/certs/mycert.pem 153.Ed 154.Pp 155You may adjust the lifetime of the certificate via the 156.Fl days 157parameter (one year in this example). 158.Ss Configuring sendmail to utilize TLS 159The global sendmail configuration files, 160.Pa /etc/mail/sendmail.cf 161and 162.Pa /etc/mail/localhost.cf 163must be modified to support TLS functionality. 164An example .mc file which has entries for TLS options, such as certificates, 165is available as 166.Pa /usr/share/sendmail/cf/knecht.mc . 167.Pp 168The pertinent options are: 169.Pp 170.Bl -bullet -compact 171.It 172CERT_DIR 173.It 174confCACERT_PATH 175.It 176confCACERT 177.It 178confSERVER_CERT 179.It 180confSERVER_KEY 181.It 182confCLIENT_CERT 183.It 184confCLIENT_KEY 185.El 186.Pp 187By default, the directory 188.Pa /etc/mail/certs , 189defined by CERT_DIR, is used to store certificates, and the server will 190use the same certificates both as a client (outgoing mail) and as a server 191(for incoming mail). 192This can be changed by having different entries for the respective roles. 193.Pp 194The next step is to edit the .mc files your 195.Pa sendmail.cf 196and 197.Pa localhost.cf 198files are generated from. 199First, change to the directory where your .mc files are stored. 200You will need to make TLS-enabled versions of the following files: 201.Pa openbsd-proto.mc 202and 203.Pa openbsd-localhost.mc . 204.Bd -literal -offset indent 205# cd /usr/share/sendmail/cf 206 207# cp openbsd-proto.mc openbsd-proto-tls.mc 208# cp openbsd-localhost.mc openbsd-localhost-tls.mc 209.Ed 210.Pp 211You must then edit 212.Pa openbsd-proto-tls.mc , 213and 214.Pa openbsd-localhost-tls.mc 215to add the following lines after the 216.Dq VERSIONID 217definition (the actual placement within the file is not critical as long 218as it is after the 219.Dq divert(0)dnl 220line). 221.Bd -literal -offset indent 222define(`CERT_DIR', `MAIL_SETTINGS_DIR`'certs') 223define(`confCACERT_PATH', `CERT_DIR') 224define(`confCACERT', `CERT_DIR/CAcert.pem') 225define(`confSERVER_CERT', `CERT_DIR/mycert.pem') 226define(`confSERVER_KEY', `CERT_DIR/mykey.pem') 227define(`confCLIENT_CERT', `CERT_DIR/mycert.pem') 228define(`confCLIENT_KEY', `CERT_DIR/mykey.pem') 229.Ed 230.Pp 231Now that you have the TLS-enabled versions of the .mc files 232you must generate .cf files from them and install the .cf 233files in 234.Pa /etc/mail . 235.Bd -literal -offset indent 236# make openbsd-proto-tls.cf openbsd-localhost-tls.cf 237 238# cp openbsd-proto-tls.cf /etc/mail/sendmail.cf 239# cp openbsd-localhost-tls.cf /etc/mail/localhost.cf 240.Ed 241.Pp 242Finally, restart sendmail with the new configuration by sending 243it a 244.Dv SIGHUP . 245.Pp 246.Dl # kill -HUP `head -1 /var/run/sendmail.pid` 247.Pp 248Note that those are backticks and not single quotes in the example above. 249.Pp 250After having installed the certificates and configuration files and having 251restarted the sendmail daemon, a new option should be presented for ESMTP 252transactions, STARTTLS. 253You can test this by connecting to the local host and issuing the 254.Dq EHLO 255command. 256.Bd -literal -offset indent 257# telnet localhost 25 258Trying ::1... 259Connected to localhost. 260Escape character is '^]'. 261220 localhost ESMTP Sendmail 8.12.1/8.12.1 ready 262EHLO localhost 263.Ed 264.Pp 265After typing 266.Em EHLO localhost 267you should receive something like the following back. 268.Bd -literal -offset indent 269250-localhost Hello localhost [IPv6:::1], pleased to meet you 270250-ENHANCEDSTATUSCODES 271250-PIPELINING 272250-8BITMIME 273250-SIZE 274250-DSN 275250-ETRN 276250-STARTTLS 277250-DELIVERBY 278250 HELP 279.Ed 280.Pp 281You should see 282.Dq STARTTLS 283listed along with the other options. 284If so, congratulations, sendmail will now use TLS to encrypt your mail 285traffic when the remote server supports it. 286If not, check 287.Pa /var/log/maillog 288to see whether sendmail has reported any security problems or other errors. 289.Ss Uses for TLS-Equipped sendmail 290The most obvious use of a cryptographically enabled sendmail installation 291is for confidentiality of the electronic mail transaction and the 292integrity checking provided by the cipher suite. 293All traffic between the two mail servers is encrypted, including the 294sender and recipient addresses. 295TLS also allows for authentication of either or both systems in the transaction. 296.Pp 297One use of public key cryptography is for strong authentication. 298We can use this authentication to selectively relay clients, including 299other mail servers and mobile clients like laptops. 300However, there have been some problems getting some mail clients to work using 301certificate-based authentication. 302Note that your clients will have to generate certificates and have them 303signed (for trust validation) by a CA (certificate authority) you also trust, 304if you configure your server to do client certificate checking. 305.Pp 306The use of the access map (usually 307.Pa /etc/mail/access ) , 308which is normally used to determine connections and relaying, 309can also be extended to give server level control for the use of TLS. 310Two new entries are available for TLS options: 311.Bl -tag -width Ds -offset indent 312.It VERIFY 313contains the status of the level of verification (held in the macro {verify}) 314.It ENCR 315the strength of the encryption (in the macro {cipher_bits}) 316.El 317.Pp 318VERIFY can also accept the argument for {cipher_bits}. 319Here are a few example entries that illustrate these features, and 320the role based granularity as well: 321.Pp 322Force strong (112-bit) encryption for communications for this server: 323.Pp 324.Dl server1.example.net ENCR:112 325.Pp 326For a TLS client, force string verification depths to at least 80 bits: 327.Pp 328.Dl TLS_Clt:desktop.example.net VERIFY:80 329.Pp 330Much more complicated access maps are possible, and error conditions (such 331as permanent or temporary, PERM+ or TEMP+) can be set on the basis of 332various criteria. 333This allows you fine-grained control over the types of connections you 334can allow. 335.Pp 336Note that it is unwise to force all SMTP clients to use TLS, as it is not 337yet widespread. 338The RFC document notes that publicly referenced SMTP servers, such as the 339MX servers for a domain, must not refuse non-TLS connections. 340However, restricted access SMTP servers, such as those for a corporate 341intranet, can use TLS as an access control mechanism. 342.Sh LIMITATIONS 343One often forgotten limitation of using TLS on a mail server is the 344payload of the mail message and the resulting security there. 345Many virus and worm files are now distributed via electronic mail. 346While the mail may be encrypted and the servers authenticated, the payload 347can still be malicious. 348The use of a good content protection program on the desktop is 349therefore still of value even with TLS at the MTA level. 350.Pp 351Because sendmail with TLS can only authenticate at the server level, true 352end-to-end authentication of the mail message cannot be performed with 353only the use of STARTLS on the server. 354The use of S/MIME or PGP e-mail and trustworthy key hierarchies can guarantee 355full confidentiality and integrity of the entire message path. 356.Pp 357Furthermore, if a mail message traverses more than just the starting and 358ending servers, there is no way to control interactions between the intervening 359mail servers, which may use non-secure connections. 360This introduces a point of vulnerability in the chain. 361.Pp 362Additionally, SMTP over TLS is not yet widely implemented. 363The standard, in fact, doesn't require it, leaving it only as an option, though 364specific sites can configure their servers to force it for specific clients. 365As such, it is difficult to foresee the widespread use of SMTP using TLS, 366despite the fact that the standard is, at the date of this writing, 367over two years old. 368.Pp 369Lastly, interoperability problems can appear between different implementations. 370.Sh SEE ALSO 371.Xr mail 1 , 372.Xr openssl 1 , 373.Xr afterboot 8 , 374.Xr sendmail 8 , 375.Xr ssl 8 376.Pp 377.Tn DARPA 378Internet Request for Comments RFC 3207 379.Pp 380http://www.sendmail.org/~ca/email/starttls.html 381.Sh HISTORY 382TLS features first appeared in sendmail 8.11. 383