<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>