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/" or "myproxy/". 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= ... 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=: ... 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 . 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= PASSPHRASE= LIFETIME= and optional strings RETRIEVER= RENEWER= CRED_NAME= CRED_DESC= The intent of the VERSION string is to allow the server to know if it is dealing with an outdated or newer client. and are the strings supplied by the user to be used for retrieval by the portal. is the ASCII representation of the lifetime of the proxy to be delegated to the portal, in seconds. and are strings specifying the retriever and renewer policy regular expressions. assigns a name to the credential, allowing multiple credentials to be stored for a given username. 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= PASSPHRASE= LIFETIME= The message can also contain an optional string : CRED_NAME= The intent of the VERSION string is to allow the server to know if it is dealing with an outdated or newer client. and 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= PASSPHRASE= The message can also contain an optional string : CRED_NAME= The intent of the VERSION string is to allow the server to know if it is dealing with an outdated or newer client. and 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= PASSPHRASE= The intent of the VERSION string is to allow the server to know if it is dealing with an outdated or newer client. and 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= // optional CRED_DESC= // optional CRED_START_TIME= // required CRED_END_TIME= // required CRED_OWNER= // required CRED_RETRIEVER= // optional CRED_RENEWER= // optional ADDL_CREDS=cred1,cred2,....,credn // If multiple creds are stored CRED_cred1_DESC= // optional CRED_cred1_START_TIME= // required CRED_cred1_END_TIME= // required CRED_cred1_OWNER= // required CRED_cred1_RETRIEVER= // optional CRED_cred1_RENEWER= // 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 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= PASSPHRASE= NEW_PHRASE= The message can also contain an optional string : CRED_NAME= The intent of the VERSION string is to allow the server to know if it is dealing with an outdated or newer client. and are the strings supplied by the user for authentication. 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= LIFETIME= and optional strings RETRIEVER= RENEWER= CRED_NAME= CRED_DESC= KEYRETRIEVER= The intent of the VERSION string is to allow the server to know if it is dealing with an outdated or newer client. is the strings supplied by the user to be used for retrieval by the portal. is the ASCII representation of the lifetime of the proxy to be delegated to the portal, in seconds. and are strings specifying the retriever and renewer policy regular expressions. is a string specifying the key retriever policy regular expression. assigns a name to the credential, allowing multiple credentials to be stored for a given username. 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= PASSPHRASE= LIFETIME= The message can also contain an optional string : CRED_NAME= The intent of the VERSION string is to allow the server to know if it is dealing with an outdated or newer client. and 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.