Simple Notification and Alarm Protocol (SNAP) November 2002
Internet Draft Noam Shapira
Document: draft-shapira-snap-05 Eran Aloni
Category: Informational Comverse Technology
Expires: May 1, 2003
November, 3 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 May 2003 Page [1]
Simple Notification and Alarm Protocol (SNAP) November 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.1.8 HTTP Port ........................................... 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 ............................................. 11
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) ............................. 12
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 .......................................... 13
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 ........................................ 14
3.3.1 Account-Lock-Reason ................................. 14
3.4 MailboxGroup ............................................ 14
3.4.1 Email-Address (M) ................................... 14
Shapira Informational - Expires May 2003 Page [2]
Simple Notification and Alarm Protocol (SNAP) November 2002
3.4.2 Server-Name ......................................... 14
3.4.3 Mailbox-Name ........................................ 14
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 ................................................ 15
3.5.5 To .................................................. 15
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 Msg-Importance ..................................... 15
3.5.12 Body ............................................... 15
3.5.13 Delivery-Report-Msg ................................ 16
3.6 CountersGroup ........................................... 16
3.6.1 Total-Voice-Message ................................. 17
3.6.2 Total-New-Voice-Message ............................. 17
3.6.3 Total-New-Urgent-Voice-Message ...................... 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.6.10 Total-Message ...................................... 17
3.6.11 Total-New-Message .................................. 17
3.6.12 Total-New-Urgent-Message ........................... 18
3.7 RejectGroup ............................................. 18
3.7.1 Reject-Reason ....................................... 18
3.8 MailboxCapacityGroup .................................... 18
3.8.1 Mailbox-Capacity .................................... 18
3.8.2 Mailbox-Capacity-Threshold .......................... 18
3.8.3 Mailbox-Full-Status ................................. 18
4 Response .................................................... 18
4.1 Status Codes ............................................ 19
4.1.1 Informational (1xx) Status Codes .................... 19
4.1.2 Successful (2xx) Status Codes .................... 19
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" ..................................... 20
4.2 Request-Id .............................................. 20
4.3 Description ............................................. 20
5 Protocol Syntax ............................................. 20
5.1 Basic Rules ............................................. 20
5.2 Request Syntax .......................................... 21
5.2.1 General Attribute Syntax............................. 21
5.2.2 Attribute Groups .................................... 21
5.2.3 Attributes .......................................... 23
Shapira Informational - Expires May 2003 Page [3]
Simple Notification and Alarm Protocol (SNAP) November 2002
5.3 Response Syntax ......................................... 24
5.4 Examples ................................................ 25
6 Security Considerations ..................................... 25
7 IANA Considerations ......................................... 26
8 References .................................................. 27
9 Acknowledgements ............................................ 28
10 Authors' Addresses ......................................... 28
A. Historical Overview of Notification Issue................... 29
B. List of changes from ..-01 version ......................... 29
C. List of changes from ..-02 version ......................... 29
D. List of changes from ..-03 version ......................... 30
E. List of changes from ..-04 version ......................... 30
Shapira Informational - Expires May 2003 Page [4]
Simple Notification and Alarm Protocol (SNAP) November 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 May 2003 Page [5]
Simple Notification and Alarm Protocol (SNAP) November 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 May 2003 Page [6]
Simple Notification and Alarm Protocol (SNAP) November 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 May 2003 Page [7]
Simple Notification and Alarm Protocol (SNAP) November 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 May 2003 Page [8]
Simple Notification and Alarm Protocol (SNAP) November 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 May 2003 Page [9]
Simple Notification and Alarm Protocol (SNAP) November 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.1.8 HTTP Port
The Notification service MUST NOT use the standard HTTP port
[RFC-HTTP] for incoming SNAP request. The Notification Service
will use port number that will be provided by IANA for incoming
SNAP requests.
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.
Shapira Informational - Expires May 2003 Page [10]
Simple Notification and Alarm Protocol (SNAP) November 2002
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.
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.
Shapira Informational - Expires May 2003 Page [11]
Simple Notification and Alarm Protocol (SNAP) November 2002
3.1.3 Application-Version (M)
The version of the application sending the request.
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.
Shapira Informational - Expires May 2003 Page [12]
Simple Notification and Alarm Protocol (SNAP) November 2002
3.2.3 Delete-Msg
Trigger: User deletes a message from mailbox.
Groups: MailboxGroup(M) ,MessageGroup(M), CountersGroup.
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.
Shapira Informational - Expires May 2003 Page [13]
Simple Notification and Alarm Protocol (SNAP) November 2002
3.3 AccountLockGroup
3.3.1 Account-Lock-Reason
A string containing a description of the lock reason.
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.4.3 Mailbox-Name
The IMAP4 [RFC-IMAP4] mailbox (folder). This attribute will be used
when the message is not deposited to the Inbox folder, rather to a
different folder. If this attribute is missing from the SNAP
request - "INBOX" value will be assumed.
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].
Shapira Informational - Expires May 2003 Page [14]
Simple Notification and Alarm Protocol (SNAP) November 2002
3.5.4 From
The message "From" header as in [RFC-2822].
3.5.5 To
The message "To" header as in [RFC-2822].
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 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.12 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 May 2003 Page [15]
Simple Notification and Alarm Protocol (SNAP) November 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.13 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 May 2003 Page [16]
Simple Notification and Alarm Protocol (SNAP) November 2002
3.6.1 Total-Voice-Message
Total number of voice messages in mailbox.
3.6.2 Total-New-Voice-Message
Number of new voice messages in mailbox. This includes messages
that are new and urgent.
3.6.3 Total-New-Urgent-Voice-Message
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.6.10 Total-Message
Total number of messages in mailbox.
3.6.11 Total-New-Message
Number of all new messages in mailbox. This includes messages that
are new and urgent.
Shapira Informational - Expires May 2003 Page [17]
Simple Notification and Alarm Protocol (SNAP) November 2002
3.6.12 Total-New-Urgent-Message
Number of all new urgent 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.
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.
Shapira Informational - Expires May 2003 Page [18]
Simple Notification and Alarm Protocol (SNAP) November 2002
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.
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.
Shapira Informational - Expires May 2003 Page [19]
Simple Notification and Alarm Protocol (SNAP) November 2002
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 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 = <any 8-bit sequence of data>
CHAR = <any US-ASCII character (octets 0 - 127)>
UPALPHA = <any US-ASCII uppercase letter "A".."Z">
LOALPHA = <any US-ASCII lowercase letter "a".."z">
ALPHA = UPALPHA | LOALPHA
DIGIT = <any US-ASCII digit "0".."9">
CTL = <any US-ASCII control character
(octets 0 - 31) and DEL (127)>
CR = <US-ASCII CR, carriage return (13)>
LF = <US-ASCII LF, linefeed (10)>
SP = <US-ASCII SP, space (32)>
HT = <US-ASCII HT, horizontal-tab (9)>
Shapira Informational - Expires May 2003 Page [20]
Simple Notification and Alarm Protocol (SNAP) November 2002
<"> = <US-ASCII double-quote mark (34)>
token = 1*<any CHAR except CTLs or separators>
phrase = *<TEXT, excluding CR ,LF>
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
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]:
<Attribute-name>:<Attribute-value>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
Shapira Informational - Expires May 2003 Page [21]
Simple Notification and Alarm Protocol (SNAP) November 2002
MessageGroup =
Message-Context
[From]
[To]
[CC]
[Subject]
[Message-Send-Time]
[Message-Receive-Time]
[Message-Size]
[Body]
[Msg-Importance]
[Msg-Sensitivity]
[Message-Id]
[Delivery-Report-Msg]
MailboxGroup =
Email-Address
[Server-Name]
[Mailbox-Name]
CountersGroup =
[Total-Voice-Message]
[Total-New-Voice-Message]
[Total-New-Urgent-Voice-Message]
[Total-Fax-Message]
[Total-New-Fax-Message]
[Total-New-Urgent-Fax-Message]
[Total-Email-Message]
[Total-New-Email-Message]
[Total-New-Urgent-Email-Message]
[Total-Message]
[Total-New-Message]
[Total-New-Urgent-Message]
[Other-Counter]
RejectGroup = [Reject-Reason]
MailboxCapacityGroup =
[Mailbox-Capacity]
[Mailbox-Capacity-Threshold]
[Mailbox-Full-Status]
AccountLockGroup = [Account-Lock-Reason]
Shapira Informational - Expires May 2003 Page [22]
Simple Notification and Alarm Protocol (SNAP) November 2002
5.2.3 Attributes
Following is the list of attributes and their valid values. The list
is constructed from:
<attribute name> = <valid values> ";" <remarks>
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
Mailbox-Name = token
Message-Context = as defined in [HINT].
Subject = token ;as described by [RFC-2822]
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
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-Message = counter
Total-New-Voice-Message = counter
Total-New-Urgent-Voice-Message = counter
Total-Fax-Message = counter
Total-New-Fax-Message = counter
Total-New-Urgent-Fax-Message = counter
Shapira Informational - Expires May 2003 Page [23]
Simple Notification and Alarm Protocol (SNAP) November 2002
Total-Email-Message = counter
Total-New-Email-Message = counter
Total-New-Urgent-Email-Message = counter
Total-Message = counter
Total-New-Message = counter
Total-New-Urgent-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 = *<TEXT, excluding CR ,LF>
Request-Id = *<ALPHA | DIGIT>
Request-Id-Line = "REQUEST-ID:" *WS 1*request-id *WS CRLF
Description-Line = "Description:" *WS *<TEXT, excluding CR ,LF>
Shapira Informational - Expires May 2003 Page [24]
Simple Notification and Alarm Protocol (SNAP) November 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
Request-Id: 9941401AA
Description: Request%20processed%20successfully
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 2003 Page [25]
Simple Notification and Alarm Protocol (SNAP) November 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
Interoperability considerations: None
Shapira Informational - Expires May 2003 Page [26]
Simple Notification and Alarm Protocol (SNAP) November 2002
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.
[RFC-2183] Troost, R., Dorner, S., and Moore, K., "Communicating
Presentation Information in Internet Messages: The
Content-Disposition Header Field", RFC 2183,August 1997.
Shapira Informational - Expires May 2003 Page [27]
Simple Notification and Alarm Protocol (SNAP) November 2002
[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-08.txt
[] Jacob Palme, "Common Internet Message Header Fields",
draft-palme-mailext-headers-08.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 Gev Decktor.
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 2003 Page [28]
Simple Notification and Alarm Protocol (SNAP) November 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 May 2003 Page [29]
Simple Notification and Alarm Protocol (SNAP) November 2002
Appendix D. List of changes from ..-03 version
- Removed Attachment-Names and nAttachments attributes
- Added that the Notification Service will receive SNAP in a
pre-defined port (2.1.8).
- Added Total-Message, Total-New-Message and
Total-New-Urgent-Message (3.6.10-12).
- Added Mailbox-Name (3.4.3) in MailboxGroup.
Appendix D. List of changes from ..-03 version
- Fixed response syntax.
- Fixed response example
- Updated references to internet drafts.
Shapira Informational - Expires May 2003 Page [30]