3.1 Example 1: GSS Authentication Protocol Process - Stock Quote Server

This example describes the GSS authentication protocol process. It builds on the use cases for Client Authentication (section 2.5.4.1.1), Server Authentication (section 2.5.4.1.2), Mutual Authentication (section 2.5.4.1.3), Security Services: Data Origin Authentication (Signing) (section 2.5.6.1), Security Services: Data Confidentiality (Sealing) (section 2.5.6.2), and their dependent use cases.

Every application protocol uses its own mechanism to transport the GSS-API security tokens from an Application Client to an Application Server. The following example explains the interactions of the Authentication Client, the Authentication Server, and the Authentication Authority (AA) through GSS-APIs [RFC2743].

This example is particularly useful for application architects and developers to design and implement application protocols that interoperate with Authentication Services.

To illustrate the use of authentication, this example uses the simple Stock Quote Service block protocol that specifies the retrieval and update of stock quotes from the Stock Quote Server.

The following table defines Stock Quote Request and Response messages without authentication data support.

Field	Field function
Length	The length of the message
Message Type	The message type (3 is an error message; 1 is a reply; 0 is a request)
Request Type	The requested action (0 is a query; 1 is an update)
Stock Symbol	The stock symbol
Stock Price	The stock price (optional)
Error code	The error code (0 is success; nonzero is failure)

Table 1: Stock Quote Service messages without authentication data support

To get the latest stock quote price, the Stock Quote Client sends a request message, as defined in Table 1, to the Stock Quote Server and receives a response message with a stock quote price. The Stock Quote Server is not required to authenticate the client to respond with a stock quote price, because anyone can query this server, but the client requires the server authentication, confidentiality, and signing services so that the client can verify that the quote is valid and was obtained from an authentic server and that the messages were not tampered with. These services help to keep these interactions private.

The Stock Quote Server restricts stock price updates to authenticated users. To update a stock quote price, the server requires client authentication; therefore, the client authenticates to the server. To retrieve a stock quote price, the client requires server authentication; therefore, the server authenticates to the client. Both the client and the server require the assurance that the messages were not tampered with and that the message exchanges were secret; this assurance requires signing and confidentiality services.

Because the application protocol is GSS API-conformant, it is required to support transport of the authentication token.

The existing Stock Quote request and response messages are extended to hold authentication tokens and protected application data messages.

The following table defines Stock Quote Request and Response messages with authentication data support.

Field	Field function
Message Type	The message type (3 is an error message; 1 is a reply; 0 is a request).
Data Blob Type	The Data Blob field type (1 is an authentication token; 2 is application protocol data; 3 is an error message).
Length	The length of the Data Blob field.
Data Blob	The data BLOB. The contents of this field are based on the Data Blob Type field. If the Data Blob Type field is 1, then this field contains the binary BLOB of the authentication token. If the Data Blob Type field is 2, then this field contains the Request Type (0 is query; 1 is update), Stock Symbol, and Stock Price field values. If the Data Blob Type field is 3 and the Message Type field is 3, then this message contains an error code.

Table 2: Stock Quote Service messages with authentication data support

To update or retrieve the stock quote, a client and server exchange one or more request and response messages with an authentication token in the Data Blob field depending on the underlying authentication protocol. When authentication finishes, the client or server sends the Data Blob field with application data that contains stock quote details. If the initial request message does not have an authentication token, the server returns an error code, because authentication is required.

Prerequisites

This example assumes the following prerequisites in addition to the preconditions of the covered use cases:

• A TCP connection is established between the Stock Quote Client and the Stock Quote Server.

• The Stock Quote Client and the Stock Quote Server have acquired the credential handles with the GSS-API GSS_Acquire_Cred function ([RFC2743] section 2.1.1) by specifying the security package.

Initial System State

• The AA has not authenticated the client identity or the server identity.

Final System State

• The AA has authenticated both the client and the server identities.

Sequence of Events

The following steps show the basics of authentication with GSS.

Figure 29: GSS authentication process with underlying authentication protocol messages

Step 1: The Stock Quote Client calls the Authentication Client's GSS-API GSS_Init_sec_context function ([RFC2743] section 2.2.1) to obtain the security token with the acquired credential handle and null input token by specifying that it requires mutual authentication, confidentiality, and signing.

Step 2: If the Authentication Client requires information from the Authentication Authority (AA) (that is, the DC) before returning the token, the Authentication Client generates authentication messages and sends the messages to the AA. The AA validates the messages. If the messages are valid, the AA generates an authentication message and sends the reply to the Authentication Client. If the Authentication Client requires more information from the AA before returning the GSS-API token, step 2 is repeated until all the required information is obtained.

Step 3: The Authentication Client generates a new GSS-API token and if more messages are expected, returns GSS_S_CONTINUE_NEEDED. Otherwise, if this is the final message, returns GSS_S_COMPLETE, and the security token to the Stock Quote Client.

Step 4: The Stock Quote Client embeds the security token in its application message and sends the message to the Stock Quote Server by using its own application-protocol-specific method. In this example, the Stock Quote Client embeds the security token in the Data Blob field, sets the Data Blob Type field value to 1, sets the Message Type to 0, and sets the other required fields in the stock quote service message, as described in Table 2.

Step 5: The Stock Quote Server calls the Authentication Server's GSS-API GSS_Accept_sec_context function ([RFC2743] section 2.2.2) with the acquired credential handle and security token from the client by specifying the Confidentiality and Integrity flags.

Step 6: If required by the authentication protocol, the Authentication Server generates an authentication message and sends the message to the AA. The AA validates the message. If the message is valid, the AA generates an authentication message and sends the reply to the Authentication Server.

If the Authentication Server requires more information from the AA before it returns the GSS-API token, step 6 is repeated until all the required information is obtained.

Step 7: The Authentication Server validates the token. If the token is valid, the Authentication Server generates a new token if required and

• If more messages are expected, returns GSS_S_CONTINUE_NEEDED,

or

• If this is the final message, returns GSS_S_COMPLETE,

and the security token to the Stock Quote Server.

Step 8: If the Authentication Server returns a token, the Stock Quote Server embeds the security token in its application message and sends the message to the Stock Quote Client by using its own application-protocol-specific transport. In this example, the Stock Quote Server embeds the security token in the Data Blob field, sets the Data Blob Type field value to 1, sets the Message Type field to 1, and sets other required fields in the stock quote service message, as described in Table 2.

Step 9: If the Authentication Client had previously returned GSS_S_CONTINUE_NEEDED, the Stock Quote Client calls the GSS_Init_sec_context function ([RFC2743] section 2.2.1) with the token from the server.

Step 10: The Authentication Client validates the token. If the token is valid, the Authentication Client generates a new token if required and

• If more messages are expected, returns GSS_S_CONTINUE_NEEDED,

or

• If this is the final message, returns GSS_S_COMPLETE,

and the security token to the Stock Quote Client.

If GSS_S_CONTINUE_NEEDED, go to Step 5.

Step 11: The Stock Quote Client generates a Data Blob field that contains the updated stock quote data and calls the Authentication Client's GSS-API GSS_Wrap function ([RFC2743] section 2.3.3) to generate a privacy and integrity-protected copy of the application Data Blob field.

Step 12: The Authentication Client returns a privacy and integrity-protected copy of the application Data Blob field.

Step 13: The Stock Quote Client builds the request message with the protected Data Blob field and other required fields and sends the message to the Stock Quote Server by using its own application-protocol-specific transport.

Step 14: The Stock Quote Server calls the Authentication Server's GSS-API GSS_Unwrap function ([RFC2743] section 2.3.4) to verify the integrity of the protected Data Blob field and also to get the plain Data Blob field contents.

Step 15: The Authentication Server verifies the integrity of the message and returns the plain Data Blob field contents to the Stock Quote Server. The Stock Quote Server interprets and updates the stock information with the contents of the application Data Blob field.

Step 16: The Stock Quote Server calls the GSS_Wrap function ([RFC2743] section 2.3.3) with the Data Blob to get the protected Data Blob field.

Step 17: The Authentication Server returns a protected Data Blob.

Step 18: The Stock Quote Server builds the response message with the protected Data Blob field and also sets other required fields, as described in Table 2. The message is sent to the Stock Quote Client.

Step 19: The Stock Quote Client calls the GSS_Unwrap function ([RFC2743] section 2.3.4) to verify the integrity of the message and also to get the plain Data Blob field contents.

Step 20: The Authentication Client returns the plain Data Blob field contents.

The Stock Quote Client interprets the response and ends the session. When finished, both the Stock Quote Client and the Stock Quote Server release the credential handles by calling the GSS-API GSS_Release_cred function ([RFC2743] section 2.1.2).