doc: add summary on SMTP over TLS (RFC3207)

Additional note on lib/smtp: the server favor implicit TLS over STARTTLS
(RFC8314), which means if server's environment is configured with
certificate, server will listen on port 465 only, not on port 25 and 465
and neither on port 465 and 587.

4 files changed, 118 insertions, 2 deletions

diff --git a/README.adoc b/README.adoc
index 2ce994bc..c3519ab2 100644
--- a/README.adoc
+++ b/README.adoc
@@ -131,7 +131,11 @@ Beside {url-godoc}[GoDoc], that provides documentation for API in packages,
 there are also additional documentations that we can't include inside source
 code due to their scope and limitation of godoc formatting itself.
 
-* link:doc/SMTP.html[Simple Mail Transfer Protocol (RFC 5321)]
+* link:doc/SMTP.html[Simple Mail Transfer Protocol (RFC5321)]
+** link:doc/ESMTP_DSN.html[Delivery Status Notification (RFC3461-3464)]
+** link:doc/ESMTP_TLS.html[SMTP Service Extension for Secure SMTP over
+Transport Layer Security (RFC3207)]
+
 * link:doc/IMF.html[Internet Message Format (RFC 5322)]
 
 === Development
diff --git a/doc/ESMTP_TLS.adoc b/doc/ESMTP_TLS.adoc
new file mode 100644
index 00000000..1c9ab138
--- /dev/null
+++ b/doc/ESMTP_TLS.adoc
@@ -0,0 +1,102 @@
+= SMTP Service Extension for Secure SMTP over Transport Layer Security
+:author: Shulhan
+:email: <ms@kilabit.info>
+:toc: left
+:toclevels: 4
+:sectnums:
+:stylesheet: solarized.css
+:url-rfc3207: https://tools.ietf.org/html/rfc3207
+
+This documentation provide summary and notes on implementation of SMTP
+service extension for secure SMTP over Transport Layer Security (TLS) as
+defined in {url-rfc3207}[RFC3207].
+
+== Service Extension
+
+The EHLO keyword value associated with the extension is "STARTTLS" with no
+parameter.
+
+A new SMTP command "STARTTLS" is defined.
+
+A publicly-referenced SMTP server (on port 25) MUST NOT require use of the
+STARTTLS extension in order to deliver mail locally.
+
+
+== STARTTLS command
+
+=== Request
+
+....
+"STARTTLS" CRLF
+....
+
+==== Success Response
+
+....
+"220" SP *text CRLF
+....
+
+After receiving a 220 response to a STARTTLS command, the client MUST start
+the TLS negotiation before giving any other SMTP commands.
+If, after having issued the STARTTLS command, the client finds out that some
+failure prevents it from actually starting a TLS handshake, then it SHOULD
+abort the connection.
+
+==== Error Response
+
+* 454 TLS not available due to temporary reason
+* 501 Syntax error (no parameters allowed)
+
+If the client receives the 454 response, the client must decide whether or not
+to continue the SMTP session.
+
+A SMTP server that is not publicly referenced may choose to require that the
+client perform a TLS negotiation before accepting any commands.
+In this case, the server SHOULD return the reply code:
+
+    "530 Must issue a STARTTLS command first" CRLF
+
+to every command other than NOOP, EHLO, STARTTLS, or QUIT.
+If the client and server are using the ENHANCEDSTATUSCODES ESMTP extension
+[RFC2034], the status code to be returned SHOULD be 5.7.0.
+
+
+== Post TLS Handshake
+
+=== Client
+
+The client MUST discard any knowledge obtained from the server, such as the
+list of SMTP service extensions, which was not obtained from the TLS
+negotiation itself.
+The client SHOULD send an EHLO command as the first command after a successful
+TLS negotiation.
+
+The list of SMTP service extensions returned in response to an EHLO command
+received after the TLS handshake MAY be different than the list returned
+before the TLS handshake.
+
+A client MUST NOT attempt to start a TLS session if a TLS session is already
+active.
+
+=== Server
+
+The server MUST discard any knowledge obtained from the client, such as the
+argument to the EHLO command, which was not obtained from the TLS negotiation
+itself.
+
+A server MUST NOT return the STARTTLS extension in response to an EHLO command
+received after a TLS handshake has completed.
+
+== Security Considerations
+
+If the SMTP client decides that the level of authentication or privacy is not
+high enough for it to continue, it SHOULD issue an SMTP QUIT command
+immediately after the TLS negotiation is complete.
+
+If the SMTP server decides that the level of authentication or privacy is not
+high enough for it to continue, it SHOULD reply to every SMTP command from the
+client (other than a QUIT command) with,
+
+    "554 Command refused due to lack of security" CRLF
+
+the server may choose to not accept any more SMTP commands.
diff --git a/doc/SMTP.adoc b/doc/SMTP.adoc
index cbf3d9e0..d93d4973 100644
--- a/doc/SMTP.adoc
+++ b/doc/SMTP.adoc
@@ -659,7 +659,9 @@ Any current uncompleted mail transaction will be aborted.
 
 == Extensions
 
-* link:ESMTP_DSN.html[Delivery Status Notification]
+* link:ESMTP_DSN.html[Delivery Status Notification (RFC3461-3464)]
+* link:ESMTP_TLS.html[SMTP Service Extension for Secure SMTP over Transport
+Layer Security (RFC3207)]
 
 
 == Glossary
diff --git a/lib/smtp/doc.go b/lib/smtp/doc.go
index 00d45aa9..95e9a90c 100644
--- a/lib/smtp/doc.go
+++ b/lib/smtp/doc.go
@@ -2,5 +2,13 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+//
 // Package smtp provide a library for building SMTP server and client.
+//
+// Limitations
+//
+// The server favor implicit TLS over STARTTLS (RFC8314).  When server's
+// environment is configured with certificate, server will listen on port
+// 465 only, not on port 25 and 465 and neither on port 465 and 587.
+//
 package smtp