NAME
   sec_login_valid_and_cert_ident - Validates and certifies a login
 				   context

 SYNOPSIS

 #include <dce/sec_login.h>

 boolean32 sec_login_valid_and_cert_ident(
         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
        A 32-bit set of flags identifying the source of the
        authentication.  Upon return after successful authentication,
        the flags in auth_src indicate what authority was used to
        validate the login context. If the authentication was
        accomplished with the network authority, the
        sec_login_auth_src_network flag is set, and the process login
        context has credentials to use the network. If the
        authentication was accomplished with local data only (either
        the principal's account is tailored for the local machine
        with overrides, or the network authority is unavailable), the
        sec_login_auth_src_local flag is set.  Login contexts that are
        authenticated locally may not be used to establish network
        credentials because they have none.

 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_valid_and_cert_ident() routine validates and certifies
 a login context established with sec_login_setup_identity().  The
 caller must supply the user's password as input with the passwd
 parameter.

 This routine combines the operations of the
 sec_login_validate_identity() and sec_login_certify_identity()
 routines.  It is intended for use by system login programs that
 need to extract trustworthy operating system credentials for use
 in setting the local identity for a process.  This operation
 destroys the contents of the passwd input parameter.

 If the network security service is unavailable or if the user's
 password has been overridden on the host, a locally authenticated
 context is created, and the auth_src parameter is set to
 sec_login_auth_src_local.  Data extracted from a locally
 authenticated context may be used to set the local OS identity, but
 it cannot be used to establish network credentials.

 This routine is a privileged operation.

 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
              The DCE Registry Server is unavailable.

 sec_login_s_acct_invalid
              The account is invalid or has expired.

 sec_login_s_privileged
              This is a privileged operation and was invoked by an
              unprivileged process.

 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_valid_and_cert_ident() routine as part of a system login
 process:

      if (sec_login_setup_identity(<user>,
           sec_login_no_flags, &login_context, &st)) {
               ... get password ...
               if (sec_login_valid_and_cert_ident(login_context,
                    password, &st)) {
                     if (auth_src == sec_login_auth_src_network) {
                        if (GOOD_STATUS(&st)
                        sec_login_set_context(login_context);
                        }
               }
               if (reset_passwd) {
                  ... reset the user's password ...
                  if (passwd_reset_fails) {
                      sec_login_purge_context(login_context)
                      ... application login failure actions ...
               }
               ... application specific login valid actions ...
           }
      }

 RELATED INFORMATION

 Functions: sec_intro
            sec_login_certify_identity
            sec_login_setup_identity
            sec_login_validate_identity