<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>SMAP connection negotiation</title>
<link rel="stylesheet" href="manpage.css" type="text/css"/>
<link rel="start" href="index.html" title="Cone: COnsole Newsreader And Emailer"/>
<link rel="up" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1"/>
<link rel="prev" href="smapsyntax.html" title="SMAP syntax overview"/>
<link rel="next" href="smapfolders.html" title="Folders"/>
<link xmlns="" rel="icon" href="icon.gif" type="image/gif"/>
<meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/>
<!--
Copyright 2002 - 2007 Double Precision, Inc. See COPYING for distribution
information.
-->
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center" rowspan="1">SMAP connection
negotiation</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="smapsyntax.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
Appendix A. Simple Mail Access Protocol, Version
1</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="smapfolders.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="conn" shape="rect" name="conn"> </a>SMAP connection negotiation</h3>
</div>
</div>
</div>
<p>It is possible to have a server that handles both IMAP4rev1
and SMAP1. This is done by establishing the initial SMAP1
client/server connection in a manner that's compatible with
IMAP. When the server receives a connection from a client, the
server sends the following reply:</p>
<div class="literallayout">
<p><br clear="none"/>
* OK [CAPABILITY <em class="replaceable"><code>capabilitylist</code></em>] <em class="replaceable"><code>message</code></em><br clear="none"/>
</p>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>Servers that offer both IMAP and SMAP must terminate the
initial reply with CRLF. SMAP-only servers can use the LF
character alone.</p>
</div>
<p>“<span class="quote"><em class="replaceable"><code>message</code></em></span>” is
free-form text, that identifies the server software in
human-readable format. “<span class="quote"><em class="replaceable"><code>capabilitylist</code></em></span>” is
a list of keywords that describe the server's technical
implementation. Keywords in the list are separated by
whitespace. Clients should separate whitespace-delimited
“<span class="quote"><em class="replaceable"><code>capabilitylist</code></em></span>”
into individual keywords. Multiple keywords may occur in any
order, and clients must search the entire list for keywords the
client understands.</p>
<p>The presence of the <code class="literal">SMAP1</code>
keyword specifies that the server implements the protocol
defined by this document. Absence of the <code class="literal">SMAP1</code> keyword indicates that the server is
probably an IMAP server. Clients that support both SMAP and
IMAP protocol can automatically revert to IMAP, if they so
choose.</p>
<p>The server's initial reply to the client may include the
“<span class="quote"><em class="replaceable"><code>message</code></em></span>” part
only, without a leading keyword capability list inside. This
indicates that the server is only an IMAP server, and does not
support SMAP.</p>
<p>“<span class="quote"><em class="replaceable"><code>capabilitylist</code></em></span>”
may include additional keywords besides <code class="literal">SMAP1</code>. This document defines the following
keywords. Other keywords may be added in the future. SMAP
clients coded to this specification should ignore keywords they
do not recognize.</p>
<div class="variablelist">
<dl>
<dt><span class="term">STARTTLS</span></dt>
<dd>
<p>This SMAP server supports an SSL/TLS connection, via
the STARTTLS command.</p>
</dd>
<dt><span class="term">AUTH=<em class="replaceable"><code>mechanism</code></em></span></dt>
<dd>
<p>This SMAP server supports the “<span class="quote"><em class="replaceable"><code>mechanism</code></em></span>”
authentication mechanism, as defined by <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc3501.txt" target="_top" shape="rect">RFC 3501</a>, and its successors.</p>
</dd>
<dt><span class="term">LANG=<em class="replaceable"><code>language</code></em></span></dt>
<dd>
<p>This SMAP1 server can return diagnostic messages in
the natural language “<span class="quote"><em class="replaceable"><code>language</code></em></span>”.
“<span class="quote"><em class="replaceable"><code>language</code></em></span>” is
a language tag defined by <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc1766.txt" target="_top" shape="rect">RFC 1766</a>. A multilingual SMAP server
lists multiple <code class="literal">LANG</code>
keywords, one keyword for each language.</p>
</dd>
<dt><span class="term">KEYWORDS</span></dt>
<dd>
<p>The SMAP1 server supports user-defined per-message
<code class="literal">KEYWORDS</code> attributes.</p>
</dd>
</dl>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The <code class="literal">STARTTLS</code> and <code class="literal">AUTH</code> keywords are also used by IMAP in the
same way. IMAP does not define the <code class="literal">LANG</code> keyword (there is an optional extension
to the base IMAP protocol specification that is functionally
similar, but not compatible, with this definition). At this
time, <code class="literal">LANG</code> does not introduce
interoperability issues with IMAP. IMAP also does not define
<code class="literal">KEYWORD</code>, a similar functionality
is indicated by the <code class="literal">PERMANENTFLAGS</code> untagged reply.</p>
<p>In the future, there's a small chance that a new IMAP
protocol extension or revision may not be compatible with the
<code class="literal">LANG</code> or <code class="literal">KEYWORDS</code> capability keywords, or any other
SMAP capability keyword. Should this occur, the next revision
of this document will remove <code class="literal">LANG</code> or <code class="literal">KEYWORD</code>
(or another incompatible keyword) from the initial capability
list. The client should issue the "<code class="literal">\SMAP1 CAPABILITY</code>" command to retrieve an
SMAP1-specific capability list that includes the complete
SMAP capability keyword list.</p>
<p>Should IMAP introduce an interoperability issue with the
<code class="literal">SMAP1</code> keyword itself, it will be
replaced by another keyword.</p>
</div>
<p>Example:</p>
<div class="literallayout">
<p><br clear="none"/>
S: * OK [CAPABILITY SMAP1 KEYWORDSAUTH=CRAM-MD5 STARTTLS<br clear="none"/>
        LANG=EN LANG=EN-US IMAP4rev1] SMAP/IMAP hybrid server ready<br clear="none"/>
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id690983" shape="rect" name="id690983"> </a>IMAP/SMAP protocol selection</h4>
</div>
</div>
</div>
<p>The first word of IMAP commands is an arbitrary command
identification tag. The first set of SMAP commands, that set
up and log in to the mail account, are prefixed by the word
<code class="literal">"\SMAP1"</code>. The backslash
character is not allowed in IMAP command identification tags.
A server that implements both IMAP and SMAP reads the first
whitespace-delimited word of the first command it receives.
If the first word in <code class="literal">"\SMAP1"</code>
the server knows that the client is using SMAP. Subsequent
server replies will now be SMAP replies. Otherwise, the first
word must be an IMAP command identification tag, so the
server reverts to IMAP mode for this client connection.</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id691010" shape="rect" name="id691010"> </a>SMAP capability list</h4>
</div>
</div>
</div>
<p>The server responds to this command with a "<code class="literal">* CAPABILITY</code>" <a class="link" href="smapsyntax.html#singleline" title="Single line replies" shape="rect">single line</a> reply. The remaining words in
the reply enumerate SMAP capabilities supported by the
server. Example:</p>
<div class="literallayout">
<p><br clear="none"/>
C: \SMAP1 CAPABILITY<br clear="none"/>
S: * CAPABILITY SMAP1 AUTH=CRAM-MD5 STARTTLS LANG=EN LANG=EN-US IMAP4rev1<br clear="none"/>
S: +OK SMAP1 capability list complete.<br clear="none"/>
</p>
</div>
<p>The server should reply with the same capability list as
the initial <code class="literal">* OK</code> message.</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id691056" shape="rect" name="id691056"> </a>Enabling encryption</h4>
</div>
</div>
</div>
<p>The <code class="literal">STARTTLS</code> capability
indicates that the server is capable of encrypting the
connection between the client and the server. See <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2595.txt" target="_top" shape="rect">RFC 2595</a> for some additional
comments on using TLS with mail-related protocols.</p>
<p>SSL/TLS negotiation begins immediately after the client
receives a successfull <a class="link" href="smapsyntax.html#statusreply" title="Status replies" shape="rect">status reply</a> from the server. Example:</p>
<div class="literallayout">
<p><br clear="none"/>
C: \SMAP1 STARTTLS<br clear="none"/>
S: +OK Ready to accept an encrypted SMAP1 connection<br clear="none"/>
<br clear="none"/>
<span class="emphasis"><em>[ TLS negotiation occurs ]</em></span><br clear="none"/>
<br clear="none"/></p>
</div>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id691107" shape="rect" name="id691107"> </a>Language selection</h4>
</div>
</div>
</div>
<p>This command instructs the server to send all subsequent
messages in a different natural language. Example:</p>
<div class="literallayout">
<p><br clear="none"/>
C: \SMAP1 LANGUAGE FR<br clear="none"/>
S: +OK Bonjour<br clear="none"/></p>
</div>
<p>The specified language must be one of the languages
enumerated in the capability list.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The UTF-8 character set is used for all languages.</p>
</div>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id691140" shape="rect" name="id691140"> </a>Userid/password login</h4>
</div>
</div>
</div>
<p>The <code class="literal">\SMAP1 LOGIN</code> command
initiates a simple userid/password login sequence. The third
word of this command is the login userid, the fourth word is
the login password. The server's <a class="link" href="smapsyntax.html#statusreply" title="Status replies" shape="rect">status reply</a> indicates whether the supplied
credentials were accepted. Example:</p>
<div class="literallayout">
<p><br clear="none"/>
C: \SMAP1 LOGIN joneil p3r472<br clear="none"/>
S: -ERR Login invalid<br clear="none"/>
C: \SMAP1 LOGIN joneil p2r798<br clear="none"/>
S: +OK Logged in<br clear="none"/></p>
</div>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id691177" shape="rect" name="id691177"> </a>SASL login</h4>
</div>
</div>
</div>
<p>The "<code class="literal">\SMAP1 AUTHENTICATE</code>"
command initiates a generic SASL-based login mechanism. The
third word of this command specifies the SASL authentication
mechanism, which must be one of the <code class="literal">AUTH</code> mechanism listed in the server's
capability list. The subsequent SASL conversation, if any, is
identical to an IMAP SASL conversation: each server challenge
is sent as a line of text that starts with the <code class="literal">></code> character, whitespace filler, then the
base64-encoded server challenge. The client replies with a
line of text containing the base64-encoded reply.
Example:</p>
<div class="literallayout">
<p><br clear="none"/>
C: \SMAP1 AUTHENTICATE LOGIN<br clear="none"/>
S: > VXNlciBOYW1lAA==<br clear="none"/>
C: bWl0bGlz<br clear="none"/>
S: > UGFzc3dvcmQA<br clear="none"/>
C: Zmxvc2pidw==<br clear="none"/>
S: +OK Logged in<br clear="none"/></p>
</div>
</div>
</div>
<div class="navfooter">
<hr/>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="smapsyntax.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="smap1.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="smapfolders.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">SMAP syntax overview </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="h" href="index.html" shape="rect">Home</a> | <a accesskey="t" href="bk01-toc.html" shape="rect">ToC</a></td>
<td width="40%" align="right" valign="top" rowspan="1" colspan="1"> Folders</td>
</tr>
</table>
</div>
</body>
</html>
