|
|
|
|
|
|
1. IntroductionThis document describes a protocol for storing and retrieving X.509 proxy credentials [RFC3820] to and from a server. The protocol uses proxy delegation [ProxyDelegation] to transfer credentials without transferring private keys. The protocol allows long-lived keys to be secured on the server while allowing convenient access to short-lived proxy credentials as needed. The protocol can also support retrieving X.509 end entity certificates [RFC3280] from a MyProxy server operating in Certificate Authority mode. Section 2 specifies the core MyProxy protocol, which is also specified in Global Grid Forum Experimental Document GFD-E.54 (but please see GFD-E.54 Errata below). Section 3 specifies backward-compatible protocol extensions and is updated as new extensions are developed. 2. The Core MyProxy ProtocolThe core MyProxy protocol was implemented in MyProxy v0.2 in September 2000. It represents the minimum requirements for a compatible MyProxy implementation. The protocol has since been extended to implement additional functionality. This section specifies the core protocol, and the following sections specify extensions. 2.1 MyProxy TCP PortThe MyProxy server listens on TCP port 7512. 2.2 Initializing the ConnectionUpon TCP connection establishment, the client and server perform the TLS protocol [RFC2246] to establish a private, authenticated channel. Server authentication via TLS is REQUIRED. The server's authenticated identity MUST have a Common Name of "fqhn", "host/fqhn", or "myproxy/fqhn", where "fqhn" is the fully qualified hostname of the server. Otherwise, the client MUST terminate the connection immediately. Clients and servers MUST support SSL 3.0 compatibility as described in [RFC2246] Section E. Clients and servers MUST NOT support SSL 2.0. Client authentication via TLS is REQUIRED for all commands except the 'Get' command (COMMAND=0), for which TLS client authentication is OPTIONAL. The server MUST support client authentication with proxy credentials, i.e., the server's TLS implementation MUST understand the proxy certificate extensions [RFC3820]. The negotiated TLS channel MUST be private, i.e., the client and server MUST NOT negotiate the NULL TLS cipher suite. Once the TLS handshake is complete and the secure channel has been established, the client sends one ASCII zero character 0x30 ('0') over the TLS channel in a dedicated TLS record (i.e., an application-level "flush" may be required to ensure this byte is transmitted in a separate TLS record from the following MyProxy protocol message). The server MUST ignore this first byte. The byte is sent for compatibility with the Globus Toolkit GSI protocol [GSI]. The MyProxy application protocol then proceeds over the TLS channel as follows. 2.3 Messaging OverviewMyProxy protocol messages are NULL-terminated UTF-8 text strings containing one or more lines of ATTRIBUTE=VALUE statements, separated by the newline character 0x0a ('\n'). Client requests contain:
followed optionally by additional ATTRIBUTE=VALUE lines. The COMMAND line specifies the requested command. The USERNAME line specifies a string identifying the "account" for storing the proxy credential. This "account" need not correspond to any system account outside MyProxy. The PASSPHRASE line specifies a passphrase used to protect the stored proxy credential. It MUST be a minimum of 6 characters in length. The LIFETIME line specifies the lifetime of the retrieved proxy credential in seconds, not exceed one billion seconds. These parameters are specified in detail for each command in the following sections. In the core protocol, the server replies to the requests with the following to indicate success:
or replies with the following to indicate 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) for display. After sending an error response, the server MUST immediately close the connection. For protocol extensibility, clients and servers MUST ignore lines in messages that they don't understand. Clients and servers MUST send lines in the order specified. In cases where multiple rounds of request and reply messages are possible, they are presented sequentially (non-pipelined) below. Clients MAY send multiple request messages before receiving replies for improved performance. On error, the server MUST ignore any remaining incoming data and terminate the connection. 2.4 The 'Get' Command (COMMAND=0)This command retrieves a proxy credential from the server. The client sends:
The USERNAME line identifies the account in which the credential to be retrieved has been stored. The PASSPHRASE line specifies the passphrase protecting the proxy credential. The server MUST verify the passphrase and reject the request if the pass phrase does not match. The LIFETIME is the requested proxy credential lifetime in seconds. The server MAY return a credential with a shorter lifetime according to its local policies. VONAME and VOMSES are optional. The VONAME line specifies the name of VO to connect VOMS server. Multiple VONAMEs can be specified in the message. The VOMSES line specifies VOMS server information under 'vomses' file format, "nickname" "voms-server" "port" "server host dn" "voname" ["gt ver"]. Multiple VOMSESs can be specified in the message. The MyProxy server will then send a RESPONSE message. If the RESPONSE indicates failure (RESPONSE=1), the server will terminate the connection. If the RESPONSE indicates success (RESPONSE=0), the protocol proceeds as follows. The client will generate a public/private key pair and send a NULL-terminated DER-encoded PKCS#10 [RFC2986] certificate request to the server. The server will then send either (a) a proxy certificate [RFC3820], containing the public key from the certificate request, signed by the private key of the stored credential, or (b) an end entity certificate [RFC3280], containing the public key from the certificate request, signed by the private key of MyProxy CA. The certificate is followed by the corresponding certificate chain. The server will set the subject of the proxy certificate as specified in [RFC3820] Section 3.4, ignoring the subject in the client's certificate request. The format of the server's message is: one byte (unsigned binary) encoding the number of certificates to be sent (255 maximum), followed by the newly signed certificate, followed by the certificates in the chain. Each certificate is DER-encoded. The certificate chain MUST include the end-entity certificate signed by a CA, and MAY also include CA certificates. When VONAME appears in the message, the server will generate VOMS proxy certificate using VONAME and VOMSES, or the server's VOMS server information. The server will set the lifetime of VOMS proxy certificate and VOMS attribute will be same as LIFETIME in the message. The server will then send a standard RESPONSE message, and both client and server will close the connection. 2.5 The 'Put' Command (COMMAND=1)This command stores a proxy credential on the server. the client sends:
The USERNAME line identifies the account in which to store the credential. The PASSPHRASE line specifies the passphrase for protecting the proxy credential. The pass phrase MUST be at least 6 characters in length. The server MUST enforce this passphrase length restriction, and MAY optionally enforce additional passphrase quality policies. LIFETIME sets the maximum lifetime allowed for retrieved proxy credentials in seconds. The server MUST enforce this maximum lifetime on subsequent 'Get' requests. Note that the passphrase does not authenticate the 'Put' request but will authenticate later 'Get' requests. The 'Put' request is authenticated via TLS. The MyProxy server will then send a RESPONSE message. If the RESPONSE indicates failure (RESPONSE=1), the server will terminate the connection. If the RESPONSE indicates success (RESPONSE=0), the protocol proceeds as follows. The server will generate a public/private key pair and send a NULL-terminated PKCS#10 [RFC2986] certificate request to the client. The client will then send a proxy certificate [RFC3820], containing the public key from the certificate request, signed by its private key, followed by the corresponding certificate chain, back to the server. The client will set the subject of the proxy certificate as specified in [RFC3820] Section 3.4, ignoring the subject in the server's certificate request. The format of the client's message is: one byte (unsigned binary) encoding the number of certificates to be sent (255 maximum), followed by the newly signed proxy certificate, followed by the certificates in the chain. Each certificate is DER-encoded. The certificate chain MUST include the end-entity certificate signed by a CA, and MAY also include CA certificates. The server then stores the credentials and sends a standard RESPONSE message indicating whether the credentials were successfully stored. Then both client and server close the connection. 2.6 The 'Info' Command (COMMAND=2)This command provides information about the existence of stored credentials. The client sends:
USERNAME identifies the account for which information is requested. PASSPHRASE and LIFETIME are unused. The client SHOULD send the above values for PASSPHRASE and LIFETIME for backward compatibility. The server SHOULD ignore the PASSPHRASE and LIFETIME lines. The MyProxy server will then send a RESPONSE message. If the credentials exist and match the client's authenticated identity, the server will send a successful response (RESPONSE=0). Otherwise, the server's response will indicate failure (RESPONSE=1). The client and server will then terminate the connection. A successful response MAY include additional information about the credentials. See the Protocol Extensions section below for the current set of extensions to this command. 2.7 The 'Destroy' Command (COMMAND=3)This command removes credentials stored on the server. The client sends:
USERNAME identifies the account for the credential to be removed from the server. PASSPHRASE and LIFETIME are unused. The client SHOULD send the above values for PASSPHRASE and LIFETIME for backward compatibility. The server SHOULD ignore the PASSPHRASE and LIFETIME lines. The MyProxy server will then send a standard RESPONSE message indicating whether the credentials were successfully removed. The client and server will then terminate the connection. 3. Protocol Extensions3.1 AuthorizationThe server MAY also reply with an Authorization message, indicating that additional client authentication is required for the requested operation:
The authorization methods are specified in Section 4. 3.2 The Password Change Command (COMMAND=4)This command changes the password protecting the stored credentials. It was introduced in MyProxy v0.5 in November 2002. The client sends:
USERNAME identifies the account for which to change the credential's pass phrase. The PASSPHRASE line specifies the current pass phrase protecting the proxy credential, and the NEW_PHRASE line specifies the new pass phrase to use. The new pass phrase MUST be at least 6 characters in length. The server MUST enforce this pass phrase length restriction, and MAY optionally enforce additional pass phrase quality policies. LIFETIME is unused. The client SHOULD send LIFETIME=0 for backward compatibility. The server SHOULD ignore the LIFETIME line. The MyProxy server will then send a standard RESPONSE message indicating whether the pass phrase was successfully changed. The client and server will then terminate the connection. 3.3 The Store Credential Command (COMMAND=5)This command stores an end-entity credential on the server. It was introduced in MyProxy v0.6.5 in April 2005. The client sends:
The USERNAME line identifies the account in which to store the credential. The PASSPHRASE line is unused. LIFETIME sets the maximum lifetime allowed for retrieved proxy credentials in seconds. The server MUST enforce this maximum lifetime on subsequent Get requests. The MyProxy server will then send a RESPONSE message. If the RESPONSE indicates failure (RESPONSE=1), the server will terminate the connection. If the RESPONSE indicates success (RESPONSE=0), the protocol proceeds as follows. The client sends the certificate, followed by the corresponding private key, followed by any additional certificates in the chain, in PEM format to the server. The server then stores the credentials and sends a standard RESPONSE message indicating whether the credentials were successfully stored. Then both client and server close the connection. 3.4 The Retrieve Credential Command (COMMAND=6)This command retrieves an end-entity credential from the server. It was introduced in MyProxy v0.6.5 in April 2005. The client sends:
The USERNAME line identifies the account in which the credential to be retrieved has been stored. The PASSPHRASE line specifies the pass phrase protecting the credential. The server MUST verify the pass phrase and reject the request if the pass phrase does not match. LIFETIME is unused. The MyProxy server will then send a RESPONSE message. If the RESPONSE indicates failure (RESPONSE=1), the server will terminate the connection. If the RESPONSE indicates success (RESPONSE=0), the protocol proceeds as follows. The server sends the certificate, followed by the corresponding private key, followed by any additional certificates in the chain, in PEM format to the client, then both client and server close the connection. 3.5 Requesting Trust RootsThe MyProxy server can send trust roots (CA certificates, certificate revocation lists, signing policy files) to clients on request. Clients include the following line in their request message to indicate that trust roots are desired:
For example:
The server MAY ignore the request for trust roots. Otherwise, the server will include the trust roots in the RESPONSE=0 message, as follows:
Note: trusted certificate filenames MUST NOT contain commas (for obvious reasons). 3.6 The Get Trust Roots Command (COMMAND=7)To request the MyProxy server to send trust roots, as above, without performing any other operation, the client can send this command, introduced in MyProxy v4.6 in March 2009. The client sends:
The MyProxy server will reply with a RESPONSE message, as usual. If the RESPONSE indicates success (RESPONSE=0), it will contain TRUSTED_CERTS and FILEDATA_ lines as above. 4. Authorization ChallengesAs specified in Section 3.1, the server MAY send an Authorization message, indicating that additional client authentication is required for the requested operation:
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. For example:
The client will choose one method, create a response according to server's challenge and send it back to the server. Upon receiving the client's response, the server can then respond with either RESPONSE=0, RESPONSE=1, or RESPONSE=2. The currently available methods, specified in the following subsections, are: 4.1. Password AuthorizationThe password method data from the server indicates a password prompt to be displayed to the user. The client returns a message containing:
4.2. Certificate AuthorizationThe X509_certificate method data from the server is a 16 byte random number, encoded in 32 byte hexadecimal ASCII character string. This random number is a challenge that must be signed by the client to prove posession of a private key. The client returns a message containing:
The server then verifies the signature, validates the certificate chain, and verifies that the Subject of the certificate chain matches the certificate stored in the MyProxy repository. 4.3. SASL AuthorizationThe SASL method allows negotiating an authentication protocol via the Simple Authentication and Security Layer. If the client wishes to perform SASL authorization in response, it sends:
The server responds with:
The SASL mechanisms in the list are separated by spaces and the list is Base64-encoded. For example, if the server supports the GSSAPI and PLAIN mechanisms, it will send:
The client responds with:
The above message is Base64 encoded. The server responds with:
The client responds with:
The client and server repeat the SASL challenge/response exchange until the SASL mechanism succeeds or fails. The MyProxy server indicates success or failure via a standard RESPONSE=0 or RESPONSE=1 reply. 5. Security ConsiderationsThe required use of server-authenticated TLS protects the MyProxy protocol against standard network-based attacks. The MyProxy server must verify that the (TLS authenticated) client is authorized to perform requested operations and deny unauthorized requests, to (for example) protect against one user overwriting (via 'Put') or removing (via 'Destroy') another user's credentials from the repository. Servers may also want to restrict the 'Info' command to authorized clients. In the case of the 'Get' command, where TLS client authentication is optional, the client must authenticate with the credential passphrase. Care should be taken to maintain the integrity of client systems to protect against passphrase stealing attacks from keyboard sniffers, trojans, and similar techniques. Additionally, client-side trusted TLS certificates should be carefully configured to ensure the client is connecting to a MyProxy server with a certificate issued by a trusted authority. The MyProxy credential repository must be well secured, as a large number of stored credentials could be vulnerable in the case of a server compromise. The server should be secured to the level of a Kerberos KDC. MyProxy servers must encrypt stored credentials with the salted, user-chosen passphrase from the Put command, and servers must not store the passphrase. This forces an attacker who compromises the server to perform a brute-force, dictionary attack to decrypt the credentials or an online attack to obtain passphrases from Get commands on the server. 6. AcknowledgementsJason Novotny, Steve Tuecke, and Von Welch designed the core MyProxy protocol. References
GFD-E.54 ErrataThe following corrections apply to the MyProxy protocol specifications in GFD-E.54 and the MyProxy article in Software: Practice and Experience:
Last modified
01/19/10. |
![[Valid CSS]](http://jigsaw.w3.org/css-validator/images/vcss)
![[Valid Atom 1.0]](http://grid.ncsa.illinois.edu/myproxy/valid-atom.png)
