//tabstop=4
//***********************************************************************
// ORBAsec SL3
// ----------------------------------------------------------------------
// Copyright (C) 2001 Adiron, LLC.
//                    All rights reserved.
// ----------------------------------------------------------------------
// $Id: SecurityLevel3.idl 75579 2006-11-26 06:40:46Z johnnyw $
//***********************************************************************

//***********************************************************************
/**
 * @note Some interfaces in this IDL module have been altered from the
 *       original Adiron sources.
 */
//***********************************************************************


#ifndef _SecurityLevel3_
#define _SecurityLevel3_

#include "tao/Policy.pidl"
#include "tao/TimeBase.pidl"
#include "tao/StringSeq.pidl"
#include "tao/WStringSeq.pidl"

#pragma prefix "adiron.com"

/**
 * The Security Level 3 module contains the data definitions and
 * the Application Programmers Interface for dealing with the
 * ORBAsec SL3 Security, and the new CSIv2 Security Protocol, which has
 * been adopted by the OMG.
 * <p>
 * The SecurityLevel3 interfaces and its security data structures
 * are based on the Principal Calculus. This is a mathematical
 * model of representing principals for the use of access control
 * and auditing.
 * <p>
 * The SecurityLevel3 Security Service is represented by two objects
 * that are returned by the ORB's resolve_initial_reference call.
 * Those two objects are the SecurityManager and the SecurityCurrent.
 * Other objects associated with the security service emanate from
 * these two objects.
 * <p>
 * The SecurityLevel3 Security Service has a Credentials model. This
 * model, which is heavily based on the Principal Calculus, yields
 * an API for accessing principal information. The credentials
 * represent a principal's credentials, as well as the establishment
 * of security contexts between client and servers.
 * <p>
 * The SecurityLevel3 Security Service is currently CSIv2 Level 2
 * compliant:
 * <ul>
 * <li>
 * It works over TLS and plain TCPIP.
 * <li>
 * It handles the GSSUP (Username/Password) mechanism for
 * CSI level Client Authentication.
 * <li>
 * It has the ability to "quote" an identity, i.e. CSIv2
 * Identity Assertion.
 * <li>
 * It has the ability to "push" privileges, which it does
 * ATLAS enabled servers.
 * <li>
 * It has the ability to install your own authorization
 * token process that can allow for delegation.
 * </ul>
 * <p>
 * The Security Level 3 ORB Security Service does supports retention
 * of CSI state. Client Authentication information and Identity
 * assertion information is transmitted on each request.
 * <p>
 * The Security Level 3 ORB Security Service does not automatically
 * support endorsement at this time (CSIv2 Level 2 compliance), but
 * does give you facility to do so.
 */
module SecurityLevel3 {

    /**
     * The Adiron VMCID, which is used in Minor Error Codes,
     * Policy Tags, etc.
     */
    const unsigned long ADIRON_VMCID = 0xA11C000;

    //-------------------------------------------------------------
    //  Security Level 3 Data Representations
    //
    //-------------------------------------------------------------

    //
    // A Principal Name
    //   A principal name always has a type, and a path of
    //   name components. They are ordered from least significant
    //   to most significant. For example, if a principal is represented
    //   by a single X.509 certificate, the first element in the path
    //   is the SubjectDN, and the second is the IssuerDN.
    //
    /**
     * A NameType is used for typing a PrincipalName data structure.
     * A NameType is a string that represents an ASN.1
     * OBJECT IDENTIFIER. Its representation usually of the form
     * "oid:1.2.3.4". Other forms may be possible. It is used
     * for encoding name type identifiers, which are ASN.1 DER encoded
     * OBJECT IDENTIFIERs, in the CSI protocol.
     * @see NameComponent
     * @see NamePath
     * @see NameValue
     * @see PrincipalName
     */
    typedef string                  NameType;

    /**
     * A NameComponent is an ordered component of a NamePath. The
     * least significant component is always the first component.
     * It is the type of a wstring to handle international character
     * values.
     * @see NameType
     * @see NamePath
     * @see NameValue
     * @see PrincipalName
     */
    typedef wstring                 NameComponent;

    /**
     * A NamePath is an ordered collection of NameComponents, ordered
     * from the least significant to most significant. For example,
     * an identity that is defined by a certificate that has a
     * SubjectDN of "C=US,CN=Joe,O=Adiron" and an IssuerDN of
     * "C=US,CN=AdironCA,O=Adiron" will have the following
     * name components:
     * <pre>
     *  NameComponent[0] = "C=US,CN=Joe,O=Adiron"
     *  NameComponent[1] = "C=US,CN=AdironCA,O=Adiron"
     * </pre>
     * @see NameType
     * @see NameComponent
     * @see NameValue
     * @see PrincipalName
     */
    typedef sequence<NameComponent> NamePath;

    /**
     * A NameValue is the value component of a PrincipalName,
     * which is a "type-value" pair. It is defined as a NamePath.
     * @see NameType
     * @see NameComponent
     * @see NamePath
     * @see PrincipalName
     */
    typedef NamePath                NameValue;

    /**
     * A PrincipalName is a "type-value" structure. The type directs
     * what the encoding and format of the components in the the
     * value component are. For example, a type of "X509DirectoryPath"
     * means that the value contains the DNs of the subject and
     * subsequent issuers.
     * @see NameType
     * @see NameComponent
     * @see NamePath
     * @see NameValue
     */
    struct PrincipalName {
        NameType          the_type;
        NameValue         the_name;
    };

    /**
     * A list of PrincipalNames.
     * @see PrincipalName
     */
    typedef sequence<PrincipalName> PrincipalNameList;


    //
    // Attributes for privileges and other things. They are type value pairs.
    //

    /**
     * A PrinAttribute is a "type-value" pair, usually attributed to
     * a Principal by some means, such as values stored in its certificate
     * or environmental concerns, such as the channel the principal was
     * authenticated over.
     * <p>
     * The type of a PrinAttribute is represented by a string.
     * <p>
     * Privilege Attribute Types, that might come from X.509 certificates
     * might be represented by OIDs. OIDs are represented as:
     * <pre>
     *   oid:n1.n2.n3.n4.n5.n6....
     *             for an OID where ni are non-negative integers.
     * </pre>
     * These OIDs are meant to be used to direct the "type-value" encoding
     * of a GSS-API ExportName, which uses an OID as a type that directs
     * the encoding of the value.
     * <p>
     * Example Environmental Attribute Types
     * <p><pre>
     *   SL3:ChannelIdentifier
     *   SL3:LocalAddress
     *   SL3:LocalPort
     *   SL3:TransportMechanism
     *   SL3:TLSCipherSuite
     * </pre>
     * @see PrinAttribute
     */
    typedef string PrinAttributeType;

    /**
     * A PrinAttributeValue is a wide character string that encodes
     * or decodes the value of an attribute. An attempt is always
     * meant to represent an attribute's value in a human readable
     * string form. If the value cannot be decoded this way, and its
     * native form is binary, then it is represented in a Hex encoding
     * of the binary form.
     * @see PrinAttribute
     */
    typedef wstring PrinAttributeValue;

    /**
     * A PrinAttribute is a "type-value" pair, usually attributed to
     * a Principal by some means, such as values stored in its certificate
     * or environmental concerns, such as the channel the principal was
     * authenticated over.
     * @see PrinAttribute
     */
    struct PrinAttribute {
        PrinAttributeType   the_type;
        PrinAttributeValue  the_value;
    };

    /**
     * A list of PrinAttributes.
     * @see PrinAttribute
     */
    typedef sequence<PrinAttribute> PrinAttributeList;


    /**
     * This is just a sequence of strings that make
     * up the components of a ResourceName.
     * @see ResourceName
     */
    typedef sequence<string> ResourceNameComponents;

   /**
     * A ResourceName is the constructed name of a "resource". A
     * ResourceName is closely modeled after CORBAmed's Resource
     * Access Decision (RAD) facility's "Resource". It contains
     * a sequence of strings.
     */
    struct ResourceName {
        ResourceNameComponents  components;
    };

    /**
     * A List of Resource Names.
     * @See ResourceName
     */
    typedef sequence<ResourceName> ResourceNameList;


    //
    // NameTypes used in SL3
    //

    /**
     * An NT_KerberosName is a NameType that signifies that the
     * value of a PrincipalName is a Kerberos formated name.
     * A KerberosName is a single string encoded in the
     * familiar "name@REALM" format.
     * <p>
     * From GSS-Kerboeros RFC 1964:
     * <p>
     * 2.1.1. Kerberos Principal Name Form
     * <p>
     * This name form shall be represented by the Object Identifier {iso(1)
     * member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
     * krb5(2) krb5_name(1)}.
     */
    const NameType NT_KerberosName = "oid:1.2.840.113554.1.2.2.1";

    /**
     * An NT_X509DirectoryNamePath is a NameType that signifies that
     * the value of a PrincipalName is constructed from a chain
     * of certificates, such that the end entity is the least
     * significant position, with the subsequent issuers following
     * in order of signature.
     * <p>
     * The coding of the names is the string encoding of
     * complete X.500 DN's, such as "C=US, CN=Joe, O=Adiron".
     * There is no indication whether the last DN in the path is a
     * "root", i.e. it's issuer is the same.
     */
    const NameType NT_X509DirectoryNamePath = "SL3:X509DirectoryPathName";

    /**
     * The NT_Anonymous is a name type that specifies that the
     * PrincipalName is representing the "anonymous" principal.
     * Its value always as a single name component of "anonymous"
     */
    const NameType NT_Anonymous = "SL3:anonymous";

    /**
     * The NT_StringName is a NameType that specifies that the
     * PrincipalName is represented by a single NameComponent
     * of name in a "scoped" name space. The name and scope
     * are separated by a single "@" character. The escape character
     * is "\". This string name as we call it is the same form
     * used for the GSSUP (GSS-UserPassword NameType). This
     * oid is the OID defined by the OMG CSIv2 specification. It
     * is the value defined by the CSI::GSS_NT_Scoped_Username_OID
     * constant.
     */
    const NameType NT_StringName = "oid:2.23.130.1.2.1";

    //
    // Privileges
    //

    /**
     * A ScopedPrivileges structure represents privileges that
     * belong to a scope defined by a principal. This structure
     * is used to represent a principal that is a privilege authority
     * that issues privileges. Privileges are represented as
     * PrinAttributes.
     */
    struct ScopedPrivileges {
        PrincipalName         privilege_authority;
        PrinAttributeList     privileges;
    };

    /**
     * A list of ScopedPrivileges
     * @see ScopedPrivileges
     */
    typedef sequence<ScopedPrivileges> ScopedPrivilegesList;

    //
    // Principals
    //

    /**
     * A Principal comes in three forms, which correspond to the
     * Principal Calculus. The forms are "Simple", "Quoting", and
     * "Proxy". Simple is a principal that represents a single
     * entity, usually "speaking for" itself. A "Quoting" principal
     * is a "compound" principal that says that one principal is
     * speaking on behalf of another, usually denoted by "(A|B)", i.e.
     * "A is quoting B", which means that "A is speaking on behalf of B".
     * A "Proxy" principal is almost the same as a "Quoting" principal.
     * However, the security service has determined that enough evidence
     * exists that proves that Principal A is authorized to speak in
     * B's behalf. This principal is denoted in the calculus as "(A for B)"
     * in contrast to the quoting principal "(A|B)".
     */
    typedef unsigned long PrincipalType;

    /**
     * The Simple Principal Type (A)
     * @see PrincipalType
     */
    const PrincipalType PT_Simple  = 0; // A,        valuetype SimplePrincipal
    /**
     * The Quoting Principal Type (A|B)
     * @see PrincipalType
     */
    const PrincipalType PT_Quoting = 1; // B | A,    valuetype QuotingPrincipal
    /**
     * The Proxy Principal Type (A for B)
     * @see PrincipalType
     */
    const PrincipalType PT_Proxy   = 2; // B for A,  valuetype ProxyPrincipal

    /**
     * A Principal is represented by a base value type, which is extended
     * for the various principals, Simple, Quoting, and Proxy. This base
     * type of a Principal may be sufficient for access control in
     * most systems.
     * @param the_type    contains the corresponding identifier
     * @param the_name    contains the logical name of the most derived
     *                    Principal. Such as if the Principal is a nested
     *                    ProxyPrincipal (i.e. C for B for A) the name here
     *                    is A.
     * @param environmental_attributes
     *                    The attributes name certain things that do are
     *                    environmental, such as IP addresses.
     * @param with_privileges
     *                    These are the privileges associated with Principal A
     *                    restricted_resources.
     *                    This attribute contains a collection of resources on which
     *                    the principal is authorized to perform actions.
     */
    valuetype Principal {
        /** This field contains the type of the Principal. */
        public PrincipalType          the_type;
        /** This field contains the name of the Principal */
        public PrincipalName          the_name;
        /**
         * This field contains the attributes of the principal
         * that are considered environmental, such as authentication
         * mechanism, authentication channel identifier, etc.
         */
        public PrinAttributeList      environmental_attributes;
        /**
         * This field contains the list of scoped privileges the
         * security service has determined belong to the particular
         * principal.
         */
        public ScopedPrivilegesList   with_privileges;
    };

    /**
     * A list of Principals.
     * @see Principal
     */
    typedef sequence<Principal> PrincipalList;

    /**
     * A Simple Principal represents a single entity. It is usually
     * derived by credentials acquisition, authentication, trust rules concerning quoting,
     * or trust rules and certificates concerning Proxying.
     * It has one extra field over the base Principal, which is
     * "alternate_names".
     */
  valuetype SimplePrincipal : /* truncatable */ Principal {
        /**
         * This field indicates whether the principal was derived or is
         * going to be derived from an authentication mechanism.
         * <p>
         * If the <code>SimplePrincipal</code> is directly or indirectly
         * (as part of a composite <code>Principal</code>) in the
         * <code>ClientCredentials.client_principal<code> or
         * <code>TargetCredentials.target_principal<code> field,
         * the <code>authenticated</code> field indicates the authentication
         * status of the <code>SimplePrincipal</code> in the client or target
         * principal, respectively.
         * <p>
         * If the <code>SimplePricipal</code> is directly or indirectly in
         * the <code>ClientCredentials.target_principal<code>
         * (or <code>TargetCredentials.client_principal<code>) field,
         * the <code>authenticated</code> field indicates the target's
         * (or client's belief) about its authentication status to the other
         * party.
         * <p>
         * If the <code>SimplePrincipal</code> is directly or indirectly in
         * the <code>the_principal</code> field of the initiator or acceptor
         * of <code>OwnCredentials</code>, the <code>authenticated</code>
         * field indicates the expectation of being authenticated to the other
         * side of the communication when the initiator or acceptor is used.
         * <p>
         * If the <code>SimplePrincipal</code> is directly or indirectly in
         * the <code>the_principal</code> field of a
         * <code>PrincipalIdentityStatement</code>,
         * the <code>authenticated</code> field indicates only the
         * "best effort" of knowing whether the principal has been possibly
         * authenticated or not. In other word, if this field is
         * <code>TRUE</code>, it is for sure that the principal has been
         * authenticated (or is expecting to be authenticated).
         * If this field is <code>FALSE</code>, the principal may or may not
         * have been authenticated. The reason for this ambiguity is that
         * a <code>PrincipalIdentityStatement</code> may be created before
         * the authentication of the principal being performed. In general,
         * the <code>authenticated</code> field of a
         * <code>SimplePrincipal</code> inside the <code>the_principal</code>
         * field of a <code>PrincipalIdentityStatement</code> should not be
         * taken as a definite answer for the authentication status of the
         * <code>SimplePrincipal</code>.
         *
         * @see ClientCredentials.client_authentication
         * @see ClientCredentials.target_authentication
         * @see TargetCredentials.client_authentication
         * @see TargetCredentials.target_authentication
         */
        // For example, if a client uses the User/Password mechanism to
        // communicate with a target, the client's OwnCredentials, created
        // using a PasswordGenerator, will have the <code>authenticated</code>
        // field in the principal in the initiator being true,
        // although the client may not have been authenticated to the target.
        //
        public boolean            authenticated;
        /**
         * This field contains the other name types, such as
         * that appear in the X.509 alternate name fields.
         */
        public PrincipalNameList  alternate_names;

    };

    /**
     * A ProxyPrincipal represents a principal that speaks for another.
     * The principal is proved that it is authorized to speak for another.
     * The system believes this, either by trust rules of its own,
     * or by delivered endorsement from the principal such as
     * Principal (B for A) where the endorsement takes the form
     * in the Principal Calculus as (T says B serves A)
     * where T is some entity trusted by the security service
     * to make those statements.
     * <p>
     * Important: This valuetype extends the Principal value type. The
     * <code>the_name</code> filed of this object will contain the name of the
     * <code>speaks_for</code> principal, as that is the name most access control
     * systems would care about. Therefore, this value type can be
     * truncated by access control systems that do not want to
     * examine the principal in detail.
     */
    valuetype ProxyPrincipal :  /* truncatable */ Principal {

        /**
         * In a Proxy Principal of (A for B) the <code>speaking</code> field
         * represents the principal A.
         */
        public Principal  speaking;

         /**
         * In a Proxy Principal of (A for B) the <code>speaks_for</code> field
         * represents the principal B.
         */
       public Principal  speaks_for;

    };

    /**
     * A QuotingPrincipal represents a principal that speaks for another.
     * The principal is not proved that it is authorized to speak for another.
     * The system derives principals like this based on statements in the
     * Pricipal Calculus, such as "A says B says r", which results in the
     * quoting principal (A|B) says r, where "r" is a statement, such as
     * a CORBA request. The security service derives principals like
     * this from the CSI Identity Assertion mechanism.
     * <p>
     * Important: This valuetype extends the Principal value type. The
     * <code>the_name</code> filed of this object will contain the name of the
     * <code>quotes_for</code> principal, as that is the name most access control
     * systems would care about. Therefore, this value type can be
     * truncated by access control systems that do not want to
     * examine the principal in detail.
     */
    valuetype QuotingPrincipal :  /* truncatable */ Principal {

        /**
         * In a Quoting Principal of (A|B) the <code>speaking</code> field
         * represents the principal A.
         */
        public Principal        speaking;

        /**
         * In a Quoting Principal of (A|B) the <code>quotes_for</code> field
         * represents the principal B.
         */
        public Principal        quotes_for;

    };

    //
    // Statements
    //

    /**
     * A Statement is a value type that has extensions which
     * represent the different relevant data directed by its StatementType.
     * There are two basic Statement Types, an IdentityStatement and
     * an EndorsementStatement. An identity statement is a statement that
     * asserts an identity. It may represent a the components of
     * an X.509 certificate during an authentication. An EndorsementStatement
     * may represent the contents of an X.509 AttributeCertificate or
     * some other notion of an endorsement, such as a certificate in
     * BizTalk XML.
     * <p>
     * Statements are contained in the Credentials Objects. They
     * represent pieces of evidence collected from which the security
     * service deduces the Principal of the Credentials Objects.
     */
    typedef unsigned long StatementType;

    /**
     * The Identity Statement Type.
     * <p>
     * A statement of this type at least extends to the
     * IdentityStatement valuetype, if not truncated
     * @see IdentityStatement
     */
    const StatementType ST_IdentityStatement    = 1; //valuetype IdentityStatement

    /**
     * The Endorsement Statement Type.
     * <p>
     * A statement of this type at least extends to the
     * EndorsementStatement valuetype, if not truncated
     * @see EndorsementStatement
     */
    const StatementType ST_EndorsementStatement = 2; //valuetype EndorsementStatement

    /**
     * An encoding is a sequence of bytes.
     */
    typedef sequence<octet> Encoding;

    /**
     * Statement encoding type.
     * <p>
     * Statements carry their original encoding information, if
     * they came from an encoding, such as list of X.509 identity
     * certificates (i.e. a chain). The encoding type may be derivable
     * from the encoding itself. For example, it's easy to tell the
     * difference between a PEM encoded certificate, and a DER encoded
     * certificate. Therefore, the encoding type may default to "Unknown".
     * Other types may exist than the ones provided as constants in
     * this module.
     */
    typedef string EncodingType;

    /**
     * The ET_NoEncoding type signifies that the statement
     * has been generated solely by the security service
     * and has no encoding.
     */
    const EncodingType ET_NoEncoding = "NoEncoding";

    /**
     * The ET_Unknown encoding type may always be used if the encoding
     * type can only be figured out from encoding itself.
     */
    const EncodingType ET_Unknown = "Unknown";

    /**
     * User Exception for a bad encoding.
     */
    exception BadEncoding {};

    /**
     * User Exception for a bad or unsupported encoding type.
     */
    exception BadEncodingType {};

    /**
     * The Statement Layer is the layer of the protocol or security
     * service from which the statement emanated, derived, or was collected.
     */
    typedef unsigned long StatementLayer;

    /**
     * Default type for a Statement Layer
     */
    const StatementLayer SL_Unknown          = 0;
    /**
     * The SL_Transport statement type signifies that the associated
     * statement is derived from the transport layer, such as
     * an X.509 Certificate from a TLS handshake.
     */
    const StatementLayer SL_Transport        = 1;
    /**
     * The SL_CSIAuthorization statement type signifies that the associated
     * statement is derived from the CSI Authorization Layer in the CSIv2
     * protocol.
     */
    const StatementLayer SL_CSIAuthorization = 2;
    /**
     * The SL_CSIClientAuth statement type signifies that the associated
     * statement is derived from the CSI Client Authentication Layer
     * in the CSIv2 protocol.
     */
    const StatementLayer SL_CSIClientAuth    = 3;
    /**
     * The SL_CSIIdentity statement type signifies that the associated
     * statement is derived from the CSI Identity Assertion Layer
     * in the CSIv2 protocol.
     */
    const StatementLayer SL_CSIIdentity      = 4;

    /**
     * The SL_UserDefined statement layer signifies that the associate
     * statement is derived or created by a user or some other
     * entity than the security service.
     */
    const StatementLayer SL_UserDefined     = 5;

    /**
     * The Statement base type contains the information common
     * to all statements. A statement has an "external" encoding, such
     * as an X509 Certificate. Some statements may not have an encoding,
     * but its extension may carry the pertinent marshable information,
     * such as a PrincipalIdentityStatement for anonymous, which is
     * generated by the security service.
     */
    valuetype Statement {
        /**
         * This field contains an identifier of the
         * service layer that generated the statement.
         * The layer that generated or delivered
         * the statement, i.e. Transport, CSIv2 Authentication,
         * CSIv2 Authorization, or CSIv2 Identity Assertion.
         */
       public StatementLayer          the_layer;
        /**
         * The type of statement, which indicates its extension
         * such as an Identity Statement or an Endorsement
         * Statement.
         */
        public StatementType           the_type;
        /**
         * This field indicates the type of encoding.
         * The encoding may be contrived, at the encoding
         * may not exist, however, the extension of the
         * statement type may contain data that can
         * be marshaled across the wire. See the Principal
         * Identity Statement.
         */
        private EncodingType  encoding_type;
        /**
         * The bytes of the encoding, if it exists.
         */
        private Encoding      the_encoding;

        /**
         * Returns the encoding type
         */
        EncodingType get_encoding_type();

        /**
         * Returns an encoding of this statement. Some implementations
         * may be able to convert. Using and encoding_type of
         * ET_Unknown, will always yield the default encoding,
         * if it exists. If the encoding does not exist,
         * a successful return containing an empty
         * sequence will result.
         */
        Encoding get_encoding(
            in EncodingType encoding_type
        ) raises (
            BadEncodingType
        );

        /**
         * This factory method allows users to create their
         * own Statements from an encoding. The statements created
         * by this factory method may have a type which is a further
         * extension of the valuetype Statement.
         */
        factory create(
            in EncodingType   encoding_type,
            in Encoding       the_encoding
        );
     };
     typedef sequence<Statement> StatementList;

    /**
     * The Identity Statement further classifies the encoding
     * as a statement that if verified asserts an identity.
     */
    valuetype IdentityStatement : Statement {
        /**
         * This field contains a possibly well known identifier that
         * may aid in the interpretation of the identity statement's
         * encoding. It may be an empty string, which signifies that
         * there is no known interpretation aid for the encoding, or
         * that there is no encoding.
         */
        public string                      interpretation_aid;
    };

    /**
     * The Principal Identity Statement is the minimal version of an
     * Identity statement that asserts a single identity that the
     * security service can translate into a principal.
     * <p>
     * An example of an identity statement is an X.509 certificate in
     * which its attributes are exposed into the principal, such as
     * privileges. This valuetype may also be further extended by the
     * security service depending on its encoding and the capabilities
     * of the security service.
     */
    valuetype PrincipalIdentityStatement : IdentityStatement {
        public Principal the_principal;
    };

    /**
     * The Endorsement Statement is a statement that is used for
     * authorization. An Endorsement statement endorses a
     * principal with certain characteristics, such as privileges
     * or the authority to act on behalf of another principal, sometimes
     * called "delegation".
     * <p>
     * According to our research, an endorsement statement may be a
     * complex entity containing  matching rules for the endorsement.
     * An endorsement may have the following general form:
     * <pre>
     *     I says Principal A matching [(P1 with [p1,...,pn]) or ....]
     *        speaks_for
     *          Principal B matching [(T1 with [t1,...,tn]) or ... ]
     *        has [s1,...,sm]
     *        on Resources matching [R1, .... Rn]
     * </pre>
     * Actual semantic reduction of principals is directed by the
     * the matching rules, and may depend on other statements as well,
     * such as local trust rules in the security service configuration.
     * Also, much of the capability of an endorsement statement is
     * dependent on its encoding.
     * <p>
     * This approach to authorization is a largely unexplored research
     * topic. There are not many or well known encodings of endorsement
     * statements. Therefore, we are reluctant to produce interfaces
     * just yet, that go beyond the encoding. However, we do expose the
     * Endorsement statement type, which may further direct the interpretation
     * of it's encoding.
     */
    valuetype EndorsementStatement : Statement {
        /**
         * This field contains a possibly well known identifier that
         * may aid in the interpretation of the identity statement's
         * encoding. It may be an empty string, which signifies that
         * there is no known interpretation aid for the encoding, or
         * that there is no encoding.
         */
        public string                      interpretation_aid;
    };

    /**
     * An X509IdentityStatement is one that extends the Principal Identity
     * Statement. If one does get an X509 IdentityStatement, it is
     * currently supported with IAIK in both DER and PEM formats.
     */
    valuetype X509IdentityStatement : PrincipalIdentityStatement {
        /**
         * This factory method allows users to create their
         * own X509Identity statements from an encoding.
         */
        factory create(
            in EncodingType   encoding_type,
            in Encoding       the_encoding
        );
    };
    typedef sequence<X509IdentityStatement> X509IdentityStatementList;

    //-------------------------------------------------------------
    //  Security Level 3 Application Users Interface
    //
    //-------------------------------------------------------------

    //
    // The Security Level 3 Credentials Model
    //

    /**
     * Credentials come in three types. OwnCredentials, ClientCredentials,
     * and TargetCredentials. OwnCredentials represent the ORB instance's
     * credentials. Each Credentials has initiating and accepting capability.
     * ClientCredentials represent an established security context with
     * a client. TargetCredentials represent an established security context
     * with a Target's Server.
     */
    typedef unsigned long CredentialsType;

    /**
     * The CT_OwnCredentials CredentialsType signifies that the
     * Credentials can be extended to the OwnCredentials Type.
     */
    const CredentialsType CT_OwnCredentials        = 0;
    /**
     * The CT_ClientCredentials CredentialsType signifies that the
     * Credentials can be extended to the ClientCredentials Type.
     */
    const CredentialsType CT_ClientCredentials     = 1;
    /**
     * The CT_TargetCredentials CredentialsType signifies that the
     * Credentials can be extended to the ClientCredentials Type.
     */
    const CredentialsType CT_TargetCredentials     = 2;

    /**
     * A Credentials object has a validity state. Some credentials
     * may be time or use dependent.
     */
    typedef long CredentialsState;

    /**
     * The Credentials with a CredentialsState of CS_Invalid cannot be
     * used in any the initiating or accepting establishment of any
     * security contexts.
     */
    const CredentialsState CS_Invalid         = -3;

    /**
     * Credentials with a CredentialsState of CS_Expired can no longer
     * be used for initiating or accepting establishment of any
     * security contexts.
     */
    const CredentialsState CS_Expired         = -2;
    /**
     * Credentials with a CredentialsState of CS_PendingRelease can no longer
     * be used for initiating or accepting establishment of any
     * security contexts. It means that "release_credentials" has been
     * called on the credentials.
     */
    const CredentialsState CS_PendingRelease  = -1;
    /**
     * Credentials with a CredentialsState of CS_Initialized cannot
     * be used for initiating or accepting establishment of any
     * security contexts. It means that credentials are in an initial
     * state. This value is for internal use, and there is no
     * reason a SecurityLevel3 user should see credentials in this state.
     */
    const CredentialsState CS_Initialized     =  0;
    /**
     * Credentials with a CredentialsState of CS_Valid can
     * be used for initiating or accepting establishment of
     * security contexts.
     */
    const CredentialsState CS_Valid           =  1;

    /**
     * Credentials have system generated identifiers
     * to which they can be referred and retrieved.
     */
    typedef string CredentialsId;
    typedef sequence<CredentialsId> CredentialsIdList;

    /**
     * A Context Id is a system generated unique identifier for identifying
     * a security context to the application.
     * Security Contexts may be long lived and not established on
     * every request. Therefore, an identifier is assigned.
     * <p>
     * Note that this Context Id is not directly related to the context
     * defined in the CSIv2 specification.
     */
    typedef string ContextId;

    /**
     * Credentials Usage
     * <p>
     * Credentials Usage refers to the concept that Credentials may
     * be used to initiate security context, accept security contexts,
     * or do both. its values are used in the acquisition
     * of credentials for the purpose of designating the abilities
     * of the credentials acquired.
     */
    typedef unsigned long CredentialsUsage;
    /**
     * The CU_Indefinite CredentialsUsage type is a value that
     * signifies the default. Depending on some other acquisition
     * arguments, the credentials usage may be able to be implicitly
     * determined.
     */
    const CredentialsUsage CU_Indefinite         = 1;
    /**
     * The CU_None CredentialsUsage type is a value that states the
     * credentials cannot be used to make or accept security
     * contexts. ClientCredentials and TargetCredentials have
     * this credentials usage.
     */
    const CredentialsUsage CU_None               = 2;
    /**
     * The CU_AcceptOnly CredentialsUsage type is a value that signifies
     * that the credentials can only be used to accept the establishment
     * of security contexts.
     */
    const CredentialsUsage CU_AcceptOnly         = 3;
    /**
     * The CU_InitiateOnly CredentialsUsage type is a value that signifies
     * that the credentials can only be used to initiate the establishment
     * of security contexts.
     */
    const CredentialsUsage CU_InitiateOnly       = 4;
    /**
     * The CU_InitiateAndAccept CredentialsUsage type is a value that
     * signifies that the credentials can be used to both initiate
     * and accept the establishment of security contexts.
     */
    const CredentialsUsage CU_InitiateAndAccept  = 5;

    /**
     * A CredsDirective is a directive on a invocation as to the
     * effects of the initiated security context will have on the
     * the accepting side. Please see ContextEstablishmentPolicy
     * for is use in context with establishing security contexts.
     * @see ContextEstablishmentPolicy
     */
    typedef unsigned long CredsDirective;
    /**
     * The CD_Default CredsDirective is a value that signifies to
     * use the capabilities of the selected credentials.
     */
    const CredsDirective CD_Default             = 0;
    /**
     * The CD_InvokeTarget CredsDirective is a value that signifies that
     * the selected credentials should only be used in a simple
     * invocation fashion. They shall not attempt to endorse or embody
     * the target to act on its behalf.
     */
    const CredsDirective CD_InvokeTarget        = 1;
    /**
     * The CD_EndorseTarget CredsDirective is a value that signifies that
     * the selected credentials, if capable, should attempt to endorse
     * the target. In other words, it gives the accepting side the ability
     * to act on behalf of the initiating side.
     */
    const CredsDirective CD_EndorseTarget       = 2;
    /**
     * The CD_EmbodyTarget CredsDirective is a value that signifies that
     * the selected credentials, if capable, should attempt to embody
     * the target. In other words, it gives the accepting side the ability
     * to impersonate the initiating side.
     */
    const CredsDirective CD_EmbodyTarget        = 3;

    /**
     * A Feature Directive is a general directive used in policy that
     * stipulates the of a particular feature. Such examples include,
     * confidentiality, integrity, client authentication, etc.
     */
    typedef long FeatureDirective;

    /**
     * The FD_DoNotUse FeatureDirective means definitely not to use
     * the feature.
     */
    const FeatureDirective FD_DoNotUse             = -2;
    /**
     * The FD_DoNotUseIfPossible FeatureDirective means not to use
     * the feature if it is possible. Note, some mechanisms may always
     * use confidentiality.
     */
    const FeatureDirective FD_DoNotUseIfPossible   = -1;
    /**
     * The FD_UseDefault FeatureDirective means to use or not to use
     * the feature depending on defaults.
     */
    const FeatureDirective FD_UseDefault           =  0;
    /**
     * The FD_UseIfPossible FeatureDirective means to use the feature
     * if it is possible.
     */
    const FeatureDirective FD_UseIfPossible        =  1;
    /**
     * The FD_Use FeatureDirective means definitely to use the feature.
     */
    const FeatureDirective FD_Use                  =  2;


    /**
     * The Initiator Type of the Initiator Side of the Credentials states
     * the kind of Initiator it is. There are three types that mirror
     * the type of Principal, Simple, Quoting, and Proxy, that the
     * initiator intends to represent to a server while trying to
     * establish a security context with the server.
     */
    typedef unsigned long InitiatorType;
    /**
     * The IT_None InitiatorType is a value that is defined for
     * completeness, and has no real use.
     */
    const InitiatorType IT_None     = 0;
    /**
     * The IT_Simple InitiatorType is a value that states that the
     * initiator is a "Simple" Principal.
     */
    const InitiatorType IT_Simple   = 1;
    /**
     * The IT_Quoting InitiatorType is a value that states that the
     * initiator will quote another principal to the server. This
     * principal is denoted in the Principal Calculus as (A|B), i.e.
     * A quoting B.
     */
    const InitiatorType IT_Quoting  = 2;
    /**
     * The IT_Proxy InitiatorType is a value that states that the
     * initiator will quote another principal to the server along with
     * getting or providing proof to the server that it can act on
     * behalf of the quoted principals. This
     * principal is denoted in the Principal Calculus as (A for B).
     */
    const InitiatorType IT_Proxy    = 3;

    /**
     * The CredsInitiator object is an object that is directly a
     * member of a particular OwnCredentials object. It represents
     * the "initiator" side of the credentials.
     */
    local interface CredsInitiator {

        /**
         * The principal attribute contains a local view of the
         * Principal that the Credentials intend to represent.
         * Note that during context establishment, the actual establish
         * client principal may be represented differently, especially
         * with respect to environmental attributes. Some environmental
         * attributes are a direct result of context establishment.
         */
        readonly attribute Principal        the_principal;
        /**
         * The supporting statements attribute contains a list of statements
         * supporting the principal associated with this initiator.
         */
        readonly attribute StatementList    supporting_statements;
        /**
         * The restricted_resources attribute contains a list of
         * resource names, by which the credentials initiator
         * believes his authorizations apply.
         */
        readonly attribute ResourceNameList restricted_resources;
        /**
         * The initiator_type attribute signifies the intent of the
         * initiator as to the principal it presents for the
         * security context establishment. It should correspond
         * to the type of the Principal. However, it might be slightly
         * different, because using CSIv2 Client Authentication
         * technically creates a "QuotingPrincipal" however, the
         * initiator type will still be simple as no CSIv2 Identity
         * Assertion will be used in establishing the security
         * context.
         */
        readonly attribute InitiatorType    initiator_type;
        /**
         * The supports_embodiment attribute is <code>TRUE</code> if these credentials
         * can be directed by use of the CredsDirective, to give the
         * the accepting end of a context establishment the ability
         * to impersonate this initiator principal.
         */
        readonly attribute boolean          supports_embodiment;
        /**
         * The supports_endorsement attribute is <code>TRUE</code> if these credentials
         * can be directed by use of the CredsDirective, to endorse
         * the accepting end of a context establishment to act
         * on behalf of this initiator principal.
         */
        readonly attribute boolean          supports_endorsement;
        /**
         * The supports_quoting attribute is <code>TRUE</code> if these credentials
         * can be directed by use of the CredsDirective, to simply
         * quote another principal on top of these credentials.
         */
        readonly attribute boolean          supports_quoting;
        /**
         * The expiry_time attribute denotes the time that these
         * credentials expire.
         */
        readonly attribute TimeBase::UtcT   expiry_time;
    };

    /**
     * The CredsAcceptor object is an object that is directly a
     * member of a particular OwnCredentials object. It represents
     * the "acceptor" side of the credentials.
     */
    local interface CredsAcceptor {

        /**
         * The principal attribute contains a local view of the
         * Principal that the Credentials intend to represent.
         * Note that during context establishment, the actual establish
         * target principal may be represented differently, especially
         * with respect to environmental attributes. Some environmental
         * attributes are a direct result of context establishment.
         */
        readonly attribute SecurityLevel3::Principal       the_principal;
        /**
         * The supporting_statements attribute contains a list of statements
         * supporting the principal associated with this acceptor.
         */
        readonly attribute SecurityLevel3::StatementList   supporting_statements;
        /**
         * The restricted_resources attribute contains a list of
         * resource names, by which the credentials initiator
         * believes his authorizations apply.
         */
        readonly attribute ResourceNameList                restricted_resources;
        /**
         * The accepts_endorsement attribute is <code>TRUE</code> if these credentials
         * supports and accepts CSIv2 endorsement information.
         */
        readonly attribute boolean                         accepts_endorsement;
        /**
         * The accepts_quoting attribute is <code>TRUE</code> if these credentials
         * supports and accepts CSIv2 Identity Assertion information.
         */
        readonly attribute boolean                         accepts_quoting;
        /**
         * The expiry_time attribute denotes the time that these
         * credentials expire.
         */
        readonly attribute TimeBase::UtcT                  expiry_time;

    };

    /**
     * This type is used to identify listeners for removal.
     * A Listener identity will be assigned to a listener when
     * it is assigned to a particular object.
     */
    typedef string ListenerId;

    /**
     * This local interface is used to notify the user when the credentials
     * have been relinquished. When credentials are "released" they may
     * stay around until their work is finished. At that point they
     * will be relinquished. Also, if the underlying transport credentials
     * are released, then the SecurityLevel3 Credentials get released
     * as well. This listener will get informed of this event.
     */
    local interface RelinquishedCredentialsListener {
        void relinquished_notify(
            in CredentialsId creds_id
        );
    };

    /**
     * The Credentials base interface contains the common items for
     * the different types of credentials.
     * @see OwnCredentials
     * @see ClientCredentials
     * @see TargetCredentials
     */
    local interface Credentials {

        /**
         * The creds_id attribute contains a system generated
         * identifier with which can uniquely reference the credentials
         * object.
         */
        readonly attribute CredentialsId    creds_id;

        /**
         * The creds_type stipulates the type of credentials, i.e.
         * to which type of credentials it may be narrowed, e.g.,
         * Own, Client, or Target.
         */
        readonly attribute CredentialsType  creds_type;

        /**
         * The creds_usage attribute stipulates the intended usage of the
         * credentials. For OwnCredentials, it will be one of
         * CU_AcceptOnly, CU_Initiate, CU_InitiateAndAccept.
         * For ClientCredentials and TargetCredentials it will be
         * CU_None.
         */
        readonly attribute CredentialsUsage creds_usage;

        /**
         * The expiry_time attribute denotes the time that these
         * credentials expire.
         */
        readonly attribute TimeBase::UtcT   expiry_time;

        /**
         * The creds_state attribute contains the
         * validity state of the credentials.
         */
        readonly attribute CredentialsState creds_state;

        /**
         * Add a listener that will get notified when the
         * OwnCredentials are finally done with any pending
         * work and are relinquished by the security service.
         */
        ListenerId add_relinquished_listener(
            in RelinquishedCredentialsListener listener
        );

        /**
         * Removes a listener. This function raises a BAD_PARAM
         * exception if the listener is not registered.
         */
        void remove_relinquished_listener(
            in ListenerId id
        );
    };
    /**
     * A list of credentials.
     */
    typedef sequence<Credentials> CredentialsList;

    /**
     * OwnCredentials are created as a result of Credentials acquisition
     * from the CredentialsCurator's CredentialsAcquirers.
     * The Credentials have an initiator and an acceptor based
     * upon its intended usage and capability. Some OwnCredentials
     * that were acquired solely for initiating contexts (i.e. client side)
     * will not have an acceptor, and visa versa.
     */
    local interface OwnCredentials : Credentials {

        /**
         * The creds_initiator attribute contains a reference to the
         * local credentials initiator associated with these credentials.
         * It is null if the creds_usage is AcceptOnly.
         */
        readonly attribute CredsInitiator  creds_initiator;

        /**
         * The creds_acceptor attribute contains a reference to the
         * local credentials acceptor associated with these credentials.
         * It is null if the creds_usage is InitiateOnly.
         */
        readonly attribute CredsAcceptor   creds_acceptor;

        /**
         * The release_credentials operation disables the credentials
         * from further initiating and/or accepting contexts.
         * Formal destruction of the Credentials object is delayed until
         * its pending work is done, at which time it becomes Invalid.
         */
        void release_credentials ();
    };

    /**
     * A list of OwnCredentials
     */
    typedef sequence<OwnCredentials> OwnCredentialsList;

    /**
     * An object of this interface represents the security context for
     * a CSIv2 based remote client. It is created as the result of accepting
     * a security context for the remote client.
     * This object is only available during the servicing of a CORBA request.
     * It can be retrieved from the
     * <code>SecurityLevel3::SecurityCurrent</code> object,
     * as it is thread based.
     * <p>
     * This object contains only the information used from the
     * <code>OwnCredentials</code> that was pertinent in establishing the
     * context. There is a pointer back to that <code>OwnCredentials</code>
     * object. Once this context is created, its attributes are guaranteed
     * not to change.
     */
    local interface ClientCredentials : Credentials {

        /**
         * The context_id attribute contains a system generated unique identifier
         * for the context,
         */
        readonly attribute ContextId                context_id;

        /**
         * The client_principal attribute contains the principal that
         * the security service can deduce is the client from the
         * information and mechanisms used.
         */
        readonly attribute Principal                client_principal;

        /**
         * The client_supporting_statements attribute contains the statements that
         * delivered from CSIv2 protocol along with any from the associated
         * OwnCredentials that are used to deduce the client principal.
         */
        readonly attribute StatementList            client_supporting_statements;

        /**
         * The client_restricted_resources attribute contains the names of the
         * resources that the security service deduces from the CSIv2
         * information and information from the associated OwnCredentials.
         */
        readonly attribute ResourceNameList         client_restricted_resources;

        /**
         * The target_principal attribute contains the exact principal that
         * the security service believes is representative of the
         * clients version of the target's principal.
         */
        readonly attribute Principal                target_principal;

        /**
         * The target_supporting_statements attribute contains the statements that
         * support the deduction of the target principal.
         */
        readonly attribute StatementList            target_supporting_statements;

        /**
         * The target_restricted_resources attribute contains names of resources
         * on which the target is restricted. This information may come
         * from the OwnCredentials.
         */
        readonly attribute ResourceNameList         target_restricted_resources;

        /**
         * This attribute refers to the OwnCredentials that were used in
         * establishing the security context.
         */
        readonly attribute OwnCredentials           parent_credentials;

        /**
         * This attribute is <code>TRUE</code> if the target has
         * authenticated the client, either over the transport, or at
         * the CSIv2 Client Authentication layer.
         */
        readonly attribute boolean                  client_authentication;

        /**
         * This attribute is <code>TRUE</code> if the target believes that
         * the client has authenticated the target over the transport.
         */
        readonly attribute boolean                  target_authentication;

        /**
         * This attribute is <code>TRUE</code> if the context is providing
         * confidentiality protection.
         */
        readonly attribute boolean                  confidentiality;

        /**
         * This attribute is <code>TRUE</code> if the context is providing
         * integrity protection.
         */
        readonly attribute boolean                  integrity;
    };

    /**
     * The TargetCredentials object is created as the result of accepting a
     * security context for a target. It represents that context.
     * It contains only the information used from the OwnCredentials
     * that was pertinent in establishing the context.
     * There is a pointer back to that OwnCredentials object.
     * Once this context is created, its attributes are guaranteed
     * not to change.
     */
    local interface TargetCredentials : Credentials {

        /**
         * The context_id attribute contains a system generated
         * unique identifier for the context.
         */
        readonly attribute ContextId               context_id;

        /**
         * The client_principal attribute contains the principal that
         * the security service believe is the target's
         * ClientCredentials client_principal attribute.
         */
        readonly attribute Principal               client_principal;

        /**
         * The client_supporting_statements attribute contains the
         * statements that support the deduction of the client principal.
         */
        readonly attribute StatementList           client_supporting_statements;

        /**
         * The client_restricted_resources attribute contains names of
         * resources on which the client believes the client is restricted.
         * This information may be derived from newly acquired endorsement
         * information.
         */
        readonly attribute ResourceNameList        client_restricted_resources;

        /**
         * The target_principal attribute contains the exact principal that
         * the security service deduces to be the target.
         */
        readonly attribute Principal               target_principal;

        /**
         * The target_supporting_statements attribute contains the statements
         * that support the deduction of the target principal.
         */
        readonly attribute StatementList           target_supporting_statements;

        /**
         * The target_restricted_resources attribute contains names of
         * resources on which the target is restricted. This information
         * may not be available.
         */
        readonly attribute ResourceNameList        target_restricted_resources;

        /**
         * The parent_credentials attribute refers to the OwnCredentials
         * that were used in establishing the security context.
         */
        readonly attribute OwnCredentials          parent_credentials;

        /**
         * The client_authentication attribute is <code>TRUE</code> if the client
         * believes that the target has authenticated the client, either
         * over the transport, or at the CSIv2 Client Authentication layer.
         */
        readonly attribute boolean                 client_authentication;

        /**
         * The target_authentication attribute is <code>TRUE</code> if the client has
         * authenticated the target over the transport.
         */
        readonly attribute boolean                 target_authentication;

        /**
         * The confidentiality attribute is <code>TRUE</code> if the context is
         * providing confidentiality protection.
         */
        readonly attribute boolean                 confidentiality;

        /**
         * The integrity attribute is <code>TRUE</code> if the context is providing
         * integrity protection.
         */
        readonly attribute boolean                 integrity;

        /**
         * The target_embodied attribute is <code>TRUE</code> if the security service
         * believes that the target is embodied to impersonate the client
         * side principal.
         */
        readonly attribute boolean                 target_embodied;

        /**
         * The target_endorsed attribute is <code>TRUE</code> if the security service
         * believes that the target is endorsed to act on behalf of the
         * client side principal.
         */
        readonly attribute boolean                 target_endorsed;

        /**
         * The release operation indicates to the CSIv2 protocol, that if
         * state is being retained for these credentials, they
         * will be discarded with the pending next request that
         * may have not yet gone out.
         * <p>
         * Any objects references that are binded to these
         * credentials after you release them will become unusable.
         *
         * This operation is experimental.
         */
        void release();
    };


    //--------------------------------------------------------------------
    // Security Invocation Policy
    //
    //--------------------------------------------------------------------

    /**
     * The ContextEstablishmentPolicy policy object directs the
     * establishment of security contexts with a target.
     * <p>
     * The CredsDirective usage is the following:
     * <dl>
     * <dt>
     * CD_Default
     * <dd>
     *       This directive means to use the default set
     *       up by the thread, the  ORB, the ORB configuration,
     *       available credentials, or other policies.
     * <dt>
     * CD_InvokeTarget
     * <dd>
     *       This directive means to use the
     *       the specified OwnCredentials to create a
     *       secure association with the target
     *       before invocation. Do not endorse or embody the target.
     *       Credentials may be IT_Simple, IT_Quoting, or IT_Proxy.
     * <dt>
     * CD_EndorseTarget
     * <dd>
     *       This directive means to use the
     *       the specified OwnCredentials to create a
     *       secure association with the target
     *       before invocation.
     *       The credentials must be
     *       IT_Simple, IT_Quoting, or IT_Proxy own credentials
     *       that supports endorsement.
     *       Note, a Initiator Credentials that is a IT_Proxy
     *       may have an endorsement statement that not only
     *       endorses this immediate client, but may very well
     *       apply to the next target.
     * <dt>
     * CD_EmbodyTarget
     * <dd>
     *       If possible give the target the ability to
     *       impersonate the client, is performed using
     *       transports that can forward their credentials
     *       in the transport that give the ability to the
     *       target to work in their own behalf. Alternatively,
     *       the authenticator may be able to be passed on.
     *       IT_Simple credentials must have or have the
     *       ability to forward credentials. This is analogous
     *       to flipping the DELEGATE bit on GSS-Kerberos Forwardable
     *       credentials. IT_Quoting principals means
     *       that you can forward the transport credentials,
     *       authenticator plus the Quoting statement.
     *       IT_Proxy principals means that you can forward
     *       the transport credentials, authenticator,
     *       and associated proxy statements.
     * </dl>
     * <p>
     * On using Own Credentials. The creds_ids name Own Credentials.
     * Also, they restrict the invocation to use only certain credentials.
     * If the cred_ids list is empty, then the own credentials for the
     * invocation are selected from a default, which may be
     * set on the thread or the ORB instance.
     */
    local interface ContextEstablishmentPolicy : CORBA::Policy {

        readonly attribute CredsDirective      creds_directive;
        readonly attribute OwnCredentialsList  creds_list;
        readonly attribute FeatureDirective    use_client_auth;
        readonly attribute FeatureDirective    use_target_auth;
        readonly attribute FeatureDirective    use_confidentiality;
        readonly attribute FeatureDirective    use_integrity;
    };

    /**
     * Type to be passed to ContextEstablishmentPolicy PolicyFactory
     * through an Any.
     */
    struct ContextEstablishmentPolicyArgument
    {
      CredsDirective      creds_directive;
      OwnCredentialsList  creds_list;
      FeatureDirective    use_client_auth;
      FeatureDirective    use_target_auth;
      FeatureDirective    use_confidentiality;
      FeatureDirective    use_integrity;
    };

    /**
     * The ContextEstablishmentPolicyType constant is
     * holds value used to denote the ContextEstablishmentPolicy.
     */
    const CORBA::PolicyType ContextEstablishmentPolicyType = ADIRON_VMCID | 1001;


    /**
     * The ObjectCredentialsPolicy object is placed on the policy list
     * of a POA to indicate the own credentials
     * that govern the accepting contexts for objects underneath
     * that POA. The credentials listed here, only if they have Accepting
     * capability, are used to created security components in the
     * IOR of the object's reference when created.
     */
    local interface ObjectCredentialsPolicy : CORBA::Policy {
        readonly attribute OwnCredentialsList   creds_list;
    };

    /**
     * Type to be passed to ObjectCredentialsPolicy PolicyFactory
     * through an Any.
     */
    typedef OwnCredentialsList ObjectCredentialsPolicyArgument;

    /**
     * The ObjectCredentialsPolicyType constant is
     * holds value used to denote the ObjectCredentialsPolicy.
     */
    const CORBA::PolicyType ObjectCredentialsPolicyType = ADIRON_VMCID | 1002;


    //--------------------------------------------------------------------
    // Security Level 3 Credentials Acquisition Mechanism
    //
    //--------------------------------------------------------------------

    /**
     * Credentials are acquired by a Credentials Acquirer by some
     * acquisition mechanism specified in the Credentials Curator.
     * Acquisition methods are available on the curator. The
     * specifics of arguments needed and the acquisition process
     * are defined by the method itself.
     */
    typedef string AcquisitionMethod;
    typedef sequence<AcquisitionMethod> AcquisitionMethodList;

    /**
     * An acquisition of credentials may quite possibly fail as well
     * as be a multistep process. A status defines the current
     * state of an acquisition.
     */
    typedef long AcquisitionStatus;
    /** Acquisition has failed. */
    const AcquisitionStatus AQST_Failed       = -2;
    /** Acquisition has expired. */
    const AcquisitionStatus AQST_Expired      = -1;
    /** Acquisition is initialized. */
    const AcquisitionStatus AQST_Initialized  =  0;
    /** Acquisition needs more processing. */
    const AcquisitionStatus AQST_Continued    =  1;
    /** Acquisition has succeeded. */
    const AcquisitionStatus AQST_Succeeded    =  2;

    /**
     * The CredentialsAcquirer object is created by the Credentials
     * Curator based on the selected method and initial acquisition
     * arguments. When this acquisition is complete and successful,
     * the created credentials can be retrieved using the get_credentials
     * operation. Once get_credentials is called, this object is destroyed.
     */
    local interface CredentialsAcquirer {

        /**
         * This attribute contains the acquisition method
         * identifier naming the method by which these credentials
         * are being acquired.
         */
        readonly attribute AcquisitionMethod acquisition_method;

        /**
         * This attribute contains the current acquisition
         * status of the acquisition process.
         */
        readonly attribute AcquisitionStatus current_status;

        /**
         * If the acquisition process is a multistep process through calls
         * to this acquirer, then this attribute contains the current
         * iteration.
         */
        readonly attribute unsigned long     nth_iteration;

        /**
         * If the <code>current_status</code> attribute contains
         * the <code>AQST_Continued</code> value,
         * this operation returns, if necessary and supported
         * by the acquisition method, any data that may direct the
         * acquisition.
         * <p>
         * If this operation in invoked when the <code>current_status</code>
         * attribute does not have the <code>AQST_Continued</code> value,
         * a <code>BAD_INV_ORDER</code> exception will be raised.
         */
        any get_continuation_data();

        /**
         * This operation continues the acquisition. The argument
         * data is dependent on the acquisition method.
         */
        AcquisitionStatus continue_acquisition(
            in  any  acquisition_arguments
        );

        /**
         * Once the <code>current_status</code> attribute has the
         * <code>AQST_Succeeded</code> value, a call to this operation
         * is used to retrieve the acquired <code>OwnCredentials</code>
         * and, optionally, place the credentials on the curator's default own
         * credentials list (for use with default ContextEstablishmentPolicy
         * and ObjectCredentialsPolicy).
         * <p>
         * The <code>CredentialsAcquirer</code> object is destroyed after
         * this call.
         * Any operation called on a destroyed <code>CredentialsAcquirer</code>
         * raises a <code>BAD_INV_ORDER</code> exception.
         * <p>
         * If this operation in invoked when the <code>current_status</code>
         * attribute does not have the <code>AQST_Succeeded</code> value,
         * a <code>BAD_INV_ORDER</code> exception will be raised.
         *
         * @param on_list  <code>TRUE</code> if these credentials go on the
         *                 default own credentials list of the
         *                 <code>CredentialsCurator</code>.
         */
        OwnCredentials get_credentials(
            in boolean on_list
        );

        /**
         * This operation is used to destroy the
         * <code>CredentialsAcquirer</code> object before
         * <code>get_credentials</code> is called.
         * Any operation called on a destroyed <code>CredentialsAcquirer</code>
         * raises a <code>BAD_INV_ORDER</code> exception.
         */
        void destroy();
    };

    /**
     * The <code>CredentialsCurator</code> object is a single object per an ORB
     * instance's Security Service. It has the ability to create
     * <code>CredentialsAcquirer</code>s and keeps a list of active default
     * credentials. It is resolved by a call to
     * <pre>
     *   ORB.resolve_initial_references("SecurityLevel3:CredentialsCurator");
     * </pre>
     * Or it may be retrieved from the <code>SecurityManager</code>'s
     * <code>credentials_curator</code> attribute.
     * <p>
     * The following pseudo code describes the process of credentials
     * acquisition using <code>CredentialsCurator</code>.
     * <pre>
     * // Resolve the Credentials Curator
     * CredentialsCurator curator = ....
     *     resolve_initial_references("SecurityLevel3:CredentialsCurator");
     *
     * // Build up an acquisition argument (e.g., using SL3CSI::CSIArgBuilder)
     * Any arg = ...
     *
     * // Acquire credentials and get a Credentials Acquirer
     * CredentialsAcquirer acquirer =
     *     curator.acquire_credentials("SL3CSIAQArgs",arg);
     *
     * // Get credentials and destroy the Credentials Acquirer
     * OwnCredentials own = acquirer.get_credentials(false);
     * </pre>
     */
    local interface CredentialsCurator {

        /**
         * This attribute contains a list of
         * acquisition methods that are supported. Method identifiers
         * are defined in modules that signify their support.
         *
         * @see "SL3CSI"
         * @see "SL3TLS"
         * @see "SL3TCPIP"
         * @see "SL3KRB5"
         */
        readonly attribute SecurityLevel3::AcquisitionMethodList
                                                        supported_methods;

        /**
         * This operation starts the process of credentials acquisition and
         * create a <code>CredentialsAcquirer</code> for a particular
         * acquisition method. It takes an initial set of arguments for
         * the acquisition. The content of the arguments are based on the
         * acquisiton method. Depending on the method, it is possible that
         * the credentials may be immediately available from a call to
         * <code>get_credentials</code> on the returned
         * <code>CredentialsAcquirer</code>.
         * <p>
         * If the process of credentials acquisition is not completed upon
         * the return of the <code>acquire_credentials</code> operation,
         * the returned <code>CredentialsAcquirer</code> object shall have
         * its <code>current_status</code> at <code>AQST_Continued</code>.
         * In this case, the <code>get_continuation_data</code> and
         * <code>continue_acquisition</code> operations shall be used to
         * complete the credentials acquisition process.
         * <p>
         * If the process of credentials acquisition fails, it is up to the
         * implementation to either throw a system exception or return a
         * <code>CredentialsAcquirer</code> with the <code>AQST_Failed</code>
         * status.
         * <p>
         * The <code>acquisition_arguments</code> parameter is a CORBA
         * <code>any</code> that is constructed according to the acquisition
         * method used. The <code>ArgumentFactory</code> from the
         * <code>SL3AQArgs</code> module is a local object that helps
         * immensely with the construction of this complex argument.
         * Extensions of that object are defined in their own separate
         * modules that pertain to the particular acquisition mechanism,
         * such as the SL3CSI, SL3TLS, SL3TCPIP, SL3KRB5 modules.
         *
         * @param acquisition_method
         *       The identifier of the desired acquisition method.
         *       A CORBA <code>BAD_PARAM</code> exception will be raised
         *       if the named method is not supported.
         * @param acquisition_arguments
         *       The argument of the desired acquisition method.
         *       This CORBA <code>any</code> type is constructed according
         *       to the particular acquisition method.
         *
         * @see "SL3AQArgs"
         * @see "SL3CSI"
         * @see "SL3TLS"
         * @see "SL3TCPIP"
         * @see "SL3KRB5"
         */
        CredentialsAcquirer acquire_credentials(
            in  SecurityLevel3::AcquisitionMethod     acquisition_method,
            in  any                                   acquisition_arguments
        );

        /**
         * The Curator's Default Own Credentials list.
         */
        readonly attribute OwnCredentialsList default_creds_list;

        /**
         * The Curator's ids of the credentials on the default list.
         */
        readonly attribute CredentialsIdList  default_creds_ids;

        /**
         * This operation retrieves Own Credentials by identifier.
         * It is not required that the identifier name a credentials
         * on the default_credentials_list.  The Curator keeps track
         * of all OwnCredentials it creates, until they are explicitly
         * released.
         */
        OwnCredentials get_own_credentials(
            in CredentialsId credentials_id
        );

        /**
         * This operation releases credentials from the default_creds_list,
         * if there, and also disables the credentials from further use,
         * provided that all their pending work is done.
         */
        void release_own_credentials (
            in CredentialsId  credentials_id
        );

    };

    //--------------------------------------------------------------------
    // Security Service ORB Objects
    //     Retrieved from the ORB by "resolve_initial_references".
    //
    //--------------------------------------------------------------------

    /**
     * The <code>SecurityManager</code> object represents the Security Level 3
     * Security Service. There is one object of this type per ORB
     * instance. It is resolved by a call to
     * <pre>
     *   ORB.resolve_initial_references("SecurityLevel3:SecurityManager");
     * </pre>
     */
    local interface SecurityManager {

        /**
         * The credentials_curator attribute contains the reference
         * to the SecurityLevel3 Credentials Curator. There is only
         * one instance per ORB.
         */
        readonly attribute CredentialsCurator credentials_curator;

        /**
         * The get_target_credentials operation retrieves the
         * TargetCredentials that represents a CSIv2 security association
         * with a Target. This operation causes communication with
         * the target in order to establish a security context.
         */
        TargetCredentials get_target_credentials(
            in  Object          the_object
        );

        /**
         * The create_context_estab_policy operation is a policy factory
         * operation that creates the Security Level 3
         * ContextEstablishmentPolicy object. This policy is placed on
         * the policy override lists of object references to direct
         * the security characteristics when communicating through
         * that object reference.
         * <p>
         * If this policy is not put on an object reference, and the
         * <a href="TransportSecurity.ObjectCredentialsPolicy.html">
         * TransportSecurity::ObjectCredentialsPolicy</a>
         * is also not on the object references policy list,
         * then the default credentials lists from the
         * <a href="SecurityLevel3.CredentialsCurator.html">
         * SecurityLevel3::CredentialsCurator</a>
         * and
         * <a href="TransportSecurity.CredentialsCurator.html">
         * TransportSecurity::CredentialsCurator</a>
         * are used.
         */
        ContextEstablishmentPolicy create_context_estab_policy(
            in CredsDirective     creds_directive,
            in OwnCredentialsList creds_list,
            in FeatureDirective   use_client_auth,
            in FeatureDirective   use_target_auth,
            in FeatureDirective   use_confidentiality,
            in FeatureDirective   use_integrity
        );

        /**
         * The create_object_creds_policy is a policy factory operation
         * that creates the ObjectCredentialsPolicy object. This policy
         * is solely for use with policies place on POAs with "POA.create_POA".
         * It restricts the POAs use of credentials. If this policy is
         * not put on a POA, and the
         * <a href="TransportSecurity.ObjectCredentialsPolicy.html">
         * TransportSecurity::ObjectCredentialsPolicy</a>
         * is also not on the  POA policy list, then the default
         * credentials lists from the
         * <a href="SecurityLevel3.CredentialsCurator.html">
         * SecurityLevel3::CredentialsCurator</a>
         * and
         * <a href="TransportSecurity.CredentialsCurator.html">
         * TransportSecurity::CredentialsCurator</a>
         * are used.
         */
        ObjectCredentialsPolicy create_object_creds_policy(
            in OwnCredentialsList   creds_list
        );
    };

    /**
     * The <code>SecurityCurrent</code> object references thread specific
     * data pertaining to the security service. It is used to retrieve
     * the client's credentials during an invocation on the server side.
     * <p>
     * There is only one instance of this object per ORB instance.
     * It is resolved by a call to
     * <pre>
     *   ORB.resolve_initial_references("SecurityLevel3:SecurityCurrent");
     * </pre>
     */
    local interface SecurityCurrent {

        /**
         * From inside the execution of a target object implementation,
         * this attribute contains the representation of the remote client's
         * credentials. This attribute is null if the client is not CSIv2
         * based, or the client is from a collocated call.
         * <p>
         * The value of this attribute, if not null, represents the
         * security context with a remote CSIv2 client.
         * If the <code>request_is_local<code> attribute is <code>FALSE</code>,
         * the current thread of execution is directly servicing a remote
         * request for the target object within the target's implemenation.
         * If the <code>request_is_local</code> attribute is <code>TRUE</code>,
         * the current thread of execution is servicing an ORB mediated call
         * on a collocated object.
         * <p>
         * If the client is not CSIv2 based, there are no CSIv2 Client
         * Credentials, and this attribute is null. In this case,
         * the user should try the
         * <a href="TransportSecurity.SecurityCurrent.html>
         * TransportSecurity::SecurityCurrent</a>,
         * as the request may have come over a secure or
         * insecure transport, such as IIOP or TLS, without a CSIv2
         * Service Context.
         */
        readonly attribute ClientCredentials client_credentials;

        /**
         * If this attribute is <code>TRUE</code>, the client_credentials attribute
         * returns the credentials of the remote client no matter how
         * deep the collocated call stack, unless of course, this request
         * is not CSIv2 based, in which case it returns null.
         * This attribute is <code>TRUE</code> if the current thread of
         * execution is servicing a request on a collocated object.
         * This attribute is <code>FALSE</code> if the current thread of
         * execution is immediately servicing a remote request.
         * <p>
         * If this attribute is <code>TRUE</code>, there may or may not be
         * a remote client. If there is a remote client and the client is
         * CSIv2 based, the <code>client_credentials</code> attribute will
         * return the credentials of the remote client.
         * <p>
         * If this attribute is <code>FALSE</code>, there will always be a
         * remote client. In such case, the <code>client_credentials</code>
         * attribute will return the credentials of the remote client,
         * unless the client is not CSIv2 based.
         */
        readonly attribute boolean request_is_local;
    };

};
#endif
