NAME
   sec_login_certify_identity - Certifies the network
 			       authentication service

 SYNOPSIS

 #include <dce/sec_login.h>

 boolean32 sec_login_certify_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. (See sec_intro for more details about
        the login context.)

 Output

 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_certify_identity() routine certifies that the Security
 Server used to set up and validate a login context is legitimate.  A
 legitimate server is one that knows the host machine's secret key.
 On some systems, this may be a privileged operation.

 Information may be retrieved via sec_login_get_pwent(),
 sec_login_get_groups(), and sec_login_get_expiration() from an
 uncertified login context, but such information cannot be trusted.
 All system login programs that use the sec_login interface must call
 sec_login_certify_identity() to certify the Security Server.  If they
 do not, they open the local file system to attacks by imposter Security
 servers returning suspect local process credentials (UUID and group
 IDs).  This operation updates the local registry with the login context
 credentials if the certification check succeeds.

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

 RETURN VALUES
 The routine returns a boolean32 value that is TRUE if the certification
 was successful, and FALSE otherwise.

 ERRORS

 sec_login_s_config
              The DCE configuration (dce_config) information is not
              available.

 sec_login_s_context_invalid
              The input context is invalid.

 sec_login_s_default_use
              It is an error to try to certify the default context.

 error_status_ok
              The call was successful.

 EXAMPLES

 Applications wishing to perform a straightforward login could use the
 sec_login package as follows:

      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_get_pwent
            sec_login_get_groups
            sec_login_get_expiration