NAME

<dce/sec_login.h>-Header for sec_login API.

SYNOPSIS

#include <dce/sec_login.h>

DESCRIPTION

Data Types

The following data types (listed in alphabetical order) are used in sec_login API.

enum sec_login_auth_src_t

Indicates the source of authentication or certification (that is, the "certification authority") of a login context. The following values are currently registered:

sec_login_auth_src_network

Login context certified by "network authority" (that is, KDS/PS, in "network TCB"). Such a login context contains usable network credentials; that is, it can be used to make protected RPCs to any other DCE subject.

sec_login_auth_src_local

Login context certified by "local authority" (that is, local TCB). Such a login context does not contain usable network credentials; that is, it can be used to make protected RPCs only within the context of the local TCB (that is, only to subjects represented by other processes co-located on the same host as the caller).

unsigned32 sec_login_flags_t

A flag word describing attributes of a login context. The following flag is currently registered:

sec_login_credentials_private

This login context is restricted to the current process. If this flag is not set, this login context may be shared with other processes (via sec_login_export_context() and sec_login_import_context()).

Additionally, the value sec_login_no_flags of sec_login_flags_t indicates that no flags are set.

idl_void_p_t sec_login_handle_t

This is a pointer to a data structure representing an account's ("network") login context (the pointed-to structure is not further specified; that is, sec_login_handle_t is an "opaque pointer").

Conceptually, the login context contains a copy of all the account's information contained in the RS datastore relevant to the accounts operating in a DCE security environment (as specified in this document), appropriately protected. In the case of the Kerberos authentication service (the only authentication service currently supported by DCE), a login context conceptually contains, among other things, TGTs and PTGTs (targeted to the account's local KDS as well as to remote KDSs)-also referred to colloquially as "network credentials".

struct sec_login_net_info_t

Indicates certain "network information" associated with a login context. It includes the following fields:

sec_id_pac_t pac

The login context's PAC.

unsigned32 acct_expiration_date

The login context's account expiration date (measured in seconds from midnight January 1, 1970 UTC).

unsigned32 passwd_expiration_date

The login context's long-term key expiration date (measured in seconds from midnight January 1, 1970 UTC).

unsigned32 identity_expiration_date

The login context's expiration date (measured in seconds from midnight January 1, 1970 UTC). Conceptually, this is the expiration date of the TGT to the local KDS held in the login context.

A value of 0 for any of the above expiration dates means "forever"; that is, the information does not expire-it remains usable indefinitely.

idl_void_p_t sec_login_passwd_t

Pointer to data structure (whose internal structure is not further specified; that is, sec_login_passwd_t is an "opaque pointer") representing a password structure, used for local host purposes.

The detailed content of this structure is implementation-dependent. As an example, on POSIX-compliant operating systems, it will typically contain fields such as, or similar to, the following:

char *pw_name

User's name.

char *pw_passwd

Encrypted password.

int pw_uid

User's POSIX UID (local host user identity).

int pw_gid

User's POSIX GID (local host principal group identity).

time_t pw_change

Password expiration date.

char *pw_gecos

User's fullname (or other account information).

char *pw_dir

Home directory.

char *pw_shell

Default shell.

time_t pw_expire

Account expiration date.

struct sec_login_tkt_info_t

The structure of optional AS ticket request flags and associated data. It includes the following fields:

sec_login_tkt_flags_t options

The types of ticket options (requested). The options are listed in the Constants section for type sec_login_tkt_flags_t.

sec_timeval_period_t postdated_dormanttime

A time period expressed in seconds relative to some other well known base time. In this instance, it indicates the dormant time to be permitted. If the ticket optionf1 field specifies a postdated ticket (flag sec_login_tkt_postdated is set), this field must be specified.

sec_timeval_period_t renewable_lifetime

The renewable lifetime of the ticket if the optionsfield specifies a renewable ticket. It must be specified if a renewable ticket is being requested (if the sec_login_tkt_renewable flag is set in the options field).

sec_timeval_period_t lifetime

A non-default ticket lifetime that is specified (in seconds) and which must be specified if a non-default ticket lifetime (sec_login_tkt_lifetime flag is set in the options field.

Constants

The following constants are used in sec_login_ calls:

sec_login_handle_t sec_login_default_handle

The value of a login context handle before setup or validation.

sec_login_flags_t sec_login_no_flags

No flags are set.

sec_login_flags_t sec_login_credentials_private

Restricts the validated network credentials to the current process. If this flag is not set, it is permissible to share credentials with descendents of current process.

sec_login_flags_t sec_login_external_tgt

Specifies that externally obtained TGTs are to be used. This is a simple proxy mechanism.

sec_login_flags_t sec_login_machine_princ

Specifies that the login context is being created or validated by the machine principal.

In addition to those already listed above, the following constants are used in sec_login_ calls to request various attributes associated with tickets (TGTs):

sec_login_tkt_flags_t sec_login_tkt_renewable

Request for a renewable ticket.

sec_login_tkt_flags_t sec_login_tkt_postdated

Request for a postdated ticket.

sec_login_tkt_flags_t sec_login_tkt_allow_postdate

Permit postdated tickets to be used.

sec_login_tkt_flags_t sec_login_tkt_proxiable

Permit proxiable tickets to be used.

sec_login_tkt_flags_t sec_login_tkt_forwardable

Request for a forwardable ticket.

sec_login_tkt_flags_t sec_login_tkt_renewable_ok

Instructions to accept a renewable ticked if a real ticket cannot be granted.

sec_login_tkt_flags_t sec_login_tkt_lifetime

Request for a non-default ticket lifetime.

Status Codes

The following status codes, listed in alphabetical order, are used in sec_login calls. The status codes used in delegation are listed separately after this list:

error_status_ok

Routine completed successfully.

sec_login_s_acct_invalid

Account is invalid.

sec_login_s_already_valid

Login context has already been validated.

sec_login_s_auth_local

Operation not valid on local context.

sec_login_s_config

Bad configuration file (or SCD could not validate the TGT).

sec_login_s_context_invalid

Context has not been validated.

sec_login_s_default_use

Illegal use of default sec_login handle.

sec_login_s_groupset_invalid

The group set is not valid.

sec_login_s_handle_invalid

Context handle not valid.

sec_login_s_info_not_avail

Information not available.

sec_login_s_internal_error

Internal error (for example, unexpected violation of internal invariants, I/O problems, and so on).

sec_login_s_no_current_context

No currently established network identity for which context exists.

sec_login_s_no_memory

No memory available.

sec_login_s_not_certified

Login context is (validated but) not certified.

Note:

This status value is considered "advisory" only (advising the caller that the login context in use is not certified). Routines that return this status value are not considered to have "failed" (unless the caller requires a certified login context); in particular, valid data may be returned to the caller with this status value.

sec_login_s_null_password

Password is a NULL password.

sec_login_s_privileged

Caller is not "privileged", in some implementation-specific (local operating system) sense.

The routines currently specified in this chapter that can return this status value are the following: sec_login_init_first(), sec_login_setup_first(), sec_login_valid_and_cert_ident(), sec_login_validate_first(). Thus, these routines fail unless the caller is "privileged" (in a local-operating-system sense that must be documented in implementation-specific documentation).

In the case of POSIX-compliant operating systems, the "classical" interpretation of "privileged" is that the caller's effective POSIX UID is 0 (but note that this "classical" interpretation is undergoing transformation as POSIX standardisation progresses). Thus on such systems, implementations of these routines fail unless the caller has effective POSIX UID 0.

sec_login_s_refresh_ident_bad

This indicates that the calling identity has changed since the login context was created or last refreshed, in one of the following senses:

1. principal UUID or primary group UUID has changed

2. groupset UUIDs have been added to. (Deletions from the groupset are okay; if the intersection of the old and new groupsets is empty, the refreshed context will have an empty groupset.)

sec_login_s_unsupp_passwd_type

The password is an unsupported type.

Status Codes Specific to Delegation

The following status codes, listed in alphabetical order, are used in sec_login calls dealing with delegation:

error_status_ok

Routine completed successfully.

err_sec_login_invalid_delegate_restriction

This self-descriptive status code is reserved for future use.

err_sec_login_invalid_target_restriction

This self-descriptive status code is reserved for future use.

err_sec_login_invalid_opt_restriction

This self-descriptive status code is reserved for future use.

err_sec_login_invalid_req_restriction

This self-descriptive status code is reserved for future use.

sec_login_s_compound_delegate

Login context already specifies a delegation chain.

sec_login_s_default_use

Invalid use of default sec_login handle

sec_login_s_invalid_context

Context has not been validated. (Not a valid login context.)

sec_login_s_invalid_compat_mode

Invalid compatibility mode selection.

sec_cred_s_invalid_cursor

Invalid credential cursor.

sec_login_s_invalid_deleg_type

Invalid delegation type selection.

sec_login_s_deleg_not_enabled

Delegation has not been enabled.

sec_login_s_no_memory

No memory available (Unable to allcoate memory).

sec_cred_s_no_more_entries

No more entries available.