From edb5211f5fcb2c265d944a1c5669372feb7e53f3 Mon Sep 17 00:00:00 2001
From: Badlop <badlop@process-one.net>
Date: Thu, 25 Jun 2009 18:02:23 +0000
Subject: [PATCH] Improve explanation about SSL for port 5223 and its option
 'tls'.

SVN Revision: 2339
---
 doc/guide.html | 12 +++++++++---
 doc/guide.tex  | 12 +++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/doc/guide.html b/doc/guide.html
index 4c0cddb3d..3b4302871 100644
--- a/doc/guide.html
+++ b/doc/guide.html
@@ -759,8 +759,14 @@ No unencrypted connections will be allowed.
 You should also set the <TT>certfile</TT> option.
 You can define a certificate file for a specific domain using the global option <TT>domain_certfile</TT>.
 </DD><DT CLASS="dt-description"><B><TT>tls</TT></B></DT><DD CLASS="dd-description"> This option specifies that traffic on
-the port will be encrypted using SSL immediately after connecting. You
-should also set the <TT>certfile</TT> option.
+the port will be encrypted using SSL immediately after connecting.
+This was the traditional encryption method in the early Jabber software,
+commonly on port 5223 for client-to-server communications.
+But this method is nowadays deprecated and not recommended.
+The preferable encryption method is STARTTLS on port 5222, as defined 
+<A HREF="http://www.xmpp.org/specs/rfc3920.html#tls">RFC 3920: XMPP Core</A>,
+which can be enabled in <TT>ejabberd</TT> with the option <TT>starttls</TT>.
+If this option is set, you should also set the <TT>certfile</TT> option.
 </DD><DT CLASS="dt-description"><B><TT>web_admin</TT></B></DT><DD CLASS="dd-description"> This option
 enables the Web Admin for <TT>ejabberd</TT> administration which is available
 at <CODE>http://server:port/admin/</CODE>. Login and password are the username and
@@ -770,7 +776,7 @@ password of one of the registered users who are granted access by the
 option specifies that Zlib stream compression (as defined in <A HREF="http://www.xmpp.org/extensions/xep-0138.html">XEP-0138</A>)
 is available on connections to the port. Client connections cannot use
 stream compression and stream encryption simultaneously. Hence, if you
-specify both <TT>tls</TT> (or <TT>ssl</TT>) and <TT>zlib</TT>, the latter
+specify both <TT>starttls</TT> (or <TT>tls</TT>) and <TT>zlib</TT>, the latter
 option will not affect connections (there will be no stream compression).
 </DD></DL><P>There are some additional global options that can be specified in the ejabberd configuration file (outside <TT>listen</TT>):
 </P><DL CLASS="description"><DT CLASS="dt-description">
diff --git a/doc/guide.tex b/doc/guide.tex
index b0dd921ec..ca8eeec5e 100644
--- a/doc/guide.tex
+++ b/doc/guide.tex
@@ -896,8 +896,14 @@ This is a detailed description of each option allowed by the listening modules:
     You should also set the \option{certfile} option.
     You can define a certificate file for a specific domain using the global option \option{domain\_certfile}.
   \titem{tls} \ind{options!tls}\ind{TLS}This option specifies that traffic on
-    the port will be encrypted using SSL immediately after connecting. You
-    should also set the \option{certfile} option.
+    the port will be encrypted using SSL immediately after connecting.
+    This was the traditional encryption method in the early Jabber software,
+    commonly on port 5223 for client-to-server communications.
+    But this method is nowadays deprecated and not recommended.
+    The preferable encryption method is STARTTLS on port 5222, as defined 
+    \footahref{http://www.xmpp.org/specs/rfc3920.html\#tls}{RFC 3920: XMPP Core},
+    which can be enabled in \ejabberd{} with the option \term{starttls}.
+    If this option is set, you should also set the \option{certfile} option.
   \titem{web\_admin} \ind{options!web\_admin}\ind{web admin}This option
     enables the Web Admin for \ejabberd{} administration which is available
     at \verb|http://server:port/admin/|. Login and password are the username and
@@ -907,7 +913,7 @@ This is a detailed description of each option allowed by the listening modules:
     option specifies that Zlib stream compression (as defined in \xepref{0138})
     is available on connections to the port. Client connections cannot use
     stream compression and stream encryption simultaneously. Hence, if you
-    specify both \option{tls} (or \option{ssl}) and \option{zlib}, the latter
+    specify both \option{starttls} (or \option{tls}) and \option{zlib}, the latter
     option will not affect connections (there will be no stream compression).
 \end{description}