PreviousNext

sec_login_refresh_identity(3sec)

Refreshes an authenticated identity for a login context

Synopsis

#include <dce/sec_login.h>

boolean32 sec_login_refresh_identity(
sec_login_handle_t login_context,
error_status_t *
status);

Parameters

Input

login_context
An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory.

Output

status
A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.

Description
The sec_login_refresh_identity( ) routine refreshes a previously established identity. It operates on an existing valid context, and cannot be used to change credentials associated with that identity. The refreshed identity reflects changes that affect ticket lifetimes, but not other changes. For example, the identity will reflect a change to maximum ticket lifetime, but not the addition of the identity as a member to a group. Only a DCE login reflects all administrative changes made since the last login.

The refreshed identity must be validated with sec_login_validate_identity( ) before it can be used.

It is an error to refresh a locally authenticated context.

Files

/usr/include/dce/sec_login.idl
The idl file from which dce/sec_login.h was derived.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

sec_login_s_context_invalid
The login context itself is not valid.

sec_login_s_default_use
Illegal use of the default login handle occurred.

sec_login_s_no_memory
Not enough memory is available to complete the operation.

error_status_ok
The call was successful.

Examples
Since the authenticated network identity for a process has a finite lifetime, there is a risk it will expire during some long network operation, preventing the operation from completing.

For a server application that must run with an authenticated network identity because they themselves sometimes act as clients of another server, the sec_login calls can be used to check the network identity expiration date, run sec_login_refresh_identity and sec_login_validate_identity before the expiration. This will prevent interruptions in the server's operation due to the restrictions in network access applied to an unauthenticated identity.

sec_login_get_expiration(login_context, &expire_time, &st);

if (expire_time < (current_time + operation_duration)) {

if (!sec_login_refresh_identity(login_context, &st)) {
... login context cannot be renewed ...
... sleep and try again ....
}

} else {

if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {
... identity validated ... } else {
... validation failed ...
exit(error_validation_failure);
}
}
}

operation( );

Related Information
Functions:

sec_intro(3sec)

sec_login_validate_identity(3sec)