POP SYS and AUTH: The SYS and AUTH POP Response Codes
Two POP3 error codes and a capability that tell a mail client whether a failed login is the user's fault or the server's.
Gellens, R., "The SYS and AUTH POP Response Codes", RFC 3206, DOI 10.17487/RFC3206, February 2002, <https://www.rfc-editor.org/info/rfc3206>.
@misc{rfc3206,
series = {Request for Comments},
number = 3206,
howpublished = {RFC 3206},
publisher = {RFC Editor},
doi = {10.17487/RFC3206},
url = {https://www.rfc-editor.org/info/rfc3206},
author = {R. Gellens},
title = {{The SYS and AUTH POP Response Codes}},
pagetotal = 6,
year = 2002,
month = feb,
} RFC text
Contents
Network Working Group R. Gellens
Request for Comments: 3206 QUALCOMM
Category: Standards Track February 2002
The SYS and AUTH POP Response Codes
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract
This memo proposes two response codes: SYS and AUTH, which enable
clients to unambiguously determine an optimal response to an
authentication failure. In addition, a new capability (AUTH-RESP-
CODE) is defined.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in this Document . . . . . . . . . . . . . . 2
3. Background . . . . . . . . . . . . . . . . . . . . . . . . 2
4. The SYS Response Code . . . . . . . . . . . . . . . . . . . 3
5. The AUTH Response Code . . . . . . . . . . . . . . . . . . 3
6. The AUTH-RESP-CODE Capability . . . . . . . . . . . . . . . 4
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 4
8. Security Considerations . . . . . . . . . . . . . . . . . . 4
9. References . . . . . . . . . . . . . . . . . . . . . . . . 5
10. Author's Address . . . . . . . . . . . . . . . . . . . . . . 5
11. Full Copyright Statement . . . . . . . . . . . . . . . . . 6
1. Introduction
RFC 2449 [POP3-EXT] defined extended [POP3] response codes, to give
clients more information about errors so clients can respond more
appropriately. In addition to the mechanism, two initial response
codes were defined (IN-USE and LOGIN-DELAY), in an attempt to
differentiate between authentication failures related to user
credentials, and other errors.
In practice, these two response codes, while helpful, do not go far
enough. This memo proposes two additional response codes: SYS and
AUTH, which enable clients to unambiguously determine an optimal
response to an authentication failure.
In addition, a new capability (AUTH-RESP-CODE) is defined.
2. Conventions Used in this Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [KEYWORDS].
3. Background
RFC 2449 [POP3-EXT] introduced the IN-USE and LOGIN-DELAY response
codes. The intent is to allow clients to clearly determine the
underlying cause of a failure in order to respond. For example,
clients need to know if the user should be asked for new credentials,
or if the POP3 session should simply be tried again later. (Some
deployed POP3 clients attempt to parse the text of authentication
failure errors, looking for strings known to be issued by various
servers which indicate the mailbox is locked.)
IN-USE indicates that an exclusive lock could not be obtained for the
user's mailbox, probably because another POP3 session is in progress.
LOGIN-DELAY informs the client that the user has not waited long
enough before authenticating again.
However, there are other error conditions which do not require new
credentials, some of which should be brought to the user's attention.
Despite the IN-USE and LOGIN-DELAY responses, clients cannot be sure
if any other error requires new user credentials.
4. The SYS Response Code
The SYS response code announces that a failure is due to a system
error, as opposed to the user's credentials or an external condition.
It is hierarchical, with two possible second-level codes: TEMP and
PERM. (Case is not significant at any level of the hierarchy.)
SYS/TEMP indicates a problem which is likely to be temporary in
nature, and therefore there is no need to alarm the user, unless the
failure persists. Examples might include a central resource which is
currently locked or otherwise temporarily unavailable, insufficient
free disk or memory, etc.
SYS/PERM is used for problems which are unlikely to be resolved
without intervention. It is appropriate to alert the user and
suggest that the organization's support or assistance personnel be
contacted. Examples include corrupted mailboxes, system
configuration errors, etc.
The SYS response code is valid with an -ERR response to any command.
5. The AUTH Response Code
The AUTH response code informs the client that there is a problem
with the user's credentials. This might be an incorrect password, an
unknown user name, an expired account, an attempt to authenticate in
violation of policy (such as from an invalid location or during an
unauthorized time), or some other problem.
The AUTH response code is valid with an -ERR response to any
authentication command including AUTH, USER (see note), PASS, or
APOP.
Servers which include the AUTH response code with any authentication
failure SHOULD support the CAPA command [POP3-EXT] and SHOULD include
the AUTH-RESP-CODE capability in the CAPA response. AUTH-RESP-CODE
assures the client that only errors with the AUTH code are caused by
credential problems.
NOTE: Returning the AUTH response code to the USER command
reveals to the client that the specified user exists. It is
strongly RECOMMENDED that the server not issue this response code
to the USER command.
6. The AUTH-RESP-CODE Capability
CAPA tag:
AUTH-RESP-CODE
Arguments:
none
Added commands:
none
Standard commands affected:
none
Announced states / possible differences:
both / no
Commands valid in states:
n/a
Specification reference:
this document
Discussion:
The AUTH-RESP-CODE capability indicates that the server includes
the AUTH response code with any authentication error caused by a
problem with the user's credentials.
7. IANA Considerations
IANA has added the AUTH-RESP-CODE capability to the list of POP3
capabilities (established by RFC 2449 [POP3-EXT]).
IANA has also added the SYS and AUTH response codes to the list of
POP3 response codes (also established by RFC 2449 [POP3-EXT]).
8. Security Considerations
Section 5, The AUTH Response Code, discusses the security issues
related to use of the AUTH response code with the USER command.
9. References
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[POP3] Myers, J. and M. Rose, "Post Office Protocol -- Version
3", STD 53, RFC 1939, May 1996.
[POP3-EXT] Gellens, R., Newman, C. and L. Lundblade, "POP3 Extension
Mechanism", RFC 2449, November 1998.
10. Author's Address
Randall Gellens
QUALCOMM Incorporated
5775 Morehouse Drive
San Diego, CA 92121-2779
U.S.A.
Phone: +1 858 651 5115
EMail: randy@qualcomm.com
11. Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
AI ELI5
On this page
§1Introduction
RFC 2449 gave POP3 a mechanism for extended response codes, so a server can say more about an error than a bare -ERR. It defined two initial codes, IN-USE and LOGIN-DELAY, to separate credential failures from other errors.
RFC 3206 says these two codes, while helpful, do not go far enough. It adds two more response codes, SYS and AUTH, and one new capability, AUTH-RESP-CODE. Together they let a client work out the best response to an authentication failure without guessing.
Mail servers could already say a little about why they said no. This memo adds two clearer reasons: the server is having a problem, or your login is the problem.
§3Why IN-USE and LOGIN-DELAY Were Not Enough
The point of response codes is to let a client see the real cause of a failure. For example, a client needs to know whether to ask the user for new credentials or simply to try the POP3 session again later. Some deployed POP3 clients had been parsing the text of failure messages, looking for strings that various servers use to say a mailbox is locked.
IN-USE means an exclusive lock on the user's mailbox could not be obtained, probably because another POP3 session is in progress. LOGIN-DELAY means the user has not waited long enough before authenticating again.
Other error conditions do not need new credentials, and some of them should be brought to the user's attention. Even with the two older codes, a client could not be sure whether any other error required new credentials.
Before, mail programs had to read the words of an error message and guess. That is like guessing why a door is locked by squinting at the sign on it.
§4The SYS Response Code
SYS announces that a failure is due to a system error, as opposed to the user's credentials or an external condition. It is hierarchical, with two second-level codes, TEMP and PERM. Case does not matter at any level.
- SYS/TEMP signals a problem likely to be temporary, so there is no need to alarm the user unless it persists. Examples are a central resource that is locked or unavailable, or insufficient free disk or memory.
- SYS/PERM signals a problem unlikely to be resolved without intervention. It is appropriate to alert the user and suggest contacting the organization's support personnel. Examples are corrupted mailboxes and system configuration errors.
The SYS code is valid with an -ERR response to any command.
SYS means the problem is on the server's side. TEMP says wait a bit and it will probably fix itself, and PERM says someone needs to fix it, so call for help.
- SYS/TEMPTemporary system problem — Likely temporary; do not alarm the user unless it persists.
- SYS/PERMPermanent system problem — Unlikely to be resolved without intervention; suggest contacting support.
- AUTHCredential problem — Wrong password, unknown user, expired account or policy violation.
§5The AUTH Response Code
AUTH tells the client that there is a problem with the user's credentials. That might be an incorrect password, an unknown user name, an expired account, an attempt to authenticate against policy (such as from an invalid location or at an unauthorized time), or some other problem.
It is valid with an -ERR response to any authentication command, including AUTH, USER, PASS or APOP.
Returning AUTH in reply to the USER command reveals to the client that the specified user exists. The RFC strongly RECOMMENDS that the server not issue this response code to USER.
AUTH means the problem is with you: the wrong password, an unknown name, or a login that is not allowed right now. The server is careful not to say it too early, because that could tell a stranger which names are real.
§6The AUTH-RESP-CODE Capability
Servers that include the AUTH response code with any authentication failure SHOULD support the CAPA command and SHOULD include the AUTH-RESP-CODE capability in the CAPA response. The capability assures the client that only errors carrying the AUTH code are caused by credential problems.
The capability definition follows the template from RFC 2449. It takes no arguments, adds no commands and affects no standard commands. It is announced in both states, with no difference between them. In short, it indicates that the server includes AUTH with any authentication error caused by a problem with the user's credentials.
AUTH-RESP-CODE is a promise on the server's door. It says: if I say AUTH, it is really your login, and if I do not say AUTH, it is not.
§8IANA and Security Considerations
IANA has added the AUTH-RESP-CODE capability to the list of POP3 capabilities, and the SYS and AUTH response codes to the list of POP3 response codes. Both lists were established by RFC 2449.
The Security Considerations section is a single pointer: the security issue is the one in the section on the AUTH response code, namely that issuing it for the USER command reveals that a user exists.
The only safety worry is that a helpful error could tell a stranger which user names are real, so servers should not say AUTH at that step.