xref: /openbsd/share/man/man8/starttls.8 (revision 1c80ab25)

.\" $OpenBSD: starttls.8,v 1.26 2018/06/27 05:39:02 jmc Exp $
.\"
.\" Copyright (c) 2001 Jose Nazario <jose@monkey.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: June 27 2018 $
.Dt STARTTLS 8
.Os
.Sh NAME
.Nm starttls
.Nd ESMTP over TLS/SSL
.Sh DESCRIPTION
STARTTLS is an ESMTP option, defined in RFC 3207, which is used to conduct
ESMTP transactions over TLS circuits.
This is used to increase the security of mail server transactions.
.Pp
STARTTLS allows for the combination of several security solutions for MTA
(mail transport agent) level services through the TLS suite.
These security features include:
.Bl -tag -width Ds
.It Confidentiality
Encryption is used to protect data from passive monitoring.
An attacker would have to recover the encryption key used to
decode the transmitted data.
.It Integrity
Hash algorithms are used to ensure the integrity of the
transmitted data, and alternatively the timestamp, protecting against a
replay attack.
This protects data from modification in transit.
.It Authentication
The use of public key encryption allows for the strong authentication of
either, or both, communicating parties.
This can be used to allow for select features, such as relaying,
to be controlled more securely.
.El
.Pp
A new ESMTP option, STARTTLS, has been added.
This is presented by the server when an ESMTP session is initiated.
The client then begins the TLS portion of the ESMTP session by issuing
the command
.Dq STARTTLS .
The remaining portion of the ESMTP session occurs over a TLS channel.
.Ss Creating a private key and certificate for an MTA
This example assumes you are creating your own self-signed certificates
for use with
.Xr smtpd 8
and STARTTLS.
If you have an existing private key and you simply wish to generate
a new certificate (for example, if your old certificate has expired),
see the section entitled
.Sx Creating a certificate with an existing private key .
.Pp
For the purposes of this example the certificates will be stored in
.Pa /etc/ssl ,
though it is possible to use a different directory if needed.
.Pp
Next, you must generate an
.Ar RSA
private key:
.Pp
.Dl # openssl genrsa -out /etc/ssl/private/mail.example.com.key 4096
.Pp
This would generate a 4096-bit
.Ar RSA
key stored in the file
.Pa mail.example.com.key .
.Pp
Once you have generated the
.Ar RSA
key, you can generate a certificate from it using the command:
.Bd -literal -offset indent
# openssl req -x509 -new -key /etc/ssl/private/mail.example.com.key \e
  -out /etc/ssl/mail.example.com.crt -days 365
.Ed
.Pp
You may adjust the lifetime of the certificate via the
.Fl days
parameter (one year in this example).
.Pp
You can verify that the newly-generated certificate has correct information
with the following command:
.Pp
.Dl # openssl x509 -in /etc/ssl/mail.example.com.crt -text
.Pp
If you don't intend to use TLS for authentication (and if you are using
self-signed certificates you probably don't) you can simply link
your new certificate to
.Pa cert.pem :
.Pp
.Dl # ln -s /etc/ssl/mail.example.com.crt /etc/ssl/cert.pem
.Pp
If, on the other hand, you intend to use TLS for authentication
you should add your certificate authority bundle to
.Pa /etc/ssl/cert.pem
(or whatever your software expects).
.Pp
Because the private key files are unencrypted,
MTAs can be picky about using tight permissions on those files.
The certificate directory and the files therein should be
readable and writable only by the owner (root).
A simple way to ensure this is to run the following:
.Pp
.Dl # chmod -R go-rwx /etc/ssl/private
.Ss Creating a certificate with an existing private key
This example assumes you already have an existing private key,
.Pa /etc/ssl/private/mail.example.com.key .
You can generate a new certificate based on this key using the command:
.Bd -literal -offset indent
# openssl req -x509 -new -key /etc/ssl/private/mail.example.com.key \e
  -out /etc/ssl/mail.example.com.crt -days 365
# chmod 600 /etc/ssl/mail.example.com.crt
.Ed
.Pp
You may adjust the lifetime of the certificate via the
.Fl days
parameter (one year in this example).
.Pp
After having installed the certificates
the mail server needs to be configured to accept TLS sessions
and use the key and certificate.
For
.Xr smtpd 8 ,
it's as simple as adding pki configuration to
.Xr smtpd.conf 5 :
.Bd -literal -offset indent
pki mail.example.com cert "/etc/ssl/mail.example.com.crt"
pki mail.example.com key "/etc/ssl/private/mail.example.com.key"

listen on [...] tls pki mail.example.com auth
.Ed
.Pp
After restarting the mail server, a new option should be presented for ESMTP
transactions, STARTTLS.
You can test this by connecting to the local host and issuing the
.Dq EHLO
command.
.Bd -literal -offset indent
# telnet localhost 25
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 localhost ESMTP OpenSMTPD
EHLO localhost
.Ed
.Pp
After typing
.Em EHLO localhost
you should receive something like the following back.
.Bd -literal -offset indent
250-localhost Hello localhost [127.0.0.1], pleased to meet you
250-8BITMIME
250-ENHANCEDSTATUSCODES
250-SIZE 36700160
250-DSN
250-STARTTLS
250 HELP
.Ed
.Pp
You should see
.Dq STARTTLS
listed along with the other options.
If so, congratulations, the MTA will now use TLS to encrypt your mail
traffic when the remote server supports it.
If not, check
.Pa /var/log/maillog
to see whether the MTA has reported any security problems or other errors.
.Ss Uses for TLS equipped MTAs
The most obvious use of a cryptographically enabled MTA
is for confidentiality of the electronic mail transaction and the
integrity checking provided by the cipher suite.
All traffic between the two mail servers is encrypted, including the
sender and recipient addresses.
TLS also allows for authentication of either or both systems in the transaction.
.Pp
One use of public key cryptography is for strong authentication.
We can use this authentication to selectively relay clients, including
other mail servers and mobile clients like laptops.
However, there have been some problems getting some mail clients to work using
certificate-based authentication.
Clients will have to generate certificates and have them
signed (for trust validation) by a trusted CA (certificate authority).
.Pp
Note that it is unwise to force all SMTP clients to use TLS, as it is not
yet widespread.
The RFC document notes that publicly referenced SMTP servers, such as the
MX servers for a domain, must not refuse non-TLS connections.
However, restricted access SMTP servers, such as those for a corporate
intranet, can use TLS as an access control mechanism.
.Sh SEE ALSO
.Xr mail 1 ,
.Xr openssl 1 ,
.Xr smtpd 8 ,
.Xr ssl 8
.Sh STANDARDS
.Rs
.%A P. Hoffman
.%D February 2002
.%R RFC 3207
.%T SMTP Service Extension for Secure SMTP over Transport Layer Security
.Re
.Sh CAVEATS
One often forgotten limitation of using TLS on a mail server is the
payload of the mail message and the resulting security there.
Many virus and worm files are now distributed via electronic mail.
While the mail may be encrypted and the servers authenticated, the payload
can still be malicious.
The use of a good content protection program on the desktop is
therefore still of value even with TLS at the MTA level.
.Pp
Because TLS can only authenticate at the server level, true
end-to-end authentication of the mail message cannot be performed with
only the use of STARTTLS on the server.
The use of S/MIME or PGP email and trustworthy key hierarchies can guarantee
full confidentiality and integrity of the entire message path.
.Pp
Furthermore, if a mail message traverses more than just the starting and
ending servers, there is no way to control interactions between the intervening
mail servers, which may use non-secure connections.
This introduces a point of vulnerability in the chain.
.Pp
Additionally, SMTP over TLS is not yet widely implemented.
The standard, in fact, doesn't require it, leaving it only as an option, though
specific sites can configure their servers to force it for specific clients.
As such, it is difficult to foresee the widespread use of SMTP using TLS,
despite the fact that the standard is, at the date of this writing,
over two years old.
.Pp
Lastly, interoperability problems can appear between different implementations.