NAME
   sec_login_setup_identity - Sets up the user's network identity

 SYNOPSIS

 #include <dce/sec_login.h>

 boolean32 sec_login_setup_identity(
         unsigned_char_p_t principal,
         sec_login_flags_t flags,
         sec_login_handle_t *login_context,
         error_status_t *status);

 PARAMETERS

 Input

 principal
        A pointer (type unsigned_char_p_t) indicating a character
        string containing the principal name on the registry account
        corresponding to the calling process.

 flags  A set of flags of type sec_login_flags_t. These contain
        information about how the new network credentials are to be used.

 Output

 login_context
        A pointer to 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.  (See sec_intro for more details
        about the login context.)

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

 DESCRIPTION

 The sec_login_setup_identity() routine creates any local context
 necessary to perform authenticated network operations.  It does not
 establish any local operating system context; that is the
 responsibility of the caller.  It is the standard network login
 function.  The network identity set up by this operation cannot be
 used until it is validated via sec_login_validate_identity().

 The sec_login_setup_identity() operation and the
 sec_login_validate_identity() operation are two halves of a single
 logical operation.  Together they collect the identity data needed
 to establish an authenticated identity.

 NOTES

 Neither sec_login_setup_identity() nor sec_login_validate_identity()
 check for account or identity expiration.  The application program
 using this interface is responsible for such checks.

 RETURN VALUES

 The routine returns TRUE if the identity has been successfully
 established.

 FILES
       SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
              The idl file from which dce/sec_login.h was derived.

 ERRORS

 sec_rgy_object_not_found
              The principal does not exist.

 sec_rgy_server_unavailable
              The network registry is not available.

 sec_login_s_no_memory
              Not enough memory is available to complete the operation.

 error_status_ok
              The call was successful.

 EXAMPLES

 The following example illustrates use of the sec_login_setup_identity()
 routine as part of a straightforward login process:

      if (sec_login_setup_identity( user_name,
                                    sec_login_no_flags,
                                    &login_context,
                                    &st )) {
         ... get password from user...

         if (sec_login_validate_identity(login_context, password,
                                  &reset_passwd, &auth_src, &st)) {

            if (!sec_login_certify_identity(login_context, &st))
                exit(error_weird_auth_svc);

            sec_login_set_context(login_context, &st);

            if (auth_src != sec_login_auth_src_network)
               printf("no network credentials");

            if (reset_passwd) {
               ... get new password from user, reset registry record ...
            };

            sec_login_get_pwent(login_context, &pw_entry, &st);

            if (pw_entry.pw_expire < todays_date) {
               sec_login_purge_context(&login_context, &st);
               exit(0)
            }

            ... any other application specific login valid actions ...
            }

         } else {
            sec_login_purge_context(&login_context, &st);

            ... application specific login failure actions ...
         }
      }

 RELATED INFORMATION

 Functions: sec_intro
            sec_login_validate_identity
            sec_login_set_context