javax.security.auth.message

Interface ClientAuth

All Known Subinterfaces:

ClientAuthContext, ClientAuthModule

All Known Implementing Classes:

JBossClientAuthContext, SimpleClientAuthModule

public interface ClientAuth

An implementation of this interface is used to secure service request messages, and validate received service response messages.

Since:

May 11, 2006

Version:

$Revision$

Author:

Anil Saldhana, Charlie Lai, Ron Monzillo (Javadoc for JSR-196)

Method Summary

Methods

Modifier and Type	Method and Description
void	cleanSubject(MessageInfo messageInfo, Subject subject) Remove implementation specific principals and credentials from the subject.
AuthStatus	secureRequest(MessageInfo messageInfo, Subject clientSubject) Secure a service request message before sending it to the service.
AuthStatus	validateResponse(MessageInfo messageInfo, Subject clientSubject, Subject serviceSubject) Validate a received service response.

Method Detail

cleanSubject

void cleanSubject(MessageInfo messageInfo,
                Subject subject)
                  throws AuthException

Remove implementation specific principals and credentials from the subject.

Parameters:

messageInfo - - A contextual object that encapsulates the client request and server response objects, and that may be used to save state across a sequence of calls made to the methods of this interface for the purpose of completing a secure message exchange.

subject - - The Subject instance from which the Principals and credentials are to be removed.

Throws:

AuthException - if an error occurs during the Subject processing.

secureRequest

AuthStatus secureRequest(MessageInfo messageInfo,
                       Subject clientSubject)
                         throws AuthException

Secure a service request message before sending it to the service.

Sign and encrpt the service request, for example.

Parameters:

messageInfo - - A contextual object that encapsulates the client request and server response objects, and that may be used to save state across a sequence of calls made to the methods of this interface for the purpose of completing a secure message exchange.

clientSubject - - A Subject that represents the source of the service request, or null. It may be used by the method implementation as the source of Principals or credentials to be used to secure the request. If the Subject is not null, the method implementation may add additional Principals or credentials (pertaining to the source of the service request) to the Subject.

Returns:

an AuthStatus object representing the completion status of the processing performed by the module.

• AuthStatus.PROCEED returned when the application request message was successfully secured. The runtime may proceed to send the request message. returned in AuthParam.
• AuthStatus.RETRY returned when the module replaces the application request message with an mechanism specific message to be sent in advance of the application message. The runtime should throw an exception if it is unable to process the rety. Otherwise, the runtime should send the request message returned in AuthParam (and without calling secureRequest).
• AuthStatus.ERROR returned when the processing by the module failed and indicates that the module has defined an appropriate error request message in the AuthParam. The runtime may send the request message returned in AuthParam (without calling SecureRequest), and must discontinue its processing of the application request.

Throws:

AuthException - when the module wishes to signal a failure in securing the request and without establishing a corresponding error request message. The runtime must discontinue its processing of the message exchange.

validateResponse

AuthStatus validateResponse(MessageInfo messageInfo,
                          Subject clientSubject,
                          Subject serviceSubject)
                            throws AuthException

Validate a received service response.

This method is called to transform the mechanism-specific response message acquired by calling getResponseMessage (on messageInfo) into the validated application message to be returned to the message processing runtime. If the response message is a (mechanism-specific) meta-message, the method implementation must attempt to transform the meta-message into the next mechanism-specific request message to be sent by the runtime.

Parameters:

messageInfo - - A contextual object that encapsulates the client request and server response objects, and that may be used to save state across a sequence of calls made to the methods of this interface for the purpose of completing a secure message exchange.

clientSubject - - A Subject that represents the recipient of the service response, or null. It may be used by the method implementation as the source of Principals or credentials to be used to validate the response. If the Subject is not null, the method implementation may add additional Principals or credentials (pertaining to the recipient of the service request) to the Subject.

serviceSubject - - A Subject that represents the source of the service response, or null. If the Subject is not null, the method implementation may add additional Principals or credentials (pertaining to the source of the service response) to the Subject.

Returns:

an AuthStatus object representing the completion status of the processing performed by the module.

• AuthStatus.PROCEED returned when the validation of the application response message succeded. The runtime may proceed to return the response message in the AuthParam to the application.
• AuthStatus.RETRY returned when the message validation succeded, but when the validated message is a mechanism specific message sent in advance of the application message. The runtime must not proceed to process the response message in the AuthParam. The runtime should throw an exception if it is unable to process the retry. Otherwise, it should send the request message returned in AuthParam (and without calling secureRequest).
• AuthStatus.ERROR returned when the validation failed and indicates that the module has defined an appropriate error request message in the AuthParam. The runtime must not proceed to process the response message in the AuthParam, and may send the request message returned in AuthParam (and without calling secureRequest).

Throws:

AuthException