C++ Security Reference

Using Security in CORBA Applications

SecurityLevel2::PrincipalAuthenticator::authenticate

Synopsis

Authenticates the principal and optionally obtains credentials for the principal.

OMG IDL Definition

Security::AuthenticationStatus 
     authenticate(
       in   Security::AuthenticationMethod  method,
       in   Security::SecurityName          security_name,
       in   Security::Opaque                auth_data,
       in   Security::AttributeList         privileges,
       out  Credentials                     creds,
       out  Security::Opaque                continuation_data,
       out  Security::Opaque                auth_specific_data );

Arguments

method

The security mechanism to be used. Valid values are Tobj::TuxedoSecurity and Tobj::CertificateBased.

security_name

The principal's identification information (for example, logon information). The value must be a pointer to a NULL-terminated string containing the username of the principal. The string is limited to 30 characters, excluding the NULL character.

When using certificate authentication, this name is used to look up a certificate in the LDAP-enabled directory service. It is also used as the basis for the name of the file in which the private key is stored. For example:

milozzi@company.com is the e-mail address used to look up a certificate in the LDAP-enabled directory service and milozzi_company.pem is the name of the private key file.

auth_data

The principals' authentication, such as their password or private key. If the Tobj:TuxedoSecurity security mechanism is specified, the value of this argument is dependent on the configured level of authentication. If the Tobj::CertificateBased argument is specified, the value of this argument is the pass phrase used to decrypt the private key of the principal.

privileges

The privilege attributes requested.

creds

The object reference of the newly created Credentials object.The object reference is not fully initialized; therefore, the object reference cannot be used until the return value of the SecurityLevel2::Current::authenticate method is SecAuthSuccess.

continuation_data

If the return value of the SecurityLevel2::Current::authenticate method is SecAuthContinue, this argument contains the challenge information for the authentication to continue. The value returned will always be empty.

auth_specific_data

Information specific to the authentication service being used. The value returned will always be empty.

Description

The SecurityLevel2::Current::authenticate method is used by the client application to authenticate the principal and optionally request privilege attributes that the principal requires during its session with the BEA Tuxedo domain.

If the Tobj::TuxedoSecurity security mechanism is to be specified, the same functionality can be obtained by calling the Tobj::PrincipalAuthenticator::logon operation, which provides the same functionality but is specifically tailored for use with the ATMI authentication security mechanism.

Return Values

The following table describes the valid return values.

Return Value	Meaning
`SecAuthSuccess`	The object reference of the newly created Credentials object returned as the value of the `creds` argument is initialized and ready to use.
`SecAuthFailure`	The authentication process was inconsistent or an error occurred during the process. Therefore, the `creds` argument does not contain an object reference to a Credentials object. If the `Tobj::TuxedoSecurity` security mechanism is used, this return value indicates that authentication failed or that the client application was already authenticated and did not call either the `Tobj::PrincipalAuthenticator::logoff` or the `Tobj_Bootstrap::destroy_current` operation.
`SecAuthContinue`	Indicates that the authentication procedure uses a challenge/response mechanism. The `creds` argument contains the object reference of a partially initialized Credentials object. The `continuation_data` indicates the details of the challenge.
`SecAuthExpired`	Indicates that the authentication data contained some information, the validity of which had expired; therefore, the `creds` argument does not contain an object reference to a Credentials object. If the `Tobj::TuxedoSecurity` security mechanism is used, this return value is never returned.
`CORBA::BAD_PARAM`	The `CORBA::BAD_PARAM` exception occurs if: Values for the `security_name`, `auth_data`, or `privileges` arguments are not specified. The length of an input argument exceeds the maximum length of the argument. The value of the `method` argument is `Tobj::TuxedoSecurity` and the content of the `auth_data` argument contains a `username` or a `clientname` as an empty or a NULL string.