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.

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle 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.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle 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 an Oracle implementation of the CORBA Security model. In this release of the Oracle 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 Oracle Tuxedo username.
Security::PrimaryGroupId	Null-terminated ASCII string containing the Oracle 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 Oracle Tuxedo domain. In this release of the Oracle 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 Oracle 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 an Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 an Oracle Tuxedo domain. This method is functionally equivalent to DITobj_PrincipalAuthenticator.authenticate, but the parameters are oriented to security.

Arguments

user_name

The Oracle 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 Oracle 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 an Oracle 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 an Oracle implementation of the CORBA Security model. In this release of the Oracle 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.