Connected: An Internet Encyclopedia
RFC 1725 - 7. Optional POP3 Commands

Top: Connected: An Internet Encyclopedia
Up: Requests For Comments
Up: RFC 1725
Prev: 6. The UPDATE State
Next: 8. POP3 Command Summary

### 7. Optional POP3 Commands

The POP3 commands discussed above must be supported by all minimal implementations of POP3 servers.

The optional POP3 commands described below permit a POP3 client greater freedom in message handling, while preserving a simple POP3 server implementation.

          NOTE: This memo STRONGLY encourages implementations to support
          these commands in lieu of developing augmented drop and scan
          listings.  In short, the philosophy of this memo is to put
          intelligence in the part of the POP3 client and not the POP3
          server.

          TOP msg n

             Arguments:
                 a message-number (required) which may NOT refer to to a
                 message marked as deleted, and a non-negative number
                 (required)

             Restrictions:
                 may only be given in the TRANSACTION state

             Discussion:
                 If the POP3 server issues a positive response, then the
                 response given is multi-line.  After the initial +OK, the
                 POP3 server sends the headers of the message, the blank
                 line separating the headers from the body, and then the
                 number of lines indicated message's body, being careful to
                 byte-stuff the termination character (as with all multi-
                 line responses).

                 Note that if the number of lines requested by the POP3
                 client is greater than than the number of lines in the
                 body, then the POP3 server sends the entire message.

             Possible Responses:
                 +OK top of message follows
                 -ERR no such message

             Examples:
                 C: TOP 1 10
                 S: +OK
                 S: <the POP3 server sends the headers of the
                    message, a blank line, and the first 10 lines
                    of the body of the message>
                 S: .
                    ...
                 C: TOP 100 3
                 S: -ERR no such message

          UIDL [msg]

          Arguments:
              a message-number (optionally)  If a message-number is given,
              it may NOT refer to a message marked as deleted.

          Restrictions:
              may only be given in the TRANSACTION state.

          Discussion:
              If an argument was given and the POP3 server issues a positive
              response with a line containing information for that message.
              This line is called a "unique-id listing" for that message.

              If no argument was given and the POP3 server issues a positive
              response, then the response given is multi-line.  After the
              initial +OK, for each message in the maildrop, the POP3 server
              responds with a line containing information for that message.
              This line is called a "unique-id listing" for that message.

              In order to simplify parsing, all POP3 servers are required to
              use a certain format for unique-id listings.  A unique-id
              listing consists of the message-number of the message,
              followed by a single space and the unique-id of the message.
              No information follows the unique-id in the unique-id listing.

              The unique-id of a message is an arbitrary server-determined
              string, consisting of characters in the range 0x21 to 0x7E,
              which uniquely identifies a message within a maildrop and
              which persists across sessions. The server should never reuse
              an unique-id in a given maildrop, for as long as the entity
              using the unique-id exists.

              Note that messages marked as deleted are not listed.

          Possible Responses:
              +OK unique-id listing follows
              -ERR no such message

          Examples:
              C: UIDL
              S: +OK
              S: 1 whqtswO00WBw418f9t5JxYwZ
              S: 2 QhdPYR:00WBw1Ph7x7
              S: .
                 ...
              C: UIDL 2
              S: +OK 2 QhdPYR:00WBw1Ph7x7
                 ...
              C: UIDL 3
              S: -ERR no such message, only 2 messages in maildrop

          APOP name digest

             Arguments:
                 a string identifying a mailbox and a MD5 digest string
                 (both required)

             Restrictions:
                 may only be given in the AUTHORIZATION state after the POP3
                 greeting

             Discussion:
                 Normally, each POP3 session starts with a USER/PASS
                 exchange.  This results in a server/user-id specific
                 password being sent in the clear on the network.  For
                 intermittent use of POP3, this may not introduce a sizable
                 risk.  However, many POP3 client implementations connect to
                 the POP3 server on a regular basis -- to check for new
                 mail.  Further the interval of session initiation may be on
                 the order of five minutes.  Hence, the risk of password
                 capture is greatly enhanced.
                 An alternate method of authentication is required which
                 provides for both origin authentication and replay
                 protection, but which does not involve sending a password
                 in the clear over the network.  The APOP command provides
                 this functionality.

                 A POP3 server which implements the APOP command will
                 include a timestamp in its banner greeting.  The syntax of
                 the timestamp corresponds to the `msg-id' in [RFC822], and
                 MUST be different each time the POP3 server issues a banner
                 greeting.  For example, on a UNIX implementation in which a
                 separate UNIX process is used for each instance of a POP3
                 server, the syntax of the timestamp might be:

                    <process-ID.clock@hostname>

                 where `process-ID' is the decimal value of the process's
                 PID, clock is the decimal value of the system clock, and
                 hostname is the fully-qualified domain-name corresponding
                 to the host where the POP3 server is running.

                 The POP3 client makes note of this timestamp, and then
                 issues the APOP command.  The `name' parameter has
                 identical semantics to the `name' parameter of the USER
                 command. The `digest' parameter is calculated by applying
                 the MD5 algorithm [RFC1321] to a string consisting of the
                 timestamp (including angle-brackets) followed by a shared
                 secret.  This shared secret is a string known only to the
                 POP3 client and server.  Great care should be taken to
                 prevent unauthorized disclosure of the secret, as knowledge
                 of the secret will allow any entity to successfully
                 masquerade as the named user.  The `digest' parameter
                 itself is a 16-octet value which is sent in hexadecimal
                 format, using lower-case ASCII characters.

                 When the POP3 server receives the APOP command, it verifies
                 the digest provided.  If the digest is correct, the POP3
                 server issues a positive response, and the POP3 session
                 enters the TRANSACTION state.  Otherwise, a negative
                 response is issued and the POP3 session remains in the
                 AUTHORIZATION state.

                 Note that as the length of the shared secret increases, so
                 does the difficulty of deriving it.  As such, shared
                 secrets should be long strings (considerably longer than
                 the 8-character example shown below).

             Possible Responses:
                 +OK maildrop locked and ready
                 -ERR permission denied

             Examples:
                 S: +OK POP3 server ready <1896.697170952@dbc.mtview.ca.us>
                 C: APOP mrose c4c9334bac560ecc979e58001b3e22fb
                 S: +OK maildrop has 1 message (369 octets)

                 In this example, the shared  secret  is  the  string  `tan-
                 staaf'.  Hence, the MD5 algorithm is applied to the string

                    <1896.697170952@dbc.mtview.ca.us>tanstaaf

                 which produces a digest value of

                    c4c9334bac560ecc979e58001b3e22fb

Next: 8. POP3 Command Summary

Connected: An Internet Encyclopedia
RFC 1725 - 7. Optional POP3 Commands