SRM over SSL (DRAFT)

Overview of this document

This document describes how SRM is to be used when the client and server communicate with SSL.

NOTE this document contains details that has not yet been agreed by the SRMSEC group. It presents a coherent picture of how SRM-over-SSL could work.

Currently, the communication security infrastructure called Grid Security Infrastructure (GSI), supplied by Globus, is in use. GSI has considerable overlap with the SSLv3 protocol with the noticeable addition of support for delegation. Delegation allows the client and server to cooperate in creating a credential (public/private key-pair) on the server that has an identity associated with the client's end-user. This allows the SRM server to act on behalf of the end-user.

In moving from GSI to SSL, something most provide the ability to delegate that is present in GSI and missing in SSL. That something is the GridSite Delegation Service (GDS). This is a delegation API that is made available via SOAP. The basic work-flow is:

1. the client contacts the server to request a public key,
2. the server generates a public/private key-pair,
3. the server replies, sending the client the public key,
4. the client signed the public key,
5. the client sends the signed public key (i.e., the certificate) to the server.

The delegated credential is recorded in the server against some delegationID. The client can specify the delegationID or can choose to use some server-generated default value.

There are some additional operations available to the client, including:

• discover the remaining lifetime of a delegated credential,
• renewing an existing credential,
• destroying an existing credential.

The current contemporary version of this delegation service is GSI v2.0.0.

Motivation

The desire to allow the SRM protocol to operate over an SSL connection is because it allows reuse of existing high-performance, and well-tested commodity software. It may also allow the use of hardware acceleration.

Goals of this document

The document describes how clients and server are to communicate using SSL to manage storage.

Non-goals of this document

The document does not discuss how to migrate current operational usage of SRM from GSI to SSL. This is covered by a separate document.

The document does not discuss GridFTP. This protocol currently uses GSI; however, it is left as future work for some other group.

Terminology

This document refers to SRM requests, responses and operations.

An SRM request is a message sent by the client that invokes precisely one of the commands listed in the SRM API.

An SRM response is the message sent by the server as a result of some specific SRM request.

An SRM operation is some well-defined process that the end-user wishes to enact on the server. Some SRM operations are synchronous in nature and correspond to precisely one request-response pair. Other operations are asynchronous and require a request-response pair to initiate the operation and one or more request-response pairs to determine when the operation has completed.

Connecting

This section describes how a TCP connection is established, destroyed and re-established.

Establishing connection

The server MUST listen for incoming TCP connections on the well-defined port for SRM-over-SSL.

The client MUST connect to the server on the well-defined port for SRM-over-SSL using TCP.

Once the TCP connection is established, the client MUST initiate the process of establishing a secure context using SSLv3.

Certificates and CRLs

The server SHOULD require the client to supply a certificate. The client MAY reject a connection that has no server certificate.

The client SHOULD require the server to supply a certificate. The server MAY reject a connection that has no client certificate.

Both parties SHOULD ensure the validity of the remote-supplied certificate. This SHOULD be achieved by maintaining up-to-date cache of the certificate revocation list from each trusted certification authority.

Connection lifetime

Either party MUST fail the connection if the other party supplies an invalid certificate. An invalid certificate is one that is badly formed, or where there is no chain-of-trust leading to a trust anchor-point, or if the certificate has been revoked.

Once the secure connection is established and before the client has sent the first request the client SHOULD NOT disconnect from the server and the server SHOULD NOT disconnect from the client.

The client SHOULD NOT disconnect from the server after the first request has been sent and before it has received the reply. If this happens the server's behaviour is unspecified.

The server SHOULD NOT disconnect from the client after receiving the first request and before the reply has been generated if the client resubmitting the request would not result in duplicate activity. If the client resubmitting the request would result in duplicate activity then the server MUST NOT disconnect from the client.

If the server disconnects when the result from the first request is pending then the client SHOULD reconnect and resubmit the request.

After the server has replied to the clients first request, either party MAY terminate the connection; however, any behaviour MUST be in keeping with the underlying HTTP version: an HTTP v1.0 server MUST disconnect and a server implementing HTTP v1.1 MUST follow the behaviour described in RFC 2616.

After the initial request-response pair, the server MAY disconnect the connection after the client has sent a request that the server is yet to reply if the client resubmitting that request would not result in duplicate activity. If the client resubmitting the request would result in duplicate activity then the server MUST NOT disconnect.

If the server disconnects when the client has one or more outstanding requests then the client MUST attempt to reconnect and send the outstanding commands.

The server MUST NOT handle the initial request differently from any subsequent requests.

The client MUST NOT handle the initial response differently from any subsequent responses.

Re-establishing the connection.

The client MAY store an SSL session id to accelerate any reconnection with the server. If the client records such information then it MUST be associated with the certificate's distinguished name that was used to establish the connection.

If context information is stored then the client MUST store the information with at least the same level of protection as the user credentials used to establish the connection; e.g., same file ownership and permissions.

If the client wishes to establish a connection with the server using a certificate with the same distinguished name as was used to obtain an SSL session id then the client MAY use that session id when establishing the connection.

If the client wishes to establish a connection with the server using a certificate with a different distinguished name from the one used to obtain an SSL session id then the client MUST NOT use that session id when establishing the connection.

The server MAY use the SSL session id when establishing a connection.

The server MUST NOT fail the connection because the client supplies a session id; however, the server MAY fail the connection for other reasons.

Request lifecycle

An end-user may wish to instruct an SRM to undertake one or more operations.

Sending the request

The client MUST send the SRM request as a SOAP-encoded XML message as part of an HTTP POST request. For details, see SOAP v1.2 part-1 and part-2.

Receiving the reply

The server MUST send the reply as an SOAP-encoded XML message as the resource addressed by the HTTP POST request. For details, see SOAP v1.2 part-1 and part-2.

Delegation

Delegation is the process of establishing a credential on the server that the server may use to conduct activity "on behalf of" the user.

Delegation endpoint

The standard delegation service is GDS v2.0.0 that is available at the same endpoint as the SRM endpoint.

The server MUST provide the standard delegation service. The server MAY provide alternative delegation services provided they do not interfere with the standard delegation service.

When the client wishes to delegate it SHOULD use the standard delegation service. If the client attempts to use a different delegation service that fails then the client MUST try the standard delegation service before failing.

When to delegate

SRM provides no mechanism to allow the client to determine which operations require delegation. Therefore the client cannot know which operations require delegation.

The client SHOULD ensure the server has a delegated credential before making any request.

The client MAY check if the server has a suitable delegated credential before delegating. If the server has such a delegated credential then the client MAY choose not to delegate.

Which delegationID to use

Each delegated credential created using the standard delegation service has an associated ID: the delegationID.

The client MAY choose the delegationID or it MAY adopt a server chosen default ID. If the client chooses the delegationID then it SHOULD use a naming scheme to reduce the risk that some other client might choose the same ID.

Identifying which delegated credential the user is to use

If the client has used a delegation service to establish a delegated credential, or the client has established an existing delegated credential that the client wishes to use for an operation then the client MUST inform the server which delegated credential is to be used.

The client MUST use the SRM argument authorizationID to specify which delegated credential is to be used.

If the client used the standard delegation service and chose the delegationID then the authorizationID field MUST have a value of the form gds:id, where id is the delegationID.

If the client used the standard delegation service and the client used the default delegation ID then the client MUST supply the authorizationID field with the value gds:@DEFAULT.

If the client used some delegation service other than the standard delegation service then the client MUST supplied a non-empty authorizationID and the value MUST NOT start gds:

If the client did not delegate a credential to the server then the client MUST NOT provide a value for the authorizationID field.

Behaviour if server has no valid delegated credential.

If the client failed to delegate then the SRM request will have an empty authorizationID field.

If authorizationID is empty and the request does not require delegated credential then the server SHOULD attempt to process the request.

If authorizationID is empty and the request requires a delegated credential then the server MUST fail the request. The TStatusCode MUST be SRM_INVALID_REQUEST and the explanation field SHOULD clearly state that the problem was a lack of delegation.

If authorizationID is non-empty then the client is identifying some delegated credential.

If authorizationID does not identify a credential known to the server then the server MUST fail the request. The TStatusCode MUST be SRM_INVALID_REQUEST and the explanation field SHOULD clearly state that the problem was a due to an unknown delegated id.

If authorizationID identifies a credential that has expired then the server MUST fail the request. The TStatusCode MUST be SRM_INVALID_REQUEST and the explanation field SHOULD clearly state that the problem was that the delegated credential has expired.

If authorizationID identifies a credential that has been destroyed then the server MUST fail the request. The TStatusCode MUST be SRM_INVALID_REQUEST and the explanation field SHOULD clearly state that the problem was because the delegated credential was destroyed.

The client MUST NOT use the TStatusCode or explanation fields to determine which requests require delegation.

Server behaviour if credential expires or is destroyed

If an asynchronous operation has been started that requires a delegated credential and the credential expires then the server MUST abort the operation as if the client issued a srmAbortRequest. Subsequent srmStatusOf requests MUST fail with SRM_ABORTED and the explanation field SHOULD clearly state that the operation was aborted because the delegated credential has expired.

If an asynchronous operation has been started that requires a delegated credential and the credential is destroyed then the server MUST abort the operation as if the client issued a srmAbortRequest. Subsequent srmStatusOf requests MUST fail with SRM_ABORTED and the explanation field SHOULD clearly state that the operation was aborted because the delegated credential was destroyed.

If an asynchronous operation has been started that does not require a delegated credential, the client supplies a delegated credential and the delegated credential either expires or is destroyed then the server SHOULD NOT abort the operation.

Renewing credentials

While an asynchronous operation is being processed the client MAY query the delegation service to determine in the certificate is about to expire.

The client MAY choose to renew a certificate if the remaining lifetime drops below some threshold value. The threshold value SHOULD include an element of randomness; for example, the value could be a + b*r where r is a random number between 0 and 1 and a and b are constants. This randomness is to prevent multiple clients attempting to renew the same credential concurrently.

If the client renews a delegated certificate then the server SHOULD use the renewed certificate.

If an asynchronous operation was aborted because a required delegated credential has expired then renewing that credential SHOULD NOT re-enable that operation.

Destroying credentials

The standard delegation service allows a client to request the immediate removal (destroy) of the delegated credential.

The client MUST NOT destroy the delegated credential if there are ongoing operations initiated with that delegationID

If the client chose the delegationID and there are no ongoing operations using that credential then the client MAY destroy the delegated credential.

If the client uses the default delegation ID then the client MUST NOT destroy the delegation credential.

-- PaulMillar - 17-Nov-2010