/* @(#)68       1.5  src/security/idl/sec_login.idl, security.src, os2dce21.dss, 960602a.1  5/17/95  09:49:18 */
/*
 * COMPONENT_NAME:  security.src
 *
 * FUNCTIONS:
 *
 * ORIGINS: 72
 *
 */
/*
 * Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.
 * ALL RIGHTS RESERVED (DCE).  See the file named COPYRIGHT.DCE in the
 * src directory for the full copyright text.
 */
/*
 * HISTORY
 * $Log: sec_login.idl,v $
 * Revision 1.1.62.3  1994/06/02  21:28:47  mdf
 * 	hp_sec_to_osf_3 drop, merge up with latest.
 * 	[1994/05/24  20:01:22  mdf]
 *
 * Revision 1.1.62.2  1994/05/11  19:13:25  ahop
 * 	hp_sec_to_osf_2 drop
 * 	Remove sec_login_get_delegation_type()
 * 	Add new login context flag - sec_login_machine_princ.
 * 	add sec_login_purge_context_exp to handle expired creds
 * 	[1994/04/29  21:08:47  ahop]
 * 
 * Revision 1.1.62.1  1994/01/28  23:11:00  burati
 * 	Delegation/EPAC changes (dlg_bl1)
 * 	[1994/01/18  20:54:43  burati]
 * 
 * Revision 1.1.60.2  1993/10/14  20:02:18  sommerfeld
 * 	Latent support for authentication forwarding
 * 	[1993/10/14  15:54:51  sommerfeld]
 * 
 * Revision 1.1.60.1  1993/10/05  22:30:45  mccann
 * 	CR8651 64 bit porting changes
 * 	[1993/10/04  19:11:49  mccann]
 *
 * Revision 1.1.4.2  1992/12/29  13:54:19  zeliff
 * 	Embedding copyright notice
 * 	[1992/12/28  20:49:41  zeliff]
 *
 * Revision 1.1.2.3  1992/05/14  19:00:13  burati
 * 	Add sec_login_auth_src_overridden
 * 	[1992/05/14  01:54:42  burati]
 * 
 * Revision 1.1.2.2  1992/05/11  23:05:02  burati
 * 	Changed passwd from [in] to [in,out] in sec_login_validate_identity
 * 	Changed passwd from [in] to [in,out] in sec_login_valid_and_cert_ident
 * 	[1992/05/11  19:55:04  burati]
 * 
 * Revision 1.1  1992/01/19  14:55:39  devrcs
 * 	Initial revision
 * 
 * $EndLog$
 */

/*
** Copyright (c) Hewlett-Packard Company 1991, 1993
** Unpublished work. All Rights Reserved.
**
*/
/* Network Login facility.  Operations to check or set network identity.
 * 
 *
 * This local interface provides an authentication system independent 
 * API to establish a principal's network, and local operating system identity.  
 * To facilitate the integration of this interface into existing applications
 * that provide login services, a set of operations to extract local operating
 * system identity information.
 *
 * In general the function <sec_login_setup_identity> which yields a handle
 * to a login context, can replace the conventional <getpwnam> call and
 * <sec_login_valid_and_cert_identity> can replace the password check using <crypt>
 * and <strcmp>  (applications that care only about network credentials may
 * use <sec_login_validate_identity> instead).
 *
 * Applications that require all of the data normally extracted via <getpwnam>
 * should extract that data from the login context via the  <sec_login_get_pwent>
 * call.  To support unauthenticated user registration service queries, data may 
 * be extracted from a login context that has not yet been validated via
 * <sec_login_validate_identity>, but unauthenticated data may come from
 * an imposter security server, and should not be trusted.  Only data
 * that has been extracted from a context certified (via 
 * <sec_login_valid_and_cert_ident>) should be trusted.
 *
 * When a network identity is set, only state information for network
 * operations has been established.  The local operating system's identity has
 * not been modified.  It is the responsibility of the caller to establish
 * any local operating identity state.       
 *
 * Neither setup_identity nor validate identity check for
 * account or identity expiration.  The user of this interface is
 * responsible for such checks.
 *
 * Usage:
 *  Applications that wish to perform a system login should use
 *  this package as follows:
 *
 *      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 ...
 *          }
 *      }
 *
 *
 */
 
[ local ]

interface sec_login {
                       
    import "dce/secsts.idl";
    import "dce/lbase.idl";
    import "dce/id_epac.idl";
    import "dce/passwd.idl";
    import "dce/rgynbase.idl";
    import "dce/rpcbase.idl";
    import "dce/sec_attr_base.idl";

    /*
     * s e c _ l o g i n _ f l a g s _ t 
     */
    typedef unsigned32  sec_login_flags_t;

        const unsigned32    sec_login_no_flags = 0;

        /* restrict network credentials to the current process, otherwise
         * share credentials with descendents of current process.
         *
         * DCE 1.0 Notes: 
         *       It is illegal to call sec_login_set_context with
         *       a "private" login context.  This means that private
         *       contexts are only useful as explicit authentication
         *       handles in user space calls to rpc_binding_set_auth_info
         *       (Kernel RPC relies on the default context for authentication).
         */
        const unsigned32    sec_login_credentials_private   = 0x1;

	/*
	 * use externally obtained TGT's (simple proxy mechanism).
	 */ 
 	const unsigned32    sec_login_external_tgt 	= 0x2;

	/*
	 * login context being created by proxy.
 	 */
 	const unsigned32    sec_login_proxy_cred 	= 0x4;

        /*
         * login context being created/validated by machine principal.
         */
        const unsigned32    sec_login_machine_princ     = 0x8;

    /* s e c _ l o g i n _ a u t h _ s r c _ t
     * 
     *  Identifies source of user authentication.  
     */
     typedef enum {
        /*
         * authentication accomplished via network authority
         */
        sec_login_auth_src_network,
        /*
         * authentication accomplished via local data. Authentication occurs
         * locally if a principal's account is tailored for the local machine,
         * or the network authority is unavailable.  Login contexts that are
         */
        sec_login_auth_src_local,
        /*
         * authentication accomplished locally, with all data including
         * (unix-encrypted) password obtained from an override entry.
         * In this case, the credentials may not be used to establish
         * network credentials (because they have none)
         */
        sec_login_auth_src_overridden
    } sec_login_auth_src_t;
 
    /* s e c _ l o g i n _ h a n d l e _ t
     *
     * A handle on opaque login context data
     */
    typedef void *sec_login_handle_t;            

    const void *sec_login_default_handle = NULL;

    /* s e c _ l o g i n _ p a s s w d _ t
     *     
     *  The sec_login interface returns a password structure that depends
     *  on the underlying system.  In most cases, the structure will
     *  look like that supported by Berkeley 4.4 and OSF:   
     *
     *  struct passwd {
     *      char    *pw_name;           * user name *
     *      char    *pw_passwd;         * encrypted password *
     *      int     pw_uid;             * user uid *
     *      int     pw_gid;             * user gid *
     *      time_t  pw_change;          * password change time *
     *      char    *pw_class;          * user access class *
     *      char    *pw_gecos;          * Honeywell login info *
     *      char    *pw_dir;            * home directory *
     *      char    *pw_shell;          * default shell *
     *      time_t  pw_expire;          * account expiration *
     *  };
     *
     *  where time_t is a long.  Thus, sec_login_passwd_t will generally
     *  point to the above structure.
     */
    typedef void *sec_login_passwd_t;  
                                      
    /* Used in passwd fields pw_uid, pw_gid when user is from remote cell. */
    const signed32  sec_login_remote_uid    = -3;
    const signed32  sec_login_remote_gid    = -3;


    /* s e c _ l o g i n _ s e t u p _ i d e n t i t y
     *
     * Setup the user's network identity.
     *
     * The setup_identity operation and the 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 to protect the confidentiality of the 
     * user's password.  If setup_identity were to perform many remote
     * operations to acquire the necessary network credentials, the operation
     * could take an arbitrary amount of time.  If a password were submitted to
     * this operation, an attacker could force long network delays and then
     * attempt to extract the user's password from the process address space.
     * This form of attack is only feasible on some machines - but
     * nevertheless, we have opted to separate the identity acquisition
     * operation into two phases and prevent this form of attack.
     *
     * NOTE: Neither setup_identity nor validate_identity check for
     * account or identity expiration.  The user of this interface is
     * responsible for such checks.
     *
     * Sealed Network credentials (or certificates) are retrieved via 
     * sec_login_setup_identity.  In a Kerberos environment this operation
     * will acquire an appropriate ticket granting ticket.
     *
     * ERRORS:
     *    sec_rgy_object_not_found     - principal does not exist
     *    sec_rgy_registry_unavailable - network registry not available
     *    sec_login_s_null_password    - principal has no password
     *    sec_login_s_no_memory        - memory allocation failure
     */
    boolean32 sec_login_setup_identity (
        [in, string]    unsigned_char_p_t   principal,
        [in]            sec_login_flags_t   flags,
        [out, ref]      sec_login_handle_t  *login_context,
        [out, ref]      error_status_t      *st
    );


     /* s e c _ l o g i n _ r e f r e s h _ i d e n t i t y
     *
     * Refresh a previously established identity.  This operation
     * operates on an existing valid context, and cannot be used to 
     * change credentials associated with that identity.  If any administrative 
     * changes to the principal's identity have occurred since the last 
     * setup/refresh  (e.g. the principal's membership in one or more groups 
     * has been revoked), the refreshed identity reflects these changes. The
     * refreshed identity must be re-validated  (using sec_login_vaidate_identity,
     * os sec_login_valid_and_cert_ident) before it can be (re-)used.  It is an
     * error to refresh a locally authenticated context.
     *
     * ERRORS:
     *    sec_rgy_object_not_found     - principal no longer exists
     *    sec_rgy_registry_unavailable - network registry not available
     *    sec_login_s_null_password    - principal has no password
     *    sec_login_s_auth_local       - operation not valid on local context
     *    sec_login_s_context_invalid  - only a previously valid context can be refreshed
     *    sec_login_s_default_use      - can't refresh default context
     */
   boolean32 sec_login_refresh_identity (
        [in]            sec_login_handle_t  login_context,
        [out, ref]      error_status_t      *st
    );


    /* CONTEXT VALIDATION
     * 
     * Basically, a context is deemed valid if  
     *
     *    A) the principal's password is correct
     *    B) the principal's account is valid for login (as determined
     *       by policy info in the network registry)
     *
     * Checking a principal's password may involve decrypting a 
     * message obtained via a remote call to the security service.
     * In such cases, the decryption may fail because the password
     * is not correct, or because the message was modified (maliciously,
     * or otherwise) in transit.  It is not possible to distinguish
     * between these two failure conditions, so a sec_rgy_passwd_invalid
     * status does not necessarily mean the password is incorrect.
     * Fortunately, this situation does not arise much in practice.         
     *
     * Validation routines may be used to validate a newly established
     * context (created by sec_login_setup_identity), or to re-validate
     * a refreshed context.  In both cases, the same error conditions
     * may arise.  However, a failure to re-validate a refreshed context
     * does not render the context useless--the context retains its whatever
     * useful life is left in its unrefreshed state.  
     */

    /* s e c _ l o g i n _ v a l i d a t e _ i d e n t i t y
     *
     * Validate the login context established via sec_login_setup_identity. 
     * The caller must know the user's password for this operation to succeed.
     * This operation MUST be invoked before the network credentials will be
     * used.  This operation is intended for use by non-privileged programs
     * performing network logins.  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.
     *
     * This operation destroys the contents of the passwd input parameter.
     *
     * DCE 1.0 Notes
     *
     * This operation does not consult local passwd data if the network is
     * unavailable.  
     *
     * ERRORS:
     *    sec_rgy_registry_unavailable 
     *    sec_rgy_object_not_found
     *    sec_rgy_passwd_invalid           
     *    sec_login_s_acct_invalid         - account not valid for login
     *    sec_login_s_null_password        - can't log with a zero-length password
     *    sec_login_s_unsupp_passwd_type   - invalid  password type
     *    sec_login_s_already_valid        - context already valid  
     *    sec_login_s_refresh_ident_bad    - identity being refreshed is no longer valid
     *    sec_login_s_default_use          - can't validate default context
     */
     boolean32 sec_login_validate_identity (
        [in]            sec_login_handle_t   login_context,
        [in, out, ref]  sec_passwd_rec_t     *passwd,
        [out, ref]      boolean32            *reset_passwd,
        [out, ref]      sec_login_auth_src_t *auth_src,
        [out, ref]      error_status_t       *st
    );


    /* CONTEXT CERTIFICATION
     *
     * A process performing a login may be "spoofed" by an imposter
     * security server.  With respect to access to network services, this 
     * results in denial of service i.e., the credentials obtained from
     * the imposter will not be valid when presented to legitimate servers
     * whose keys are not known to the imposter.  This is inconvenient,
     * but does not consitute a security threat.
     * 
     * System login programs will generally want to use the local
     * os credentials obtained from a login context via the sec_login_get_pwent
     * and sec_login_get_groups calls to set the process' local identity.
     * In this case, an imposter security service is a real threat to security.
     * An attacker could bring up an imposter with a known root password, and
     * log in as root on any host machine that can be made to contact the
     * imposter.  Context certification prevents this form of attack on
     * local security.
     * 
     * Context certification is based on knowledge of the host machine's
     * key (access to the host machines's key is protected by local security). 
     * In particular, a certified context is one that has been successfully
     * used to acquire and decrypt a Privilege Ticket to the host machine 
     * on which the login is occurring, demonstrating thereby that there
     * is a valid trust path from user's native cell to the host machine's 
     * native cell.  An imposter security server can not accomplish this unless
     * it has already cracked local security.  In that case, all bets are off anyway.
     *
     * System login programs SHOULD NEVER set local os credentials obtained
     * from an uncertified context.  All sec_login routines that return data
     * from a login context return a warning status <sec_login_s_not_certified>
     * if the context has not been certified.
     *
     * NOTE: A locally authenticated context is certified by virtue of the
     * fact that local authentication information is protected by local
     * security.
     *
     */


    /* s e c _ l o g i n _ v a l i d _ a n d _ c e r t _ i d e n t
     *
     * Validate and certify a login context established via sec_login_setup_identity. 
     * The caller must know the user's password for this operation to succeed.
     * This opertion is intended for use by system login programs that need to
     * extract trustworthy OS credentials for use in setting a process' local
     * identity.  This operation destroys the contents of the passwd input parameter.
     *
     * If the network security service is unavailable, or 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  locally authenticated context may be used to 
     * set local OS identity, but cannot be used to establish network credentials
     *
     * sec_login_valid_and_cert_ident is a privileged operation
     *       
     * DCE 1.0 Notes:
     *
     * Overrides are not implemented
     *
     * ERRORS:
     *    sec_rgy_registry_unavailable 
     *    sec_rgy_object_not_found
     *    sec_rgy_passwd_invalid           
     *    sec_login_s_acct_invalid         - account not valid for login
     *    sec_login_s_null_password        - can't log with a zero-length password
     *    sec_login_s_unsupp_passwd_type   - invalid  password type
     *    sec_login_s_already_valid        - context already valid
     *    sec_login_s_refresh_ident_bad    - identity being refreshed is not valid
     *    sec_login_s_privileged           - calling process is not privileged
     *    sec_login_s_default_use          - can't validate default context
     */
     boolean32 sec_login_valid_and_cert_ident (
        [in]            sec_login_handle_t   login_context,
        [in, out, ref]  sec_passwd_rec_t     *passwd,
        [out, ref]      boolean32            *reset_passwd,
        [out, ref]      sec_login_auth_src_t *auth_src,
        [out, ref]      error_status_t       *st
    );
            

    /* s e c _ l o g i n _ v a l i d _ f r o m _ k e y t a b l e
     *
     * This function takes a setup/refreshed login context, and attempts
     * to validate that context by looking up keys in the specified key
     * table.  If <try_kvno> specifies a particular key version number, that
     * version number is tried first, otherwise the "current" key version
     * is tried first.  In either case, if the first try fails, the function
     * loops through the key table, trying any and all all existing keys (for the 
     * principal represented by the login context).  The version number of the
     * the key that actually worked, if any, is returned in <used_kvno>.
     * See key_mgmt.idl for information on the <authn_service> and <arg>
     * parameters.
     *
     * DCE 1.0 Notes:
     *    This function is not documented in DCE 10
     *
     * ERRORS:
     *   Any errors returned by sec_login_validate_identity, sec_key_mgmt_get_key,
     *   sec_key_mgmt_initialize_cursor, and sec_key_mgmt_get_next_key may be 
     *   returned by this function.
     */
    void sec_login_valid_from_keytable (
        [in]        sec_login_handle_t          login_context,
        [in]        unsigned32                  authn_service,
        [in]        void                        *arg,
        [in]        unsigned32                  try_kvno,
        [out]       unsigned32                  *used_kvno,
        [out]       boolean32                   *reset_passwd,
        [out]       sec_login_auth_src_t        *auth_src,
        [out]       error_status_t              *st
      );                                              


    /* s e c _ l o g i n _ c e r t i f y _ i d e n t i t y
     * 
     * This routine certifies a context by making an authorized call to
     * the local host's sec_clientd process.  This is not a privileged
     * operation, but relies on the availability of sec_clientd.
     *
     * ERRORS:
     *    sec_login_s_not_certified  
     *    sec_login_s_context_invalid
     *    sec_login_s_default_use     - can't certify the default context
     */
     boolean32 sec_login_certify_identity (
        [in]        sec_login_handle_t   login_context,
        [out, ref]  error_status_t       *st
    );


    /* s e c _ l o g i n _ s e t _ c o n t e x t
     *
     * Set the default network credentials for the calling process to those
     * specified by the login context.  This context must have been previously 
     * validated (contexts acquired through sec_login_get_current_context or
     * sec_login_newgroups don't need to be validated since those functions
     * return previously validated contexts).
     *
     * ERRORS:
     *    sec_login_s_auth_local
     *    sec_login_s_context_invalid
     *    sec_login_s_default_use 
     */
     void sec_login_set_context (
        [in]            sec_login_handle_t  login_context,
        [out, ref]      error_status_t      *st
    );


    /* s e c _ l o g i n _ g e t _ c u r r e n t _ c o n t e x t
     *
     * Retrieve a handle to the login context for the currently established
     * network identity.  
     * ERRORS:
     *    sec_login_s_no_current_context 
     */
    void sec_login_get_current_context (
        [out, ref]      sec_login_handle_t  *login_context,
        [out, ref]      error_status_t      *st
    );


    /* s e c _ l o g i n _ p u r g e _ c o n t e x t
     *
     * free any storage allocated for a login context and destroy the
     * associated network credentials, if any.  Applications should be
     * cautious when purging the current context as this destroys network
     * credentials for all processes that share the credentials.  
     *
     * ERRORS:
     *    sec_login_s_default_use 
     *
     * The handle parameter is in,out so that it can be reset to NULL.  
     */
     void sec_login_purge_context (
        [in, out, ref]  sec_login_handle_t  *login_context,
        [out, ref]      error_status_t      *st
    );

    /* s e c _ l o g i n _ p u r g e _ c o n t e x t _ e x p
     *
     * destroy expired network credentials.
     */
    void sec_login_purge_context_exp (
        [in]        unsigned32          buf_len,
        [in, size_is(buf_len)]
                    byte                buf[],
        [in]        signed32            purge_time,
        [out]       error_status_t      *st
    );


    /* s e c _ l o g i n _ r e l e a s e _ c o n t e x t
     *
     * free any storage allocated for a login context.  Unlike
     * sec_login_purge_context this function does not destroy the associated
     * network credentials.  If the network credentials are in use by other
     * or are referred to by other sec_login_handles, they will continue to
     * exist.
     *
     * ERRORS:
     *    sec_login_s_default_use 
     */
     void sec_login_release_context (
        [in, out, ref]  sec_login_handle_t  *login_context,
        [out, ref]      error_status_t      *st
    );

/*
 * Bootstrap Routines 
 * 
 * The bootstrap routines are provided to enable the initial process,
 * and the sec_clientd helper process, acting in concert, to establish 
 * default credentials that can be inherited by children of the initial
 * process (especially, daemon processes running on the local host).  The
 * bootstrap routines are similar to the normal sec_login_setup/validate
 * routines, except that they assume the host machine principal and
 * therefore, do not require a principal name or password (both are
 * available from local configuration info.  
 *
 * It is not necessary to call sec_login_set_context on the host machine 
 * context to setup host machine context inheritance.
 *
 * These operation are privileged.
 *
 * There is no need for special refresh function.  sec_clientd can
 * get the current context, refresh, and validate it via the  normal
 * sec_login interface.
 *
 *
 * DCE 1.0 Notes
 *
 * sec_login_init_first is a no-op.  Sec_clientd calls sec_login_setup_first
 * and sec_login_validate_first.  All privileged process that do not have
 * their own default identity (i.e., neither they, nor any of their ancestors have
 * called sec_login_set_context) inherit the host machine credentials.
 *
 * 
 */

    /* s e c _ l o g i n _ i n i t _ f i r s t
     *
     * Initialize the default context inheritance mechanism.  If the default 
     * inheritance mechanism is already initialized, the operation fails.
     * Typically, this routine will be called by the initial process at
     * machine boot time to initialize the default context inheritance
     * mechanism for the host machine process hierarchy.
     *
     * ERRORS:
     *    sec_login_s_default_use  - default context already initialized 
     *    sec_login_s_privileged   - called in unprivileged process 
     */
    void sec_login_init_first (
        [out, ref]      error_status_t      *st
    );


    /* s e c _ l o g i n _ s e t u p _ f i r s t
     *
     * Setup the default context network identity.  If the default context
     * already contains valid credentials, the routine fails.  Typically, 
     * this routine will be called from the sec_clientd helper process to 
     * breathe life into the default credentials for the host machine process 
     * hierarchy
     *
     * This routines uses the host name available via the local dce_config
     * interface as the principal name for the setup, so it does need a
     * principal name as input. 
     *
     * ERRORS:
     *    sec_login_s_default_use      - default context is already in use
     *    sec_login_s_no_current_context 
     *    sec_login_s_privileged       - called in unprivileged process 
     *    sec_login_s_config           - dce config info not available
     *    sec_rgy_object_not_found     - principal does not exist
     *    sec_rgy_registry_unavailable - network registry not available
     *    sec_login_s_default_use      - default identity already exists
     *    sec_login_s_no_memory        - memory allocation failure
     */
    boolean32 sec_login_setup_first (
        [out, ref]      sec_login_handle_t  *init_context,
        [out, ref]      error_status_t      *st
    );



    /* s e c _ l o g i n _ v a l i d a t e _ f i r s t
     *
     * Validate the default login context established via sec_login_setup_first.
     * Typically, this operation will be called from the sec_clientd helper process 
     * to validate the default credentials for the host machine process hierarchy.
     * This operation uses the password for the local host, and therefore does
     * not require a password parameter.
     *
     * ERRORS:
     *    sec_login_s_privileged       - called in unprivileged process 
     *    sec_rgy_registry_unavailable 
     *    sec_login_s_auth_failure
     */
     boolean32 sec_login_validate_first (
        [in]        sec_login_handle_t   init_context,
        [out, ref]  boolean32            *reset_passwd,
        [out, ref]  sec_login_auth_src_t *auth_src,
        [out, ref]  error_status_t       *st
    );


/* 
 * The following routines extract data from a login context.  These routines do not
 * require a previously validated/certified context, but any data retrieved from an
 * uncertified  context may come from an imposter security server and should not be
 * trusted.  These routines return a <sec_login_s_not_certified> warning status if
 * the input login context is has not been certified.
 */

    /* s e c _ l o g i n _ g e t _ p w e n t
     *
     * extract a passwd file entry for the current network login state.
     * This is useful for establishing the local OS context.  If no 
     * password data are available, the pwent parameter is set to NULL.
     * If the input context is not certified, the routine attempts to
     * find an entry in the local /etc/passwd file before consulting 
     * the network (local data are trustworthy, while network data
     * obtained with an uncertified context are not).  This allows 
     * system login programs to determine whether or not the user 
     * has local root privileges before prompting for a password.
     * 
     * NOTE:
     *  the passwd structure will point to data stored in the login_context and
     *  should be treated as read-only data.  Writing to these data objects may
     *  cause unexpected failures.
     *
     * WARNINGS:
     *    sec_login_s_not_certified
     *
     * ERRORS:
     *    sec_login_s_default_use 
     */
     void sec_login_get_pwent (
        [in]            sec_login_handle_t                login_context,
        [out]           sec_login_passwd_t                *pwent,
        [out, ref]      error_status_t                    *st
    );

    /* s e c _ l o g i n _ g e t _ g r o u p s
     *
     * extract the concurrent groupset for which the user has established
     * network privileges.  
     *
     * DCE 1.0 Notes:
     *
     * The groupset returned from a locally authenticated context 
     * (auth_src == sec_login_auth_src_local) is always NULL 
     * (num_groups = 0).  System login programs should use the unix
     * initgroups() call to establish local OS concurrent groupsets
     * when a context is locally authenticated.
     *
     * WARNINGS:
     *    sec_login_s_not_certified 
     *
     * ERRORS:
     *    sec_login_s_default_use 
     */
     void sec_login_get_groups (
        [in]            sec_login_handle_t  login_context,
        [out, ref]      unsigned32          *num_groups,
        [out, ref]      signed32            **group_set,
        [out, ref]      error_status_t      *st
    );

    /* s e c _ l o g i n _ g e t _ e x p i r a t i o n
     *
     * Extract the expiration date for the authentication identity from
     * the login context.  The expiration time is filled in if it is available,
     * otherwise set to 0.  This allows the application to provide feedback
     * as to when the user's identity will need to be refreshed.
     *
     * WARNINGS:
     *    sec_login_s_not_certified  
     *
     * ERRORS:
     *    sec_login_s_auth_local 
     *    sec_login_s_no_current_context (the default context was specified, but
     *                                    none exists)
     */
     void sec_login_get_expiration (
        [in]            sec_login_handle_t  login_context,
        [out, ref]      signed32            *identity_expiration,
        [out, ref]      error_status_t      *st
    );

    
    /* s e c _ l o g i n _ n e t _ i n f o _ t
     *
     * The structure of network information obtainable from a login
     * context.  The pac contains uuids, and may, in some, cases, contain
     * string names.  uuids may be converted to string names by calling
     * sec_id_gen_name.  A value of 0 for an expiration date means
     * there is no expiration date i.e. that the passwd/account is
     * good indefinitely
     */

/* CMVC 5209, OT 7619, sec_login_net_info_t tag added */
    typedef struct sec_login_net_info_t {
        sec_id_pac_t  pac;
        unsigned32    acct_expiration_date;
        unsigned32    passwd_expiration_date;
        unsigned32    identity_expiration_date;
    }  sec_login_net_info_t;


    /* s e c _ l o g i n _ i n q u i r e _ n e t _ i  n f o  
     *
     * Extract a principal's network info.  This routine allocates
     * some substructure which must be cleaned up via a call to
     * sec_login_free_net_info.  The input login context must 
     * be a previously validated context.
     *
     * ERRORS:
     *    sec_login_s_auth_local
     *    sec_login_s_context_invalid
     *    sec_login_s_no_current_context (the default context was specified, but
     *                                    none exists)
     */
    void sec_login_inquire_net_info (
        [in]       sec_login_handle_t    login_context,
        [out]      sec_login_net_info_t  *net_info,
        [out]      error_status_t        *st
    );

    /* s e c _ l o g i n _ f r e e _ n e t _ i  n f o  
     *
     * Free network info substructure allocated by successful 
     * sec_login_inquire_net_info.
     */
    
    void sec_login_free_net_info (
        [in, out]      sec_login_net_info_t  *net_info
    );

/*
**  Miscellaneous Routines 
*/

    /* s e c _ l o g i n _ c h e c k _ p a s s w d
     * 
     * OBSOLETE (and no longer implemented).  Use sec_login_setup_identity 
     * and sec_login_validate_identity instead.
     *
     * Verify the user's knowledge of their password.  This function will
     * return true if the password matches the one belonging to the named
     * user, false otherwise.  This function should be used in place of the
     * conventional comparison against the encrypted password in the passwd
     * file structure.  This function is only useful for checking the user's
     * knowledge of the password - it cannot be used to set network credentials
     * (as it does not establish a login context).
     *
     * This function will apply any appropriate local overrides and will
     * attempt to access the local user registry if the network registry is
     * unavailable.
     */
    boolean32 sec_login_check_passwd (
        [in, string]        unsigned_char_p_t    principal,
        [in, ref]           sec_passwd_rec_t     *passwd,
        [out, ref]          sec_login_auth_src_t *auth_src,
        [out, ref]          error_status_t       *st
    );


    /* s e c _ l o g i n _ n e w g r o u p s
     *
     * Setup a new login context with the specified group list.  This operation
     * does not need to be validated as the user identity does not change - and 
     * knowledge of the password is not needed, but the login_context should be 
     * purged when no longer needed.  
     *
     * ERRORS:
     *    sec_login_s_groupset_invalid
     *
     * NOTE: 
     *  Currently you can only have groups from the local cell.
     *  Perhaps, someday this restriction will be
     *  relaxed.
     */
    boolean32 sec_login_newgroups (
        [in]            sec_login_handle_t  login_context,
        [in]            sec_login_flags_t   flags,
        [in]            unsigned32          num_local_groups,
        [in, length_is(num_local_groups)]
                        sec_id_t            local_groups[],
        [out]           sec_login_handle_t  *restricted_context,
        [out, ref]      error_status_t      *st
    );

    /* s e c _ l o g i n _ e x p o r t _ c o n t e x t
     *
     * Obtain an exportable version of the the login context information.
     * This information may be passed to another process running on the 
     * same machine.
     *
     * Errors:
     *  sec_login_s_no_memory       - buffer too short, len_needed parm
     *                                contains needed length
     */

    void sec_login_export_context (
        [in]        sec_login_handle_t  login_context,
        [in]        unsigned32          buf_len,
        [out, size_is(*len_used)]
                    byte                buf[],
        [out]       unsigned32          *len_used,
        [out]       unsigned32          *len_needed,
        [out]       error_status_t      *st
    );

    /* s e c _ l o g i n _ i m p o r t _ c o n t e x t
     *
     * Import a context obtained via a call to sec_login_export_context
     * performed on the same machine.  This function is generally reserved to
     * the privileged user.
     */
    void sec_login_import_context (
        [in]        unsigned32          buf_len,
        [in, size_is(buf_len)]
                    byte                buf[],
        [out]       sec_login_handle_t  *login_context,
        [out]       error_status_t      *st
    );

   /* s e c _ l o g i n _ i n q  _ p a g
     *
     * Obtain pag from login context. 
     */
    unsigned32 sec_login_inq_pag( 
        [in]        sec_login_handle_t  *login_context,
        [out]       error_status_t      *st
    );

    /* sec_login_become_initiator
     * 
     * This functions constructs a new login context that enables the selected
     * delegation type.
     * The parameter my_login_context specifies the identity of the caller.
     * Semantics of arguments
     *   my_login_context -          specifies the identity of the caller.
     *   delegation_type_permitted - determines the delegation type to be per-
     *                               mitted using the generated login context.
     *   delegate_restrictions -     the list of delegates that are permitted.
     *   target_restrictions -       the list of targets to whom this identity
     *                               may be presented.
     *   optional_restrictions -     the list of application defined optional
     *                               restrictions that apply to this delegation
     *                               context.
     *   required_restrictions -     the list of application defined required
     *                               restrictions that apply to this delegation
     *                               context.
     *   compatibility_mode -        specifies the compatibility mode desired
     *                               when operating on DCE 1.0 servers.
     *   error_status -              error status.
     */

    sec_login_handle_t sec_login_become_initiator (
        [in]sec_login_handle_t          my_login_context,
        [in]sec_id_delegation_type_t    delegation_type_permitted,
        [in]sec_id_restriction_set_t    *delegate_restrictions,
        [in]sec_id_restriction_set_t    *target_restrictions,
        [in]sec_id_opt_req_t            *optional_restrictions,
        [in]sec_id_opt_req_t            *required_restrictions,
        [in]sec_id_compatibility_mode_t	compatibility_mode,
        [out]error_status_t             *error_status
    );


    /* sec_login_become_delegate
     * 
     * This function is used by intermediate servers to become a delegate for
     * their caller.
     * Semantics of arguments
     *   callers_identity - specifies the identity of the server's RPC client
     *                      as obtained from the RPC runtime.
     *   my_login_context - specifies the identity of the intermediate server.
     *                      This context must be a simple context (i.e., this
     *                      cannot be a context that represents a compound
     *                      identity created by the become_delegate function).
     *   delegation_type_permitted - determines the delegation type to be
     *                      permitted using the generated login context.
     *   delegate_restrictions - the list of delegates that are permitted 
     *   target_restrictions -	 the list of targets to whom this identity may
     *                      be presented.
     *   optional_restrictions - the list of application defined optional
     *                      restrictions that apply to this delegation context.
     *   required_restrictions - the list of application defined required
     *                      restrictions that apply to this delegation context.
     *   compatibility_mode - specifies the compatibility mode desired when 
     *                      operating on DCE 1.0 servers.
     *   error_status -	    error status.
     */

    sec_login_handle_t sec_login_become_delegate (
        [in]rpc_authz_cred_handle_t     callers_identity,
        [in]sec_login_handle_t          my_login_context,
        [in]sec_id_delegation_type_t    delegation_type_permitted,
        [in]sec_id_restriction_set_t    *delegate_restrictions,
        [in]sec_id_restriction_set_t    *target_restrictions,
        [in]sec_id_opt_req_t            *optional_restrictions,
        [in]sec_id_opt_req_t            *required_restrictions,
        [in]sec_id_compatibility_mode_t compatibility_mode,
        [out]error_status_t             *error_status
    );


    /* sec_login_become_impersonator
     * 
     * This function is used by intermediate servers to become an impersonator
     * for their caller.
     * Semantics of arguments
     *   callers_identity - specifies the identity of the server's RPC client
     *                      as obtained from the RPC runtime.
     *   delegation_type_permitted - determines the delegation type to be
     *                      permitted using the generated login context.
     *   delegate_restrictions - the list of delegates that are permitted
     *   target_restrictions - the list of targets to whom this identity may be
     *                      presented.
     *   optional_restrictions - the list of application defined optional
     *                      restrictions that apply to this delegation context.
     *   required_restrictions - the list of application defined required
     *                      restrictions that apply to this delegation context.
     *   error_status -     error status.
     */

    sec_login_handle_t sec_login_become_impersonator (
	[in]rpc_authz_cred_handle_t     callers_identity,
        [in]sec_login_handle_t          my_login_context,
	[in]sec_id_delegation_type_t    delegation_type_permitted,
	[in]sec_id_restriction_set_t    *delegate_restrictions,
	[in]sec_id_restriction_set_t    *target_restrictions,
	[in]sec_id_opt_req_t            *optional_restrictions,
	[in]sec_id_opt_req_t            *required_restrictions,
	[out]error_status_t             *error_status
    );


    /* sec_login_set_extended_attrs
     * 
     * This function constructs a new login context that contains the requested
     * extended attributes.
     * Attributes cannot be added to a delegation chain in this manner, thus if
     * a login context referring to a delegation chain is passed to this call,
     * an invalid context error will be returned.
     * Semantics of arguments
     *   my_login_context - specifies the identity of the caller.
     *   num_attributes - the number of attributes passed in this call.
     *   attributes - the list of attributes to be set in the new login context
     *       If any of the requested attributes are not authorized for the
     *       caller, none are set and a vector of indices listing the invalid
     *       attributes is returned.
     *   error_status - error status.
     */

    sec_login_handle_t sec_login_set_extended_attrs (
	[in]sec_login_handle_t  my_login_context,
	[in]unsigned32          num_attributes,
	[in]sec_attr_t          attributes[],
	[out]error_status_t     *error_status
    );


    /* sec_login_disable_delegation
     *
     * This function returns a login context without delegation or
     * impersonation enabled, from one that has one of the two delegation_types
     * enabled.
     * Semantics of arguments
     *  login_context - specifies the identity of the caller
     *  error_status - error_status.
     */
    sec_login_handle_t sec_login_disable_delegation(
        [in]sec_login_handle_t          login_context,
        [out]error_status_t             *error_status
    );

    /* sec_login_cred_get_initiator
     *
     * This function is used to extract the initiator's privilege attributes
     * from a specified login context.
     * Semantics of arguments
     * login_context - 		specifies the login context to extract the
     *                          initiator from.
     * error_status -		error status.
     */
    sec_cred_pa_handle_t sec_login_cred_get_initiator (
        [in]sec_login_handle_t          login_context,
        [out]error_status_t             *error_status
    );

    /* sec_login_cred_get_delegate
     *
     * This function is used to iterate through and extract the privilege
     * attributes of the delegates listed in a specified login context.
     * Semantics of arguments
     * login_context -          specifies the login context to extract the
     *                          delegates from.
     * cursor -                 an input/output cursor used to iterate through
     *                          the set of delegates in the login context.
     * error_status -           error status.
     */
    sec_cred_pa_handle_t sec_login_cred_get_delegate (
        [in]sec_login_handle_t          login_context,
        [in,out]sec_cred_cursor_t       *cursor,
        [out]error_status_t             *error_status
    );

    /* sec_login_cred_init_cursor
     *
     * This function is used to initialize a sec_cred_cursor_t for use in calls
     * to the iterative routine sec_login_cred_get_delegate.
     * Semantics of arguments
     * cursor -                 an input/output cursor used to iterate through
     *                          the list of delegates.
     * error_status -           error status.
     */
    void sec_login_cred_init_cursor (
        [in,out]sec_cred_cursor_t       *cursor,
        [out]error_status_t             *error_status
    );

    /* sec_login_tkt_flags_t
     *
     * These are options used to request various attributes
     * associated with tickets.
     */
    typedef unsigned32 sec_login_tkt_flags_t;
        /*
         * request renewable ticket
         */
        const unsigned32 sec_login_tkt_renewable        = 0x1;

        /*
         * request postdated ticket
         */
        const unsigned32 sec_login_tkt_postdated        = 0x2;

        /*
         * allow postdated tickets
         */
        const unsigned32 sec_login_tkt_allow_postdate   = 0x4;

        /*
         * allow proxiable tickets
         */
        const unsigned32 sec_login_tkt_proxiable        = 0x8;

        /*
         * request forwardable ticket
         */
        const unsigned32 sec_login_tkt_forwardable      = 0x10;

        /*
         * accept renewable ticket if real ticket cannot be granted
         */
        const unsigned32 sec_login_tkt_renewable_ok     = 0x20;

        /*
         * request non-default ticket lifetime
         */
        const unsigned32 sec_login_tkt_lifetime         = 0x40;

    /* sec_login_tkt_info_t
     *
     * The structure of optional AS ticket request flags 
     * and associated data.
     */
    typedef struct {
        sec_login_tkt_flags_t    options;
        sec_timeval_period_t     postdated_dormanttime;
        sec_timeval_period_t     renewable_lifetime;
        sec_timeval_period_t     lifetime;
    } sec_login_tkt_info_t;

    /* sec_login_tkt_request_options
     *
     * This function is used by a client to request specific AS ticket
     * options. This optional function should be called after
     * sec_login_setup_identity or sec_login_refresh_identity and
     * before sec_login_validate_identity or sec_login_valid_and_cert_ident.
     * 
     * Input should consist of a login context handle in the
     * setup or refreshed state, and a structure which specifies
     * the types of ticket options requested. If the user requests
     * a renewable/postdated ticket, or a non-default ticket lifetime,
     * additional data must be provided in the renewable_lifetime, 
     * postdated_dormanttime, and lifetime fields of the sec_login_tkt_info_t 
     * structure, respectively.
     *
     * The data is placed in the KRB_REQUEST_INFO portion of the
     * login context. These options will override the defaults
     * when the ticket is requested at validation time.
     */
     void sec_login_tkt_request_options (
         [in]    sec_login_handle_t    login_context,
         [in]    sec_login_tkt_info_t  *tkt_info,
         [out]   error_status_t        *status
     );
}
