MyProxyv2 protocol


Section A
------- -

Basic Tenants:
 
 1) All communications between MyProxy process will be authenticated
    via GSSAPI. The MyProxyServer will always be the accepting side and
    will have an identity of "host/<fully qualified host name>" or
    "myproxy/<fully qualified host name>".
 
 2) The transport protocol will be SSL (Kerberos support is planned)
    Each message will be integrity protected and encrypted via gss_wrap().
 
 3) Messages will consist of either one or more NULL-terminated ASCII text
    strings or a single chunk of arbitrary data whose meaning is determined
    by the context of the current state of the protocol.
 
 4) All communications will be over TCP.
 
 5) By default the MyProxy server will listen on port 7512 unless
    otherwise specified. [NOTE - the port number choice is arbitrary.]
 
 6) MyProxy server always replies to the requests with either a OK,
    ERROR, or AUTHORIZATION message:

    An OK message will simply contain:
 
    VERSION=MYPROXYv2
    RESPONSE=0
 
    An ERROR message will contain:
 
    VERSION=MYPROXYv2
    RESPONSE=1
    ERROR=<error text>
    ERROR=<error text>
    ...
  
    There may be one or more lines of error text, with the intent that the
    client may concatenate them together (separated with carriage returns).
	
    The line separator is the LF character: '\n'.

    After sending an ERROR response myproxy-server will close the
    connection and no more data should be sent in either direction.

    If the client sends an empty passphrase, the server can also reply
    with a MYPROXY_AUTHORIZATION_RESPONSE message:

    VERSION=MYPROXYv2
    RESPONSE=2
    AUTHORIZATION_DATA=<method id>:<method data>
    ...

    There may be more then one line of authorization data. The purpose
    of this message is to provide the client with available
    authorization methods along with data needed to use the
    methods. The client will choose one method, create a response
    according to server's challenge and send it back to the server.
    The first four bytes of the response convey a method
    identifier (see myproxy_authorization.[ch] for supported methods).
    Currently, the identifier is specified in the first byte only.
    The remaining three bytes are ignored.
    The contents of the remaining part of the response depends on the
    particular authorization method and is not specified here.

    The server will verify the response, check authorization data,
    check authorization policy and reply with either an OK or an ERROR
    message. Then the protocol will continue.

    Currently there are two supported methods: the original password
    based and a new X.509 certificate based. When using the later one,
    the server will generate a random 32 bytes long challenge, encode
    it into an ASCII string and send to the client as <method
    data>. The client will sign the challenge with its private key and
    send the result back along with the whole certificate chain.
    Format of the client's response in this case is following:
      - first four bytes state length of the signature
      - signature itself
      - four bytes state number of certificates sent
      - certificates in the ASN.1 encoding.

    Since the original client never sends an empty password,
    compatibility is retained (the MYPROXY_AUTHORIZATION_RESPONSE
    message is sent iff the server receives an empty password).

 7) The delegated credentials are sent over the wire as a chain of 
    certificates in a _single_ message. 

    The message contains: A byte that indicates the number of certificates
    in the message followed by the certificates of the certificate chain.
    Each certificate is encoded in the stardard X.509 v3 ASN.1 format.

    The first certificate sent is the newly delegated certificate, 
    followed by the first certificate of the certificate chain,
    and the rest of the chain. The last certificate sent should be the user 
    certificate signed by the CA. The CA certificate does not have to be
    included.

 8) For protocol extensibility, clients and servers are expected to
    ignore lines in messages that they don't understand.
 
 ====

Section B
------- -
 
 MyProxyInit <-> MyProxyServer protocol
 
 The following illustrates a MyProxyInit process connecting to a
 MyProxyServer process and storing a proxy for later retrieval.
 
 1) MyProxyInit will make a connection to the MyProxyServer at the
    host and port as specified by its configuration or the user.
 
 2) MyProxyInit will initiate the GSSAPI context setup loop, with
    MyProxyServer accepting. See Section A.1. 
 
 3) MyProxyInit will then send a message to MyProxyServer containing
    the following strings:
 
    VERSION=MYPROXYv2
    COMMAND=1
    USERNAME=<username>
    PASSPHRASE=<pass phrase>
    LIFETIME=<lifetime>

    and optional strings

    RETRIEVER=<retriever_dn>
    RENEWER=<renewer_dn>
    CRED_NAME=<credential name>
    CRED_DESC=<credential description>

    The intent of the VERSION string is to allow the server to know
    if it is dealing with an outdated or newer client.
 
    <username> and <pass phrase> are the strings supplied by the
    user to be used for retrieval by the portal. <lifetime> is the
    ASCII representation of the lifetime of the proxy to be delegated
    to the portal, in seconds. <retriever_dn> and <renewer_dn> are strings 
    specifying the retriever and renewer policy regular expressions.
    <credential name> assigns a name to the credential, allowing
    multiple credentials to be stored for a given username.
    <credential description> can provide additional descriptive text
    to be displayed in MyProxyInfo requests, for example.

 4) MyProxyServer will then respond with either a OK or an ERROR message.
    See Section A.6 for details.

 5) Next, the server will perform delegation with the client.
    The MyProxyServer will generate a public/private key pair and send
    the public key to the MyProxyInit client as a certificate request.
    MyProxyInit client will sign the request with its proxy private key
    and send the new certificate and the entire certificate chain back
    to the server. 
    See section A.8 for details of the certificate chain message.

 6) MyProxyServer will read the individual certificates, chain them back
    up together into a new delegated credentials and store them. The server 
    also stores the retriever and renewer DN strings if they are specified.

 7) MyProxyServer will then respond with either a OK message if it
    successfully stored the proxy or an ERROR message if an error occurred. 
    For example, an error might occur when the stored proxy already exists
    for the same username but belongs to another user.
    For the reply message details see section A.6.
 
 8) At this point, both sides should close the connection.
 
 ====

Section C
------- -
 
 MyProxyGet <-> MyProxyServer protocol
 
 The following illustrates a MyProxyGet process connecting to
 a MyProxyServer process and retrieving a proxy for use.
 
 1) MyProxyGet makes a connection to the MyProxyServer as
    indicated by its configuration or arguments.
 
 2) MyProxyGet will initiate the GSSAPI context setup loop, with
    MyProxyServer accepting. See Section A.1. 
 
 3) MyProxyGet will then send a message to MyProxyServer containing
    the following strings:
 
    VERSION=MYPROXYv2
    COMMAND=0
    USERNAME=<username>
    PASSPHRASE=<pass phrase>
    LIFETIME=<requested lifetime>

    The message can also contain an optional string :
    CRED_NAME=<credential name>

    The intent of the VERSION string is to allow the server to know
    if it is dealing with an outdated or newer client.
 
    <username> and <pass phrase> are the strings supplied by the
    user to the portal to be used for retrieval by the portal.

 4) MyProxyServer will then respond with either a OK, ERROR, or
    AUTHORIZATION message.  See Section A.6 for details.
 
 5) Next, the server will delegate the user credential to the client.
    The MyProxyGet will generate a public/private key pair and send
    the public key to the MyProxyServer as a certificate request.
    MyProxyServer will sign the request with the private key of the stored
    user credential and send it as a new certificate back to the client 
    along with the rest of the certificate chain of the stored credential.
    See section A.7 for details of the certificate chain message.
    The MyProxyGet will then chain up the certificates together and create
    the new user credentials.

 6) MyProxyServer will then respond with either a OK message if it
    successfully completed sending the certificates or an ERROR message 
    if an error occurred. See section A.6 for details.
 
 7) At this point, both sides should close the connection.

 ====

Section D
------- -
 
 MyProxyDestroy <-> MyProxyServer protocol
 
 The following illustrates a MyProxyDestroy process connecting to
 a MyProxyServer process and removing a proxy.
 
 1) MyProxyDestroy makes a connection to the MyProxyServer as
    indicated by its configuration or arguments.
 
 2) MyProxyDestroy will initiate the GSSAPI context setup loop, with
    MyProxyServer accepting. See section A.1. 
 
 3) MyProxyDestroy will then send a message to MyProxyServer containing
    the following strings:
 
    VERSION=MYPROXYv2
    COMMAND=3
    USERNAME=<username>
    PASSPHRASE=<pass phrase>
 
    The message can also contain an optional string :
    CRED_NAME=<credential name>

    The intent of the VERSION string is to allow the server to know
    if it is dealing with an outdated or newer client.
 
    <username> and <pass phrase> are the strings supplied by the
    user to the portal used for retrieval of a proxy from the portal.

 4) MyProxyServer will then respond with either a OK or an ERROR message.
    See section A.6 for details.
 
 5) At this point, both sides should close the connection.

 ====


Section E
------- -

 MyProxyInfo <->MyProxyServer protocol

 The following illustrates a MyProxyInfo process connecting to a
 MyProxyServer process and queries information about a proxy.

 1) MyProxyInfo makes a connection to the MyProxyServer as indicated by its
    configuration or arguments.

 2) MyProxyInfo will initiate the GSSAPI context setup loop, with
    MyProxyServer accepting. See section A.1.

 3) MyProxyInfo will then send a message to MyProxyServer containing the
    following strings:

    VERSION=MYPROXYv2
    COMMAND=2
    USERNAME=<username>
    PASSPHRASE=<pass phrase>

    The intent of the VERSION string is to allow the server to know if it is
    dealing with an outdated or newer client.

    <username> and <pass phrase> are the strings supplied by the user.

 4) MyProxyServer will then respond with either a OK or an ERROR message. 
    See section A.6 for details. If the response is OK it will also contain 
    the following strings:
    
    CRED_NAME=<credential name>		        // optional
    CRED_DESC=<credential description>		// optional
    CRED_START_TIME=<start_time>		// required
    CRED_END_TIME=<end_time>			// required
    CRED_OWNER=<subject_name>			// required
    CRED_RETRIEVER=<retriever regex>		// optional
    CRED_RENEWER=<renewer regex>		// optional
    
    ADDL_CREDS=cred1,cred2,....,credn    	// If multiple creds are stored
    CRED_cred1_DESC=<credential description>	// optional
    CRED_cred1_START_TIME=<start_time>		// required
    CRED_cred1_END_TIME=<end time>		// required
    CRED_cred1_OWNER=<subject name>		// required
    CRED_cred1_RETRIEVER=<retriever regex>	// optional
    CRED_cred1_RENEWER=<renewer regex>		// optional
    ....

    The time strings carry information on lifetime of the proxy in a
    repository. Both the times are in unix format, i.e. number seconds since
    the Epoch (00:00:00 UTC January 1, 1970). The <subject_name> field
    contains DN of the proxy's owner.

 5) At this point, both sides should close the connection.
 
======

Section F
------- -

MyProxyChangePasswd <-> MyProxyServer protocol

 The following illustrates a MyProxyChangePasswd process connecting to a
 MyProxyServer process and changes password of a proxy.

 1) MyProxyChangePasswd makes a connection to the MyProxyServer as
    indicated by its configuration or arguments.

 2) MyProxyChangePasswd will initiate the GSSAPI context setup loop, with
    MyProxyServer accepting. See section A.1. 
 
 3) MyProxyChangePasswd will then send a message to MyProxyServer containing
    the following strings:
 
    VERSION=MYPROXYv2
    COMMAND=4
    USERNAME=<username>
    PASSPHRASE=<credential pass phrase>
    NEW_PHRASE=<new pass phrase>
 
    The message can also contain an optional string :
    CRED_NAME=<credential name>

    The intent of the VERSION string is to allow the server to know
    if it is dealing with an outdated or newer client.
 
    <username> and <credential pass phrase> are the strings supplied
    by the user for authentication. <new pass phrase> is the new pass
    phrase assigned to the credential.

 4) MyProxyServer will then respond with either a OK or an ERROR message.
    See section A.6 for details.
 
 5) At this point, both sides should close the connection.
 
======

Section G
------- -

MyProxyStoreCertificate <-> MyProxyServer protocol
 
 The following illustrates a MyProxyStoreCertificate process connecting to a
 MyProxyServer process and storing a proxy for later retrieval.
 
 1) MyProxyStoreCertificate will make a connection to the MyProxyServer at the
    host and port as specified by its configuration or the user.
 
 2) MyProxyStoreCertificate will initiate the GSSAPI context setup loop, with
    MyProxyServer accepting. See Section A.1. 
 
 3) MyProxyStoreCertificate will then send a message to MyProxyServer 
    containing the following strings:
 
    VERSION=MYPROXYv2
    COMMAND=5
    USERNAME=<username>
    LIFETIME=<lifetime>

    and optional strings

    RETRIEVER=<retriever_dn>
    RENEWER=<renewer_dn>
    CRED_NAME=<credential name>
    CRED_DESC=<credential description>
    KEYRETRIEVER=<retriever_dn>

    The intent of the VERSION string is to allow the server to know
    if it is dealing with an outdated or newer client.
 
    <username> is the strings supplied by the user to be used for retrieval 
    by the portal. <lifetime> is the ASCII representation of the lifetime of 
    the proxy to be delegated to the portal, in seconds. <retriever_dn> and 
    <renewer_dn> are strings specifying the retriever and renewer policy 
    regular expressions.  <key retriever dns> is a string specifying the key 
    retriever policy regular expression.  <credential name> assigns a name to 
    the credential, allowing multiple credentials to be stored for a given 
    username.  <credential description> can provide additional descriptive 
    text to be displayed in MyProxyInfo requests, for example.

 4) MyProxyServer will then respond with either a OK or an ERROR message.
    See Section A.6 for details.

 5) Next, the client will send the users end-entity credentials to the
    server. 

 6) MyProxyServer will read the individual certificates and store it. The 
    server also stores the retriever, renewer, or key retriever DN strings if 
    they are specified.

 7) MyProxyServer will then respond with either a OK message if it
    successfully stored the proxy or an ERROR message if an error occurred. 
    For example, an error might occur when the stored proxy already exists
    for the same username but belongs to another user.
    For the reply message details see section A.6.
 
 8) At this point, both sides should close the connection.
 
 ====

Section H
------- -
 
 MyProxyRetrieve <-> MyProxyServer protocol
 
 The following illustrates a MyProxyRetrieve process connecting to
 a MyProxyServer process and retrieving the end-entity credentials.
 
 1) MyProxyRetrieve makes a connection to the MyProxyServer as
    indicated by its configuration or arguments.
 
 2) MyProxyRetrieve will initiate the GSSAPI context setup loop, with
    MyProxyServer accepting. See Section A.1. 
 
 3) MyProxyRetrieve will then send a message to MyProxyServer containing
    the following strings:
 
    VERSION=MYPROXYv2
    COMMAND=6
    USERNAME=<username>
    PASSPHRASE=<pass phrase>
    LIFETIME=<requested lifetime>

    The message can also contain an optional string :
    CRED_NAME=<credential name>

    The intent of the VERSION string is to allow the server to know
    if it is dealing with an outdated or newer client.
 
    <username> and <pass phrase> are the strings supplied by the
    user to the portal to be used for retrieval by the portal.

 4) MyProxyServer will then respond with either a OK, ERROR, or
    AUTHORIZATION message.  See Section A.6 for details.
 
 5) Next, the server will retrieve the user credential and send it to the 
    client.

 6) At this point, both sides should close the connection.