diff options
Diffstat (limited to 'TAO/orbsvcs/orbsvcs/SecurityLevel3.idl')
| -rw-r--r-- | TAO/orbsvcs/orbsvcs/SecurityLevel3.idl | 2039 |
1 files changed, 2039 insertions, 0 deletions
diff --git a/TAO/orbsvcs/orbsvcs/SecurityLevel3.idl b/TAO/orbsvcs/orbsvcs/SecurityLevel3.idl new file mode 100644 index 00000000000..018e6daf69b --- /dev/null +++ b/TAO/orbsvcs/orbsvcs/SecurityLevel3.idl @@ -0,0 +1,2039 @@ +//tabstop=4 +//*********************************************************************** +// ORBAsec SL3 +// ---------------------------------------------------------------------- +// Copyright (C) 2001 Adiron, LLC. +// All rights reserved. +// ---------------------------------------------------------------------- +// $Id$ +//*********************************************************************** + +//*********************************************************************** +/** + * @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 |