//tabstop=4
//***********************************************************************
// ORBAsec SL3
// ----------------------------------------------------------------------
// Copyright (C) 2001 Adiron, LLC.
//                    All rights reserved.
// ----------------------------------------------------------------------
// $Id$
//***********************************************************************
#ifndef _SL3CSIArgs_IDL_
#define _SL3CSIArgs_IDL_
#include <SL3/SecurityLevel3.idl>
#include <SL3/Trust.idl>
#include <SL3/UserPassword.idl>
#include <SL3/TransportSecurity.idl>
#include <SL3/SL3AQArgs.idl>
#include <SL3OMG/ATLAS.idl>
#include <SL3/SL3Authorization.idl>
#include <SL3/ATLASCache.idl>

#pragma prefix "adiron.com"

/**
 * This module contains structures and a factory interface to
 * create tagged argument lists that will be given to the
 * args parameter of the SecurityLevel3::CredentialsCurator.
 * <p>
 * ORBAsec SL3 uses this kind of mechanism because it is the
 * easiest way to represent optional arguments.
 * <P>
 * To alleviate the hassles of dealing with any's and creating
 * them, there is a factory retrieved by ORB::resolve_initial_references
 * using "SL3:ArgumentFactory". From this object one may create an
 * acquisition argument builder. This approach takes most of the work
 * out of forming the Credentials acquisition argument.
 * The form of the arguments and their requiredness or optionality
 * are defined by the specific acquisition mechanisms using them.
 *
 * The Credentials Acquired with these arguments handle the
 * CORBA CSIv2 protocol.
 */
module SL3CSI {

    /**
     * There is currently only one acquisition method for
     * CSI based Credentials.
     */
    const SecurityLevel3::AcquisitionMethod AQM_CSIArgs = "CSIArgs";

    /**
     * An object of this interface is created by the Argument Factory Object.
     * It aids in creating the Credentials Acquisition Argument for
     * CSI based Credentials.
     */
    local interface CSIArgBuilder : SL3AQArgs::GenericArgBuilder {

        /**
         * This operation explicitly disables caching of ATLAS tokens.
         * This is used in the case where CSI credentials are needed
         * in order to communicate with an external cache. If cacheing
         * were enabled in this case, then there would be a cache for
         * the cache, which gets recursively messy.
         */
         void addSetNoLocalCache();

        /**
         * This operation adds an already existing ATLASCache as an
         * acquisition argument. This is used in the case where an
         * externalized cache is to be used. If a cache is not
         * explicitly added to the argument, then a new cache will
         * be created by the Credentials Curator.
         */
        void addATLASCache(
            in ATLASCache::AuthTokenCache cache
        );

        /**
         * This operation places a user defined Password Generator
         * in the acquisition argument.
         */
        void addUserPasswordCAGenerator(
            in UserPassword::PasswordGenerator generator
        );

        /**
         * This operation places a user defined Password Processor
         * in the acquisition argument.
         */
        void addUserPasswordCAProcessor(
            in UserPassword::PasswordProcessor  processor
        );

        /**
         * This operation causes the creation credentials that
         * have a "quoted" principal. CSI Credentials of this
         * type will assert the particular principal name to a server.
         */
        void addNamedQuotedPrincipal(
            in SecurityLevel3::PrincipalName   principal_name
        );

        /**
         * This operation causes the creation credentials that
         * have a "quoted" principal. CSI Credentials of this
         * type will assert the particular identity to a server.
         */
        void addEncodedQuotedPrincipal(
            in SecurityLevel3::IdentityStatement   identity
        );

        /**
         * This operation places a user defined Trust Decider in
         * the acquisition argument.
         */
        void addLocalTrustInServerDecider(
            in Trust::LocalTrustInServerDecider trust_decider
        );

        /**
         * This operation causes CSI Credentials to be created
         * over a particular transport as if you created the
         * transport credentials using the
         * TransportSecurity::CredentialsCurator and used the
         * addUseTransportCredentials operation of this object.
         */
        void addTransportCredentialsAQArgs(
            in TransportSecurity::MechanismId       mechanism_id,
            in TransportSecurity::AcquisitionMethod acquisition_method,
            in any                                  acquisition_arguments
        );

        /**
         * This operation causes CSI Credentials to be created
         * over a particular transport credentials that have
         * already been created by using the
         * TransportSecurity::CredentialsCurator.
         */
        void addUseTransportCredentials(
            in TransportSecurity::OwnCredentials    credentials
        );

        /**
         * This operation adds an ATLAS to your CSI Credentials.
         * ATLAS is the Authorization Token Layer Acquisition Service.
         * Each ATLAS represents a specific Authorization context, and
         * is used to give your clients the ability to "log" in, and
         * present credentials (i.e. an Authorization Token) for which
         * to work the requests. It also gives the ability for clients
         * to cache the tokens, so performance will be better.
         * <p>
         * None of the arguments can be null.
         * <p>
         * The cache_id is the caching Id, according to the ATLAS
         * specification which must be unique to this authorization
         * context, amongst all other authorization contexts. If you
         * do not have a cache id, then this argument should be an
         * empty octet sequence.
         * <P>
         * The token_dispenser is the ATLAS AuthTokenDispenser interface.
         * This cannot be a "local" object.
         * <p>
         * The supports_delegation_by_client and requires_delegation_by_client
         * arguments tell the client the way in which it
         * will use the ATLAS. This
         * information gets put in the ATLAS Profile, which is put
         * in the IOR of the objects associated with the credentials.
         * <p>
         * The token_processor is the "sister" to the ATLAS, as it
         * understands the tokens that the ATLAS ships out to clients.
         * It is specific to the Authorization context. It may be
         * a local object, but also can make remote calls.
         */
        void addATLASObject(
            in ATLAS::ATLASCacheId              cache_id,
            in ATLAS::AuthTokenDispenser        token_dispenser,
            in boolean                          supports_delegation_by_client,
            in boolean                          requires_delegation_by_client,
            in SL3Authorization::TokenProcessor token_processor
        );

    };

    /**
     * This interface is a factory for arguments that will
     * be in use for ORBAsec credentials acquisition mechanisms.
     * It is retrievable off the ORB at "SL3:ArgumentFactory"
     */
    local interface ArgumentFactory {

        /**
         * Creates a new CSI Argument Builder object with the specified
         * Credentials usage.
         */
        CSIArgBuilder createCSIArgBuilder(
            in SecurityLevel3::CredentialsUsage usage
        );

        /**
         * This operation creates a Tagged Argument containing
         * an flag that will disable the creation of the default
         * ATLASCache.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createSetNoLocalCache();

        /**
         * This operation creates a Tagged Argument containing
         * an ATLASCache implementation to use for caching ATLAS
         * tokens.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createATLASCache(
            in ATLASCache::AuthTokenCache cache
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createUserPasswordCAGenerator(
            in UserPassword::PasswordGenerator generator
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createUserPasswordCAProcessor(
            in UserPassword::PasswordProcessor  processor
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createKerberosCAGenerator(
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createKerberosCAProcessor(
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createNamedQuotedPrincipal(
            in SecurityLevel3::PrincipalName   prin_name
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createEncodedQuotedPrincipal(
            in SecurityLevel3::IdentityStatement   prin_name
        );

        /**
         * This operation creates a Arg_TrustInServerDecider tagged
         * argument.
         */
        SL3AQArgs::Argument createLocalTrustInServerDecider(
            in Trust::LocalTrustInServerDecider trust_decider
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createTransportCredentialsAQArgs(
            in TransportSecurity::MechanismId       mechanism_id,
            in TransportSecurity::AcquisitionMethod acquisition_method,
            in any                                  acquisition_arguments
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createUseTransportCredentials(
            in TransportSecurity::OwnCredentials    credentials
        );

        /**
         * This operation creates a Tagged Argument containing
         * the following information for acquiring CSI credentials.
         * <p>
         * For a description of the arguments, please see the
         * corresponding operation in the CSIArgBuilder.
         *
         * @see CSIArgBuilder
         */
        SL3AQArgs::Argument createATLASObject(
            in ATLAS::ATLASCacheId              cache_id,
            in ATLAS::AuthTokenDispenser        token_dispenser,
            in boolean                          supports_endorsement_by_client,
            in boolean                          requires_endorsement_by_client,
            in SL3Authorization::TokenProcessor token_processor
        );

    };

};
#endif