[ новости /+++ | форум | теги | ]

Каталог документации / Раздел "Электронная почта" (Архив | Для печати)

Обзор протокола IMAP4 rev 1

Автор: Сергей Холодилов (sergh)
The RSDN Group

Оригинал: sergh.pisem.net

Версия текста: 1.0

Этот документ - часть моего отчёта по лабораторной работе, цель которой состояла в реализации простого клиента IMAP4 rev1. Глубже, чем было нужно по работе, я в IMAP не лез. Когда в тексте упоминается "проект" речь идёт о написанной мною реализации. Также в тексте периодически встречаются упоминания "pochta.ru", это бесплатный почтовый сервис http://pochta.ru, один из немногих, предоставляющих доступ к ящику по протоколу IMAP4. Проект тестировался только с pochta.ru, с ними работает нормально.

Описание несколько упрощено, но зато общая идея становится ясна быстро и без потерь. Заранее признаю - не всё в стандарте IMAP4 мне понятно, но всё было и не нужно. К счастью. То, что описано - понятно.

Чтобы не соблазнять спамеров, встречающиеся в тексте почтовые и IP адреса изменены.

Overview

Протокол IMAP4 rev 1 описан в RFC 2060, принятом в 1996 году. IMAP предназначен для управления письмами, хранящимися на почтовом сервере, аббревиатура расшифровывается как Internet Message Access Protocol.

Протокол довольно сложный, имеет 24 стандартные команды (сравните с 12-ю командами POP3), плюс возможны расширения.

Типы данных

Помимо обычных и интуитивно понятных типов данных, RFC 2060 описывает два типа строк:

• "quoted string" - строка, заключённая в кавычки. Не может содержать символы CR, LF и символы из второй половины таблицы ASCII, символы <"> и <\> маскируются символом <\>.
• "literal string" - литерал. Может содержать любые символы, кроме 0 (интересное ограничение, непонятно зачем нужно). Перед самими данными в фигурных скобках передаётся длина строки.

Более точное определение строк:

string          ::= quoted / literal

quoted          ::= <"> *QUOTED_CHAR <">
QUOTED_CHAR     ::= <any TEXT_CHAR except quoted_specials> / "\" quoted_specials
quoted_specials ::= <"> / "\"
TEXT_CHAR       ::= <any CHAR except CR and LF>
CHAR            ::= <any 7-bit US-ASCII character except NUL, 0x01 - 0x7f>

literal         ::= "{" number "}" CRLF *CHAR8
                    ;; Number represents the number of CHAR8 octets
CHAR8           ::= <any 8-bit octet except NUL, 0x01 - 0xff>

Взаимодействие клиента и сервера - общий взгляд

Соединение устанавливается клиентом, используется протокол TCP, 143-й порт. Клиент посылает серверу команды (commands), сервер посылает клиенту ответы (responses). Команды выглядят так:

тег команда <аргументы> CRLF

Где тег - любая последовательность букв, цифр и ещё некоторых символов, уникальная в пределах сессии. Ответы сервера относятся к одной из трёх групп:

• "tagged". Ответ начинается с тега, указанного клиентом при посылке команды. Это признак либо успешного (если после тега идёт OK), либо неудачного завершения (если NO или BAD) обработки команды. В случае успешного завершения, ответ может содержать какие-то полезные данные, в случае неуспешного - содержит причину в текстовом виде.
• "начинается с символа +". Обычно что-то типа "+ go ahead". Означает, что сервер готов принять продолжение, так на сервер передаются литеральные строки. Клиент передаёт на сервер длину строки и CRLF, после чего ждёт разрешения передачи данных; сервер может не разрешить, например, если уже переданная часть команды некорректна. Такое правило введено потому, что литеральные строки могут быть очень длинными, чтобы зря не гонять данные по сети, сначала нужно удостовериться, что их примут.
• "начинается с символа *" Так передаётся основная информация. Обычно имеет форму * <тип информации> <сама информация>. Например * LIST (\Seen) "." "inbox". Поле "тип информации" (в данном случае - LIST) определяет, что следует далее в ответе и в каком формате оно следует (в данном случае - флаги, символ разделитель, имя папки). Есть исключения, например ответ * 123 EXIST. Не очень понятно, почему нельзя было всё сделать одинаково.

Типичный обмен сообщениями выглядит так:

> произвольный_тег команда <аргументы> CRLF
< * какие-то данные CRLF
< * ещё какие-то данные CRLF
< тот_же_самый_тег OK команда Completed CRLF

Неуспешное выполнение:

> произвольный_тег команда <аргументы> CRLF
< * какие-то данные CRLF
< * ещё какие-то данные CRLF
< тот_же_самый_тег NO у вас документов нет CRLF

В случае передачи литеральной строки на сервер:

> произвольный_тег команда <аргументы> {длина}CRLF
< + go ahead CRLF
> <данные, столько, сколько указано> CRLF
< * какие-то данные CRLF
< тот_же_самый_тег OK команда Completed CRLF

Если литеральную строчку нужно передать серверу, он не спрашивает разрешения, а просто передаёт.

> произвольный_тег команда <аргументы> CRLF
< * какие-то данные {длина}CRLF
< <данные, сколько указано>CRLF
< тот_же_самый_тег OK команда Completed CRLF

Такое взаимодействие имеет две особенности:

• Клиент может послать на сервер одновременно две (несколько) команды. Благодаря тегам, он сможет разобраться, какая из них как закончилась. Как сервер будет распараллеливать выполнение и будет ли вообще - другой вопрос. Клиента это, в общем-то, не касается.
• Можно возразить, что конец команды найти легко, но вот разделить посылаемые сервером "какие-то данные" между командами затруднительно. Тут всплывает вторая особенность: даже в случае, когда клиент посылает только одну команду, эти данные не обязательно относятся к ней. В RFC 2060 не прописаны все возможные случаи, когда сервер может начать внеплановое общение, но в частности, таким способом сервер сообщает об асинхронных событиях, типа пришедшего нового письма.

Состояние сессии - общий взгляд

Взаимодействуя с сервером, клиент переводит его в одно из пяти состояний. Приведённый в RFC 2060 граф переходов:

            +--------------------------------------+
            |initial connection and server greeting|
            +--------------------------------------+
                      || (1)       || (2)        || (3)
                      VV           ||            ||
            +-----------------+    ||            ||
            |non-authenticated|    ||            ||
            +-----------------+    ||            ||
             || (7)   || (4)       ||            ||
             ||       VV           VV            ||
             ||     +----------------+           ||
             ||     | authenticated  |<=++       ||
             ||     +----------------+  ||       ||
             ||       || (7)   || (5)   || (6)   ||
             ||       ||       VV       ||       ||
             ||       ||    +--------+  ||       ||
             ||       ||    |selected|==++       ||
             ||       ||    +--------+           ||
             ||       ||       || (7)            ||
             VV       VV       VV                VV
            +--------------------------------------+
            |     logout and close connection      |
            +--------------------------------------+

Состояния:

• Установка соединения и приветствие со стороны сервера.

• Клиент не аутентифицирован
• Клиент аутентифицирован
• Выделена текущая папка
• Выход и закрытие соединения

Переходы (цифры соответствуют цифрам на графе):

1. Обычное соединение
2. Соединение с предварительной аутентификацией (в случае, если аутентификация выполнена некоторым "внешним" способом и клиенту не нужно аутентифицироваться явно).
3. Отклонённое соединение
4. Успешная аутентификация (команды LOGIN или AUTHENTICATE)
5. Успешное выделение папки (SELECT или EXAMINE)
6. Закрытие папки или неудачная попытка выделить папку (CLOSE, SELECT, EXAMINE)
7. Выход (команда LOGOUT), остановка сервера или разрыв соединения.

Очевидно, команды можно посылать только тогда, когда сессия находится в одном из трёх состояний:

• Клиент не аутентифицирован
• Клиент аутентифицирован
• Выделена текущая папка

В разных состояниях допустимы разные команды, где команду использовать можно, а где нельзя понятно по смыслу команды, здесь эта информация не приводится, в RFC она есть.

Содержимое почтового ящика - общий взгляд

Тезисно:

• Почтовый ящик состоит из папок (boxes), папки могут содержать другие папки и письма.
• Всегда есть папка INBOX.
• Чтобы обращаться к письмам, нужно выделить папку, в которой они лежат.
• Для каждого письма, помимо самого письма, хранится UID (уникальный идентификатор) и набор флагов.
• Есть стандартные флаги (\Seen, \Recent, \Answered .), сервер может поддерживать нестандартные.
• Чтобы удалить письмо, ему нужно установить флаг \Deleted. Реально письмо будет удалено из папки при выполнении команды EXPUNGE или при закрытии папки командой CLOSE. Если просто завершить сессию (LOGOUT) или выделить другую папку (SELECT), письма удалены не будут.
• Обращаться к письмам можно либо по номеру в папке, либо по UID.
• Номер в папке - от 1 до количества писем в папке. Можно обращаться к нескольким письмам сразу, задавая интервал, например так: 23:35 (номер первого : номер последнего).
• Чтобы обращаться к письму по UID, используются стандартные команды, к которым добавлен префикс "UID". Например, команда "FETCH 1" обращается к первому письму в папке, а "UID FETCH 12345" к письму с UID равным 12345, аналогично с интервалами. В проекте эти возможности не используется. С точки зрения RFC, "UID" - 24-я команда, я бы назвал её как-нибудь иначе.
• Письма в папке нумеруются в порядке появления, UID более нового письма гарантировано больше, чем UID любого старого. Правда, если произойдёт перегенерация UID, это правило будет относиться только к письмам, добавленным после перегенерации.
• UID писем нужны для того, чтобы хранить письма локально, и синхронизировать содержимое локальной и удалённой папок, не скачивая всё подряд. IMAP-сервер "должен постараться" хранить значения UID писем неизменными между сессиями. Но иногда у него может всё-таки не получиться, в этом случае он должен сгенерировать всем новые UID и увеличить UIDVALIDITY папки. Увидев изменённое значение UIDVALIDITY клиент сможет понять, что про синхронизацию можно забыть, придётся получать всё по новой.

Команды

Соединение

Сразу после успешного соединения, сервер посылает клиенту приветствие. Оно может выглядеть так (типичный случай):

< * OK Привет, юзер!

Так (с автоматической аутентификацией):

< * PREAUTH Здравствуйте, Иван Иванович!

Или, если не повезло, так:

< * BYE Ушла на базу, вернусь после пяти

LOGIN

Аутентификация:

> a000 LOGIN user password
< a000 OK LOGIN COMPLETED

Да, пароль идёт открытым текстом. Более защищённый вариант предлагает команда AUTHENTICATE, но с ней я не стал разбираться.

LOGOUT

Завершение сессии и выход

> a000 LOGOUT
< * BYE IMAP4rev1 Server logging out
< a000 OK LOGOUT COMPLETED

LIST

Возвращает список папок

> a000 LIST arg1 arg2
< * LIST (<флаги>) "<символ-разделитель в иерархических именах>" "<имя папки>"
< ...
< * LIST (<флаги>) "<символ-разделитель в иерархических именах>" "<имя папки>"
< a000 OK LIST COMPLETED

Аргументы:

• arg1 - имя папки в контексте которой проводится поиск папок. RFC 2060 не указывает, что делать, если arg1 - "", реализация на pochta.ru в этом случае ищет папки от корня. Возможно это вызвано тем, что на pochta.ru имя корневой папки - "", возможно я недостаточно внимательно читал RFC.
• arg2 - шаблон, которому должно удовлетворять имя найденной папки. * - любое, % - любое в пределах одного уровня иерархии. Если arg2 - "", возвращается корень иерархии папок.

Результаты:

• <флаги> - список флагов установленных для письма.
• <символ разделитель в иерархических именах> - что написано, то и есть. RCF 2060 требует, чтобы это был один символ, других ограничений вроде нет. рochta.ru использует "." Вероятность того, что у разных папок будут разные разделители.
• <имя папки> - имя папки

В проекте используется только форма LIST "" *

CREATE

Создаёт папку (см. замечание об именах папок в конце статьи). Сервер SHOULD уметь создавать сразу весь запрашиваемый путь. Но не MUST

> a000 CREATE "qwerty"
< a000 OK CREATE completed

DELETE

Удаляет папку. Сложное поведение в случае существования вложенных папок:

• удаление папки не приводит к удалению вложенных в неё папок
• если вложенные папки есть, они остаются, а сама папка переводится в состояние \Noselect. Такую папку невозможно выбрать. А вложенные - можно!
• Если удалить оставшиеся вложенные папки, можно будет "добить" и родительскую.

> a000 DELETE "qwerty"
< a000 OK DELETE completed

RENAME

Переименовывает папку

> a000 RENAME "qwerty" "asdfg"
< a000 OK RENAME completed

SELECT

Выделяет папку, возвращает различную информацию о папке.

> a000 SELECT INBOX
< * 172 EXISTS
< * 1 RECENT
< * OK [UNSEEN 12] Message 12 is first unseen
< * OK [UIDVALIDITY 3857529045] UIDs valid
< * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
< * OK [PERMANENTFLAGS (\Deleted \Seen)] Limited
< a000 OK [READ-WRITE] SELECT completed

Разберём ответ построчно (приблизительно и не очень точно):

< * 172 EXISTS

Количество писем в папке

< * 1 RECENT

Количество новых писем в папке

< * OK [UNSEEN 12] Message 12 is first unseen

Необязательная строчка. Первое не просмотренное письмо.

< * OK [UIDVALIDITY 3857529045] UIDs valid

UIDVALIDITY папки.

< * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)

Флаги, определённые в папке. Других флагов папке по идее нет.

< * OK [PERMANENTFLAGS (\Deleted \Seen)] Limited 

Флаги, которые можно менять.

< a000 OK [READ-WRITE] SELECT completed

Команда завершилась успешно, предоставлен доступ на чтение и запись.

Проект обрабатывает только первые две строчки, остальное просто пропускает.

CLOSE

Снимает выделение с текущей папки, удаляя при этом все сообщения, помеченные флагом \Deleted.

> a000 CLOSE
< a000 OK CLOSE COMPLETED

FETCH

Возвращает указанные части указанных сообщений. В проекте применяются два варианта:

• Возврат флагов и полей (точнее, используется форма FETCH X:Y, возвращающая данные для нескольких писем подряд).

> A0028 FETCH 1 (flags body.peek[header.fields (Date from to subject)])
< * 1 FETCH (FLAGS (\Answered \Seen) BODY[HEADER.FIELDS (Date from to subject)] {282}
< From: Ivan Ivanich <[email protected]>
< To: =?windows-1251?Q?=27=FF=C5=CF=D6=C5=C8_=F3=CD=CA=CD=C4=D5=CA=CD=C1=27?=
< 	 <[email protected]>
< Subject: =?windows-1251?Q?RE=3A_SharePoint_=D5_=C1=DF=C5_=C1=DF=C5_=C1=DF?=
< 	=?windows-1251?Q?=C5?=
< Date: Tue, 22 Jan 2002 11:07:52 +0300
< 
< )
< A0028 OK Completed (0.000 sec)

• Возврат полного текста письма

> A0032 FETCH 1 body[]
< * 1 FETCH (BODY[] {2531}
< X-Sieve: cmu-sieve 2.0
< Return-Path: <[email protected]>
< Received: from imap.front.ru (imap.front.ru [80.68.244.14])
< 	by imap.pisem.net (8.12.1/8.12.1) with ESMTP id g0M87LQ9090073
< 	for <[email protected]>; Tue, 22 Jan 2002 11:07:21 +0300 (MSK)?g
< 	(envelope-from [email protected])
< Received: from bull.ivanovich.spb.su (mail.ivanovich.ru [000.000.00.000])
< 	by imap.front.ru (8.12.2/8.12.2) with ESMTP id g0M85H2X055212
< 	for <[email protected]>; Tue, 22 Jan 2002 11:05:33 +0300 (MSK)
< 	(envelope-from [email protected])
< Received: by bull.ivanovich.spb.su with Internet Mail Service (5.5.2650.21)
< 	id <DLLJ6ACF>; Tue, 22 Jan 2002 11:07:56 +0300
< Message-ID: <[email protected]>
< From: Ivan Ivanich <[email protected]>
< To: =?windows-1251?Q?=27=FF=C5=CF=D6=C5=C8_=F3=CD=CA=CD=C4=D5=CA=CD=C1=27?=
< 	 <[email protected]>
< Subject: =?windows-1251?Q?RE=3A_SharePoint_=D5_=C1=DF=C5_=C1=DF=C5_=C1=DF?=
< 	=?windows-1251?Q?=C5?=
< Date: Tue, 22 Jan 2002 11:07:52 +0300
< MIME-Version: 1.0
< X-Mailer: Internet Mail Service (5.5.2650.21)
< Content-Type: text/plain;
< 	charset="windows-1251"
< Content-Transfer-Encoding: base64
< 
< 0eXw5e...

... (поскольку это настоящее письмо от настоящего человека, я его не публикую)

< DQoNCtEg8+Lg5uXt6OXsLA0K3vDgDQo=
< 
< )
< A0032 OK Completed (0.000 sec)

Кратко про аргументы:

• Первый аргумент - интервал писем, информацию о которых мы хотим получить. В данном случае - о письме с номером 1.
• Второй аргумент - информация, которую мы хотим получить. Если запрашивается несколько полей, нужно заключить список в скобки, если одно - не обязательно.
• Flags - флаги письма
• body[.] и body.peek[.] - всё письмо или его часть, в зависимости от содержимого квадратных скобок. Если в скобках ничего нет, то возвращается всё письмо, если что-то есть, то возвращается только запрошенное. Peek-вариант отличается тем, что не устанавливает письму флаг \Seen.
• header.fields(.) - заголовки письма, в скобках список.

А формат ответа проще посмотреть, чем описывать словами.

APPEND

Записывает письмо в папку.

> a000 APPEND имя-папки {310}
< + go ahead
> Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
> From: Fred Foobar <[email protected]>
> Subject: afternoon meeting
> To: [email protected]
> Message-Id: <[email protected]>
> MIME-Version: 1.0
> Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
>
> Hello Joe, do you think we can meet at 3:30 tomorrow?
>
< a000 OK APPEND Complete

Аргументом команды является имя папки и само письмо, ещё при желании можно передать флаги и дату (здесь не указано, так как в проекте эти аргументы не используются). Письмо должно быть корректным письмом, то есть соответствовать RFC 822.

Если письмо добавляется в текущую папку, и добавление прошло успешно, сервер SHOULD отправить уведомление вида * 123 EXISTS, посчитав и новое письмо. Моя реализация на это очень рассчитывает, pochta.ru соответствует.

STORE

Изменяет указанные флаги указанных сообщений. Так - добавляет к списку флагов указанные:

> A003 STORE 1 +FLAGS.SILENT (\Seen \Deleted)
< A003 OK STORE completed

Так - удаляет из списка флагов:

> A003 STORE 1 -FLAGS.SILENT (\Deleted)
< A003 OK STORE completed

Так - заменяет список флагов:

> A003 STORE 1 FLAGS.SILENT (\Seen \Deleted)
< A003 OK STORE completed

Если вместо FLAGS.SILENT использовать просто FLAGS, сервер будет посылать дополнительные ответы с информацией о состоянии флагов затронутых писем. Например так:

> A003 STORE 2:4 +FLAGS (\Deleted)
< * 2 FETCH FLAGS (\Deleted \Seen)
< * 3 FETCH FLAGS (\Deleted)
< * 4 FETCH FLAGS (\Deleted \Flagged \Seen)
< A003 OK STORE completed 

COPY

Копирует сообщение в указанную папку

> A003 COPY 1 "qwerty"
< A003 OK COPY completed

Остальные команды

Следующие команды не реализованы по причине сложности и/или моей лени. Они добавляют протоколу дополнительные возможности, которые не поддерживаются проектом:

• AUTHENTICATE - защищённая аутентификация. Описана в RFC 1731 "IMAP4 Authentication Mechanism", я его так и не прочёл.
• SUBSCRIBE, UNSUBSCRIBE, LSUB - протокол поддерживает возможность подписки. Я даже не разбирался, на что подписываемся.
• SEARCH - протокол поддерживает возможность поиска письма. Довольно сложная команда, поглядел, поглядел, не стал разбираться.

Следующие команды могли быть реализованы, но не понадобились. Никаких особых новых возможностей не добавляют:

• CAPABILITY - ответ содержит перечисление необязательных и нестандартных возможностей, поддерживаемых сервером. Единственная необязательная стандартная возможность - защищённая аутентификация, но она всё равно не поддерживается клиентом.
• NOOP - в ответ на эту команду сервер должен выложить всю "внеплановую" информацию, которая у него накопилась с последнего обращения клиента.
• EXAMINE - аналог SELECT, отличие в том, что открывает папки в режиме только для чтения.
• STATUS - возвращает информацию об указанной папке. Количество сообщений, и т.п.
• CHECK - просто проверка слуха.
• UID - упоминавшийся выше префикс, позволяющий обращаться к письмам по UID.
• EXPUNGE - явная очистка папки от писем с флагом \Deleted.

И ещё три слова про команды

Во-первых, про имена. С именами папок всё не просто. С одной стороны, все команды, работающие с папками (LIST, CREATE, DELETE, RENAME, SELECT, EXAMINE, APPEND) доступны в режиме "Клиент аутентифицирован, папка НЕ выбрана". Логично предположить, что в этом режиме должны использоваться полные имена папок. Логично предположить, что в режиме "Выбрана текущая папка" эти команды должны работать так же, то есть использовать полные имена (по принципу наименьшего удивления). Логично предположить, что и единственная оставшаяся команда COPY будет работать с полными именами. С другой стороны, в RFC это явно не оговаривается, зато упоминаются некие "пространства имён". В общем, дело тёмное. Но на любимой pochta.ru все имена должны быть полные, ещё одно очко в пользу логики.

Во-вторых, про строки. Согласно RFC 2060, везде, где можно употребить обычную строку, можно употребить и литерал. Например, можно так:

> a000 LOGIN {31}
< + go ahead
> длинное русское имя с пробелами {8}
< + go ahead
> password
< a000 OK LOGIN Completed

Здесь первые два перевода строки являются составной частью литералов, последний - завершает команду. Другой вопрос - поддержит ли такое поведение сервер. И не отреагирует ли он "симметричным ответом"?

В-третьих, про UID. Если вы пишите не лабораторную работу, а настоящего клиента, наверное их придётся использовать. Команды и идеи должны быть те же, а вот детали и подробности.. Ничем не могу помочь, не пробовал.

Партнёры:

Хостинг: