percy_protocol.txt

------------------------------------------------------------------------
From:  ITBA                                          
                                                  I. Manfredi

                                                  F. Bernad

                                                  J. Legammare

                                                  N. Rampoldi
                                                  
Request for Comments: undefined               
Category: Standards Track
                                                  June 2021
------------------------------------------------------------------------


                        PERCY Protocol -- PP/1.0


Abstract

  This protocol aims to provide interaction between a client and a
  http proxy server.

Status of This Memo

  This document specifies an Internet standards track protocol for the
  Internet community, and requests discussion and suggestions for
  improvements.  Distribution of this document is unlimited.

Copyright Notice 

  Copyright (C) Instituto Tecnológico de Buenos Aires (2021).  All Rights Reserved.

Table of Contents

   1. Introduction ........................................................ 
   2. Requirements ........................................................
   3. Connections  ........................................................
      3.1. Making a request ...............................................
      3.2. Sending a response .............................................
      3.3. PERCY Request Message Format ...................................
      3.4. PERCY Response Message Format ..................................
      3.5. Conventions   ..................................................
           3.5.1. Preferred request syntax  ...............................
           3.5.2. Preferred response syntax  ..............................
   4. Request Methods .....................................................
      4.1. Overview  ......................................................
      4.2. Request Methods Definitions  ...................................
           4.2.1. Request Historical Connections  .........................
           4.2.2. Request Concurrent Connections  .........................
           4.2.3. Request Bytes Sent  .....................................
           4.2.4. Request Bytes received  .................................
           4.2.5. Request Bytes Transferred  ..............................
           4.2.6. Request I/O Buffer Size  ................................
           4.2.7. Request Selector Timeout  ...............................
           4.2.8. Request Failed Connections  .............................
      4.3. Modification Methods Definitions  ..............................
           4.3.1 Enable o disable sniffer .................................
           4.3.2. Set I/O Buffer Size .....................................
           4.3.3. Set Selector Timeout ....................................
      4.4. Method Error Handling  .........................................
           4.4.1. Retrieval Methods  ......................................
           4.4.2. Modification Methods  ...................................
                  4.4.2.1. Enable o disable sniffer (Sec. 4.3.1.)  ........
                  4.4.2.2. Set I/O Buffer Size (Sec. 4.3.2.)  .............
                  4.4.2.3. Set Selector Timeout (Sec. 4.3.3.)  ............
           4.4.3. Unauthorized Requests ...................................



1. Introduction

   PERCY is a stateless request/response protocol that operates by
   exchanging messages between a client and a server.  A PERCY "client" 
   is a program that establishes a connection to a server for the purpose 
   of sending one or more requests.  A PERCY "server" is a program that 
   receives and analyzes requests and proceeds to sending PERCY responses.
   This protocol aims to provide interaction between a client and a http proxy 
   management service using UDP in a byte oriented way.  Furthermore, it allows
   the client to change the proxy configuration while the server is running.
   To assure the privacy and security of the client, an authentication with 
   the server is mandatory on each request made. 

2. Requirements

   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 RFC 2119 [34].
    
   An implementation is not compliant if it fails to satisfy one or more  
   of the MUST or REQUIRED level requirements for the protocols it
   implements.  An implementation that satisfies all the MUST or REQUIRED
   level and all the SHOULD level requirements for its protocols is said
   to be "unconditionally compliant"; one that satisfies all the MUST
   level requirements but not all the SHOULD level requirements for its
   protocols is said to be "conditionally compliant."

3. Connections
                                            
3.1. Making a request
  
   In order to send a request to the http proxy management service, the client MUST send an
   UDP message to the port and address the server is listening to.  This service is 
   conventionally located on UDP port 9090 and loopback address.  A passphrase MUST be provided
   to authorize each request.

3.2. Sending a response

   Once a request is received, the server MUST analyze the passphrase sent by the client.
   Once the passphrase is validated, the server MUST send a response corresponding to
   the requested method.  There may be subsequent requests/responses, all following the 
   structure defined below.

3.3. PERCY Request Message Format

   The request message contains field/bytes in the following diagram:

    +----------+----------+----------+----------+----------+----------+----------+
    |    VER   |      PASSPHRASE     |   TYPE   |  METHOD  |   RESV   |   VALUE  |
    +----------+---------------------+----------+----------+----------+----------+
    |     1    |          6          |    1     |     1    |    1     |    2     |
    +----------+----------+----------+----------+----------+----------+----------+
  
   where:

    VER             A single byte field that specifies the version of the PERCY protocol being used.
                    Currently X'01' is the only available version.

    PASSPHRASE      A six byte field that specifies a passphrase to authorize the request.

    TYPE            A single byte field that specifies the type of the method being requested.
                    The values are:

                    X'00'               a retrieval request

                    X'01'               a modification request

                    X'02'               a server response

    METHOD         A single byte field that specifies the method being requested.

    RESV           A single byte field reserved for future use.
      
    VALUE          A two byte field that specifies an OPTIONAL value for the method being requested.
                   Commonly used for modification requests. 


3.4. PERCY Response Message Format

   The response message retrieval methods responses contains field/bytes 
   in the following diagram:

        +----------+----------+----------+----------+
        |    VER   |  STATUS  |   RESV   |   VALUE  |
        +----------+----------+----------+----------+
        |     1    |     1    |    1     |     8    |
        +----------+----------+----------+----------+
  
   where:

    VER             A single byte field that specifies the version of the PERCY protocol being used.
                    Currently X'01' is the only available version.

    STATUS          A single byte field that specifies the status of the result for the requested method.
                    The values are:   
    
                    X'00'               a successful response

                    X'01'               unauthorized request 

                    X'02'               an unsuccesful response 

    RESV           A single byte field reserved for future use.

    VALUE          An eight byte field that specifies an OPTIONAL value in response of the requested method.
                   Commonly used for retrieval methods responses.                    

3.5. Conventions                                                

3.5.1. Preferred request syntax

   When making a retrieval type requests it is RECOMMENDED to set the value field as X'00'. 

3.5.2. Preferred response syntax

   When sending a response it is RECOMMENDED to set the value field with zeros for 
   modification methods.

4. Request Methods 

4.1.  Overview
         
   The request method byte is the primary source of request semantics;
   it indicates the purpose for which the client has made this request
   and what is expected by the client as a successful result.  These
   methods are divided into two categories: retrieval and modification.
   
   The values currently defined for RETRIEVAL METHODS are:

    +---------+-------------------------------------------------+-------+
    | Method  | Description                                     | Sec.  |
    +---------+-------------------------------------------------+-------+
    | X'00'   | Request the number of historical connections.   | 4.2.1 |
    +---------+-------------------------------------------------+-------+
    | X'01'   | Request the number of concurrent connections.   | 4.2.2 |
    +---------+-------------------------------------------------+-------+
    | X'02'   | Request the number of bytes sent.               | 4.2.3 |
    +---------+-------------------------------------------------+-------+
    | X'03'   | Request the number of bytes received.           | 4.2.4 |
    +---------+-------------------------------------------------+-------+
    | X'04'   | Request the number of total bytes transferred.  | 4.2.5 |
    +---------+-------------------------------------------------+-------+
    | X'05'   | Request I/O buffer sizes                        | 4.2.6 |
    +---------+-------------------------------------------------+-------+
    | X'06'   | Request selector timeout.                       | 4.2.7 |
    +---------+-------------------------------------------------+-------+
    | X'07'   | Request the number of failed connections.       | 4.2.8 |
    +---------+-------------------------------------------------+-------+

   The values currently defined for MODIFICATION METHODS are:

    +---------+-------------------------------------------------+-------+
    | Config. | Description                                     | Sec.  |
    +---------+-------------------------------------------------+-------+
    | X'00'   | Enable o disable sniffer                        | 4.3.1 |
    +---------+-------------------------------------------------+-------+
    | X'01'   | Set I/O buffer size.                            | 4.3.2 |
    +---------+-------------------------------------------------+-------+
    | X'02'   | Set selector timeout.                           | 4.3.3 |
    +---------+-------------------------------------------------+-------+

4.2. Retrieval Methods Definitions

4.2.1. Request Historical Connections

   The X'00' retrieval method returns the number of historical connections, meaning the amount of clients
   that have connected to the server.  In response of a valid X'00' request, the server MUST reply setting
   the value field with the integer number of historical connections stored in big endian format.

4.2.2. Request Concurrent Connections

   The X'01' retrieval method returns the number of concurrent connections, meaning the amount of clients
   that are connected to the server.  In response of a valid X'01' request, the server MUST reply setting
   the value field with the integer number of concurrent connections stored in big endian format.

4.2.3. Request Bytes Sent

   The X'02' retrieval method returns the number of bytes sent from a client to the origin server.  In response of
   a valid X'02' request, the server MUST reply setting the value field with the integer number of bytes sent by the
   server stored in big endian format.

4.2.4. Request Bytes received

   The X'03' retrieval method returns the number of bytes received by a client from the origin server.  In response of a
   valid X'03' request, the server MUST reply setting the value field with the integer number of bytes received by the
   server stored in big endian format.

4.2.5. Request Bytes Transferred

   The X'04' retrieval method returns the number of total bytes transferred by the proxy.  In response of a valid
   X'04' request, the server MUST reply setting the value field with the integer number of bytes received by the server
   stored in big endian format.

4.2.6. Request I/O Buffer Size

   The X'05' retrieval method returns the size of the I/O buffer used by the server.  In response of a valid X'05'
   request, the server MUST reply setting the value field with the integer value of the I/O buffer size used by the
   server stored in big endian format.

4.2.7. Request Selector Timeout

   The X'06' retrieval method returns the interval in seconds the selector should block waiting for a connection
   to become ready.  In response of a valid X'06' request, the server MUST reply setting the value field with the
   integer interval in seconds stored in big endian format.

4.2.8. Request Failed Connections

   The X'07' retrieval method returns the number of failed.  In response of a valid X'07' request, the server
   MUST reply setting the value field with the integer number of failed connections stored in big endian format.

4.3. Modification Methods Definitions

4.3.1 Enable o disable sniffer

   The X'00' modification method disables or enables the proxy sniffer. The desired size MUST be one of the following
   integers stored in big endian format specified in the value field. 1 to enable, 0 to disable.  In response of a
   valid X'00' request, the server MUST reply with a X'00' state.

4.3.2. Set I/O Buffer Size

   The X'01' modification method sets the size of the buffers dedicated to I/O operations by the server.
   The desired size MUST be an integer value between 1024 and 8192 stored in big endian format specified in
   the value field.  In response of a valid X'01' request, the server MUST reply with a X'00' state.

4.3.3. Set Selector Timeout

   The X'02' modification method sets the interval in seconds the selector should block waiting for a connection
   to become ready. The desired interval MUST be an integer value between 4 and 12 stored in big endian format
   in the value field. In response of a valid X'02' request, the server MUST reply with a X'00' state.

4.4. Method Error Handling

4.4.1. Retrieval Methods

   A server SHOULD reply with a X'00' status to all retrieval methods, except for unauthorized requests.

4.4.2. Modification Methods

4.4.2.1. Enable o disable sniffer (Sec. 4.3.1.)

   When the value received in the value field is invalid, the server MUST reply with
   a X'02' state.

4.4.2.2. Set I/O Buffer Size (Sec. 4.3.2.)

   When the value received in the value field is invalid, the server MUST reply with
   a X'02' state.

4.4.2.3. Set Selector Timeout (Sec. 4.3.3.)

   When the value received in the value field is invalid, the server MUST reply with
   a X'02' state.

4.4.3. Unauthorized Requests

   When the value received in the passphrase field is invalid, the server MUST reply with
   a X'01' state.