Snapshot release 20030304-1130
Charles Cazabon <[email protected]> Tue, 4 Mar 2003 11:34:01 -0600
| Newsgroups | gmane.mail.bikini.devel |
|---|---|
| Message-ID | <[email protected]> |
Snapshot 20030304-1130 released and uploaded. From the CHANGELOG:
2003-03-04
Bring spec document up to date with latest discussions on mailing list.
Update formal grammar to match protocol.
Update example output to match spec changes.
Add capability tokens to spec document.
Add additional references.
Add example of login with unsupported method.
Change description of "U" response from "unimplemented" to "unsupported".
Editor removed trailing whitespace; sorry about the noisy diff. I'll try
to keep whitespace changes separate in future.
Diff follows.
diff -urN --exclude=bikini.html --exclude=bikini.txt bikini-20030303-1610/CHANGELOG bikini-20030304-1130/CHANGELOG
--- bikini-20030303-1610/CHANGELOG Wed Dec 31 18:00:00 1969
+++ bikini-20030304-1130/CHANGELOG Tue Mar 4 11:30:54 2003
@@ -0,0 +1,13 @@
+2003-03-04
+
+ Bring spec document up to date with latest discussions on mailing list.
+ Update formal grammar to match protocol.
+ Update example output to match spec changes.
+ Add capability tokens to spec document.
+ Add additional references.
+ Add example of login with unsupported method.
+ Change description of "U" response from "unimplemented" to "unsupported".
+ Editor removed trailing whitespace; sorry about the noisy diff. I'll try
+ to keep whitespace changes separate in future.
+
+end
diff -urN --exclude=bikini.html --exclude=bikini.txt bikini-20030303-1610/bikini/constants.py bikini-20030304-1130/bikini/constants.py
--- bikini-20030303-1610/bikini/constants.py Mon Mar 3 16:10:07 2003
+++ bikini-20030304-1130/bikini/constants.py Tue Mar 4 11:30:54 2003
@@ -22,7 +22,7 @@
'permanent' : 'E',
'temporary' : 'A',
'continuation' : '+',
- 'unimplemented' : 'U',
+ 'unsupported' : 'U',
}
MODIFIERS = {
@@ -30,10 +30,9 @@
}
CAPABILITIES = (
- 'AUTH-ANONYMOUS', # 'auth anonymous' support
- 'AUTH-PLAIN', # 'auth plain' support
- 'AUTH-LOGIN', # 'auth login' support
- 'SEND', # 'send' implemented as a stub
+ 'AUTH=ANONYMOUS', # 'auth anonymous' support
+ 'AUTH=PLAIN', # 'auth plain' support
+ 'AUTH=LOGIN', # 'auth login' support
'MESSAGE-SIZE %d' % os.environ.get ('DATABYTES', 0), # max message size for put
)
diff -urN --exclude=bikini.html --exclude=bikini.txt bikini-20030303-1610/bikini/server.py bikini-20030304-1130/bikini/server.py
--- bikini-20030303-1610/bikini/server.py Mon Mar 3 16:10:07 2003
+++ bikini-20030304-1130/bikini/server.py Tue Mar 4 11:30:54 2003
@@ -640,7 +640,7 @@
self.respond ('temporary', 'command failed temporarily (%s)' % err)
except UnimplementedError, err:
- self.respond ('unimplemented', 'command not implemented (%s)' % err)
+ self.respond ('unsupported', 'command not implemented (%s)' % err)
#######################################
diff -urN --exclude=bikini.html --exclude=bikini.txt bikini-20030303-1610/bikini/serverauth.py bikini-20030304-1130/bikini/serverauth.py
--- bikini-20030303-1610/bikini/serverauth.py Mon Mar 3 16:10:07 2003
+++ bikini-20030304-1130/bikini/serverauth.py Tue Mar 4 11:30:54 2003
@@ -125,7 +125,7 @@
self.respond ('temporary', 'command failed temporarily (%s)' % err)
except UnimplementedError, err:
- self.respond ('unimplemented', 'command not implemented (%s)' % err)
+ self.respond ('unsupported', 'command not implemented (%s)' % err)
self.respond ('success', str (args))
log (DEBUG, 'auth uid %i gid %i name "%s" homedir %s\n' % (auth.uid, auth.gid, auth.fullname, auth.dir))
diff -urN --exclude=bikini.html --exclude=bikini.txt bikini-20030303-1610/bikini.texi bikini-20030304-1130/bikini.texi
--- bikini-20030303-1610/bikini.texi Mon Mar 3 16:10:07 2003
+++ bikini-20030304-1130/bikini.texi Tue Mar 4 11:30:54 2003
@@ -127,19 +127,19 @@
@c character set; refer to these documents for more detail.
@cindex mail store
-A mail store is the top-level container accessed by a BikINI session. It MAY
-contain directories, and it MUST contain at least one mail folder (the
-@samp{inbox}). The root of the mail store has the path @samp{} (i.e., the empty
+A mail store is the top-level container accessed by a BikINI session. It MAY
+contain directories, and it MUST contain at least one mail folder (the
+@samp{inbox}). The root of the mail store has the path @samp{} (i.e., the empty
path).
@cindex directory
-A directory is a container that contains zero or more directories, or zero or
-more mail folders, or both. Directories are identified by path relative to the
-root of the mailstore (i.e. @samp{directory} or @samp{dir1/dir2}). Clients MUST
-NOT include a trailing slash when identifying a directory to a server. Servers
-MUST include a trailing slash on directory paths in the response to the
-@samp{LISTDIRS} command to differentiate them from mail folders. The directory
-structure of a mail store MAY correspond to a filesystem structure on the
+A directory is a container that contains zero or more directories, or zero or
+more mail folders, or both. Directories are identified by path relative to the
+root of the mailstore (i.e. @samp{directory} or @samp{dir1/dir2}). Clients MUST
+NOT include a trailing slash when identifying a directory to a server. Servers
+MUST include a trailing slash on directory paths in the response to the
+@samp{LISTDIRS} command to differentiate them from mail folders. The directory
+structure of a mail store MAY correspond to a filesystem structure on the
server, but this is not necessarily the case.
@cindex folder
@@ -176,18 +176,18 @@
makes implementation significantly easier and reduces the resource-intensiveness
of the server.
-Case-insensitivity is required in legacy protocols, but adds code for little
-reason otherwise. BikINI is a new protocol and therefore doesn't require it.
-@emph{Commands and responses in BikINI are therefore case-sensitive.} Clients
-MUST send commands in upper case; upper and lower case characters may appear in
-identifiers, paths, flags, and the server MAY include upper and lower case
-characters in message identifiers, response modifiers, and descriptive text
+Case-insensitivity is required in legacy protocols, but adds code for little
+reason otherwise. BikINI is a new protocol and therefore doesn't require it.
+@emph{Commands and responses in BikINI are therefore case-sensitive.} Clients
+MUST send commands in upper case; upper and lower case characters may appear in
+identifiers, paths, flags, and the server MAY include upper and lower case
+characters in message identifiers, response modifiers, and descriptive text
responses.
-Similarly, legacy protocols allow for arbitrary runs of whitespace around
-commands and arguments. This adds code to clients and servers for little
-purpose and is therefore not required in a new protocol like BikINI. Clients and
-servers MUST NOT add padding of any type (including extra whitespace) to
+Similarly, legacy protocols allow for arbitrary runs of whitespace around
+commands and arguments. This adds code to clients and servers for little
+purpose and is therefore not required in a new protocol like BikINI. Clients and
+servers MUST NOT add padding of any type (including extra whitespace) to
commands, arguments, or responses other than that explicitly stated in
this protocol specification.
@@ -239,8 +239,8 @@
provide preliminary approval before completing the operation (i.e. message
submission with the @samp{PUT} command).
-In this case, the server sends a @samp{K} reply indicating the client may
-proceed to send its message data, or a @samp{A}, @samp{E}, @samp{U}, or @samp{X}
+In this case, the server sends a @samp{K} reply indicating the client may
+proceed to send its message data, or a @samp{A}, @samp{E}, @samp{U}, or @samp{X}
reply indicating the command cannot be processed.
@c ----------------------------------------------------------------------------
@@ -252,23 +252,23 @@
@item single-line response
-A single-character status code (@samp{A}, @samp{E}, @samp{K}, @samp{U}, or
-@samp{X}), optionally followed by one or more single-character response
-modifiers, followed by a single space and optional text, and terminated with CR
-LF. @xref{Server Response Codes}. The space between the code and text is
-required even if text is not present. The text format is dependent on the
+A single-character status code (@samp{A}, @samp{E}, @samp{K}, @samp{U}, or
+@samp{X}), optionally followed by one or more single-character response
+modifiers, followed by a single space and optional text, and terminated with CR
+LF. @xref{Server Response Codes}. The space between the code and text is
+required even if text is not present. The text format is dependent on the
command this is in response to.
All non-success responses are single-line responses.
@item multi-line response
-A multi-line response has by zero or more @samp{+} lines, each terminated with
-CR LF, followed by a @samp{K} single-line response to indicate completion of the
+A multi-line response has by zero or more @samp{+} lines, each terminated with
+CR LF, followed by a @samp{K} single-line response to indicate completion of the
multi-line response.
-All multi-line responses are positive responses. Note that a multi-line
-response may have a total of only one line if there are precisely zero @samp{+}
+All multi-line responses are positive responses. Note that a multi-line
+response may have a total of only one line if there are precisely zero @samp{+}
lines.
Servers MUST NOT add response modifiers to the continuation @samp{+} lines of
@@ -284,8 +284,8 @@
the length of the 8-bit message content which follows immediately after the
CR LF which terminates the initial response line.
-In this case, the text of the response is the decimal representation of the size
-of the message content to be transferred, in bytes. The server MUST NOT include
+In this case, the text of the response is the decimal representation of the size
+of the message content to be transferred, in bytes. The server MUST NOT include
additional padding, leading zeroes, or other information is in this text.
This is followed by exactly SIZE bytes of 8-bit data representing the message
@@ -301,29 +301,29 @@
The server MUST NOT send any data to the client except in response to a
command.
-The client MUST NOT derive any information from the text portion of a @samp{A},
-@samp{E}, @samp{K}, @samp{U}, or @samp{X} single-line response, other than an
+The client MUST NOT derive any information from the text portion of a @samp{A},
+@samp{E}, @samp{K}, @samp{U}, or @samp{X} single-line response, other than an
optional informational message to display to the user.
@c ----------------------------------------------------------------------------
@node Server Response Codes
@subsection Server Response Codes
-Response codes are a single character, followed immediately by zero or more
+Response codes are a single character, followed immediately by zero or more
response modifiers, followed by a single space and zero or more characters of
additional information.
-The server must not send a space between the response code and optional response
+The server must not send a space between the response code and optional response
modifiers.
-The additional information is optional for some response codes (defined below).
-If the additional information is required (non-optional), it has a strict format
+The additional information is optional for some response codes (defined below).
+If the additional information is required (non-optional), it has a strict format
defined by the command in question.
When the additional information section is optional, it is free-form and
continues until the end of the line.
-The server MUST send a space between the response code and the @samp{CR LF}
-which terminates the response line if the additional information section is not
+The server MUST send a space between the response code and the @samp{CR LF}
+which terminates the response line if the additional information section is not
supplied.
@table @samp
@@ -342,36 +342,35 @@
@item A
-Temporary failure. The command was syntactically correct, but failed due to a
-transient error. The command might succeed if it is re-tried under similar
-conditions. This could be due to a server software error, administrative
+Temporary failure. The command was syntactically correct, but failed due to a
+transient error. The command might succeed if it is re-tried under similar
+conditions. This could be due to a server software error, administrative
prohibition or policy. The additional information section is optional, free-
-form, and continues to the end of the line. Servers SHOULD use this to describe
+form, and continues to the end of the line. Servers SHOULD use this to describe
the failure reason in more detail.
@item E
-Permanent failure. The command was syntactically correct, but failed
-permanently. The command will not succeed if it is re-tried under the same
-conditions. This could be due to a server software error, administrative
-prohibition or policy (i.e. read-only mail archive fails all @samp{PUT},
-@samp{SETFLAG}, etc commands), etc. The additional information section is
-optional, free-form, and continues to the end of the line. Servers SHOULD use
+Permanent failure. The command was syntactically correct, but failed
+permanently. The command will not succeed if it is re-tried under the same
+conditions. This could be due to a server software error, administrative
+prohibition or policy (i.e. read-only mail archive fails all @samp{PUT},
+@samp{SETFLAG}, etc commands), etc. The additional information section is
+optional, free-form, and continues to the end of the line. Servers SHOULD use
this to describe the failure reason in more detail.
@item U
-Not implemented. The command was recognized, but is not implemented by the
-server. The additional information section is optional, free-form, and continues
-to the end of the line. Servers MAY use this to describe the condition in more
-detail.
+Not supported. The command was recognized, but is not supported by the server.
+The additional information section is optional, free-form, and continues to the
+end of the line. Servers MAY use this to describe the condition in more detail.
@item +
-Successful completion of a command with a multiline response. The additional
-information section of each such response line is required, strictly formatted,
-and continues to the end of the line. The specific format depends on the
-command. Following the @samp{+} response lines is one @samp{K} line to indicate
+Successful completion of a command with a multiline response. The additional
+information section of each such response line is required, strictly formatted,
+and continues to the end of the line. The specific format depends on the
+command. Following the @samp{+} response lines is one @samp{K} line to indicate
the completion of the multiline response.
@end table
@@ -380,13 +379,13 @@
@node Server Response Modifiers
@subsection Server Response Modifiers
-Server reponses MAY include a non-repeating sequence of one or more single-character
-response modifiers immediately following the response code (i.e. not preceded by
+Server reponses MAY include a non-repeating sequence of one or more single-character
+response modifiers immediately following the response code (i.e. not preceded by
a space).
-Servers MUST NOT send a response modifier which is not defined in this
-specification. Servers MUST NOT send the same response modifier more than once
-in a given response. Servers MAY send multiple response modifiers in any order.
+Servers MUST NOT send a response modifier which is not defined in this
+specification. Servers MUST NOT send the same response modifier more than once
+in a given response. Servers MAY send multiple response modifiers in any order.
Clients MUST NOT expect response modifiers to be in any particular order.
The following response modifiers are defined:
@@ -395,17 +394,17 @@
@item C
-The server is closing the connection after this response. The server will close
-the session immediately after sending the @samp{CR LF} which terminates this
+The server is closing the connection after this response. The server will close
+the session immediately after sending the @samp{CR LF} which terminates this
response, exactly as if the client had sent a @samp{QUIT} command.
Servers MAY do this to manage load or for other reasons.
-Clients MUST NOT treat this as an error condition. If a client wishes to
-perform additional operations on this mail store after receiving a response
-including the @samp{C} response modifier, they must establish a new connection,
-authorize with the @samp{AUTH} command, and then proceed with their operation.
-Clients SHOULD NOT require user approval (i.e. clicking OK to a warning dialog)
+Clients MUST NOT treat this as an error condition. If a client wishes to
+perform additional operations on this mail store after receiving a response
+including the @samp{C} response modifier, they must establish a new connection,
+authorize with the @samp{AUTH} command, and then proceed with their operation.
+Clients SHOULD NOT require user approval (i.e. clicking OK to a warning dialog)
prior to doing this.
@end table
@@ -417,10 +416,10 @@
There are differences between a mail store, a directory, and a mail folder in
BikINI.
-Mail folders can only contain messages, not directories or other mail folders.
-The root of a BikINI mail store is a directory with the path @samp{} (i.e. the
-empty path). Every BikINI mail store contains a mail folder with path
-@samp{inbox} which is the default location of incoming new mail which doesn't
+Mail folders can only contain messages, not directories or other mail folders.
+The root of a BikINI mail store is a directory with the path @samp{} (i.e. the
+empty path). Every BikINI mail store contains a mail folder with path
+@samp{inbox} which is the default location of incoming new mail which doesn't
get filed into another, more specific mail folder by server-side sorting rules.
Directories can contain mail folders and other directories. Otherwise,
@@ -525,17 +524,17 @@
MUST be the internal timestamp of the source message.
The format used is that of the W3C's Date and Time Formats
-@samp{YYYY-MM-DDThh:mm:ssTZD} without punctuation, with a timezone offset
+@samp{YYYY-MM-DDThh:mm:ssTZD} without punctuation, with a timezone offset
indicator of @samp{Z} to indicate UTC (-0000).
@strong{Examples:}
@example
- 19970716T192030Z
- 20030301T120000Z
+ 19970716T192030Z
+ 20030301T120000Z
@end example
-Servers MUST NOT use any other timezone offset when presenting the timestamp
+Servers MUST NOT use any other timezone offset when presenting the timestamp
messages attribute to a client.
@c ----------------------------------------------------------------------------
@@ -548,8 +547,8 @@
leading zeroes.
If the sender (client or server) of a @samp{size} attribute stores an RFC-822-
-or RFC-2822-format message using an end-of-line convention other than Unix-style
-LF- only, the sender must convert the message to LF-only before calculating the
+or RFC-2822-format message using an end-of-line convention other than Unix-style
+LF- only, the sender must convert the message to LF-only before calculating the
message's size.
@xref{message blob}.
@@ -666,15 +665,78 @@
when transmitting the message, a message containing a bare @samp{LF}
character will be corrupted.
-BikINI avoids this conversion by specifying that message content is sent as a
-length-prefixed 8-bit message. A BikINI message might not end with a newline.
-If a message is "lines of text", such as an [RFC-822]/[RFC-2822] message, it is
-transmitted using @samp{LF}-only line endings. If a BikINI protocol receiver
-wishes to store a message locally using @samp{CR LF} line endings, it must
-perform the conversion after receiving the message, and must convert the message
-back to @samp{LF}-only line endings before calculating the message's size and
+BikINI avoids this conversion by specifying that message content is sent as a
+length-prefixed 8-bit message. A BikINI message might not end with a newline.
+If a message is "lines of text", such as an [RFC-822]/[RFC-2822] message, it is
+transmitted using @samp{LF}-only line endings. If a BikINI protocol receiver
+wishes to store a message locally using @samp{CR LF} line endings, it must
+perform the conversion after receiving the message, and must convert the message
+back to @samp{LF}-only line endings before calculating the message's size and
retransmitting the message over BikINI.
+@c ============================================================================
+@node capabilities
+@section Capability Tokens
+
+BikINI is designed to be an extensible protocol; clients should continue to work
+even if servers are upgraded to support new protocol features and vice versa.
+To accomplish this, clients need a way to determine what capabilities are
+supported by a given server.
+
+The @samp{CAPS} command provides this information. The server's response is
+a multiline response, with one line per capability. The format of each line
+is a single capability token, optionally followed by additional information
+in a format specific to that token.
+
+Servers MUST NOT send any capability tokens not defined in this specification.
+Clients MUST ignore tokens they do not understand.
+
+Currently defined tokens are:
+
+@itemize @bullet
+
+@item AUTH=PLAIN
+The server accepts @samp{PLAIN} as an @samp{AUTH} method.
+This capability contains no additional information.
+See [AUTH-PLAIN].
+
+@item AUTH=LOGIN
+The server accepts @samp{LOGIN} as an @samp{AUTH} method.
+This capability contains no additional information.
+
+@item AUTH=CRAM-MD5
+The server accepts @samp{CRAM-MD5} as an @samp{AUTH} method.
+This capability contains no additional information.
+See [AUTH-CRAM-MD5].
+
+@item AUTH=DIGEST-MD5
+The server accepts @samp{DIGEST-MD5} as an @samp{AUTH} method.
+This capability contains no additional information.
+See [AUTH-DIGEST-MD5].
+
+@item AUTH=GSSAPI
+The server accepts @samp{GSSAPI} as an @samp{AUTH} method.
+This capability contains no additional information.
+See [AUTH-GSSAPI].
+
+@item AUTH=KERBEROS_V4
+The server accepts @samp{KERBEROS_V4} as an @samp{AUTH} method.
+This capability contains no additional information.
+See [SASL].
+
+@item AUTH=ANONYMOUS
+The server accepts @samp{ANONYMOUS} as an @samp{AUTH} method.
+This capability's additional information is an optional list of mail folder
+paths available for anonymous reading separated by single spaces.
+See [AUTH-ANONYMOUS].
+
+@item MESSAGE-SIZE
+Servers MAY advertise their maximum incoming message size using this capability.
+This capability's additional information is the maximum allowed size of incoming
+messages (octets) in decimal format, without leading zeroes or other padding.
+
+@end itemize
+
@c ****************************************************************************
@chapter Operational Considerations
@@ -730,7 +792,7 @@
@item The parameter @emph{auth-method} is required. Other parameters vary
depending on the method.
@item If a server does not support a particular auth-method for any reason, it MUST return
-an "unimplemented" @samp{U} response. This includes the case where an authentication
+an "unsupported" @samp{U} response. This includes the case where an authentication
method is implemented but forbidden by policy (such as not allowing insecure
auth methods in an unencrypted session).
@item Upon initial connection, a client will immediately send the @samp{AUTH}
@@ -739,9 +801,9 @@
list of supported auth methods with the @samp{caps} command. Clients MAY choose
to remember what auth methods are supported by a particular host so as to avoid
choosing an unsupported auth-method in their next session.
-@item Servers MUST NOT close the session immediately after a successful response
-to the @samp{AUTH} command. If the login would normally be successful but the
-server wishes to close the session, it must use the "temporary error" @samp{A}
+@item Servers MUST NOT close the session immediately after a successful response
+to the @samp{AUTH} command. If the login would normally be successful but the
+server wishes to close the session, it must use the "temporary error" @samp{A}
response code.
@end itemize
@@ -770,7 +832,7 @@
@end example
@example
-C: AUTH cram-md5 dXNlckBob3N0LmRvbWFpbgBteSBwYXNzd29yZAA=
+C: AUTH CRAM-MD5 dXNlckBob3N0LmRvbWFpbgBteSBwYXNzd29yZAA=
S: U cram-md5 auth-method not available
@end example
@@ -794,7 +856,7 @@
@strong{Possible Responses:}
@itemize @bullet
-@item Positive multi-line. The text portion of the continuation lines is
+@item Positive multi-line. The text portion of the continuation lines is
required and strictly formatted.
@item Negative single-line. The text portion of the response is optional,
free form, and continues until the end of the line.
@@ -802,17 +864,20 @@
@strong{Notes:}
@itemize @bullet
-@item The format of the text in each multi-line response line is
+@item The format of the text in each multi-line response line is
@samp{@emph{capability-token}[SP @emph{capability-info} ...]}}.
@end itemize
+For currently defined capability tokens, @xref{capabilities}.
+
@strong{Examples:}
@example
C: CAPS
-S: AUTH-ANONYMOUS
- AUTH-PLAIN
- AUTH-LOGIN
+S: AUTH=ANONYMOUS
+ AUTH=PLAIN
+ AUTH=LOGIN
+ AUTH=KERBEROS_V4
SEND
K ok
@end example
@@ -847,7 +912,7 @@
@strong{Possible Responses:}
@itemize @bullet
-@item None. The server will close the connection immediately. The client SHOULD
+@item None. The server will close the connection immediately. The client SHOULD
close the connection as soon as it has finished sending the @samp{QUIT} command.
@end itemize
@@ -855,9 +920,9 @@
@itemize @bullet
@item This command cannot fail. The server MUST close the connection when the
@samp{QUIT} command is received.
-@item The @samp{QUIT} command is only valid in the index state. If a client
-wishes to close a connection while in the opening state (i.e. before
-successfully logging in), it just closes the connection without sending a
+@item The @samp{QUIT} command is only valid in the index state. If a client
+wishes to close a connection while in the opening state (i.e. before
+successfully logging in), it just closes the connection without sending a
command.
@end itemize
@@ -878,9 +943,9 @@
@strong{Possible Responses:}
@itemize @bullet
-@item Positive multi-line. The text portion of the intermediate lines of a
-positive multiline response is the path to a directory or mail folder relative
-to the mail store root. Directories end with a slash. Mail folders do not end
+@item Positive multi-line. The text portion of the intermediate lines of a
+positive multiline response is the path to a directory or mail folder relative
+to the mail store root. Directories end with a slash. Mail folders do not end
with a slash.
@item Negative single-line. The text portion of the response is optional,
free form, and continues until the end of the line.
@@ -888,7 +953,7 @@
@strong{Notes:}
@itemize @bullet
-@item As every BikINI mail store (as presented to the client) must contain the
+@item As every BikINI mail store (as presented to the client) must contain the
@samp{inbox} mail folder, a positive response to the @samp{LISTDIRS} command
will never have zero continuation @samp{+} lines. Servers MUST include
the @samp{inbox} mail folder in @samp{LISTDIRS} output.
@@ -896,16 +961,16 @@
continuation @samp{+} lines in any order they choose. Clients MUST be prepared
for listings where a folder or directory is listed before the parent directory
containing it.
-@item The order of items in the listings is not guaranteed to be stable.
-Servers MAY change the order of items on each @samp{LISTDIRS} command. Clients MUST
-NOT assume the order of listings will be the same between two @samp{LISTDIRS}
+@item The order of items in the listings is not guaranteed to be stable.
+Servers MAY change the order of items on each @samp{LISTDIRS} command. Clients MUST
+NOT assume the order of listings will be the same between two @samp{LISTDIRS}
commands.
-@item Servers MAY support multiple clients accessing the same mail store
-simultaneously. Folders and directories can therefore be created, deleted,
-moved, or renamed in situations other than in response to commands by the
-client. Clients MUST NOT assume that the directory and folder structure is
-stable. Clients MUST be prepared for a folder or directory to be renamed,
-moved, or deleted in between their last @samp{LISTDIRS} command and a subsequent
+@item Servers MAY support multiple clients accessing the same mail store
+simultaneously. Folders and directories can therefore be created, deleted,
+moved, or renamed in situations other than in response to commands by the
+client. Clients MUST NOT assume that the directory and folder structure is
+stable. Clients MUST be prepared for a folder or directory to be renamed,
+moved, or deleted in between their last @samp{LISTDIRS} command and a subsequent
attempt to access that folder or directory.
@end itemize
@@ -1141,7 +1206,7 @@
@strong{Possible Responses:}
@itemize @bullet
-@item Positive multi-line. The text portion of the continuation lines is
+@item Positive multi-line. The text portion of the continuation lines is
required and strictly formatted.
@item Negative single-line. The text portion of the response is optional,
free form, and continues until the end of the line.
@@ -1149,14 +1214,14 @@
@strong{Notes:}
@itemize @bullet
-@item The format of the text in each multi-line response line is
+@item The format of the text in each multi-line response line is
@samp{@emph{message-identifier SP [flags] ":" content-size ":" message-timestamp}}.
@item Clients MUST be prepared for messages to be created, deleted, moved, or
to have their metadata changed by events other than a command from the client.
Clients MUST NOT assume a message's existence, timestamp, flags, size, or other
information will not change between the @samp{LISTMSGS} command and a subsequent
command.
-@item The successful response to the @samp{LISTMSGS} command on an empty mail
+@item The successful response to the @samp{LISTMSGS} command on an empty mail
folder will have zero continuation @samp{+} lines and one success @samp{K} line.
@end itemize
@@ -1310,7 +1375,7 @@
@strong{Possible Responses:}
@itemize @bullet
-@item Positive single-line. The text portion of the response is
+@item Positive single-line. The text portion of the response is
required and contains the message-identifier for the message's new location.
@item Negative single-line. The text portion of the response is optional,
free form, and continues until the end of the line.
@@ -1324,7 +1389,7 @@
@strong{Examples:}
@example
-C: MVMSG inbox/1045853047.5854.twoflower.internal.do projects/alpha
+C: MVMSG inbox/1045853047.5854.twoflower projects/alpha
S: K 1045853047.5854.localhost
@end example
@@ -1442,10 +1507,10 @@
followed by additional envelope recipient addresses, each followed by an
ASCII NUL.
@item All addresses in the envelope data MUST be in fully-qualified form.
-@item The server MAY use any method it chooses to deliver the message to the
-recipients. This may be by handing the message to the local Mail Transfer Agent
-(MTA) for delivery via SMTP @emph{or another protocol}, by delivering directly into
-another BikINI mail store on the server, other methods, or a combination of
+@item The server MAY use any method it chooses to deliver the message to the
+recipients. This may be by handing the message to the local Mail Transfer Agent
+(MTA) for delivery via SMTP @emph{or another protocol}, by delivering directly into
+another BikINI mail store on the server, other methods, or a combination of
these methods.
@item Some delivery methods may impose stricter requirements on the format of
a message than BikINI does. For example, messages with partial final lines
@@ -1473,13 +1538,13 @@
@example
-@c ALPHA = %x41-5A / %x61-7A
-@c ; Latin Capital Letter A-Latin Capital Letter Z /
-@c ; Latin Small Letter a-Latin Small Letter z
-
-@c CHAR = %x01-7F
-@c ; Any C0 Controls and Basic Latin, excluding NULL from
-@c ; Code Charts, pages 7-6 through 7-9 in [UNICODE]
+@c ALPHA = %x41-5A / %x61-7A
+@c ; Latin Capital Letter A-Latin Capital Letter Z /
+@c ; Latin Small Letter a-Latin Small Letter z
+
+@c CHAR = %x01-7F
+@c ; Any C0 Controls and Basic Latin, excluding NULL from
+@c ; Code Charts, pages 7-6 through 7-9 in [UNICODE]
CR = %x0D
; Carriage Return
@@ -1491,7 +1556,7 @@
; Internet standard newline
@c CTL = %x00-1F / %x7F
-@c ; Controls. Not used, but referenced in comments.
+@c ; Controls. Not used, but referenced in comments.
DIGIT = %x30-39
; Digit Zero-Digit Nine
@@ -1499,44 +1564,41 @@
DQUOTE = %x22
; Quotation Mark
-@c HTAB = %x09
-@c ; Horizontal Tabulation
+@c HTAB = %x09
+@c ; Horizontal Tabulation
SP = %x20
; space
@c VCHAR = %x21-7E
-@c ; Visible (printing) characters
+@c ; Visible (printing) characters
@c WSP = SP / HTAB
-@c ; White Space
+@c ; White Space
@end example
@example
-path-root = "."
- ; indicates the root of the mail store
+NONZERODIGIT = %x31-39
+ ; Digit One-Digit Nine
path-separator = "/"
; may not occur in path components
path-component-char = %x21-2E / %x30-7E
; all visible (printing) US-ASCII characters except <path-separator>
- ; ??? should this allow high characters (i.e. %x7f-ff) ?
- ; If so, which of the high characters are generally considered
- ; "printing" characters?
path-component = 1*<path-component-char>
; path component
-directory-path = <path-root> 1*(<path-separator> <path-component>)
+directory-path = <path-component> *(<path-separator> <path-component>)
;
mail-folder = path-component
; name of a mail folder
-folder-path = <path-root> 0*(<path-separator> <path-component>) <path-separator> <mail-folder>
+folder-path = *(<path-component> <path-separator>) <mail-folder>
; complete path from mail store root to mail folder name
user-identifier = ???
@@ -1562,25 +1624,38 @@
; current flags are uppercase only ; because of case-sensitivity,
; new flags can be added later using "r", etc.
-flags = (["D"] ["F"] ["N"] ["R"] ["S"] ["T"])
- ; flags are always in US-ASCII order and cannot be repeated
+flags = *flag
+ ; flags are in any order but cannot be repeated
-content-size = %x31-39 0*(%x30-39)
+content-size = NONZERODIGIT *DIGIT
; Positive nonzero decimal number with no leading zeroes.
-weekday = "Sun" / "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat"
+year = 4DIGIT
+ ; valid values are 1970 - 9999. We'll need to revisit this before
+ ; Y10K.
+
+month = 2DIGIT
+ ; valid values are 01 - 12 ; leading zero is required for < 10
+
+day = 2DIGIT
+ ; valid values are 01 - 31 ; leading zero is required for < 10
-month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
+hour = 2DIGIT
+ ; valid values are 00 - 23 ; leading zero is required for < 10
-message-timestamp = <weekday> "," SP 2DIGIT SP <month> SP 4*5DIGIT SP 2DIGIT ":" 2DIGIT ":" 2DIGIT SP "-0000"
+minute = 2DIGIT
+ ; valid values are 00 - 59 ; leading zero is required for < 10
-message-listing = <message-identifier> SP 0*<flag> ":" <content-size> ":" <message-timestamp>
- ; in LISTMSGS output, the trailing "/" indicates a directory
- ; instead of a mail folder. If a flag is present, that means it is set.
+second = 2DIGIT
+ ; valid values are 00 - 59 ; leading zero is required for < 10
+
+message-timestamp = <year> <month> <day> "T" <hour> <minute> <second> "Z"
+ ; this is in UTC
+
+message-listing = <message-identifier> SP <flags> ":" <content-size> ":" <message-timestamp>
+ ; If a flag is present, that means it is set.
; Note flags are optional and may not be present if all flags are
; cleared.
- ; ??? This format might change if other metadata is required in LISTMSGS
- ; output.
@end example
@@ -1596,11 +1671,11 @@
C: AUTH PLAIN dXNlckBob3N0LmRvbWFpbgBteSBwYXNzd29yZAA=
S: K ok
C: LISTMSGS inbox
-S: + 1044547809.6813_14.twoflower S:13626
- + 1045443985.21669.discworld S:3602
- + 1044557867.9263_7.twoflower NRS:15820
- + 1044561911.10174_19.twoflower S:5476
- + 1044566229.11296_22.twoflower NS:6644
+S: + 1044547809.6813_14.twoflower S:13626:20010327T115332Z
+ + 1045443985.21669.discworld S:3602:19980812T165402Z
+ + 1044557867.9263_7.twoflower NRS:15820:20030227T193206Z
+ + 1044561911.10174_19.twoflower S:5476:20021108T081428Z
+ + 1044566229.11296_22.twoflower NS:6644:20030227T195712Z
K ok
C: GET inbox/1044557867.9263_7.twoflower
S: K 15820
@@ -1624,11 +1699,11 @@
K ok
C: LISTMSGS inbox
S: K ok
- + 1044547809.6813_14.twoflower S:13626
- + 1045443985.21669.discworld S:3602
- + 1044557867.9263_7.twoflower RS:15820
- + 1044561911.10174_19.twoflower S:5476
- + 1044566229.11296_22.twoflower S:6644
+ + 1044547809.6813_14.twoflower S:13626:20010327T115332Z
+ + 1045443985.21669.discworld S:3602:19980812T165402Z
+ + 1044557867.9263_7.twoflower RS:15820:20030227T193206Z
+ + 1044561911.10174_19.twoflower S:5476:20021108T081428Z
+ + 1044566229.11296_22.twoflower S:6644:20030227T195712Z
K ok
C: QUIT
S: K goodbye
@@ -1667,12 +1742,12 @@
finished
S: K 1045443985.Q49P3838.discworld
C: LISTMSGS foobar/pymsgauth
-S: + 1045443985.Q49P3838.discworld :3534
+S: + 1045443985.Q49P3838.discworld :3534:20030304T113829Z
K ok
C: SETFLAG F foobar/pymsgauth/1045443985.Q49P3838.discworld
S: K flag set
C: LISTMSGS foobar/pymsgauth
-S: + 1045443985.Q49P3838.discworld F:3534
+S: + 1045443985.Q49P3838.discworld F:3534:20030304T113829Z
K ok
C: QUIT
S: K goodbye
@@ -1688,12 +1763,48 @@
Note that the message's 'N' (new) flag is initially cleared when
stored with the @samp{PUT} command.
+@c ============================================================================
+@section Log in procedure, including a failed login due to unsupported method
+
+@example
+C: AUTH PLAIN dXNlckBob3N0LmRvbWFpbgBteSBwYXNzd29yZAA=
+S: U AUTH PLAIN unsupported
+C: CAPS
+S: + AUTH=CRAM-MD5
+ + AUTH=KERBEROS_V4
+ + MESSAGE-SIZE 2000000
+ K ok
+C: AUTH KERBEROS_V4
+[...]
+@end example
+
+The client connects and tries to log in using @samp{AUTH PLAIN}. The server
+forbids this in unencrypted sessions (no @samp{STARTTLS}), so it replies
+with @samp{U} "unsupported". The client issues the @samp{CAPS} command
+to retrieve a list of supported @samp{AUTH} methods and logs in using one
+of them.
+
+Note that the server's CAPS response might be different after the STARTTLS
+command, as it might then include @samp{AUTH=PLAIN}.
+
@c ****************************************************************************
@chapter Security Considerations
@c ****************************************************************************
@chapter References
+[AUTH-ANONYMOUS] Newman, C., "Anonymous SASL Mechanism", RFC 2245, Innosoft, November 1997.
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2245.txt}
+
+[AUTH-PLAIN] Newman, C., "Using TLS with IMAP, POP3 and ACAP", RFC 2595, Innosoft, June 1999.
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2595.txt}
+
+[AUTH-CRAM-MD5] Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP AUTHorize Extension for Simple Challenge/Response", RFC 2195, MCI, September 1997.
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2195.txt}
+
+[AUTH-DIGEST-MD5] Leach, P., and Newman, C., "Using Digest Authentication as a SASL Mechanism", RFC 2831, Microsoft and Innosoft, May 2000.
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2831.txt}
+
[CHARSET] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC 1700, USC/Information Sciences Institute, October 1994.
[IMAP4] Crispin, "Internet Message Access Protocol - Version 4rev1", RFC 2060, University of Washington, December 1996.
@@ -1718,6 +1829,9 @@
[RFC-2822] Resnick, P., "Internet Message Format", STD 11, RFC 2822, QUALCOMM Incorporated, April 2001.
@uref{ftp://ftp.rfc-editor.org/in-notes/RFC-2822.txt}
+
+[SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, Netscape Communications, October 1997.
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2222.txt}
[SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, USC/Information Sciences Institute, August 1982.
@uref{ftp://ftp.rfc-editor.org/in-notes/rfc821.txt}
--
-----------------------------------------------------------------------
Charles Cazabon <[email protected]>
BikINI project website: http://www.qcc.ca/~charlesc/software/bikini/
GPL'ed software available at: http://www.qcc.ca/~charlesc/software/
-----------------------------------------------------------------------