Using Security in CORBA Applications

Automation Security Reference

This topic contains the Automation method descriptions for CORBA security. This topic includes the following section:

Method Descriptions

Notes:

The Automation security methods do not support certificate authentication or the use of the SSL protocol.

Note:

The BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.

Note:

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. BEA Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

Method Descriptions

This section describes the Automation Security Service methods.

DISecurityLevel2_Current

The DISecurityLevel2_Current object is a BEA implementation of the CORBA Security model. In this release of the BEA Tuxedo software, the get_attributes(), set_credentials(), get_credentials(), and Principal_Authenticator() methods are supported.

DISecurityLevel2_Current.get_attributes

Synopsis

Returns attributes for the Current interface.

MIDL Mapping

HRESULT get_attributes( [in] VARIANT attributes, [in,out,optional] VARIANT* exceptionInfo, [out,retval] VARIANT* returnValue);

Automation Mapping

Function get_attributes(attributes, [exceptionInfo])

Parameters

`attributes`

The set of security attributes (privilege attribute types) whose values are desired. If this list is empty, all attributes are returned.

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Description

This method gets privilege (and other) attributes from the credentials for the client application from the Current interface.

Return Values

A variant containing an array of DISecurity_SecAttribute objects. The following table describes the valid return values.

Return Value	Meaning
`Security::Public`	Empty (Public is returned when no authentication was performed.)
`Security::AccessId`	Null-terminated ASCII string containing the BEA Tuxedo username.
`Security::PrimaryGroupId`	Null-terminated ASCII string containing the BEA Tuxedo name of the client application.

DISecurityLevel2_Current.set_credentials

Synopsis

Sets credentials type.

MIDL Mapping

HRESULT set_credentials( [in] Security_CredentialType cred_type, [in] DISecurityLevel2_Credentials* cred, [in,out,optional] VARIANT* exceptionInfo);

Automation Mapping

Sub set_credentials(cred_type As Security_CredentialType, cred As DISecurityLevel2_Credentials, [exceptionInfo])

Description

This method can be used only to set SecInvocationCredentials; otherwise, set_credentials raises CORBA::BAD_PARAM. The credentials must have been obtained from a previous call to DISecurityLevel2_Current.get_credentials.

Arguments

`cred_type`

The type of credentials to be set; that is, invocation, own, or nonrepudiation.

`cred`

The object reference to the Credentials object, which is to become the default.

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Return Values

None.

DISecurityLevel2_Current.get_credentials

Synopsis

Gets credentials type.

MIDL Mapping

HRESULT get_credentials( [in] Security_CredentialType cred_type, [in,out,optional] VARIANT* exceptionInfo, [out,retval] DISecurityLevel2_Credentials** returnValue);

Automation Mapping

Function get_credentials(cred_type As Security_CredentialType, [exceptionInfo]) As DISecurityLevel2_Credentials

Description

This call can be used only to get SecInvocationCredentials; otherwise, get_credentials raises CORBA::BAD_PARAM. If no credentials are available, get_credentials raises CORBA::BAD_INV_ORDER.

Arguments

`cred_type`

The type of credentials to get.

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Return Values

A DISecurityLevel2_Credentials object for the active credentials in the client application only.

DISecurityLevel2_Current.principal_authenticator

Synopsis

Returns the PrincipalAuthenticator.

MIDL Mapping

HRESULT principal_authenticator([out, retval] DITobj_PrincipalAuthenticator** returnValue);

Automation Mapping

Property principal_authenticator As DITobj_PrincipalAuthenticator

Description

The PrincipalAuthenticator returned by the principal_authenticator property is of actual type DITobj_PrincipalAuthenticator. Therefore, it can be used as a DISecurityLevel2_PrincipalAuthenticator.

Note: This method raises CORBA::BAD_INV_ORDER if it is called on an invalid SecurityCurrent object.

Return Values

A DITobj_PrincipalAuthenticator object.

DITobj_PrincipalAuthenticator

The DITobj_PrincipalAuthenticator object is used to log in to and log out of the BEA Tuxedo domain. In this release of the BEA Tuxedo software, the authenticate, build_auth_data(), continue_authentication(), get_auth_type(), logon(), and logoff() methods are implemented.

DITobj_PrincipalAuthenticator.authenticate

Synopsis

Authenticates the client application.

MIDL Mapping

HRESULT authenticate(
     [in] long 						method,
     [in] BSTR 						security_name,
     [in] VARIANT 						auth_data,
     [in] VARIANT 						privileges,
     [out] DISecurityLevel2_Credentials**

						creds,
     [out] VARIANT* 						continuation_data,
     [out] VARIANT* 						auth_specific_data,
     [in,out,optional] VARIANT* 						exceptionInfo,
     [out,retval] Security_AuthenticationStatus* returnValue);

Automation Mapping

Function authenticate(method As Long, security_name As String, auth_data, privileges, creds As DISecurityLevel2_Credentials, continuation_data, auth_specific_data, [exceptionInfo]) As Security_AuthenticationStatus

Arguments

`method`

Must be Tobj::TuxedoSecurity. If method is invalid, authenticate raises CORBA::BAD_PARAM.

`security_name`

The BEA Tuxedo username.

`auth_data`

As returned by DITobj_PrincipalAuthenticator.build_auth_data. If auth_data is invalid, authenticate raises CORBA::BAD_PARAM.

`privileges`

As returned by DITobj_PrincipalAuthenticator.build_auth_data. If privileges is invalid, authenticate raises CORBA::BAD_PARAM.

`creds`

Placed into the SecurityCurrent object.

`continuation_data`

Always empty.

`auth_specific_data`

Always empty.

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

`Description`

This method authenticates the client application via the IIOP Listener/Handler so that it can access a BEA Tuxedo domain.

Return Values

A Security_AuthenticationStatus Enum value. The following table describes the valid return values.

Return Value	Meaning
`Security::AuthenticationStatus:: SecAuthSuccess`	The authentication succeeded.
`Security::AuthenticationStatus:: SecAuthFailure`	The authentication failed, or the client application was already authenticated and did not invoke `Tobj::PrincipalAuthenticator:logoff` or `Tobj_Bootstrap::destroy_current`.

DITobj_PrincipalAuthenticator.build_auth_data

Synopsis

Creates authentication data and attributes for use by DITobj_PrincipalAuthenticator.authenticate.

MIDL Mapping

HRESULT build_auth_data(
  [in] BSTR 				user_name,
  [in] BSTR 				client_name,
  [in] BSTR 				system_password,
  [in] BSTR 				user_password,
  [in] VARIANT 				user_data,
  [out] VARIANT* 				auth_data,
  [out] VARIANT* 				privileges,
  [in,out,optional] VARIANT* exceptionInfo);

Automation Mapping

Sub build_auth_data(user_name As String, client_name As String, system_password As String, user_password As String, user_data, auth_data, privileges, [exceptionInfo])

`Arguments`

`user_name`

The BEA Tuxedo username.

`client_name`

A name of the CORBA client application.

`system_password`

The password for the CORBA client application.

`user_password`

The user password (for default authentication service).

`user_data`

Client application-specific data (custom authentication service).

`auth_data`

For use by authenticate.

`privileges`

For use by authenticate.

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Note: If user_name, client_name, or system_password is NULL or empty, or exceeds 30 characters, the subsequent authenticate method invocation raises the CORBA::BAD_PARAM exception.

Note: The user_password and user_data parameters are mutually exclusive, depending on the requirements of the authentication service used in the configuration of the BEA Tuxedo domain. The default authentication service expects a user password. A customized authentication service may require user data. If both user_password and user_data are specified, the subsequent authentication call raises the CORBA::BAD_PARAM exception.

`Description`

This method is a helper function that creates authentication data and attributes to be used by DITobj_PrincipalAuthenticator.authenticate.

Note: This method raises CORBA::BAD_INV_ORDER if it is called with an invalid SecurityCurrent object.

Return Values

None.

DITobj_PrincipalAuthenticator.continue_authentication

Synopsis

Always returns Security::AuthenticationStatus::SecAuthFailure.

MIDL Mapping

HRESULT continue_authentication( [in] VARIANT response_data, [in,out] DISecurityLevel2_Credentials** creds, [out] VARIANT* continuation_data, [out] VARIANT* auth_specific_data, [in,out,optional] VARIANT* exceptionInfo, [out,retval] Security_AuthenticationStatus* returnValue);

Automation Mapping

Function continue_authentication(response_data, creds As DISecurityLevel2_Credentials, continuation_data, auth_specific_data, [exceptionInfo]) As Security_AuthenticationStatus

Description

Because the BEA Tuxedo software does authentication in one step, this method always fails and returns Security::AuthenticationStatus::SecAuthFailure.

Return Values

Always returns SecAuthFailure.

DITobj_PrincipalAuthenticator.get_auth_type

Synopsis

Gets the type of authentication expected by the BEA Tuxedo domain.

MIDL Mapping

HRESULT get_auth_type(
        [in, out, optional] VARIANT* exceptionInfo, 
        [out, retval] Tobj_AuthType* returnValue);

Automation Mapping

Function get_auth_type([exceptionInfo]) As Tobj_AuthType

Argument

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Description

This method returns the type of authentication expected by the BEA Tuxedo domain.

Note: This method raises CORBA::BAD_INV_ORDER if it is called with an invalid SecurityCurrent object.

Returned Values

A reference to the Tobj_AuthType enumeration. The following table describes the valid return values.

Return Value	Meaning
`TOBJ_NOAUTH`	No authentication is needed; however, the client application can still authenticate itself by specifying a username and a client application name. No password is required. To specify this level of security, specify the `NONE` value for the `SECURITY` parameter in the `RESOURCES` section of the `UBBCONFIG` file.
`TOBJ_SYSAUTH`	The client application must authenticate itself to the BEA Tuxedo domain, and must specify a username, a name, and a password for the client application. To specify this level of security, specify the `APP_PW` value for the `SECURITY` parameter in the `RESOURCES` section of the `UBBCONFIG` file.
`TOBJ_APPAUTH`	The client application must provide proof material that authenticates the client application to the BEA Tuxedo domain.The proof material may be a password or a digital certificate. To specify this level of security, specify the `USER_AUTH` value for the `SECURITY` parameter in the `RESOURCES` section of the `UBBCONFIG` file.

DITobj_PrincipalAuthenticator.logon

Synopsis

Logs in to the BEA Tuxedo domain. The correct input parameters depend on the authentication level.

MIDL Mapping

HRESULT logon(
  [in] BSTR 						user_name,
  [in] BSTR						client_name,
  [in] BSTR 						system_password,
  [in] BSTR 						user_password,
  [in] VARIANT 						user_data,
  [in,out,optional] VARIANT* 						exceptionInfo,
  [out,retval] Security_AuthenticationStatus*
 						returnValue);

Automation Mapping

Function logon(user_name As String, client_name As String, system_password As String, user_password As String, user_data, [exceptionInfo]) As Security_AuthenticationStatus

Description

For remote CORBA client applications, this method authenticates the client application via the IIOP Listener/Handler so that the remote client application can access a BEA Tuxedo domain. This method is functionally equivalent to DITobj_PrincipalAuthenticator.authenticate, but the parameters are oriented to security.

Arguments

`user_name`

The BEA Tuxedo username. This parameter is required for TOBJ_NOAUTH, TOBJ_SYSAUTH, and TOBJ_APPAUTH authentication levels.

`client_name`

The name of the CORBA client application. This parameter is required for TOBJ_NOAUTH, TOBJ_SYSAUTH, and TOBJ_APPAUTH authentication levels.

system_password

A password for the CORBA client application. This parameter is required for TOBJ_SYSAUTH and TOBJ_APPAUTH authentication levels.

`user_password`

The user password (default authentication service). This parameter is required for the TOBJ_APPAUTH authentication level.

user_data

Application-specific data (custom authentication service). This parameter is required for the TOBJ_APPAUTH authentication level.

Note: If user_name, client_name, or system_password is NULL or empty, or exceeds 30 characters, the subsequent authenticate method invocation raises the CORBA::BAD_PARAM exception.

Note: If the authorization level is TOBJ_APPAUTH, only one of user_password or user_data may be supplied.

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Return Values

The following table describes the valid return values.

Return Value	Meaning
`Security::AuthenticationStatus:: SecAuthSuccess`	The authentication succeeded.
`Security::AuthenticationStatus:: SecAuthFailure`	The authentication failed, or the client application was already authenticated and did not call one of the following methods: `Tobj::PrincipalAuthenticator:logoff` `Tobj_Bootstrap::destroy_current`

DITobj_PrincipalAuthenticator.logoff

Synopsis

Discards the current security context associated with the CORBA client application.

MIDL Mapping

HRESULT logoff([in, out, optional] VARIANT* exceptionInfo);

Automation Mapping

Sub logoff([exceptionInfo])

Description

This call discards the context associated with the CORBA client application, but does not close the network connections to the BEA Tuxedo domain. Logoff also invalidates the current credentials. After logging off, calls using existing object references fail if the authentication type is not TOBJ_NOAUTH.

If the client application is currently authenticated to a BEA Tuxedo domain, calling Tobj_Bootstrap.destroy_current() calls logoff implicitly.

Argument

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Return Values

None.

DISecurityLevel2_Credentials

The DISecurityLevel2_Credentials object is a BEA implementation of the CORBA Security model. In this release of the BEA Tuxedo software, the get_attributes() and is_valid() methods are supported.

DISecurityLevel2_Credentials.get_attributes

Synopsis

Gets the attribute list attached to the credentials.

MIDL Mapping

HRESULT get_attributes( [in] VARIANT attributes, [in,out,optional] VARIANT* exceptionInfo, [out,retval] VARIANT* returnValue);

Automation Mapping

Function get_attributes(attributes, [exceptionInfo])

Arguments

`attributes`

The set of security attributes (privilege attribute types) whose values are desired. If this list is empty, all attributes are returned.

`exceptioninfo`

An optional input argument that allows the client application to get additional exception data if an error occurs.

Description

This method returns the attribute list attached to the credentials of the client application. In the list of attribute types, you are required to include only the type value(s) for the attributes you want returned in the AttributeList. Attributes are not currently returned based on attribute family or identities. In most cases, this is the same result you would get if you called DISecurityLevel2.Current::get_attributes(), since there is only one valid set of credentials in the client application at any instance in time. The results could be different if the credentials are not currently in use.

Return Values

A variant containing an array of DISecurity_SecAttribute objects.

DISecurityLevel2_Credentials.is_valid

Synopsis

Checks the status of credentials.

MIDL Mapping

HRESULT is_valid( [out] IDispatch** expiry_time, [in,out,optional] VARIANT* exceptionInfo, [out,retval] VARIANT_BOOL* returnValue

Automation Mapping

Function is_valid(expiry_time As Object, [exceptionInfo]) As Boolean

Description

This method returns TRUE if the credentials used are active at the time; that is, you did not call DITobj_PrincipalAuthenticator.logoff or destroy_current. If this method is called after DITobj_PrincipalAuthenticator.logoff(), FALSE is returned. If this method is called after destroy_current(), the CORBA::BAD_INV_ORDER exception is raised.

Return Values

The output expiry_time as a DITimeBase_UtcT object set to max.