//tabstop=4
//***********************************************************************
// ORBAsec SL3                                                     
// ----------------------------------------------------------------------
// Copyright (C) 2001 Adiron, LLC.                                 
//                    All rights reserved.                         
// ----------------------------------------------------------------------
// $Id$
//***********************************************************************
//
// Marked modifications Copyright (C) 2002, 2003 ObjectSecurity Ltd.
//
#ifndef _USER_PASSWORD_IDL_
#define _USER_PASSWORD_IDL_

#include <mico/security/sl3pm.idl>

#include <mico/security/gssup.idl>

#pragma prefix "adiron.com"

/**
 * This module contains two valuetypes
 * used to implement the UserPassword CSI Client Authentication
 * protocol. The application writer extends these classes with
 * the proper implementation.
 * <p>
 * We are using valuetypes here, instead of local interfaces, 
 * because local interfaces require a POA to be activated. This situation
 * is not good for the client. Also, making invocations on local objects
 * is problematic during outcalls from the security service.
 *
 */
module UserPassword {

    /**
     * Values of type ErrorCode are returned from the PasswordGenerator
     * and PasswordProcessor.
     */
    typedef unsigned long ErrorCode;
    
    /** Successful return */
    const ErrorCode EC_Success     = 0;
    /** Unspecified Error */
    const ErrorCode EC_Unspecified = GSSUP::GSS_UP_S_G_UNSPECIFIED;
    /** Processor Error, named user is unknown */
    const ErrorCode EC_NoUser      = GSSUP::GSS_UP_S_G_NOUSER;
    /** Processor Error, password for user is invalid */
    const ErrorCode EC_BadPassword = GSSUP::GSS_UP_S_G_BAD_PASSWORD;
    /** Generator Error, target name is supported or unknown */
    const ErrorCode EC_BadTarget   = GSSUP::GSS_UP_S_G_BAD_TARGET;
    
    /**
     * This local interface is an generator that represents one principal
     * but may have many different names and passwords under different
     * realms.
     * <p>
     * An application writer extends each of the generated implementations
     * of each operation of this valuetype.
     */

    // change to local interface from valuetype done by ObjectSecurity

    local interface PasswordGenerator {
    
        /**
         * This operation returns the PrincipalName of the 
         * represented local principal for the credentials.
         * The principal named here, will show up as a quoting principal
         * over any transport principal the CSI Credentials are based upon.
         * An outcall from the security service is made on this operation
         * once. It is made when the credentials are being created.
         */
        SL3PM::PrincipalName 
	client_authentication_principal();

        /**
         * This operation returns true if for a given target realm,
         * a user name exists with a password. An outcall from the 
         * security service is made on this operation
         * every time a context needs to be
         * established with the target, creating a CSI Client Authentication
         * Token using the CSI GSSUP Client Authentication Mechanism.
         *
         * @param target   The name of the Client Authentication
         *                 realm of the target.
         * @param username Return of the username for the requested realm.
         * @param password Return of the password for the username.
         * @return   True if username and password are found for the
         *           target, and username and password contain meaningful
         *           values.
         */ 
        ErrorCode generate_password(
	    in SL3PM::PrincipalName   target,
            out wstring                        username,
            out wstring                        password
        );
    };
    
    /**
     * This local interface is a processor for verifying user name passwords
     * using the CSI GSSUP Client Authentication mechanism.
     * <p>
     * An application writer extends each of the generated implementations
     * of each operation of this valuetype.
     */

    // change to local interface from valuetype done by ObjectSecurity

    local interface PasswordProcessor {
    
        /**
         * This operation returns true if client authentication
         * using this mechanism at the CSI Client Authentication Layer
         * is required. If this operation returns false, then if a 
         * Client Authentication token is not delivered, the invocation
         * may still be accepted.
         */
        boolean client_authen_required();
        
        /**
         * This operation returns the principal name that represents
         * the authentication realm. An outcall from the security service
         * will be made on this operation during credentials setup to
         * establish the CSI IOR Component.
         */
        SL3PM::PrincipalName
            password_target();
        
        /**
          * This operation returns EC_Success if the password for the named
          * principal is valid. An call is made to this operation by
          * the Server Side Security service's CSI ClientAuthentication Layer
          * every time a CSI Client Authentication Token needs to be
          * verified.
          */
        ErrorCode verify_password(
            in  wstring                       username,
            in  wstring                       password,
            out SL3PM::PrincipalName principal
        );
    };
};
#endif // _USER_PASSWORD_IDL_