Simple Notification and Alarm Protocol (SNAP) February 2002 Internet Draft Noam Shapira Document: draft-shapira-snap-03 Nir Flatau Category: Informational Eran Aloni Expires: September 28, 2002 Comverse Technology February, 28 2002 Simple Notification and Alarm Protocol (SNAP) Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This memo suggests a protocol for messaging notification in which a messaging system (e.g. email server, voice mail system, etc.) notifies a notification service, and through it the user, that changes have occurred in a user's mailbox (new message arrived, mailbox is full, etc.). The protocol aims to provide the end-user with unified notification of events occurring on different messaging systems. A mailing list has been established to discuss this draft and promote the issue of Notification to RFC. To subscribe, send email with "subscribe snap" to majordomo@lists.neystadt.org or using web at http://www.neystadt.org/cgi-bin/majordomo. Shapira Informational - Expires September 2002 Page [1] Simple Notification and Alarm Protocol (SNAP) February 2002 Table of Contents 1 Introduction ................................................ 5 1.1 Scope ................................................... 5 1.2 Terminology ............................................. 6 1.3 Notification Protocol High level requirements ........... 7 1.3.1 Informative ......................................... 7 1.3.2 Minimum latency ..................................... 7 1.3.3 Large Scale ......................................... 7 1.4 Organization of This Document ........................... 7 2 Basic Operation ............................................. 8 2.1 The Transport Layer...................................... 8 2.1.1 HTTP Compliance ..................................... 9 2.1.2 HTTP Method ......................................... 9 2.1.3 Request URI ......................................... 9 2.1.4 Request Payload ..................................... 9 2.1.5 Charset and Encoding ................................ 9 2.1.6 Response Payload .................................... 9 2.1.7 Persistent Connections .............................. 10 2.2 Request Flow ............................................ 10 2.2.1 Request Order ....................................... 10 2.2.2 Coherence ........................................... 10 2.2.3 Response ............................................ 10 2.2.4 Retries ............................................. 10 2.2.5 Pipelining .......................................... 11 3 Request ..................................................... 11 3.1 Protocol Header ......................................... 11 3.1.1 Notification-Protocol-Version (M) ................... 11 3.1.2 Application-Name (M) ................................ 11 3.1.3 Application-Version (M) ............................. 11 3.1.4 Server-Type (M) ..................................... 12 3.1.5 Request-Type (M) .................................... 12 3.1.6 Request-Time ........................................ 12 3.1.7 Request-Id .......................................... 12 3.2 Request Types ........................................... 12 3.2.1 New-Msg ............................................. 12 3.2.2 Read-Msg ............................................ 12 3.2.3 Delete-Msg .......................................... 12 3.2.4 Purge-Msg ........................................... 13 3.2.5 Reject-Msg .......................................... 13 3.2.6 Login ............................................... 13 3.2.7 Logout .............................................. 13 3.2.8 Update .............................................. 13 3.2.9 Mailbox-Full ........................................ 13 3.2.10 Account-Locked ..................................... 13 3.3 AccountLockGroup ........................................ 13 3.3.1 Account-Lock-Reason ................................. 13 3.4 MailboxGroup ............................................ 14 3.4.1 Email-Address (M) ................................... 14 3.4.2 Server-Name ......................................... 14 Shapira Informational - Expires September 2002 Page [2] Simple Notification and Alarm Protocol (SNAP) February 2002 3.5 MessageGroup ............................................ 14 3.5.1 Message-Context (M) ................................. 14 3.5.2 Msg-Sensitivity ..................................... 14 3.5.3 Message-Id .......................................... 14 3.5.4 From ................................................ 14 3.5.5 To .................................................. 14 3.5.6 CC .................................................. 15 3.5.7 Subject ............................................. 15 3.5.8 Message-Send-Time ................................... 15 3.5.9 Message-Receive-Time ................................ 15 3.5.10 Message-Size ....................................... 15 3.5.11 Attachment-Names ................................... 15 3.5.12 nAttachments ....................................... 15 3.5.13 Msg-Importance ..................................... 15 3.5.14 Body ............................................... 15 3.5.15 Delivery-Report-Msg ................................ 16 3.6 CountersGroup ........................................... 16 3.6.1 Total-Voice-Messages ................................ 17 3.6.2 Total-New-Voice-Messages ............................ 17 3.6.3 Total-New-Urgent-Voice-Messages ..................... 17 3.6.4 Total-Fax-Message ................................... 17 3.6.5 Total-New-Fax-Message ............................... 17 3.6.6 Total-New-Urgent-Fax-Message ........................ 17 3.6.7 Total-Email-Message ................................. 17 3.6.8 Total-New-Email-Message ............................. 17 3.6.9 Total-New-Urgent-Email-Message ...................... 17 3.7 RejectGroup ............................................. 17 3.7.1 Reject-Reason ....................................... 17 3.8 MailboxCapacityGroup .................................... 17 3.8.1 Mailbox-Capacity .................................... 17 3.8.2 Mailbox-Capacity-Threshold .......................... 18 3.8.3 Mailbox-Full-Status ................................. 18 4 Response .................................................... 18 4.1 Status Codes ............................................ 18 4.1.1 Informational (1xx) Status Codes .................... 18 4.1.2 Successful (2xx) Status Codes .................... 18 4.1.3 Redirection (3xx) Status Codes .................... 19 4.1.4 Client Error (4xx) Status Codes .................... 19 4.1.5 Server Error (5xx) Status Codes .................... 19 4.1.6 "404 Not Found" ..................................... 19 4.2 Request-Id .............................................. 20 4.3 Description ............................................. 20 5 Protocol Syntax ............................................. 20 5.1 Basic Rules ............................................. 20 5.2 Request Syntax .......................................... 20 5.2.1 General Attribute Syntax............................. 21 5.2.2 Attribute Groups .................................... 21 5.2.3 Attributes .......................................... 22 5.3 Response Syntax ......................................... 23 Shapira Informational - Expires September 2002 Page [3] Simple Notification and Alarm Protocol (SNAP) February 2002 5.4 Examples ................................................ 24 6 Security Considerations ..................................... 24 7 IANA Considerations ......................................... 25 8 References .................................................. 26 9 Acknowledgements ............................................ 27 10 Authors' Addresses ......................................... 27 A. Historical Overview of Notification Issue................... 28 B. List of changes from ..-01 version ......................... 28 C. List of changes from ..-02 version ......................... 28 Shapira Informational - Expires September 2002 Page [4] Simple Notification and Alarm Protocol (SNAP) February 2002 1. Introduction 1.1 Scope The suite of Internet mail protocols (POP3, IMAP4) allows different mail clients to access and manipulate electronic mail messages on a messaging system. These protocols do not provide off-line methods by which a user can be notified upon changes in the mailbox status. Further, none of the mentioned protocols define a way to aggregate the status within the user's various mailboxes. In order to provide a user with the ability of unified notification and one centralized message-waiting indication (MWI), a notification service is needed to aggregate the information of all the events occurring on the user's different messaging systems. This memo suggests a protocol in which a messaging system notifies a notification service of events occurring in a user's mailbox. For example, when a message is deposited (SMTP), the email server sends a "new message" notification to the service, which may then notify the user by sending him a Short Text Message (SMS). The following figure depicts the SNAP scope: +--------+ +--------+ New | | | | Message | Email | \ | SMS | -------> |Server 1| \ _ | | +--------+ \ /| +--------+ ^ \ / | \ / | \ / +--------+ | _|+--------------+ / +-----------+ Read | Voice | | | |/ |Message | Message | Mail |-------->| Notification |------->|Waiting | -------> | Server | | ^ _ | Service |\ |Indication | +--------+ | | /| +--------------- \ +-----------+ | |/ \ | / ^ \ |/| | \ +--------+ / | | \ +--------+ Delete | | /| | | \ | | Message | Email |/ | | | _|| WAP | -------> |Server 2| | | | | Push | +--------+ | | | +--------+ | | | | | | SNAP Shapira Informational - Expires September 2002 Page [5] Simple Notification and Alarm Protocol (SNAP) February 2002 This can be extended to include other mailbox events that are of importance to a user, such as "mailbox full" and "message rejected". Each notification should include additional information that is available to the user such as the number of messages in the mailbox, mailbox quota, and MIME headers of incoming messages. 1.2 Terminology 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 [KEYWORDS]. This specification uses the following terms: Message Waiting Indication (MWI) A mechanism that indicates to the user that a message is waiting in a mailbox. The MWI can be indicated by SMS icon, telephony stutter tone, MWI lamp on the phone, etc. The MWI has two states: ON or OFF. Notification Event An event that might cause a notification to the user or change the MWI state (ON or OFF). Messaging System A system that maintains a set of one or more mailboxes for user's messages, for example: Email servers, Voice-mail systems, etc. The messaging system is the application that initiates the SNAP session. Notification Service A system that is responsible for aggregating all Notification Events from the different Messaging Systems, and sends them to the user. The messaging system will use the SNAP to send Notification Events to the Notification service. Notification Protocol A protocol that describes how to pass Notification Event information from the Messaging System to the Notification Service. This memo will propose the SNAP as a Notification Protocol. The Messaging System is referred to as the "Source" of the notification and the Notification Service as the "Service". In client/server terms, the Source is the client and the Service is the server. Shapira Informational - Expires September 2002 Page [6] Simple Notification and Alarm Protocol (SNAP) February 2002 1.3 Notification Protocol High level requirements This section will describe the major requirements from a Notification Protocol and will serve as a basis for the design of the SNAP. 1.3.1 Informative The Notification Protocol should be informative enough to allow the Notification Service to: - Identify the person that should be informed on the mailbox status change. - Decide if the Notification Event is interesting enough for the user. This will enable the service provider and the end user to personalize the notification behavior for each user. For example, the user of the Notification Service can decide to be notified only on receipt of a message from a specific person, or with a specific subject. - Practice different MWI behaviors (e.g. turn MWI indication off after all the messages in all the user's mailboxes have been read). 1.3.2 Minimum latency The latency between the original time of the Notification Event and the time the end user receives the notification depends on various network elements taking part in the notification process. The Notification Protocol should enable the Messaging System to inform the Notification Service as soon as possible to help minimize notification latency. 1.3.3 Scalability The Notification Protocol should assume that it will be applied in large scale systems including one or more messaging systems and a notification service. 1.4 Organization of This Document This document tries to separate it's three main issues: - Protocol flow (covered in section 2) covers the underlying transport protocol (HTTP) and the request flow. - Protocol semantics covers the request payload (section 3) and the response payload (section 4) semantics. - Protocol syntax (covered in section 5) covers the payload, defined in section 3 and 4, syntax. Shapira Informational - Expires September 2002 Page [7] Simple Notification and Alarm Protocol (SNAP) February 2002 2. Basic Operation The Messaging System notifies a Notification Service of events occurring (Notification Events) in a user's mailbox. A Messaging System can be roughly broken down into the following processes: Message Deposit process- a message is deposited in a user's mailbox. In this case, if the deposit is successful, the Messaging System will send a "new message" request to the Notification Service. The request will include partial MIME headers of the incoming message. If the new message was rejected, the Messaging System will send a "message reject" request. An example of a process like this is the SMTP process in email servers. Mailbox manipulation process - Handles user's interaction with mailbox. The process sends requests when a user logs in, logs out, reads a message, or deletes a message. These requests will help the service to hold email counters and operate the Message Waiting Indication (MWI) mechanism. For example userĘs login can trigger notification event that will eventually turn MWI off. An example of a process like this is the IMAP4 process in email servers. Management process - purges old messages, locks a mailbox if it has exceeded its quota, etc. The management process sends "purge message", "mailbox full", and "account locked" requests. The above breakdown serves to illustrate the flow and is not part of the suggested protocol. The syntax of each request is described later in the memo. The SNAP will use a request/response model protocol to transfer the information between the Messaging System and the Notification service. The Notification Service "listens" for notification requests. When a request is accepted, it is processed and a response is returned. 2.1 The Transport Layer The suggested protocol uses HTTP as an underlying transport layer. The messaging system sends a HTTP request with the POST method. The notification service replies with a HTTP response. A great deal of thought has been spent on choosing the correct underlying transport protocol. HTTP has been chosen as it is widely deployed over the net and provides the needs of the notification protocol - as described in section 1.3 in this document. Shapira Informational - Expires September 2002 Page [8] Simple Notification and Alarm Protocol (SNAP) February 2002 2.1.1 HTTP Compliance The source and the service MUST comply with HTTP 1.1 as described in [RFC-HTTP]. 2.1.2 HTTP Method The source MUST use the HTTP POST method in the request. 2.1.3 Request URI The Uniform Resource Identifiers (URI) sent by the source to the service MUST be agreed by the Messaging Server and the Notification Service. The URI MUST comply with [RFC-URI]. 2.1.4 Request Payload The source MUST pass the request payload in the HTTP body as described in [RFC-HTTP]. The payload will be a set of MIME like field-value pairs. The source MUST use the HTTP Content-type value: text/SNAP in the request. The request payload will be described in section 3. Section 5 will describe the payload syntax. 2.1.5 Charset and Encoding The source MUST send a charset header if the protocol fields are not in the ISO-8859-1 char set as described in [RFC-HTTP]. The source MAY specify parameter values in character sets other than US-ASCII as specified in [RFC-2184]. 2.1.6 Response Payload The service MUST send a response using the HTTP response standard error codes. The response payload MUST be passed by the HTTP body as described in [RFC-HTTP]. The service MUST use the HTTP Content-type value: text/SNAP in response. Section 4 describes the response payload. Section 5 describes the response syntax. Shapira Informational - Expires September 2002 Page [9] Simple Notification and Alarm Protocol (SNAP) February 2002 2.1.7 Persistent Connections The underlying transport may support sending multiple requests over the same connection. The Notification Service MUST support persistent connections and use them upon source requests. The motivation for this is that Notification Service is assumed to be handling large amount of requests and this will significantly optimize its operation. 2.2 Request Flow 2.2.1 Request Order The source SHOULD send the requests to the service in the same order as the events that triggered them occurred. This will help to keep a consistent behavior. For example: if there are two notifications events, one indicating the user has one new message and the second indicating there are two new messages, the user must receive the first before the second. This will be completed my a request time stamp that will help the service maintain the consistent behavior. See Request-Time attribute. 2.2.2 Coherence The source MUST send a request only after the action has been successfully completed. For example, "new message" notification MUST be sent only after the message has been deposited in the user mailbox. 2.2.3 Response Upon receiving a request, the service MUST return a response including a status code. The source SHOULD parse the response to retrieve the error code and determine success or failure of the request. 2.2.4 Retries Upon receiving a response from the service indicating a failure, the source SHOULD retry the request in case the service failure is recoverable (i.e. temporary). If the source does not receive a response from the service, it SHOULD retry as well. Shapira Informational - Expires September 2002 Page [10] Simple Notification and Alarm Protocol (SNAP) February 2002 Section 4 describes the different possible responses and gives general guidelines regarding which responses should result in a retry. 2.2.5 Pipelining The source SHOULD pipeline requests according to [RFC-HTTP] part 8.1.2. If the source pipelines requests, the service SHOULD send its responses in the same order in which they where received. 3. Request Each Request includes a Header and a Body. Each of them consists of pairs of fields and values. This section describes the semantics of these attributes. Section 5 describes the attributes' syntax. Each request MUST include a protocol header. One of the attributes in the protocol header is the Request-Type. The Request-Type value describes an event that triggered the request (for example "NewMessage") and which additional attributes are included in the request body. The additional attributes are grouped. The groups and attributes in each group are listed in this section. Mandatory attributes in each group are marked with (M). Mandatory groups tied to a request type are also marked with (M). If a group is mandatory for a request type , the mandatory attributes of the group MUST appear in the request. The source MUST send all mandatory attributes as described below: 3.1 Protocol Header The header consists of the following attributes: 3.1.1 Notification-Protocol-Version (M) The version of this protocol MUST be 1.0. 3.1.2 Application-Name (M) The name of the source sending the request. This name identifies the source and need not be unique. 3.1.3 Application-Version (M) The version of the application sending the request. Shapira Informational - Expires September 2002 Page [11] Simple Notification and Alarm Protocol (SNAP) February 2002 3.1.4 Server-Type (M) The type of server sending the request. Source MUST send either "EMAIL" or "VOICE" in this field. In the future the protocol may be extended to add other values. 3.1.5 Request-Type (M) A string specifying the type of the request. Request types are listed in section 3.2. 3.1.6 Request-Time The time the request was sent by the source. Value MUST be in GMT. 3.1.7 Request-Id A unique identifier used by the source of the request to identify the request. This MAY be an incremental counter or a text value. The source SHOULD set the Request-Id attribute if it is pipelining in order to retry failed requests, since the order of responses is not guaranteed. The source is RECOMMENDED to set this attribute for debugging and logging purposes. 3.2 Request Types This section describes the trigger for sending each request type and lists the groups of attributes that SHOULD appear in the request. 3.2.1 New-Msg Trigger: A new message has been deposited in the user's mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. 3.2.2 Read-Msg Trigger: User reads a message from his mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. 3.2.3 Delete-Msg Trigger: User deletes a message from mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. Shapira Informational - Expires September 2002 Page [12] Simple Notification and Alarm Protocol (SNAP) February 2002 3.2.4 Purge-Msg Trigger: Messaging System purges a message from mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. 3.2.5 Reject-Msg Trigger: Messaging System rejects a message destined to a user. Groups: MailboxGroup(M) ,MessageGroup(M), RejectGroup, CountersGroup. 3.2.6 Login Trigger: User logs into mailbox. Groups: MailboxGroup(M) , CountersGroup. 3.2.7 Logout Trigger: User logs out of mailbox. Groups: MailboxGroup(M) , CountersGroup. 3.2.8 Update Trigger: An event has occurred in the mailbox but Messaging System is unaware of the event type. Groups: MailboxGroup(M) ,MessageGroup, CountersGroup. 3.2.9 Mailbox-Full Trigger: The user mailbox has exceeded its threshold quota. Groups: MailboxGroup(M) , CountersGroup, MailboxCapacityGroup. 3.2.10 Account-Locked Trigger :The user mailbox has been locked for administrative reasons. Groups : MailboxGroup(M) , CountersGroup, AccountLockGroup. 3.3 AccountLockGroup 3.3.1 Account-Lock-Reason A string containing a description of the lock reason. Shapira Informational - Expires September 2002 Page [13] Simple Notification and Alarm Protocol (SNAP) February 2002 3.4 MailboxGroup 3.4.1 Email-Address (M) The fully qualified email address for the mailbox. 3.4.2 Server-Name The name of the host the source is running on. 3.5 MessageGroup 3.5.1 Message-Context (M) The message context is used by the service to enable the end user to define different behaviors for different message types. This attribute must comply with the Message-Context as defined in [HINT]. 3.5.2 Msg-Sensitivity The message content sensitivity as seen by the sender. The legal values are Personal, private, company confidential as defined in [HEADER]. The absence of this header field in the request will indicate that the message is not sensitive. 3.5.3 Message-Id Unique identifier that can be used by the Notification Service or any other user agent (UA) to retrieve the message. The message id should comply with [RFC-2822]. The Message-Id MUST persist across sessions in the source, in order to allow the UA to retrieve the message at any time. In case where the source is an Email Server, the source SHOULD send the IMAP4 UID [RFC-IMAP4]. 3.5.4 From The message "From" header as in [RFC-2822]. 3.5.5 To The message "To" header as in [RFC-2822]. Shapira Informational - Expires September 2002 Page [14] Simple Notification and Alarm Protocol (SNAP) February 2002 3.5.6 CC The message "cc" header as in [RFC-2822]. 3.5.7 Subject The message "Subject" header as in [RFC-2822]. 3.5.8 Message-Send-Time The time the message has been sent as described in the message. This MAY be the value of the Date header as defined in [RFC-2822]. 3.5.9 Message-Receive-Time The time the message was received in the source expressed in GMT. This MAY be the value of the IMAP4 Internal Date Message Attribute as defined in [RFC-IMAP4] 3.5.10 Message-Size A number that indicates the message size in bytes. If there are attachments to the message, the size SHOULD include the size of the attachments. 3.5.11 Attachment-Names A comma-separated list of possible filenames extracted from the Content-Disposition header [RFC-2183]. 3.5.12 nAttachments The number of attachments as described above. 3.5.13 Msg-Importance Importance of message as described in [HEADER] - Importance is a user-presentation attributes intended to convey the senders sense of importance of the message to the recipient. Legal values are 'high', 'low' or 'normal'. 3.5.14 Body The source SHOULD send the body of the MIME message in certain requests as described later. When doing so, the following apply: Shapira Informational - Expires September 2002 Page [15] Simple Notification and Alarm Protocol (SNAP) February 2002 The source MUST copy the Content-Type header from the MIME message to the request header. The source MUST NOT send the body if the Content-Type is not "text". All text subtypes are allowed. The source MAY send only part of the body (for example the first 100 octets). The source MUST add a Content-Length header to the request specifying the size of the body. 3.5.15 Delivery-Report-Msg If the message received is a DSN or a MDN, a string with value Yes. See RFC [RFC-DSN] and [RFC-MDN] 3.6 CountersGroup The counter group includes the count of messages in the user's mailbox according to categories. The categories are type (as defined in Message-Context), Freshness (New or not) and Urgency (Urgent or not). A message is considered fresh if its unseen flag is true. It is considered Urgent if the Msg-Importance attribute as described in the MessageGroup is "high". Categorization to type is done with accordance to the email Message-Context attribute as described in the MessageGroup. The value of each counter MUST be 0 or higher; or (-1) CAN be used if value is unknown. Following are a set of pre-defined counter types. The pre-defined types are for Email, Voice and Fax messages. Each one is mapped to a different Message-Context value: - Email - "text-message" - Voice - "voice-message" - Fax - "fax-message" Other counters (for other types of Message-Context) may be added as following: - Total-X - Total-New-X - Total-New-Urgent-X Where X is a known Message-context as defined later in this document. Shapira Informational - Expires September 2002 Page [16] Simple Notification and Alarm Protocol (SNAP) February 2002 3.6.1 Total-Voice-Messages Total number of voice messages in mailbox. 3.6.2 Total-New-Voice-Messages Number of new voice messages in mailbox. This includes messages that are new and urgent. 3.6.3 Total-New-Urgent-Voice-Messages Number of new urgent voice messages in mailbox. 3.6.4 Total-Fax-Message Total number of fax messages in mailbox. 3.6.5 Total-New-Fax-Message Number of new fax messages in mailbox. This includes messages that are new and urgent. 3.6.6 Total-New-Urgent-Fax-Message Number of new urgent fax messages in mailbox. 3.6.7 Total-Email-Message Total number of email messages in mailbox. 3.6.8 Total-New-Email-Message Number of new email messages in mailbox. This includes messages that are new and urgent. 3.6.9 Total-New-Urgent-Email-Message Number of new urgent email messages in mailbox. 3.7 RejectGroup 3.7.1 Reject-Reason A string containing a description of the reject reason. 3.8 MailboxCapacityGroup 3.8.1 Mailbox-Capacity Actual usage percentage of user's mailbox. Shapira Informational - Expires September 2002 Page [17] Simple Notification and Alarm Protocol (SNAP) February 2002 3.8.2 Mailbox-Capacity-Threshold Usage percentage threshold of user's mailbox. If Mailbox-Capacity > Mailbox-Capacity-Threshold --> Mailbox is full. This is also the default if one (or both) of these attributes are not part of the request. If Mailbox-Capacity <= Mailbox-Capacity-Threshold --> Mailbox was full, but it is not full any more (capacity is now below threshold) 3.8.3 Mailbox-Full-Status The mailbox full status attribute SHOULD be used to describe the implications of the fact that the mailbox is full, e.g. "Message retrieval disabled" or "No more messages can be stored in the mailbox". 4. Response The service MUST send a response for each request. The response MUST include a standard status code [RFC-HTTP]. The service MAY use proprietary status codes, as long as they comply with the standard classification of status codes according to their numbering convention. The syntax of the response in ABNF is listed in section 5. 4.1 Status Codes 4.1.1 Informational (1xx) Status Codes The service SHOULD not send any informational status codes. The source MUST ignore all informational status codes sent by the service. 4.1.2 Successful (2xx) Status Codes The service SHOULD return "200 Ok" status code if request succeeded. The service MAY return additional success (2xx) codes. After receiving a successful status code, the source MUST NOT perform retries. Shapira Informational - Expires September 2002 Page [18] Simple Notification and Alarm Protocol (SNAP) February 2002 4.1.3 Redirection (3xx) Status Codes 4.1.3.1 "301 Moved Permanently" Upon receiving this status code, the source MUST resend the notification request to the new URI specified in the location field of the response. When sending other requests after receiving this response, the source SHOULD use the new URL that is part of the URI returned in the "location" field. 4.1.3.2 "307 Temporary Redirect" Upon receiving this status code, the source MUST resend the request to the new URI specified in the location field of the response. The source MUST NOT change its behavior when sending future requests. 4.1.4 Client Error (4xx) Status Codes The service MUST send a client error status code when it finds out that the request format or content are illegal. The service SHOULD use the "400 Bad Request" status code, but MAY also use other (including proprietary) client error status codes. The source MUST NOT perform retries upon receiving one of these status codes as a reply. 4.1.5 Server Error (5xx) Status Codes The service MUST return a server error status code when it fails to process the request due to some internal error. The service SHOULD use the "500 Internal Server Error" status code, but MAY also use other (including proprietary) server error status codes. Upon receiving any server error status code, the source SHOULD perform retries. 4.1.6 "404 Not Found" The service MUST NOT return a "404 Not Found" status code. The HTTP server will return this status code when it cannot find the service. The source MUST treat this error as if it were a Server error par 4.1.5 above). Shapira Informational - Expires September 2002 Page [19] Simple Notification and Alarm Protocol (SNAP) February 2002 4.2 Request-Id The service MUST send the Request-Id if available as part of the original request. 4.3 Description The response MAY include additional text description. 5. Protocol Syntax Section 2 describes the interaction with the underlying transport protocol. Section 3 described the semantics of each attribute in the header and the body of the request. Section 4 described the semantics of each attribute in the response. This section will describe the syntax of the request and the response. The section uses the [RFC-ABNF] syntax. 5.1 Basic Rules The following rules are defined in [RFC-HTTP] OCTET = CHAR = UPALPHA = LOALPHA = ALPHA = UPALPHA | LOALPHA DIGIT = CTL = CR = LF = SP = HT = <"> = token = 1* phrase = * SNAP is a case insensitive in all attributes and values - unless specified otherwise. 5.2 Request Syntax The SNAP request from a source to a service is composed of a header and a body. SNAP-Request = ProtocolHeader ProtocolBody Shapira Informational - Expires September 2002 Page [20] Simple Notification and Alarm Protocol (SNAP) February 2002 A protocol body is composed of a set of one or more Attribute groups as defined in section 3. ProtocolBody = 1*AttributeGroup 5.2.1 General Attribute Syntax Header and body attributes are lines composed in the same manner as in [RFC-2822]: :CRLF Attribute-value can be in different charset and encoding as described in sub-section 2.1.2. 5.2.2 Attribute Groups ProtocolHeader = Notification-Protocol-Version Application-Name Application-Version Server-Type Request-Type [Request-Time] [Request-Id] AttributeGroup = MailboxGroup | MessageGroup | CountersGroup | RejectGroup | MailboxCapacityGroup | AccountLockGroup MessageGroup = Message-Context [From] [To] [CC] [Subject] [Message-Send-Time] [Message-Receive-Time] [Message-Size] [Body] [Attachment-Names] [nAttachments] [Msg-Importance] [Msg-Sensitivity] [Message-Id] [Delivery-Report-Msg] Shapira Informational - Expires September 2002 Page [21] Simple Notification and Alarm Protocol (SNAP) February 2002 MailboxGroup = Email-Address [Server-Name] CountersGroup = [Total-Voice-Messages] [Total-New-Voice-Messages] [Total-New-Urgent-Voice-Messages] [Total-Fax-Message] [Total-New-Fax-Message] [Total-New-Urgent-Fax-Message] [Total-Email-Message] [Total-New-Email-Message] [Total-New-Urgent-Email-Message] [Other-Counter] RejectGroup = [Reject-Reason] MailboxCapacityGroup = [Mailbox-Capacity] [Mailbox-Capacity-Threshold] [Mailbox-Full-Status] AccountLockGroup = [Account-Lock-Reason] 5.2.3 Attributes Following is the list of attributes and their valid values. The list is constructed from: = ";" Notification-Protocol-Version = 1*DIGIT "."1*DIGIT Application-Name = token Application-Version = token Server-Type = "EMAIL"|"VOICE" Request-Type = "New-Msg" | "Read-Msg" | "Delete-Msg" | "Purge-Msg" | "Reject-Msg" | "login" | "logout" | "update" | "Mailbox-Full" | "Account-Locked" mailbox = As defined in "Address Specification" in [RFC-2822] Email-Address = mailbox From = mailbox To = mailbox CC = mailbox SubscribrerId = token Server-Name = token Message-Context = as defined in [HINT]. Subject = token ;as described by [RFC-2822] Shapira Informational - Expires September 2002 Page [22] Simple Notification and Alarm Protocol (SNAP) February 2002 date-time = As defined in "Date and Time Specification" [RFC-2822] Request-Time = datetime Message-Send-Time = datetime Message-Receive-Time = datetime Message-Size = *DIGITS Body = Token Attachment-Names = Token 1*[","Token] nAttachments = *DIGITS Msg-Importance = "high" | "normal" |"low" ; see [HEADER] Msg-Sensitivity = "Personal" | "Private" | "Company-Confidential" ; see [HEADER] Message-Id = token Delivery-Report-Msg = "Yes"|"No" counter = "-1" | *DIGIT Total-Voice-Messages = counter Total-New-Voice-Messages = counter Total-New-Urgent-Voice-Messages= counter Total-Fax-Message = counter Total-New-Fax-Message = counter Total-New-Urgent-Fax-Message = counter Total-Email-Message = counter Total-New-Email-Message = counter Total-New-Urgent-Email-Message = counter Other-Counter = "Total-" Message-Context | "Total-New-" Message-Context | "Total-New-Urgent-" Message-Context Note: Message-Context in Other-Counter - MUST not be one of the following: "voice-message", "fax-message" or "text-message" as they are predefined counters. percentage = ("0".."100") Mailbox-Capacity = percentage Mailbox-Capacity-Threshold = percentage Reject-Reason = phrase Mailbox-Full-Status = phrase Account-Lock-Reason = phrase 5.3 Response Syntax Response = 1Status-Line *1Request-Id-Line *1Description-Line Status-Line = Protocol-Version SP Status-Code SP Reason-Phrase CRLF Protocol-Version = "Protocol Name" "/" 1*DIGIT "." 1*DIGIT Status-Code = "1" 2*DIGIT | "2" 2*DIGIT |"3" 2*DIGIT |"4" 2*DIGIT |"5" 2*DIGIT Reason-Phrase = * Request-Id = * Request-Id-Line = "REQUEST-ID:" *WS 1*request-id *WS CRLF Description-Line = * Shapira Informational - Expires September 2002 Page [23] Simple Notification and Alarm Protocol (SNAP) February 2002 5.4 Examples: Request example: POST /Notification-Service/notif.cgi HTTP/1.1 ;The URI Content-Type: text/SNAP; ;From HTTP charset="utf-8" ;From HTTP Content-Length: nnnn ;From HTTP Notification-Protocol-Version:1.1 Application-Name:Applic Application-Version:1.0 Server-Type:Email Request-Type:New-Msg Request-Time:15Feb2000%2012:02:00%20+0000 Request-Id:9941401AA Message-Context:text-message ;Indicate email Message-Id:9999 Email-Address:joe@email.com Server-Name:ES1 Total-Email-Message:20 Total-New-Email-Message:20 Message-Send-Time:15Feb2000%2012:02:00%20+0000 Message-Receive-Time:15Feb2000%2012:02:00%20+0000 Message-Size:20000 Msg-Importance:high From:Budd@email.com To:joe@email.com Subject:Hello%20Joe Response example (1): HTTP/1.1 200 OK CRLF Request Id: 9941401AA CRLF Request processed successfully CRLF 6. Security Considerations The SNAP describes a server-to-server protocol (Messaging Server and a Notification Server). The protocol defines the means by which the Notification Service will receive the event information and trigger a notification message / action to the user. Following is a set of threats implementers MUST take in consideration when defining the integration between the Messaging Server and the Notification Service: Shapira Informational - Expires September 2002 Page [24] Simple Notification and Alarm Protocol (SNAP) February 2002 6.1 Denial of Service (DoS) SNAP defines the way by which a Messaging System passes the information to the Notification Service. DoS attack, might prevent a user from receiving a notification message by overloading the notification server. The possible countermeasures include: validating the notification request before processing it, limiting the number of notification requests from a single store, etc. 6.2 IP Spoofing As SNAP's payload holds private user's data, message data and mailbox data, IP spoofing may cause an attack on the user's privacy. 6.3 Impersonation A Messaging System impersonation might cause the Notification Service to send notification messages on events that did not occur. 6.4 Network Snooping Packet sniffing on the SNAP payload may impose a threat on the user's privacy. The SNAP's payload SHOULD be secured in order to prevent network snooping. 7. IANA Considerations This specification calls for the registration of the new MIME content-type text/SNAP. The registration template: To: ietf-types@iana.org Subject: Registration of MIME media type text/SNAP MIME media type name: text MIME subtype name: SNAP Required parameters: See section 3 defined mandatory parameters Optional parameters: See section 3 defined non-mandatory parameters Encoding considerations: None Security considerations: None Shapira Informational - Expires September 2002 Page [25] Simple Notification and Alarm Protocol (SNAP) February 2002 Interoperability considerations: None Published specification: This draft Applications which use this media type: Messaging System and Notification Services as defined in this draft. Additional information: Magic number(s): None File extension(s): None Macintosh File Type Code(s): None Person & email address to contact for further information: Noam Shapira: noam.shapira@comverse.com Intended usage: Common Author/Change controller: noam.shapira@comverse.com 8. References [RFC-HTTP] Fielding, et al, "Hypertext Transfer Protocol HTTP/1.1", RFC 2616, June 1999 [RFC-MIME1] Freed, N., and Borenstein, N., "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996. [RFC-2822] P. Resnick, "Internet Message Format", RFC 2822, April 2001 [RFC-ABNF] Crocker, D., Editor, and Overell, P., "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC-URI] Berners-Lee, T., Fielding, R., and Masinter, L., "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. Shapira Informational - Expires September 2002 Page [26] Simple Notification and Alarm Protocol (SNAP) February 2002 [RFC-2183] Troost, R., Dorner, S., and Moore, K., "Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field", RFC 2183,August 1997. [RFC-2184] Freed, N., and Moore, K., "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations", RFC 2184, August 1997. [RFC-IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4rev1", RFC 2060, University of Washington, December 1996. [HINT] E. Burger, E. Candell, C. Eliot, G. Klyne, "Message Context for Internet Mail", draft - draft-ietf-vpim-hint-07.txt [HEADER] Jacob Palme, "Common Internet Message Header Fields", draft-palme-mailext-headers-06.txt [RFC-DSN] K. Moore, G. Vaudreuil, "An Extensible Message Format for Delivery Status Notifications", RFC 1894, January 1996 [RFC-MDN] R. Fajman, "An Extensible Message Format for Message Disposition Notifications", RFC 2298, March 1998 9. Acknowledgements The authors wish to acknowledge the following people who helped in the development of this draft: The participants in SNAP mailing list who contributed to SNAP formation, the VPIM working group for both hosting a discussion on SNAP and providing very important insights. In particular Greg Vaudreuil from Lucent Technologies, who contributed some very useful advice and Glenn Parsons, VPIM WG Chair who facilitated and contributed to this activity. The authors also wish to acknowledge the following colleagues from Comverse Technology for advising and reviewing the draft: Erez Reinshmidt, Ari Erev, John Neystadt, Olga Elin, Arie Levy, Asaf Barak, Eli Jacobi, Dmitry Rubinstein and Rami Neudorfer. 10. Authors' Addresses Noam Shapira Comverse Technology 29 Habarzel st. Tel-Aviv Israel Phone: +972-3-7663605 Fax: +972-3-6454866 EMail: noam.shapira@comverse.com Shapira Informational - Expires September 2002 Page [27] Simple Notification and Alarm Protocol (SNAP) February 2002 Appendix A. Historical Overview of Notification Issue. During previous years and even now there were a number of proposals in IETF regarding Notification. It is possible to retrieve the documentation information from the following documents: draft-roach-sip-subscribe-notify draft-ietf-sip-events draft-martin-sieve-notify draft-mahy-sip-message-waiting draft-khare-notification (ISENS at 1998) draft-nerenberg-sin-framework draft-nerenberg-sin-imap All these documents were considered in the drafting of this proposal. Appendix B. List of changes from ..-01 version Following are the changes: - Added Notification Protocol High level requirements. - Better define the SNAP scope and the document structure. - Bind the SNAP with HTTP. - Chosen a new format for the SNAP - 2822 like. - Added Security and IANA considerations. - Extended the terminology section - Make sure that time attributes are compatible to [RFC-2822]. - Changed MessageType to Message-Context - compatible to [HINT]. - Changed MsgPriority to Msg-Importance Appendix C. List of changes from ..-02 version Following are the changes: - In 2.2.4 Added retry as a result of no response. - Counters: Better define the categorizing and add the ability to add new counters. - Added that SNAP is case insensitive. - Added dash to names (e.g. RequestType to Request-Type). - Removed GMT requirement from Message-Send-Time - Removed MIXER reference and changed to draft-palme-mailext-headers-06.txt. - In 2.2.1 Request Order: Changed from MUST to SHOULD. Shapira Informational - Expires September 2002 Page [28]