NAME
   sec_login_validate_identity - Validates a login context's identity

 SYNOPSIS

 #include <dce/sec_login.h>

 boolean32 sec_login_validate_identity(
         sec_login_handle_t login_context,
         sec_passwd_rec_t *passwd,
         boolean32 *reset_passwd,
         sec_login_auth_src_t *auth_src,
         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.  (See sec_intro for more details
        about the login context.)

 passwd
        A password record to be checked against the password in the
        principal's registry account. The routine returns TRUE if the
        two match. The contents of the passwd parameter are erased
        after the call has finished processing it.

 Output

 reset_passwd
        A pointer to a 32-bit boolean32 value. The routine returns
        TRUE if the account password has expired and must be reset.

 auth_src
        How the the login context was authorized.  The
        sec_login_auth_src_t data type distinguishes the various
        ways the login context was authorized. There are three
        possible values:

        sec_login_auth_src_network

        sec_login_auth_src_local

        sec_login_auth_src_overridden

 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_validate_identity() routine validates the login context
 established with sec_login_setup_identity().  This operation must be
 invoked before the network credentials can be used. The caller must
 supply the user's password in a sec_passwd_rec_t as input with the
 passwd parameter.  The following example sets up a plaintext password
 for the passwd parameter:

      sec_passwd_str_t      tmp_passwd;

      passwd.version_number = sec_passwd_c_version_none;
      passwd.pepper = NULL;
      passwd.key.key_type = sec_passwd_plain;

      strncpy( (char *) tmp_passwd,
               (char *) my_passwd,
               sec_passwd_str_max_len );
      tmp_passwd[sec_passwd_str_max_len] = ' ';
      passwd_rec.key.tagged_union.plain = &(tmp_passwd[0]);

 When a network identity is set, only state information for network
 operations has been established. The local operating system identity
 has not been modified.  It is the responsibility of the caller to
 establish any local operating identity state.

 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. The operations are independent
 so the user's password need not be sent across the network.  The
 identity validation performed by sec_login_validate_identity() is a
 local operation.

 NOTES

 A context is not secure and must not be set or exported until the
 authentication service is itself authenticated with the
 sec_login_certify_identity() call.

 System login programs that set local operating system identity
 using data extracted from a login context should use
 sec_login_valid_and_cert_ident() instead of
 sec_login_validate_identity().

 If the Security server and client clocks are not synchronized to
 within 2 to 3 minutes of each other, this call can return a password
 validation error.

 RETURN VALUES

 The routine returns TRUE if the login identity has been successfully
 validated.

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

 ERRORS

 sec_rgy_passwd_invalid
              The input string does not match the account password.

 sec_rgy_server_unavailable
              There is no data with which to compare the input string.

 sec_login_s_acct_invalid
              The account is invalid or has expired.

 sec_login_s_null_password
              The input string is NULL.

 sec_login_s_default_use
              The input context was the default context, which cannot
              be validated.

 sec_login_s_already_valid
              The login context has already been validated.

 sec_login_s_unsupp_passwd_type
              The password type is not supported.

 sec_login_s_no_memory
              Not enough memory is available to complete the operation.

 sec_login_s_preauth_failed
              Preauthentication failure.

 error_status_ok
              The call was successful.

 EXAMPLES

 The following example illustrates use of the
 sec_login_validate_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_certify_identity
            sec_login_setup_identity
            sec_login_valid_and_cert_ident