javax.security.auth.message.ClientAuth Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jboss-jaspi-api_1.0_spec Show documentation
JSR-196: Java Authentication SPI for Containers 1.0 API
The newest version!
package javax.security.auth.message;

import javax.security.auth.Subject;

//$Id$

/**
 *  An implementation of this interface is used to secure service request 
 *  messages, and validate received service response messages.
 *  @author Anil Saldhana
 *  @author Charlie Lai, Ron Monzillo (Javadoc for JSR-196)
 *  @since  May 11, 2006 
 *  @version $Revision$
 */
public interface ClientAuth
{
   /**
    * Remove implementation specific principals and credentials from the subject.
    * @param 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.
    * @param subject - The Subject instance from which the Principals and credentials 
    *                      are to be removed. 
    * @throws AuthException if an error occurs during the Subject processing.
    */
   public void cleanSubject( MessageInfo messageInfo, Subject subject)
   throws AuthException;
   
   /**
    * Secure a service request message before sending it to the service.
    * 
    * Sign and encrpt the service request, for example.
    * 
    * @param 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.
    * @param 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.
    * @return 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.
    */
   public AuthStatus secureRequest(MessageInfo messageInfo, Subject clientSubject)
   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.
    * 
    * @param 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.
    * 
    * @param 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.
    *                  
    * @param 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.
    * @return 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
    */
   public AuthStatus validateResponse(MessageInfo messageInfo, Subject clientSubject, 
         Subject serviceSubject)
   throws AuthException;
}