NAME
   sec_login_become_initiator - Constructs a new login context that
                                enables delegation for the calling client

 SYNOPSIS

 #include <dce/sec_login.h>

 sec_login_handle_t sec_login_become_initiator(
         sec_login_handle_t my_login_context,
         sec_id_delegation_type_t delegation_type_permitted,
         sec_id_restriction_set_t *delegate_restrictions,
         sec_id_restriction_set_t *target_restrictions,
         sec_id_opt_req_t *optional_restrictions,
         sec_id_opt_req_t *required_restrictions,
         sec_id_compatibility_mode_t compatibility_mode,
         error_status_t *status);

 PARAMETERS

 Input

 my_login_context
        A value of sec_login_handle_t that provides an opaque handle to
        the identity of the client that is enabling delegation. The
        sec_login_handle_t that specifies the client's identity is
        supplied as output of the following calls:

         + sec_login_get_current_context() if the client inherited the
           identity of the current context

         + The sec_login_setup_identity() and the
           sec_login_validate_identity() pair that together establish
           an authentiated identity if a new identity was established

 delegation_type_permitted
        A value of sec_id_delegation_type_t that specifies the type of
        delegation to be enabled.  The types available are:

        sec_id_deleg_type_none
                  No delegation.

        sec_id_deleg_type_traced
                  Traced delegation.

        sec_id_deleg_type_impersonation
                  Simple (impersonation) delegation.

 Note each subsequent intermediate delegate of the delegation chain
 started by the initiating client must set the delegation type to traced
 if the initiating client set it to traced or to simple if the
 initiating client set it to simple.   Intermediate delegates, however,
 can set the delegation type to no delegation to indicate that the
 delegation chain can proceed no further.

 delegate_restrictions
        A pointer to a sec_id_restriction_set_t that supplies a list
        of servers that can act as delegates for the client initiating
        delegation.

 target_restrictions
        A pointer to a sec_id_restriction_set_t that supplies a list
        of servers that can act as targets for the client initiating
        delegation.

 optional_restrictions
        A pointer to a sec_id_opt_req_t that supplies a list of
        application-defined optional restrictions that apply to the
        client initiating delegation.

 required_restrictions
        A pointer to a sec_id_opt_req_t that supplies a list of
        application-defined required restrictions that apply to the
        client initiating delegation.

 compatibility_mode
        A value of sec_id_compatibility_mode_t that specifies the
        compatibility mode to be used when the initiating client
        interacts with pre-1.1 servers.  The modes available are:

        sec_id_compat_mode_none
                  Compatibility mode is off.

        sec_id_compat_mode_initiator
                  Compatibility mode is on.  The pre-1.1 PAC data is
                  extracted from the EPAC of the initiating client.

        sec_id_compat_mode_caller
                  Compatibility mode is on. The pre-1.1 PAC data
                  extracted from the EPAC of the last client in the
                  delegation chain.

 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_become_initiator() enables delegation for the calling
 client by constructing a new login context (in a sec_login_handle_t)
 that carries delegation information.  This information includes the
 delegation type, delegate, and target restrictions, and any
 application-defined optional and required restrictions.

 The new login context is then used to to set up authenticated rpc with
 an intermediate server using the rpc_binding_set_auth_info() call. The
 intermediary can continue the delegation chain by calling
 sec_login_become_delegate (if the delegation type is
 sec_id_deleg_type_traced) or sec_login_become_impersonator (if the
 delegation type is sec_id_deleg_type_impersonation).

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

 ERRORS

 sec_login_s_invalid_context

 sec_login_s_invalid_deleg_type

 err_sec_login_invalid_delegate_restriction

 err_sec_login_invalid_target_restriction

 err_sec_login_invalid_opt_restriction

 err_sec_login_invalid_req_restriction

 sec_login_s_invalid_compat_mode

 error_status_ok

 RELATED INFORMATION

 Functions: sec_intro
            sec_login_become_delegate
            sec_login_become_impersonator
            sec_login_get_current_context
            sec_login_setup_identity
            sec_login_validate_identity