RFC 2221

IMAP4 Login Referrals

📅 published October 1997, from ietf

RFC 2221: IMAP4 Login Referrals 🎀

  • RFC number: 2221
  • Title: IMAP4 Login Referrals
  • Author: M. Gahrns, from Microsoft (Mike Gahrns, see Section 9 🫶)
  • Category: Standards Track
  • Date: October 1997
  • Obsoletes / Updates: this title block doesn't list anything it obsoletes or updates 🤷‍♀️

Status of this Memo

okay so this part is the official "what is this doc" bit 📜. It says this is an Internet standards track protocol for the Internet community, and it's asking everyone to discuss it and send suggestions for making it better 💬. If you want to know where the protocol sits in the official standardization process, check the current edition of "Internet Official Protocol Standards" (STD 1) 🧐. And distribution is unlimited, so share it with everyone 🌈.

Copyright (C) The Internet Society (1997). All Rights Reserved. 💜

1. Abstract ✨

this is giving "big mailbox migration energy" 📦. When you have tons of users and a bunch of IMAP4 [RFC-2060] servers, you sometimes need to move people from one server to another 🚚. Maybe hardware broke, maybe the org reshuffled, whatever 😭.

Login referrals are the fix 🦋. They let clients quietly hop over to a different IMAP4 server when someone's home server has changed, so the user never has to think about it 🪄.

Then there's the "proxy method" 🙈, where the local server goes and fetches everything from the remote server for the client, then passes it along. The referral way is kinda iconic because the client connects directly to the remote server. That's usually a better use of bandwidth, and the local server doesn't have to pretend to be the client when it logs in over there 🔥.

2. Conventions used in this document 📚

In examples, "C:" means lines from the client and "S:" means lines from the server 💻.

A home server is an IMAP4 server that holds the user's inbox 🏠.

A remote server is a server that holds remote mailboxes 🌍.

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] 💅. These are the official keyword rules, so don't mess with them 🫢.

3. Introduction and Overview 🌸

IMAP4 servers that support this extension MUST list the keyword LOGIN-REFERRALS in their CAPABILITY response. The client doesn't have to do anything special to turn on the LOGIN-REFERRALS capability in a server. It just works ✨.

Some rules for the referral chain 🔗: a LOGIN-REFERRALS capable IMAP4 server SHOULD NOT return a referral to a server that will return a referral. And a client MUST NOT follow more than 10 levels of referral without consulting the user 🙅‍♀️. Nobody wants to get dragged through a 47-hop referral maze 💀.

A LOGIN-REFERRALS response code MUST contain as an argument a valid IMAP server URL as defined in [IMAP-URL] 🔗. No vibes-based URLs allowed 😤.

A home server referral is either a tagged NO or OK, or an untagged BYE response that has a LOGIN-REFERRALS response code in it 🎯.

Example 🎀:

A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/] Remote Server

NOTE: user;AUTH=* is specified as required by [IMAP-URL] to avoid a client falling back to anonymous login 🙈. Keep that ;AUTH=* part, bestie, it's there for a reason 🔐.

4. Home Server Referrals 🏡

A home server referral can come back in response to an AUTHENTICATE or LOGIN command, or it can show up in the connection startup banner 🎉. If the server sends a home server referral in a tagged NO response, it means that server has zero mailboxes the user can access 🚫. If the referral comes in a tagged OK response, the user's personal mailboxes are somewhere else, but the server still has public mailboxes the user can read 📬. After a home server referral, the client can not make any assumptions about whether the move is permanent or temporary 🤷‍♀️. Don't assume, bestie 🙃.

4.1. LOGIN and AUTHENTICATE Referrals 🔑

An IMAP4 server MAY respond to a LOGIN or AUTHENTICATE command with a home server referral if it wants to send the user to another IMAP4 server 🧚.

Examples 🎀:

C: A001 LOGIN MIKE PASSWORD
S: A001 NO [REFERRAL IMAP://MIKE@SERVER2/] Specified user
        is invalid on this server. Try SERVER2.
C: A001 LOGIN MATTHEW PASSWORD
S: A001 OK [REFERRAL IMAP://MATTHEW@SERVER2/] Specified
        user's personal mailboxes located on Server2, but
        public mailboxes are available.
C: A001 AUTHENTICATE GSSAPI
   <authentication exchange>
S: A001 NO [REFERRAL IMAP://user;AUTH=GSSAPI@SERVER2/]
        Specified user is invalid on this server. Try
        SERVER2.

4.2. BYE at connection startup referral 👋

An IMAP4 server MAY respond with an untagged BYE and a REFERRAL response code that has an IMAP URL pointing to a home server. This is for when the server won't accept connections and wants to send the client to another IMAP4 server 🚪.

Example 🎀:

S: * BYE [REFERRAL IMAP://user;AUTH=*@SERVER2/] Server not
         accepting connections.  Try SERVER2

5. Formal Syntax 🧩

This uses the augmented Backus-Naur Form (BNF) described in [ABNF] 🧠. It also amends the "resp_text_code" element of the IMAP4 grammar from [RFC-2060] 🛠️.

resp_text_code =/ "REFERRAL" SPACE <imapurl>
   ; See [IMAP-URL] for definition of <imapurl>
   ; See [RFC-2060] for base definition of resp_text_code

6. Security Considerations 🔐

This part is serious, bestie 😭. The login referral mechanism uses IMAP URLs, so it has the same security considerations as general internet URLs [RFC-1738], and in particular IMAP URLs [IMAP-URL] 🫣.

A server MUST NOT give a login referral if authentication for that user fails. The point is to avoid leaking info about someone's account to an unauthorized person 🙈. No free info for the nosy 🚫.

With the LOGIN-REFERRALS capability, it's potentially easier to build a rogue "password catching" server 😈. That server collects login data and then refers the client to the real IMAP4 server. Referrals make that attack easier to set up, but the referral response also makes the intrusion easier to detect 🕵️‍♀️. Plot twist, but still a warning 🚨.

7. References 📖

[RFC-2060], Crispin, M., "Internet Message Access Protocol - Version 4rev1", RFC 2060, December 1996.

[IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, September 1997.

[RFC-1738], Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994.

[RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997.

[ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for Syntax Specifications: ABNF", Work in Progress.

8. Acknowledgments 🫶

Lots of valuable suggestions came from private chats and the IMAP4 mailing list 💌. Raymond Cheng, Mark Crispin, Mark Keasling, Chris Newman and Larry Osterman made major contributions to this document, so give them all the flowers 💐🌷.

9. Author's Address 📮

Mike Gahrns Microsoft One Microsoft Way Redmond, WA, 98072

Phone: (206) 936-9833 EMail: mikega@microsoft.com

Copyright (C) The Internet Society (1997). 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 implmentation may be prepared, copied, published andand 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. 💖

📦 where this page comes from