tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search

RFC 4037

Proposed STD
Pages: 56
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: OPES

Open Pluggable Edge Services (OPES) Callout Protocol (OCP) Core

Part 1 of 3, p. 1 to 15
None       Next RFC Part

 


Top       ToC       Page 1 
Network Working Group                                        A. Rousskov
Request for Comments: 4037                       The Measurement Factory
Category: Standards Track                                     March 2005


    Open Pluggable Edge Services (OPES) Callout Protocol (OCP) Core

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2005).

Abstract

   This document specifies the core of the Open Pluggable Edge Services
   (OPES) Callout Protocol (OCP).  OCP marshals application messages
   from other communication protocols: An OPES intermediary sends
   original application messages to a callout server; the callout server
   sends adapted application messages back to the processor.  OCP is
   designed with typical adaptation tasks in mind (e.g., virus and spam
   management, language and format translation, message anonymization,
   or advertisement manipulation).  As defined in this document, the OCP
   Core consists of application-agnostic mechanisms essential for
   efficient support of typical adaptations.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
       1.1.  Scope  . . . . . . . . . . . . . . . . . . . . . . . . .  4
       1.2.  OPES Document Map  . . . . . . . . . . . . . . . . . . .  5
       1.3.  Terminology  . . . . . . . . . . . . . . . . . . . . . .  6
   2.  Overall Operation  . . . . . . . . . . . . . . . . . . . . . .  7
       2.1.  Initialization . . . . . . . . . . . . . . . . . . . . .  7
       2.2.  Original Dataflow  . . . . . . . . . . . . . . . . . . .  8
       2.3.  Adapted Dataflow . . . . . . . . . . . . . . . . . . . .  8
       2.4.  Multiple Application Messages  . . . . . . . . . . . . .  9
       2.5.  Termination  . . . . . . . . . . . . . . . . . . . . . .  9
       2.6.  Message Exchange Patterns  . . . . . . . . . . . . . . .  9
       2.7.  Timeouts . . . . . . . . . . . . . . . . . . . . . . . . 10
       2.8.  Environment  . . . . . . . . . . . . . . . . . . . . . . 11
   3.  Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Top      ToC       Page 2 
       3.1.  Message Format . . . . . . . . . . . . . . . . . . . . . 12
       3.2.  Message Rendering  . . . . . . . . . . . . . . . . . . . 13
       3.3.  Message Examples . . . . . . . . . . . . . . . . . . . . 14
       3.4.  Message Names  . . . . . . . . . . . . . . . . . . . . . 15
   4.  Transactions . . . . . . . . . . . . . . . . . . . . . . . . . 15
   5.  Invalid Input  . . . . . . . . . . . . . . . . . . . . . . . . 16
   6.  Negotiation  . . . . . . . . . . . . . . . . . . . . . . . . . 16
       6.1.  Negotiation Phase  . . . . . . . . . . . . . . . . . . . 17
       6.2.  Negotiation Examples . . . . . . . . . . . . . . . . . . 18
   7.  'Data Preservation' Optimization . . . . . . . . . . . . . . . 20
   8.  'Premature Dataflow Termination' Optimizations . . . . . . . . 21
       8.1.  Original Dataflow  . . . . . . . . . . . . . . . . . . . 22
       8.2.  Adapted Dataflow . . . . . . . . . . . . . . . . . . . . 23
       8.3.  Getting Out of the Loop  . . . . . . . . . . . . . . . . 24
   9.  Protocol Element Type Declaration Mnemonic (PETDM) . . . . . . 25
       9.1     Optional Parameters  . . . . . . . . . . . . . . . . . 27
   10. Message Parameter Types  . . . . . . . . . . . . . . . . . . . 28
       10.1.   uri. . . . . . . . . . . . . . . . . . . . . . . . . . 28
       10.2.   uni. . . . . . . . . . . . . . . . . . . . . . . . . . 28
       10.3.   size . . . . . . . . . . . . . . . . . . . . . . . . . 29
       10.4.   offset . . . . . . . . . . . . . . . . . . . . . . . . 29
       10.5.   percent  . . . . . . . . . . . . . . . . . . . . . . . 29
       10.6.   boolean. . . . . . . . . . . . . . . . . . . . . . . . 30
       10.7.   xid .  . . . . . . . . . . . . . . . . . . . . . . . . 30
       10.8.   sg-id. . . . . . . . . . . . . . . . . . . . . . . . . 30
       10.9.   modp. . . . . . . . . . . . . . . . . . . . . . . . .  30
       10.10.  result. . . . . . . . . . . . . . . . . . . . . . . .  30
       10.11.  feature . . . . . . . . . . . . . . . . . . . . . . .  32
       10.12.  features. . . . . . . . . . . . . . . . . . . . . . .  32
       10.13.  service . . . . . . . . . . . . . . . . . . . . . . .  32
       10.14.  services. . . . . . . . . . . . . . . . . . . . . . .  33
       10.15.  Dataflow Specializations. . . . . . . . . . . . . . .  33
   11. Message Definitions . . . . . . . . . . . . . . . . . . . . .  33
       11.1.   Connection Start (CS) . . . . . . . . . . . . . . . .  34
       11.2.   Connection End (CE) . . . . . . . . . . . . . . . . .  35
       11.3.   Service Group Created (SGC) . . . . . . . . . . . . .  35
       11.4.   Service Group Destroyed (SGD) . . . . . . . . . . . .  36
       11.5.   Transaction Start (TS). . . . . . . . . . . . . . . .  36
       11.6.   Transaction End (TE). . . . . . . . . . . . . . . . .  36
       11.7.   Application Message Start (AMS) . . . . . . . . . . .  37
       11.8.   Application Message End (AME) . . . . . . . . . . . .  37
       11.9.   Data Use Mine (DUM) . . . . . . . . . . . . . . . . .  38
       11.10.  Data Use Yours (DUY). . . . . . . . . . . . . . . . .  39
       11.11.  Data Preservation Interest (DPI). . . . . . . . . . .  39
       11.12.  Want Stop Receiving Data (DWSR) . . . . . . . . . . .  40
       11.13.  Want Stop Sending Data (DWSS) . . . . . . . . . . . .  41
       11.14.  Stop Sending Data (DSS) . . . . . . . . . . . . . . .  41
       11.15.  Want Data Paused (DWP). . . . . . . . . . . . . . . .  42

Top      ToC       Page 3 
       11.16.  Paused My Data (DPM). . . . . . . . . . . . . . . . .  43
       11.17.  Want More Data (DWM). . . . . . . . . . . . . . . . .  43
       11.18.  Negotiation Offer (NO). . . . . . . . . . . . . . . .  44
       11.19.  Negotiation Response (NR) . . . . . . . . . . . . . .  45
       11.20.  Ability Query (AQ). . . . . . . . . . . . . . . . . .  46
       11.21.  Ability Answer (AA) . . . . . . . . . . . . . . . . .  46
       11.22.  Progress Query (PQ) . . . . . . . . . . . . . . . . .  47
       11.23.  Progress Answer (PA). . . . . . . . . . . . . . . . .  47
       11.24.  Progress Report (PR). . . . . . . . . . . . . . . . .  48
   12. IAB Considerations  . . . . . . . . . . . . . . . . . . . . .  48
   13. Security Considerations . . . . . . . . . . . . . . . . . . .  48
   14. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  50
   15. Compliance  . . . . . . . . . . . . . . . . . . . . . . . . .  50
       15.1.  Extending OCP Core . . . . . . . . . . . . . . . . . .  51
   A.  Message Summary . . . . . . . . . . . . . . . . . . . . . . .  52
   B.  State Summary   . . . . . . . . . . . . . . . . . . . . . . .  53
   C.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  54
   16. References  . . . . . . . . . . . . . . . . . . . . . . . . .  54
       16.1.  Normative References . . . . . . . . . . . . . . . . .  54
       16.2.  Informative References . . . . . . . . . . . . . . . .  54
   Author's Address. . . . . . . . . . . . . . . . . . . . . . . . .  55
   Full Copyright Statement. . . . . . . . . . . . . . . . . . . . .  56

1.  Introduction

   The Open Pluggable Edge Services (OPES) architecture [RFC3835]
   enables cooperative application services (OPES services) between a
   data provider, a data consumer, and zero or more OPES processors.
   The application services under consideration analyze and possibly
   transform application-level messages exchanged between the data
   provider and the data consumer.

   The OPES processor can delegate the responsibility of service
   execution by communicating with callout servers.  As described in
   [RFC3836], an OPES processor invokes and communicates with services
   on a callout server by using an OPES callout protocol (OCP).  This
   document specifies the core of that protocol ("OCP Core").

   The OCP Core specification documents general application-independent
   protocol mechanisms.  A separate series of documents describes
   application-specific aspects of OCP.  For example, "HTTP Adaptation
   with OPES" [OPES-HTTP] describes, in part, how HTTP messages and HTTP
   meta-information can be communicated over OCP.

   Section 1.2 provides a brief overview of the entire OPES document
   collection, including documents describing OPES use cases and
   security threats.

Top      ToC       Page 4 
1.1.  Scope

   The OCP Core specification documents the behavior of OCP agents and
   the requirements for OCP extensions.  OCP Core does not contain
   requirements or mechanisms specific for application protocols being
   adapted.

   As an application proxy, the OPES processor proxies a single
   application protocol or converts from one application protocol to
   another.  At the same time, OPES processor may be an OCP client,
   using OCP to facilitate adaptation of proxied messages at callout
   servers.  It is therefore natural to assume that an OPES processor
   takes application messages being proxied, marshals them over OCP to
   callout servers, and then puts the adaptation results back on the
   wire.  However, this assumption implies that OCP is applied directly
   to application messages that OPES processor is proxying, which may
   not be the case.

      OPES processor scope                         callout server scope
      +-----------------+                           +-----------------+
      | pre-processing  |         OCP scope         |                 |
      |            +- - - - - - - - - - - - - - - - - - -+            |
      | iteration  |     <== ( application data ) ==>    | adaptation |
      |            +- - - - - - - - - - - - - - - - - - -+            |
      | post-processing |                           |                 |
      +-----------------+                           +-----------------+

   An OPES processor may preprocess (or postprocess) proxied application
   messages before (or after) they are adapted at callout servers.  For
   example, a processor may take an HTTP response being proxied and pass
   it as-is, along with metadata about the corresponding HTTP
   connection.  Another processor may take an HTTP response, extract its
   body, and pass that body along with the content-encoding metadata.
   Moreover, to perform adaptation, the OPES processor may execute
   several callout services, iterating over several callout servers.
   Such preprocessing, postprocessing, and iterations make it impossible
   to rely on any specific relationship between application messages
   being proxied and application messages being sent to a callout
   service.  Similarly, specific adaptation actions at the callout
   server are outside OCP Core scope.

   This specification does not define or require any specific
   relationship among application messages being proxied by an OPES
   processor and application messages being exchanged between an OPES
   processor and a callout server via OCP.  The OPES processor usually
   provides some mapping among these application messages, but the
   processor's specific actions are beyond OCP scope.  In other words,
   this specification is not concerned with the OPES processor role as

Top      ToC       Page 5 
   an application proxy or as an iterator of callout services.  The
   scope of OCP Core is communication between a single OPES processor
   and a single callout server.

   Furthermore, an OPES processor may choose which proxied application
   messages or information about them to send over OCP.  All proxied
   messages on all proxied connections (if connections are defined for a
   given application protocol), everything on some connections, selected
   proxied messages, or nothing might be sent over OCP to callout
   servers.  OPES processor and callout server state related to proxied
   protocols can be relayed over OCP as application message metadata.

1.2.  OPES Document Map

   This document belongs to a large set of OPES specifications produced
   by the IETF OPES Working Group.  Familiarity with the overall OPES
   approach and typical scenarios is often essential when one tries to
   comprehend isolated OPES documents.  This section provides an index
   of OPES documents to assist the reader with finding "missing"
   information.

   o  "OPES Use Cases and Deployment Scenarios" [RFC3752] describes a
      set of services and applications that are considered in scope for
      OPES and that have been used as a motivation and guidance in
      designing the OPES architecture.

   o  The OPES architecture and common terminology are described in "An
      Architecture for Open Pluggable Edge Services (OPES)" [RFC3835].

   o  "Policy, Authorization, and Enforcement Requirements of OPES"
      [RFC3838] outlines requirements and assumptions on the policy
      framework, without specifying concrete authorization and
      enforcement methods.

   o  "Security Threats and Risks for OPES" [RFC3837] provides OPES risk
      analysis, without recommending specific solutions.

   o  "OPES Treatment of IAB Considerations" [RFC3914] addresses all
      architecture-level considerations expressed by the IETF Internet
      Architecture Board (IAB) when the OPES WG was chartered.

   o  At the core of the OPES architecture are the OPES processor and
      the callout server, two network elements that communicate with
      each other via an OPES Callout Protocol (OCP).  The requirements
      for this protocol are discussed in "Requirements for OPES Callout
      Protocols" [RFC3836].

Top      ToC       Page 6 
   o  This document specifies an application agnostic protocol core to
      be used for the communication between an OPES processor and a
      callout server.

   o  "OPES Entities and End Points Communications" [RFC3897] specifies
      generic tracing and bypass mechanisms for OPES.

   o  The OCP Core and communications documents are independent from the
      application protocol being adapted by OPES entities.  Their
      generic mechanisms have to be complemented by application-specific
      profiles.  "HTTP Adaptation with OPES" [OPES-HTTP] is such an
      application profile for HTTP.  It specifies how
      application-agnostic OPES mechanisms are to be used and augmented
      in order to support adaptation of HTTP messages.

   o  Finally, "P: Message Processing Language" [OPES-RULES] defines a
      language for specifying what OPES adaptations (e.g., translation)
      must be applied to what application messages (e.g., e-mail from
      bob@example.com).  P language is intended for configuring
      application proxies (OPES processors).

1.3.  Terminology

   In this document, the keywords "MUST", "MUST NOT", "REQUIRED",
   "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
   and "OPTIONAL" in this document are to be interpreted as described in
   [RFC2119].  When used with the normative meanings, these keywords
   will be all uppercase.  Occurrences of these words in lowercase
   constitute normal prose usage, with no normative implications.

   The OPES processor works with messages from application protocols and
   may relay information about those application messages to a callout
   server.  OCP is also an application protocol.  Thus, protocol
   elements such as "message", "connection", or "transaction" exist in
   OCP and other application protocols.  In this specification, all
   references to elements from application protocols other than OCP are
   used with an explicit "application" qualifier.  References without
   the "application" qualifier refer to OCP elements.

   OCP message: A basic unit of communication between an OPES processor
      and a callout server.  The message is a sequence of octets
      formatted according to syntax rules (section 3.1).  Message
      semantics is defined in section 11.

   application message: An entity defined by OPES processor and callout
      server negotiation.  Usually, the negotiated definition would
      match the definition from an application protocol (e.g., [RFC2616]
      definition of an HTTP message).

Top      ToC       Page 7 
   application message data: An opaque sequence of octets representing a
      complete or partial application message.  OCP Core does not
      distinguish application message structures (if there are any).
      Application message data may be empty.

   data: Same as application message data.

   original: Referring to an application message flowing from the OPES
      processor to a callout server.

   adapted: Referring to an application message flowing from an OPES
      callout server to the OPES processor.

   adaptation: Any kind of access by a callout server, including
      modification, generation, and copying.  For example, translating
      or logging an SMTP message is adaptation of that application
      message.

   agent: The actor for a given communication protocol.  The OPES
      processor and callout server are OCP agents.  An agent can be
      referred to as a sender or receiver, depending on its actions in a
      particular context.

   immediate: Performing the specified action before reacting to new
      incoming messages or sending any new messages unrelated to the
      specified action.

   OCP extension: A specification extending or adjusting this document
      for adaptation of an application protocol (a.k.a., application
      profile; e.g., [OPES-HTTP]), new OCP functionality (e.g.,
      transport encryption and authentication), and/or new OCP Core
      version.

2.  Overall Operation

   The OPES processor may use the OPES callout protocol (OCP) to
   communicate with callout servers.  Adaptation using callout services
   is sometimes called "bump in the wire" architecture.

2.1.  Initialization

   The OPES processor establishes transport connections with callout
   servers to exchange application messages with the callout server(s)
   by using OCP.  After a transport-layer connection (usually TCP/IP) is
   established, communicating OCP agents exchange Connection Start (CS)
   messages.  Next, OCP features can be negotiated between the processor
   and the callout server (see section 6).  For example, OCP agents may
   negotiate transport encryption and application message definition.

Top      ToC       Page 8 
   When enough settings are negotiated, OCP agents may start exchanging
   application messages.

   OCP Core provides negotiation and other mechanisms for agents to
   encrypt OCP connections and authenticate each other.  OCP Core does
   not require OCP connection encryption or agent authentication.
   Application profiles and other OCP extensions may document and/or
   require these and other security mechanisms.  OCP is expected to be
   used, in part, in closed environments where trust and privacy are
   established by means external to OCP.  Implementations are expected
   to demand necessary security features via the OCP Core negotiation
   mechanism, depending on agent configuration and environment.

2.2.  Original Dataflow

   When the OPES processor wants to adapt an application message, it
   sends a Transaction Start (TS) message to initiate an OCP transaction
   dedicated to that application message.  The processor then sends an
   Application Message Start (AMS) message to prepare the callout server
   for application data that will follow.  Once the application message
   scope is established, application data can be sent to the callout
   server by using Data Use Mine (DUM) and related OCP message(s).  All
   of these messages correspond to the original dataflow.

2.3.  Adapted Dataflow

   The callout server receives data and metadata sent by the OPES
   processor (original dataflow).  The callout server analyses metadata
   and adapts data as it comes in.  The server usually builds its
   version of metadata and responds to the OPES processor with an
   Application Message Start (AMS) message.  Adapted application message
   data can be sent next, using Data Use Mine (DUM) OCP message(s).  The
   application message is then announced to be "completed" or "closed"
   by using an Application Message End (AME) message.  The transaction
   may be closed by using a Transaction End (TE) message, as well.  All
   these messages correspond to adapted data flow.

       +---------------+                             +-------+
       |     OPES      | == (original data flow) ==> |callout|
       |   processor   | <== (adapted data flow) === |server |
       +---------------+                             +-------+

   The OPES processor receives the adapted application message sent by
   the callout server.  Other OPES processor actions specific to the
   application message received are outside scope of this specification.

Top      ToC       Page 9 
2.4.  Multiple Application Messages

   OCP Core specifies a transactions interface dedicated to exchanging a
   single original application message and a single adapted application
   message.  Some application protocols may require multiple adapted
   versions for a single original application message or even multiple
   original messages to be exchanged as a part of a single OCP
   transaction.  For example, a single original e-mail message may need
   to be transformed into several e-mail messages, with one custom
   message for each recipient.

   OCP extensions MAY document mechanisms for exchanging multiple
   original and/or multiple adapted application messages within a single
   OCP transaction.

2.5.  Termination

   Either OCP agent can terminate application message delivery,
   transaction, or connection by sending an appropriate OCP message.
   Usually, the callout server terminates adapted application message
   delivery and the transaction.  Premature and abnormal terminations at
   arbitrary times are supported.  The termination message includes a
   result description.

2.6.  Message Exchange Patterns

   In addition to messages carrying application data, OCP agents may
   also exchange messages related to their configuration, state,
   transport connections, application connections, etc.  A callout
   server may remove itself from the application message processing
   loop.  A single OPES processor can communicate with many callout
   servers and vice versa.  Though many OCP exchange patterns do not
   follow a classic client-server model, it is possible to think of an
   OPES processor as an "OCP client" and of a callout server as an "OCP
   server".  The OPES architecture document [RFC3835] describes
   configuration possibilities.

   The following informal rules illustrate relationships between
   connections, transactions, OCP messages, and application messages:

   o  An OCP agent may communicate with multiple OCP agents.  This is
      outside the scope of this specification.

   o  An OPES processor may have multiple concurrent OCP connections to
      a callout server.  Communication over multiple OCP connections is
      outside the scope of this specification.

Top      ToC       Page 10 
   o  A connection may carry multiple concurrent transactions.  A
      transaction is always associated with a single connection (i.e., a
      transaction cannot span multiple concurrent connections).

   o  A connection may carry at most one message at a time, including
      control messages and transaction-related messages.  A message is
      always associated with a single connection (i.e., a message cannot
      span multiple concurrent connections).

   o  A transaction is a sequence of messages related to application of
      a given set of callout services to a single application message.

      A sequence of transaction messages from an OPES processor to a
      callout server is called original flow.  A sequence of transaction
      messages from a callout server to an OPES processor is called
      adapted flow.  The two flows may overlap in time.

   o  In OCP Core, a transaction is associated with a single original
      and a single adapted application message.  OCP Core extensions may
      extend transaction scope to more application messages.

   o  An application message (adapted or original) is transferred by
      using a sequence of OCP messages.

2.7.  Timeouts

   OCP violations, resource limits, external dependencies, and other
   factors may lead to states in which an OCP agent is not receiving
   required messages from the other OCP agent.  OCP Core defines no
   messages to address such situations.  In the absence of any extension
   mechanism, OCP agents must implement timeouts for OCP operations.  An
   OCP agent MUST forcefully terminate any OCP connection, negotiation,
   transaction, etc.  that is not making progress.  This rule covers
   both dead- and livelock situations.

   In their implementation, OCP agents MAY rely on transport-level or
   other external timeouts if such external timeouts are guaranteed to
   happen for a given OCP operation.  Depending on the OCP operation, an
   agent may benefit from "pinging" the other side with a Progress Query
   (PQ) message before terminating an OCP transaction or connection.
   The latter is especially useful for adaptations that may take a long
   time at the callout server before producing any adapted data.

Top      ToC       Page 11 
2.8.  Environment

   OCP communication is assumed usually to take place over TCP/IP
   connections on the Internet (though no default TCP port is assigned
   to OCP in this specification).  This does not preclude OCP from being
   implemented on top of other transport protocols, or on other
   networks.  High-level transport protocols such as BEEP [RFC3080] may
   be used.  OCP Core requires a reliable and message-order-preserving
   transport.  Any protocol with these properties can be used; the
   mapping of OCP message structures onto the transport data units of
   the protocol in question is outside the scope of this specification.

   OCP Core is application agnostic.  OCP messages can carry
   application-specific information as a payload or as
   application-specific message parameters.

   OCP Core overhead in terms of extra traffic on the wire is about 100
   - 200 octets per small application message.  Pipelining, preview,
   data preservation, and early termination optimizations, as well as
   as-is encapsulation of application data, make fast exchange of
   application messages possible.

3.  Messages

   As defined in section 1.3, an OCP message is a basic unit of
   communication between an OPES processor and a callout server.  A
   message is a sequence of octets formatted according to syntax rules
   (section 3.1).  Message semantics is defined in section 11.  Messages
   are transmitted on top of OCP transport.

   OCP messages deal with transport, transaction management, and
   application data exchange between a single OPES processor and a
   single callout server.  Some messages can be emitted only by an OPES
   processor; some only by a callout server; and some by both OPES
   processor and callout server.  Some messages require responses (one
   could call such messages "requests"); some can only be used in
   response to other messages ("responses"); some may be sent without
   solicitation; and some may not require a response.

Top      ToC       Page 12 
3.1.  Message Format

   An OCP message consists of a message name followed by optional
   parameters and a payload.  The exact message syntax is defined by the
   following Augmented Backus-Naur Form (ABNF) [RFC2234]:

   message = name [SP anonym-parameters]
             [CRLF named-parameters CRLF]
             [CRLF payload CRLF]
             ";" CRLF

   anonym-parameters = value *(SP value)               ; space-separated
   named-parameters  = named-value *(CRLF named-value) ; CRLF-separated
   list-items        = value *("," value)              ; comma-separated

   payload = data

   named-value = name ":" SP value

   value     = structure / list / atom
   structure = "{" [anonym-parameters] [CRLF named-parameters CRLF] "}"
   list      = "(" [ list-items ] ")"
   atom      = bare-value / quoted-value

   name = ALPHA *safe-OCTET
   bare-value = 1*safe-OCTET
   quoted-value = DQUOTE data DQUOTE
   data = size ":" *OCTET                   ; exactly size octets

   safe-OCTET = ALPHA / DIGIT / "-" / "_"
   size = dec-number                        ; 0-2147483647
   dec-number = 1*DIGIT                     ; no leading zeros or signs

   Several normative rules accompany the above ABNF:

   o  There is no "implied linear space" (LWS) rule.  LWS rules are
      common to MIME-based grammars but are not used here.  The
      whitespace syntax is restricted to what is explicitly allowed by
      the above ABNF.

   o  All protocol elements are case sensitive unless it is specified
      otherwise.  In particular, message names and parameter names are
      case sensitive.

   o  Sizes are interpreted as decimal values and cannot have leading
      zeros.

   o  Sizes do not exceed 2147483647.

Top      ToC       Page 13 
   o  The size attribute in a quoted-value encoding specifies the exact
      number of octets following the column (':') separator.  If size
      octets are not followed by a quote ('"') character, the encoding
      is syntactically invalid.

   o  Empty quoted values are encoded as a 4-octet sequence "0:".

   o  Any bare value can be encoded as a quoted value.  A quoted value
      is interpreted after the encoding is removed.  For example, number
      1234 can be encoded as four octets 1234 or as eight octets
      "4:1234", yielding exactly the same meaning.

   o  Unicode UTF-8 is the default encoding.  Note that ASCII is a UTF-8
      subset, and that the syntax prohibits non-ASCII characters outside
      of the "data" element.

   Messages violating formatting rules are, by definition, invalid.  See
   section 5 for rules governing processing of invalid messages.

3.2.  Message Rendering

   OCP message samples in this specification and its extensions may not
   be typeset to depict minor syntactical details of OCP message format.
   Specifically, SP and CRLF characters are not shown explicitly.  No
   rendering of an OCP message can be used to infer message format.  The
   message format definition above is the only normative source for all
   implementations.

   On occasion, an OCP message line exceeds text width allowed by this
   specification format.  A backslash ("\"), a "soft line break"
   character, is used to emphasize a protocol-violating
   presentation-only linebreak.  Bare backslashes are prohibited by OCP
   syntax.  Similarly, an "\r\n" string is sometimes used to emphasize
   the presence of a CRLF sequence, usually before OCP message payload.
   Normally, the visible end of line corresponds to the CRLF sequence on
   the wire.

   The next section (section 3.3) contains specific OCP message
   examples, some of which illustrate the above rendering techniques.

Top      ToC       Page 14 
3.3.  Message Examples

   OCP syntax provides for compact representation of short control
   messages and required parameters while allowing for parameter
   extensions.  Below are examples of short control messages.  The
   required CRLF sequence at the end of each line is not shown
   explicitly (see section 3.2).

   PQ;
   TS 1 2;
   DWM 22;
   DWP 22 16;
   x-doit "5:xyzzy";

   The above examples contain atomic anonymous parameter values, such as
   number and string constants.  OCP messages sometimes use more
   complicated parameters such as item lists or structures with named
   values.  As both messages below illustrate, structures and lists can
   be nested:

   NO ({"32:http://www.iana.org/assignments/opes/ocp/tls"});
   NO ({"54:http://www.iana.org/assignments/opes/ocp/http/response"
   Optional-Parts: (request-header)
   },{"54:http://www.iana.org/assignments/opes/ocp/http/response"
   Optional-Parts: (request-header,request-body)
   Transfer-Encodings: (chunked)
   });

   Optional parameters and extensions are possible with a named
   parameters approach, as illustrated by the following example.  The
   DWM (section 11.17) message in the example has two anonymous
   parameters (the last one being an extension) and two named parameters
   (the last one being an extension).

   DWM 1 3
   Size-Request: 16384
   X-Need-Info: "26:twenty six octet extension";

   Finally, any message may have a payload part.  For example, the Data
   Use Mine (DUM) message below carries 8865 octets of raw data.

   DUM 1 13
   Modp: 75
   \r\n
   8865:... 8865 octets of raw data ...;

Top      ToC       Page 15 
3.4.  Message Names

   Most OCP messages defined in this specification have short names,
   formed by abbreviating or compressing a longer but human-friendlier
   message title.  Short names without a central registration system
   (such as this specification or the IANA registry) are likely to cause
   conflicts.  Informal protocol extensions should avoid short names.
   To emphasize what is already defined by message syntax,
   implementations cannot assume that all message names are very short.



(page 15 continued on part 2)

Next RFC Part