/* @(#)16	1.4  src/security/idl/sec_pwd_mgmt.idl, security.src, os2dce21.dss, 960602a.1 5/17/95 09:51:25  */
/*
 *   COMPONENT_NAME: security.src
 *
 *   FUNCTIONS: none
 *
 *   ORIGINS: 72
 *
 */
/*
 * @OSF_COPYRIGHT@
 * COPYRIGHT NOTICE
 * Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc.
 * ALL RIGHTS RESERVED (DCE).  See the file named COPYRIGHT.DCE for
 * the full copyright text.
 */
/*
 * HISTORY
 * $Log: sec_pwd_mgmt.idl,v $
 * Revision 1.1.2.3  1994/07/15  15:00:23  mdf
 * 	Hewlett Packard Security Code Drop
 * 	[1994/07/14  17:17:37  mdf]
 *
 * Revision 1.1.2.2  1994/06/17  18:42:35  devsrc
 * 	cr10872 - fix copyright
 * 	[1994/06/17  18:10:40  devsrc]
 * 
 * Revision 1.1.2.1  1994/05/11  19:14:25  ahop
 * 	hp_sec_to_osf_2 drop
 * 	sec_password interface definitions.
 * 	[1994/04/29  21:10:01  ahop]
 * 
 * $EndLog$
 */
/*
**
** Copyright (c) Hewlett-Packard Company 1994
** Unpublished work. All Rights Reserved.
**
*/
/* Password Management facility.
 *
 * This interface provides a set of operations to manage password
 * generation, reuse, and strength checking.
 *
 * These operations are local (client side only).
 *
 */

[ local ]

interface sec_pwd_mgmt {

    import "dce/passwd.idl";
    import "dce/rgybase.idl";
    import "dce/sec_login.idl";

    /* s e c _ p w d _ m g m t _ h a n d l e _ t
     *
     * A handle to opaque sec_pwd_mgmt_info_t.
     */
    typedef void *sec_pwd_mgmt_handle_t;

    /* s e c _ p w d _ m g m t _ s e t u p
     *
     * This operation accepts as input or looks up the necessary
     * information regarding a user's password management policy. It
     * returns a handle to this data.
     *
     * Input:
     *    context: a handle to a registry server used to obtain
     *           ERA information. 
     *    login_name: the name of the account whose password is being
     *           created or changed.
     *    your_lc: the login context of the principal who is authorized
     *           to change or create the user's password. If NULL is
     *           specified, the default security login context for the
     *           current address space is used.
     *    pwd_mgmt_bind_h: the binding handle to the password management
     *           server. If this value is NULL, it will retrieve a binding
     *           handle form the binding information contained in the
     *           pwd_mgmt_binding ERA.
     *
     * Output:
     *    pwd_mgmt_h: a handle to the data required to generate a password.
     *           This is an opaque pointer to a a sec_pwd_mgmt_info_t
     *           structure.
     *    stp: error status.
     *
     * Errors:
     *    sec_s_no_memory: unable to allocate memory.
     *    sec_rgy_server_unavailable: The DCE Registry Server is unavailable.
     *    error_status_ok: The call was successful.
     */
    void sec_pwd_mgmt_setup (
        [out]       sec_pwd_mgmt_handle_t    *pwd_mgmt_h,      /* [out] */
        [in]        sec_rgy_handle_t         context,          /* [in]  */
        [in]        sec_rgy_login_name_t     login_name,       /* [in]  */
        [in]        sec_login_handle_t       your_lc,          /* [in]  */
        [in]        rpc_binding_handle_t     pwd_mgmt_bind_h,  /* [in]  */
        [out]       error_status_t           *stp              /* [out] */
    );

    /* s e c _ p w d _ m g m t _ g e t _ v a l _ t y p e
     *
     * Retrieves the value of the pwd_val_type ERA from the handle
     * specified by pwd_mgmt_h.
     *
     * Input:
     *    pwd_mgmt_h: a handle obtained from sec_pwd_mgmt_setup.
     *
     * Output:
     *    pwd_val_type: value of the pwd_val_type ERA. It can be one of
     *           4 values - NONE(0), USER_SELECT(1), USER_CAN_SELECT(2),
     *           GENERATION_REQUIRED(3).
     *    stp: error status.
     *
     * Errors:
     *    error_status_ok: The call was successful.
     *    No errors are defined at this time.
     */
    void sec_pwd_mgmt_get_val_type (
        [in]       sec_pwd_mgmt_handle_t    pwd_mgmt_h,       /* [in]  */
        [out]      signed32                 *pwd_val_type,    /* [out] */
        [out]      error_status_t           *stp              /* [out] */
    ); 

    /* s e c _ p w d _ m g m t _ g e n _ p w d
     *
     * Generates a password by calling the password management server.
     *
     * Input:
     *    pwd_mgmt_h: a handle obtained from sec_pwd_mgmt_setup.
     *    num_pwds: number of generated passwords requested.
     *
     * Output:
     *    num_returned: the number of passwords actually returned.
     *    gen_pwds: an array of the generated passwords.
     *    stp: error status.
     *
     * Errors:
     *    error_status_ok: The call was successful.
     *    sec_rgy_era_pwd_mgmt_auth_type: The pwd_mgmt_binding ERA
     *           must have authentication information
     *    rpc_binding_from_string_binding errors
     *    rpc_binding_set_auth_info errors
     *    sec_pwd_mgmt_svr_unavail: The Password Management server
     *           is unavailable
     *    sec_pwd_mgmt_svr_error: Password Management server generic
     *           error.
     *    rpc_ns_binding_import_begin errors
     *    rpc_ns_binding_import_next errors
     */
    void sec_pwd_mgmt_gen_pwd (
        [in]      sec_pwd_mgmt_handle_t    pwd_mgmt_h,      /* [in]  */ 
        [in]      unsigned32               num_pwds,        /* [in]  */
        [out]     unsigned32               *num_returned,   /* [out] */
        [out, size_is(num_pwds), length_is(*num_returned)]     
                  sec_passwd_rec_t         gen_pwds[],      /* [out] */
        [out]     error_status_t           *stp             /* [out] */ 
    );

    /* s e c _ p w d _ m g m t _ f r e e _ h a n d l e
     *
     * Frees the handle returned by sec_pwd_mgmt_setup.
     *
     * Input:
     *    pwd_mgmt_h: a handle obtained from sec_pwd_mgmt_setup.
     * Output:
     *    stp: error status.
     * Errors:
     *    error_status_ok: The call was successful.
     *    No other errors are defined.
     *
     */
    void sec_pwd_mgmt_free_handle (
        [in]      sec_pwd_mgmt_handle_t    *pwd_mgmt_h,      /* [in]  */
        [out]     error_status_t           *stp              /* [out] */
    );
}
