rfc2244.txt

RFC 的详细文档！

   reconfiguring or upgrading the server.

   In some cases, such as when the value has special meaning to the
   server, it is useful to have the server enforce validation by
   returning the INVALID response code to a STORE command. These cases
   MUST be explicitly identified in the dataset class specification
   which SHOULD include specific fixed rules for validation.  Since a
   given ACAP server may be unaware of any particular dataset class
   specification, clients MUST NOT depend on the presence of enforced
   validation on the server.

1.5.     Definitions


   access control list (ACL)
        A set of identifier, rights pairs associated with an object.  An
        ACL is used to determine which operations a user is permitted to
        perform on that object.  See section 3.5.

   attribute
        A named value within an entry.  See section 3.1.




Newman & Myers              Standards Track                     [Page 2]

RFC 2244                          ACAP                     November 1997


   comparator
        A named function which can be used to perform one or more of
        three comparison operations: ordering, equality and substring
        matching.  See section 3.4.

   context
        An ordered subset of entries in a dataset, created by a SEARCH
        command with a MAKECONTEXT modifier.  See section 3.3.

   dataset
        One level of hierarchy in ACAP's tree of entries.

   dataset class specification
        The rules which allow a client to interpret the data within a
        portion of ACAP's tree of entries.

   entry
        A set of attributes with a unique entry name.  See section 3.1.

   metadata
        Information describing an attribute, its value and any access
        controls associated with that attribute.  See section 3.1.2.

   NIL  This represents the non-existence of a particular data item.

   NUL  A control character encoded as 0 in US-ASCII [US-ASCII].

   octet
        An 8-bit value.  On most modern computer systems, an octet is
        one byte.

   SASL Simple Authentication and Security Layer [SASL].

   UTC  Universal Coordinated Time as maintained by the Bureau
        International des Poids et Mesures (BIPM).

   UTF-8
        An 8-bit transformation format of the Universal Character Set
        [UTF8].  Note that an incompatible change was made to the coded
        character set referenced by [UTF8], so for the purpose of this
        document, UTF-8 refers to the UTF-8 encoding as defined by
        version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646]
        including amendments one through seven.








Newman & Myers              Standards Track                     [Page 3]

RFC 2244                          ACAP                     November 1997


1.6.     ACAP Command Overview

   The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic
   protocol services.  The SEARCH command is used to select, sort, fetch
   and monitor changes to attribute values and metadata.  The
   UPDATECONTEXT and FREECONTEXT commands are also used to assist in
   monitoring changes in attribute values and metadata.  The STORE
   command is used to add, modify and delete entries and attributes.
   The DELETEDSINCE command is used to assist a client in
   re-synchronizing a cache with the server.  The GETQUOTA, SETACL,
   DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine
   storage quotas and examine or modify access permissions.

2.       Protocol Framework

2.1.     Link Level

   The ACAP protocol assumes a reliable data stream such as provided by
   TCP.  When TCP is used, an ACAP server listens on port 674.

2.2.     Commands and Responses

   An ACAP session consists of the establishment of a client/server
   connection, an initial greeting from the server, and client/server
   interactions.  These client/server interactions consist of a client
   command, server data, and a server completion result.

   ACAP is a text-based line-oriented protocol.  In general,
   interactions transmitted by clients and servers are in the form of
   lines; that is, sequences of characters that end with a CRLF.  The
   protocol receiver of an ACAP client or server is either reading a
   line, or is reading a sequence of octets with a known count (a
   literal) followed by a line.  Both clients and servers must be
   capable of handling lines of arbitrary length.

2.2.1.   Client Protocol Sender and Server Protocol Receiver

   The client command begins an operation.  Each client command is
   prefixed with a identifier (an alphanumeric string of no more than 32
   characters, e.g., A0001, A0002, etc.) called a "tag".  A different
   tag SHOULD be generated by the client for each command.

   There are two cases in which a line from the client does not
   represent a complete command.  In one case, a command argument is
   quoted with an octet count (see the description of literal in section
   2.6.3); in the other case, the command arguments require server





Newman & Myers              Standards Track                     [Page 4]

RFC 2244                          ACAP                     November 1997


   feedback (see the AUTHENTICATE command).  In some of these cases, the
   server sends a command continuation request if it is ready for the
   next part of the command.  This response is prefixed with the token
   "+".

        Note: If, instead, the server detected an error in a
        command, it sends a BAD completion response with tag
        matching the command (as described below) to reject the
        command and prevent the client from sending any more of the
        command.

        It is also possible for the server to send a completion or
        intermediate response for some other command (if multiple
        commands are in progress), or untagged data.  In either
        case, the command continuation request is still pending;
        the client takes the appropriate action for the response,
        and reads another response from the server.

   The ACAP server reads a command line from the client, parses the
   command and its arguments, and transmits server data and a server
   command completion result.

2.2.2.   Server Protocol Sender and Client Protocol Receiver

   Data transmitted by the server to the client come in four forms:
   command continuation requests, command completion results,
   intermediate responses, and untagged responses.

   A command continuation request is prefixed with the token "+".

   A command completion result indicates the success or failure of the
   operation.  It is tagged with the same tag as the client command
   which began the operation.  Thus, if more than one command is in
   progress, the tag in a server completion response identifies the
   command to which the response applies.  There are three possible
   server completion responses: OK (indicating success), NO (indicating
   failure), or BAD (indicating protocol error such as unrecognized
   command or command syntax error).

   An intermediate response returns data which can only be interpreted
   within the context of a command in progress.  It is tagged with the
   same tag as the client command which began the operation.  Thus, if
   more than one command is in progress, the tag in an intermediate
   response identifies the command to which the response applies.  A
   tagged response other than "OK", "NO", or "BAD" is an intermediate
   response.





Newman & Myers              Standards Track                     [Page 5]

RFC 2244                          ACAP                     November 1997


   An untagged response returns data or status messages which may be
   interpreted outside the context of a command in progress.  It is
   prefixed with the token "*".  Untagged data may be sent as a result
   of a client command, or may be sent unilaterally by the server.
   There is no syntactic difference between untagged data that resulted
   from a specific command and untagged data that were sent
   unilaterally.

   The protocol receiver of an ACAP client reads a response line from
   the server.  It then takes action on the response based upon the
   first token of the response, which may be a tag, a "*", or a "+" as
   described above.

   A client MUST be prepared to accept any server response at all times.
   This includes untagged data that it may not have requested.

   This topic is discussed in greater detail in the Server Responses
   section.

2.3.     Server States

   An ACAP server is in one of three states.  Most commands are valid in
   only certain states.  It is a protocol error for the client to
   attempt a command while the server is in an inappropriate state for
   that command.  In this case, a server will respond with a BAD command
   completion result.

2.3.1.   Non-Authenticated State

   In non-authenticated state, the user must supply authentication
   credentials before most commands will be permitted.  This state is
   entered when a connection starts.

2.3.2.   Authenticated State

   In authenticated state, the user is authenticated and most commands
   will be permitted.  This state is entered when acceptable
   authentication credentials have been provided.

2.3.3.   Logout State

   In logout state, the session is being terminated, and the server will
   close the connection.  This state can be entered as a result of a
   client request or by unilateral server decision.







Newman & Myers              Standards Track                     [Page 6]

RFC 2244                          ACAP                     November 1997


            +--------------------------------------+
            |initial connection and server greeting|
            +--------------------------------------+
                      || (1)                  || (2)
                      VV                      ||
            +-----------------+               ||
            |non-authenticated|               ||
            +-----------------+               ||
             || (4)      || (3)               ||
             ||          VV                   ||
             ||          +----------------+   ||
             ||          | authenticated  |   ||
             ||          +----------------+   ||
             ||            || (4)             ||
             VV            VV                 VV
            +--------------------------------------+
            |     logout and close connection      |
            +--------------------------------------+

         (1) connection (ACAP greeting)
         (2) rejected connection (BYE greeting)
         (3) successful AUTHENTICATE command
         (4) LOGOUT command, server shutdown, or connection closed

2.4.     Operational Considerations

2.4.1.   Untagged Status Updates

   At any time, a server can send data that the client did not request.

2.4.2.   Response when No Command in Progress

   Server implementations are permitted to send an untagged response
   while there is no command in progress.  Server implementations that
   send such responses MUST deal with flow control considerations.
   Specifically, they must either (1) verify that the size of the data
   does not exceed the underlying transport's available window size, or
   (2) use non-blocking writes.

2.4.3.   Auto-logout Timer

   If a server has an inactivity auto-logout timer, that timer MUST be
   of at least 30 minutes duration.  The receipt of ANY command from the
   client during that interval MUST suffice to reset the auto-logout
   timer.






Newman & Myers              Standards Track                     [Page 7]

RFC 2244                          ACAP                     November 1997


2.4.4.   Multiple Commands in Progress