Simple Notification and Alarm Protocol (SNAP) December 2001 Internet Draft Noam Shapira Document: draft-shapira-snap-02 Nir Flatau Category: Informational Eran Aloni Expires: May 20, 2002 Comverse Technology December, 20 2001 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 May 2002 Page [1] Simple Notification and Alarm Protocol (SNAP) December 2001 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 NotificationProtocolVersion (M) ..................... 11 3.1.2 ApplicationName (M) ................................. 11 3.1.3 ApplicationVersion (M) .............................. 11 3.1.4 ServerType (M) ...................................... 11 3.1.5 RequestType (M) ..................................... 12 3.1.6 RequestTime ......................................... 12 3.1.7 RequestId ........................................... 12 3.2 Request Types ........................................... 12 3.2.1 NewMsg .............................................. 12 3.2.2 ReadMsg ............................................. 12 3.2.3 DeleteMsg ........................................... 12 3.2.4 PurgeMsg ............................................ 12 3.2.5 RejectMsg ........................................... 13 3.2.6 Login ............................................... 13 3.2.7 Logout .............................................. 13 3.2.8 Update .............................................. 13 3.2.9 MailboxFull ......................................... 13 3.2.10 AccountLocked ...................................... 13 3.3 AccountLockGroup ........................................ 13 3.3.1 AccountLockReason ................................... 13 3.4 MailboxGroup ............................................ 14 3.4.1 EmailAddress (M) .................................... 14 3.4.2 ServerName .......................................... 14 Shapira Informational - Expires May 2002 Page [2] Simple Notification and Alarm Protocol (SNAP) December 2001 3.5 MessageGroup ............................................ 14 3.5.1 Message-Context (M) ................................. 14 3.5.2 MsgSensitivity ...................................... 14 3.5.3 MessageId ........................................... 14 3.5.4 From ................................................ 14 3.5.5 To .................................................. 14 3.5.6 CC .................................................. 15 3.5.7 Subject ............................................. 15 3.5.8 MessageSendTime ..................................... 15 3.5.9 MessageReceiveTime .................................. 15 3.5.10 MessageSize ........................................ 15 3.5.11 AttachmentNames .................................... 15 3.5.12 nAttachments ....................................... 15 3.5.13 MsgImportance ...................................... 15 3.5.14 Body ............................................... 16 3.5.15 DeliveryReportMsg .................................. 16 3.6 CountersGroup ........................................... 16 3.6.1 nVoiceMessages ...................................... 16 3.6.2 nNewVoiceMessages ................................... 16 3.6.3 nNewUrgentVoiceMessages ............................. 17 3.6.4 nFaxMessages ........................................ 17 3.6.5 nNewFaxMessages ..................................... 17 3.6.6 nNewUrgentFaxMessages ............................... 17 3.6.7 nEmailMessages ...................................... 17 3.6.8 nNewEmailMessages ................................... 17 3.6.9 nNewUrgentEmailMessages ............................. 17 3.7 RejectGroup ............................................. 17 3.7.1 RejectReason ........................................ 17 3.8 MailboxCapacityGroup .................................... 17 3.8.1 MailboxCapacity ..................................... 17 3.8.2 MailboxCapacityThreshold ............................ 17 3.8.3 MailboxFullStatus ................................... 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 .................... 18 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 .............................................. 19 4.3 Description ............................................. 19 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 May 2002 Page [3] Simple Notification and Alarm Protocol (SNAP) December 2001 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 Shapira Informational - Expires May 2002 Page [4] Simple Notification and Alarm Protocol (SNAP) December 2001 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 May 2002 Page [5] Simple Notification and Alarm Protocol (SNAP) December 2001 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 May 2002 Page [6] Simple Notification and Alarm Protocol (SNAP) December 2001 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 May 2002 Page [7] Simple Notification and Alarm Protocol (SNAP) December 2001 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 May 2002 Page [8] Simple Notification and Alarm Protocol (SNAP) December 2001 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 May 2002 Page [9] Simple Notification and Alarm Protocol (SNAP) December 2001 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 MUST send the requests to the service in the same order as the events that triggered them occurred. This ensures 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. 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). Section 4 describes the different possible responses and gives general guidelines regarding which responses should result in a retry. Shapira Informational - Expires May 2002 Page [10] Simple Notification and Alarm Protocol (SNAP) December 2001 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 RequestType. The value of RequestType 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 NotificationProtocolVersion (M) The version of this protocol MUST be 1.0. 3.1.2 ApplicationName (M) The name of the source sending the request. This name identifies the source and need not be unique. 3.1.3 ApplicationVersion (M) The version of the application sending the request. 3.1.4 ServerType (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. Shapira Informational - Expires May 2002 Page [11] Simple Notification and Alarm Protocol (SNAP) December 2001 3.1.5 RequestType (M) A string specifying the type of the request. Request types are listed in section 3.2. 3.1.6 RequestTime The time the request was sent by the source. Value MUST be in GMT. 3.1.7 RequestId 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 RequestId 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 NewMsg Trigger: A new message has been deposited in the user's mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. 3.2.2 ReadMsg Trigger: User reads a message from his mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. 3.2.3 DeleteMsg Trigger: User deletes a message from mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. 3.2.4 PurgeMsg Trigger: Messaging System purges a message from mailbox. Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup. Shapira Informational - Expires May 2002 Page [12] Simple Notification and Alarm Protocol (SNAP) December 2001 3.2.5 RejectMsg 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 MailboxFull Trigger: The user mailbox has exceeded its threshold quota. Groups: MailboxGroup(M) , CountersGroup, MailboxCapacityGroup. 3.2.10 AccountLocked Trigger :The user mailbox has been locked for administrative reasons. Groups : MailboxGroup(M) , CountersGroup, AccountLockGroup. 3.3 AccountLockGroup 3.3.1 AccountLockReason A string containing a description of the lock reason. Shapira Informational - Expires May 2002 Page [13] Simple Notification and Alarm Protocol (SNAP) December 2001 3.4 MailboxGroup 3.4.1 EmailAddress (M) The fully qualified email address for the mailbox. 3.4.2 ServerName 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 MsgSensitivity The message content sensitivity as seen by the sender. The legal values are Personal, private, company confidential as defined in [MIXER]. The absence of this header field in the request will indicate that the message is not sensitive. 3.5.3 MessageId 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 MessageId 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 May 2002 Page [14] Simple Notification and Alarm Protocol (SNAP) December 2001 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 MessageSendTime 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]. The value MUST be converted to GMT. 3.5.9 MessageReceiveTime 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 MessageSize 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 AttachmentNames 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 MsgImportance Importance of message as described in [MIXER] - 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'. Shapira Informational - Expires May 2001 Page [15] Simple Notification and Alarm Protocol (SNAP) December 2001 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: 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 DeliveryReportMsg 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 (Voice, Fax or Email), 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 MsgImportance attribute as described in the MessageGroup is "high". Categorization to type is a proprietary vendor feature. The source SHOULD categorize all messages as Email messages. The value of each counter MUST be 0 or higher; or (-1) CAN be used if value is unknown. 3.6.1 nVoiceMessages Total number of voice messages in mailbox. 3.6.2 nNewVoiceMessages Number of new voice messages in mailbox. This includes messages that are new and urgent. Shapira Informational - Expires May 2002 Page [16] Simple Notification and Alarm Protocol (SNAP) December 2001 3.6.3 nNewUrgentVoiceMessages Number of new urgent voice messages in mailbox. 3.6.4 nFaxMessages Total number of fax messages in mailbox. 3.6.5 nNewFaxMessages Number of new fax messages in mailbox. This includes messages that are new and urgent. 3.6.6 nNewUrgentFaxMessages Number of new urgent fax messages in mailbox. 3.6.7 nEmailMessages Total number of email messages in mailbox. 3.6.8 nNewEmailMessages Number of new email messages in mailbox. This includes messages that are new and urgent. 3.6.9 nNewUrgentEmailMessages Number of new urgent email messages in mailbox. 3.7 RejectGroup 3.7.1 RejectReason A string containing a description of the reject reason. 3.8 MailboxCapacityGroup 3.8.1 MailboxCapacity Actual usage percentage of user's mailbox. 3.8.2 MailboxCapacityThreshold Usage percentage threshold of user's mailbox. If MailboxCapacity > MailboxCapacityThreshold --> Mailbox is full. This is also the default if one (or both) of these attributes are not part of the request. If MailboxCapacity <= MailboxCapacityThreshold --> Mailbox was full, but it is not full any more (capacity is now below threshold) Shapira Informational - Expires May 2002 Page [17] Simple Notification and Alarm Protocol (SNAP) December 2001 3.8.3 MailboxFullStatus 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. 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. Shapira Informational - Expires May 2002 Page [18] Simple Notification and Alarm Protocol (SNAP) December 2001 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). 4.2 RequestId The service MUST send the requestId if available as part of the original request. 4.3 Description The response MAY include additional text description. Shapira Informational - Expires May 2002 Page [19] Simple Notification and Alarm Protocol (SNAP) December 2001 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 = * 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 A protocol body is composed of a set of one or more Attribute groups as defined in section 3. ProtocolBody = 1*AttributeGroup Shapira Informational - Expires May 2002 Page [20] Simple Notification and Alarm Protocol (SNAP) December 2001 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 = NotificationProtocolVersion ApplicationName ApplicationVersion ServerType RequestType [RequestTime] [RequestId] AttributeGroup = MailboxGroup | MessageGroup | CountersGroup | RejectGroup | MailboxCapacityGroup | AccountLockGroup MailboxGroup = EmailAddress [ServerName] MessageGroup = Message-Context [From] [To] [CC] [Subject] [MessageSendTime] [MessageRecievedtime] [MessageSize] [Body] [AttachmentNames] [nAttachments] [MsgImportance] [MsgSensitivity] [ReplyRequested] [MessageId] [DeliveryReportMsg] Shapira Informational - Expires May 2002 Page [21] Simple Notification and Alarm Protocol (SNAP) December 2001 CountersGroup = [nVoiceMessages] [nNewVoiceMessages] [nNewUrgentVoiceMessages] [nFaxMessages] [nNewFaxMessages] [nNewUrgentFaxMessages] [nEmailMessages] [nNewEmailMessages] [nNewUrgentEmailMessages] RejectGroup = [RejectReason] MailboxCapacityGroup = [MailboxCapacity] [MailboxCapacityThreshold] [MailboxFullStatus] AccountLockGroup = [AccountLockReason] 5.2.3 Attributes Following is the list of attributes and their valid values. The list is constructed from: = ";" NotificationProtocolVersion = 1*DIGIT "."1*DIGIT ApplicationName = token ApplicationVersion = token ServerType = "EMAIL"|"VOICE" RequestType = "newmsg" | "readmsg" | "deletemsg" | "purgemsg" | "rejectmsg" | "login" | "logout" | "update" | "mailboxfull" | "accountlocked" mailbox = As defined in "Address Specification" in [RFC-2822] EmailAddress = mailbox From = mailbox To = mailbox CC = mailbox SubscribrerId = token ServerName = token Message-Context = as defined in [HINT]. Subject = token ;as described by [RFC-2822] Shapira Informational - Expires May 2002 Page [22] Simple Notification and Alarm Protocol (SNAP) December 2001 date-time = As defined in "Date and Time Specification" [RFC-2822] requestTime = datetime MessageSendTime = datetime MessageRecievedtime = datetime MessageSize = *DIGITS Body = Token AttachmentNames = Token 1*[","Token] nAttachments = *DIGITS MsgImportance = "high" | "normal" |"low" ; see [MIXER] MsgSensitivity = "Personal" | "Private" | "Company-Confidential" ; see [MIXER] MessageId = token DeliveryReportMsg = "Yes"|"No" counter = "-1" | *DIGIT nVoiceMessages = counter nNewVoiceMessages = counter nNewUrgentVoiceMessages= counter nFaxMessages = counter nNewFaxMessages = counter nNewUrgentFaxMessages = counter nEmailMessages = counter nNewEmailMessages = counter nNewUrgentEmailMessages = counter percentage = ("0".."100") MailboxCapacity = percentage MailboxCapacityThreshold = percentage RejectReason = phrase MailboxFullStatus = phrase AccountLockReason = 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 May 2002 Page [23] Simple Notification and Alarm Protocol (SNAP) December 2001 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 NotificationProtocolVersion:1.1 ApplicationName:Applic ApplicationVersion:1.0 ServerType:Email RequestType:NewMsg RequestTime:15Feb2000%2012:02:00%20+0000 RequestId:9941401AA Message-Context:text-message ;Indicate email MessageId:9999 EmailAddress:joe@email.com ServerName:ES1 nVoiceMessages:20 nNewVoiceMessages:20 MessageSendTime:15Feb2000%2012:02:00%20+0000 MessageRecieveTime:15Feb2000%2012:02:00%20+0000 MessageSize:20000 MsgImportance: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 May 2002 Page [24] Simple Notification and Alarm Protocol (SNAP) December 2001 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 May 2002 Page [25] Simple Notification and Alarm Protocol (SNAP) December 2001 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 May 2002 Page [26] Simple Notification and Alarm Protocol (SNAP) December 2001 [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 [MIXER ] S. Kille, "MIXER (Mime Internet X.400 Enhanced Relay): Mapping between X.400 and RFC 822/MIME", January 1998 [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 May 2002 Page [27] Simple Notification and Alarm Protocol (SNAP) December 2001 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 MsgImportance Shapira Informational - Expires May 2002 Page [28]