Enum postman_pop3::Command

pub enum Command {
    APOP,
    AUTH,
    CAPA,
    DELE,
    LIST,
    NOOP,
    QUIT,
    PASS,
    RETR,
    RSET,
    STAT,
    TOP,
    UIDL,
    USER,
}

Variants

APOP

APOP is used to do digest auth

Restrictions

Only be given in the AUTHORIZATION stqaate after the POP3 greeting or after an unsuccessful USER or PASS command

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 onw 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).

Syntax

S: +OK POP3 server ready <process-id.clock@hostname>
C: APOP <username> <digest of "<process-id.clock@hostname><password>">
S: +OK [msg]

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

AUTH

AUTH command indicates an authentication mechanism to the server.

Restrictions

Only be given in the AUTHORIZATION state

Discussion

The AUTH command indicates an authentication mechanism to the server. If the server supports the requested authentication mechanism, it performs an authentication protocol exchange to authenticate and identify the user. Optionally, it also negotiates a protection mechanism for subsequent protocol interactions. If the requested authentication mechanism is not supported, the server

should reject the AUTH command by sending a negative response.

The authentication protocol exchange consists of a series of server challenges and client answers that are specific to the authentication mechanism. A server challenge, otherwise known as a ready response, is a line consisting of a "+" character followed by a single space and a BASE64 encoded string. The client answer consists of a line containing a BASE64 encoded string. If the client wishes to cancel an authentication exchange, it should issue a line with a single "*". If the server receives such an answer, it must reject the AUTH command by sending a negative response.

A protection mechanism provides integrity and privacy protection to the protocol session. If a protection mechanism is negotiated, it is applied to all subsequent data sent over the connection. The protection mechanism takes effect immediately following the CRLF that concludes the authentication exchange for the client, and the CRLF of the positive response for the server. Once the protection mechanism is in effect, the stream of command and response octets is processed into buffers of ciphertext. Each buffer is transferred over the connection as a stream of octets prepended with a four octet field in network byte order that represents the length of the following data. The maximum ciphertext buffer length is defined by the protection mechanism.

The server is not required to support any particular authentication mechanism, nor are authentication mechanisms required to support any protection mechanisms. If an AUTH command fails with a negative response, the session remains in the AUTHORIZATION state and client may try another authentication mechanism by issuing another AUTH command, or may attempt to authenticate by using the USER/PASS or APOP commands. In other words, the client may request authentication types in decreasing order of preference, with the USER/PASS or APOP command as a last resort.

Should the client successfully complete the authentication exchange, the POP3 server issues a positive response and the POP3 session enters the TRANSACTION state.

Syntax

List supported auth methods

C: AUTH
S: +OK <msg>
S: <auth>
S: .

Check and start a specific auth

C: AUTH <auth>
S: <challenge>
C: <response>
S: +OK <msg>

Examples

S: +OK POP3 server ready
C: AUTH KERBEROS_V4
S: + AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
   +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
   WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
S: + or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: +OK Kerberos V4 authentication successful

CAPA

CAPA returns a list of capabilities supported by the POP3 server

Restrictions

Available in both the AUTHORIZATION and TRANSACTION states

Discussion

An -ERR response indicates the capability command is not implemented and the client will have to probe for capabilities as before.

An +OK response is followed by a list of capabilities, one per line. Each capability name MAY be followed by a single space and a space-separated list of parameters. Each capability line is limited to 512 octets (including the CRLF). The capability list is terminated by a line containing a termination octet (".") and a CRLF pair.

Available capabilities

• TOP
• USER
• SASL
• RESP-CODES
• LOGIN-DELAY
• PIPELINING
• EXPIRE
• UIDL
• IMPLEMENTATION

Syntax

C: CAPA
S: +OK <msg>
S: <capability>
S: .

Examples

C: CAPA
S: +OK Capability list follows
S: TOP
S: USER
S: SASL CRAM-MD5 KERBEROS_V4
S: RESP-CODES
S: LOGIN-DELAY 900
S: PIPELINING
S: EXPIRE 60
S: UIDL
S: IMPLEMENTATION Shlemazle-Plotz-v302
S: .

DELE

DELE will delete a mail from maildrop

Restrictions

Only be given in the TRANSACTION state

Discussion

The POP3 server marks the message as deleted. Any future reference to the message-number associated with the message in a POP3 command generates an error. The POP3 server does not actually delete the message until the POP3 session enters the UPDATE state.

Syntax

C: DELE <id>
S: +OK [msg]

Examples

C: DELE 1
S: +OK message 1 deleted

C: DELE 2
S: -ERR message 2 already deleted

LIST

LIST will list maildrop mails

Restrictions

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 "scan 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 also called a "scan listing" for that message. If there are no messages in the maildrop, then the POP3 server responds with no scan listings--it issues a positive response followed by a line containing a termination octet and a CRLF pair.

In order to simplify parsing, all POP3 servers are required to use a certain format for scan listings. A scan listing consists of the message-number of the message, followed by a single space and the exact size of the message in octets. Methods for calculating the exact size of the message are described in the "Message Format" section below. This memo makes no requirement on what follows the message size in the scan listing. Minimal implementations should just end that line of the response with a CRLF pair. More advanced implementations may include other information, as parsed from the message.

NOTE: This memo STRONGLY discourages implementations from supplying additional information in the scan listing. Other, optional, facilities are discussed later on which permit the client to parse the messages in the maildrop.

Note that messages marked as deleted are not listed.

Syntax

List all mails

C: LIST
S: +OK [msg]
S: <id> <size>
S: .

List single mail

C: LIST <id>
S: +OK <id> <size>

Examples

C: LIST
S: +OK 2 messages (320 octets)
S: 1 120
S: 2 200
S: .

C: LIST 2
S: +OK 2 200

C: LIST 3
S: -ERR no such message, only 2 messages in maildrop

NOOP

NOOP will do nothing, used to keep heartbeat.

Restrictions

Only be given in the TRANSACTION state

Discussion

The POP3 server does nothing, it merely replies with a positive response.

Syntax

C: NOOP
S: +OK

Examples

C: NOOP
S: +OK

QUIT

QUIT will terminate this connection by client.

Syntax

C: QUIT
S: +OK [msg]

Examples

C: QUIT
S: +OK dewey POP3 server signing off (maildrop empty)

PASS

PASS is used to send password.

Restrictions

Only be given in the AUTHORIZATION state immediately after a successful USER command

Discussion

When the client issues the PASS command, the POP3 server uses the argument pair from the USER and PASS commands to determine if the client should be given access to the appropriate maildrop.

Since the PASS command has exactly one argument, a POP3 server may treat spaces in the argument as part of the password, instead of as argument separators.

Syntax

C: PASS <passowrd>
S: +OK [msg]

Examples

C: USER mrose
S: +OK mrose is a real hoopy frood
C: PASS secret
S: -ERR maildrop already locked

C: USER mrose
S: +OK mrose is a real hoopy frood
C: PASS secret
S: +OK mrose's maildrop has 2 messages (320 octets)

RETR

RETR will be used to retrieve a mail

Restrictions

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 message corresponding to the given message-number, being careful to byte-stuff the termination character (as with all multi-line responses).

Syntax

C: RETR <id>
S: +OK [msg]
S: <the POP3 server sends the entire message here>
S: .

Examples

C: RETR 1
S: +OK 120 octets
S: <the POP3 server sends the entire message here>
S: .

RSET

RSET will reset the connection to initial state.

Restrictions

Only be given in the TRANSACTION state

Discussion

If any messages have been marked as deleted by the POP3 server, they are unmarked. The POP3 server then replies with a positive response.

Syntax

C: RSET
S: +OK [msg]

Examples

C: RSET
S: +OK maildrop has 2 messages (320 octets)

STAT

STAT will show the stat of maildrop.

Restrictions

Only be given in the TRANSACTION state

Discussion

The POP3 server issues a positive response with a line containing information for the maildrop. This line is called a "drop listing" for that maildrop.

In order to simplify parsing, all POP3 servers are required to use a certain format for drop listings. The positive response consists of "+OK" followed by a single space, the number of messages in the maildrop, a single space, and the size of the maildrop in octets. This memo makes no requirement on what follows the maildrop size. Minimal implementations should just end that line of the response with a CRLF pair. More advanced implementations may include other information.

NOTE: This memo STRONGLY discourages implementations
from supplying additional information in the drop
listing.  Other, optional, facilities are discussed
later on which permit the client to parse the messages
in the maildrop.

Note that messages marked as deleted are not counted in either total.

Syntax

C: STAT
S: OK <count> <size>

Examples

C: STAT
S: +OK 2 320

TOP

TOP will used to send top lines of messages.

Restrictions

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

Syntax

C: TOP <id> <lines>
S: +OK
S: <the POP3 server sends the headers of the
   message, a blank line, and the first <lines>
   of the body of the message>
S: .

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

UIDL will used to do "unique-id listing".

Restrictions

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 one to 70 characters in the range 0x21 to 0x7E, which uniquely identifies a message within a maildrop and which persists across sessions. This persistence is required even if a session ends without entering the UPDATE state. 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.

While it is generally preferable for server implementations to store arbitrarily assigned unique-ids in the maildrop, this specification is intended to permit unique-ids to be calculated as a hash of the message. Clients should be able to handle a situation where two identical copies of a message in a maildrop have the same unique-id.

Syntax

List all mails with unique id

C: UIDL
S: +OK
S: <id> <unique-id>
S: .

List single mail with unique id

C: UIDL <id>
S: +OK <id> <unique-id>

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

USER

USER is used to send user name

Restrictions

Only be given in the AUTHORIZATION state after the POP3 greeting or after an unsuccessful USER or PASS command

Discussion

To authenticate using the USER and PASS command combination, the client must first issue the USER command. If the POP3 server responds with a positive status indicator ("+OK"), then the client may issue either the PASS command to complete the authentication, or the QUIT command to terminate the POP3 session. If the POP3 server responds with a negative status indicator ("-ERR") to the USER command, then the client may either issue a new authentication command or may issue the QUIT command.

The server may return a positive response even though no such mailbox exists. The server may return a negative response if mailbox exists, but does not permit plaintext password authentication.

Syntax

C: USER <username>
S: +OK [msg]

Examples

C: USER frated
S: -ERR sorry, no mailbox for frated here

C: USER mrose
S: +OK mrose is a real hoopy frood

Trait Implementations

impl Clone for Command

pub fn clone(&self) -> Command

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Command

impl Debug for Command

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Command

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'_> From<&'_ Request> for Command

pub fn from(v: &Request) -> Self

Performs the conversion.

impl<'_> From<&'_ Response> for Command

pub fn from(v: &Response) -> Self

Performs the conversion.

impl FromStr for Command

type Err = Error

The associated error which can be returned from parsing.

pub fn from_str(s: &str) -> Result<Self>

Parses a string s to return a value of this type.