/* @(#)54       1.4  src/security/idl/daclif.idl, security.src, os2dce21.dss, 960602a.1  5/17/95  09:49:31 */
/*
 * COMPONENT_NAME:  security.client.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: daclif.idl,v $
 * Revision 1.1.6.1  1994/01/28  23:10:42  burati
 * 	Add sec_acl_bind_auth (dlg_bl1)
 * 	[1994/01/18  20:51:46  burati]
 *
 * Revision 1.1.4.3  1992/12/29  13:28:55  zeliff
 *      Embedding copyright notice
 *      [1992/12/28  20:48:08  zeliff]
 *
 * Revision 1.1.4.2  1992/11/16  18:29:55  burati
 * 	CR4812 Add authentication types so handle can keep track of auth info
 * 	[1992/11/14  00:41:06  burati]
 *
 * Revision 1.1.2.2  1992/05/08  14:48:24  burati
 * 	Clean up comments
 * 	[1992/05/07  15:15:04  burati]
 * 
 * 	Add sec_acl_get_mgr_types_semantics(...)
 * 	Add sec_acl_calc_mask(...)
 * 	[1992/04/29  03:04:55  burati]
 * 
 * Revision 1.1  1992/01/19  14:55:23  devrcs
 * 	Initial revision
 * 
 * $EndLog$
 */

/*  daclif.idl
**
** Copyright (c) Hewlett-Packard Company 1991, 1993
** Unpublished work. All Rights Reserved.
**
*/
/*
** SEC_ACL local access interface (API) 
*/

[
    local
]

interface sec_acl_if {

    import "dce/aclbase.idl";
    import "dce/sec_login.idl";

    /* Authentication information for the sec_acl_bind_auth call */
    typedef enum {
        sec_acl_bind_auth_none,
        sec_acl_bind_auth_dce
    } sec_acl_bind_auth_info_type_t;

    typedef union switch (sec_acl_bind_auth_info_type_t info_type) {
        case sec_acl_bind_auth_none:
            ;                       /* don't authenticate handle */
        case sec_acl_bind_auth_dce:
            struct {
                unsigned32          authn_lvl;
                unsigned32          authn_svc;
                unsigned32          authz_svc;
                sec_login_handle_t  identity;
            } dce_info;
    } sec_acl_bind_auth_info_t;


    /*  s e c _ a c l _ b i n d
     *
     *  Return an opaque sec_acl_handle to the object specified by entry_name.
     *  If the bind_to_entry predicate is true, and the entry_name refers to
     *  both an entry in the global namespace and an actual object (ie there's
     *  two possible ACLs associated with this name), then the client agent
     *  will bind to the entry in the namespace.  By default, bind_to_entry is
     *  passed in false and the client agent will bind to the object itself.
     *
     */

    void sec_acl_bind (
        [in]        unsigned char * 	    entry_name,
        [in]        boolean32               bind_to_entry,
        [out]       sec_acl_handle_t        *h,
        [out]       error_status_t          *status
    );


    /*  s e c _ a c l _ b i n d _ a u t h
     *
     *  Return an opaque sec_acl_handle to the object specified by entry_name.
     *  If the bind_to_entry predicate is true, and the entry_name refers to
     *  both an entry in the global namespace and an actual object (ie there's
     *  two possible ACLs associated with this name), then the client agent
     *  will bind to the entry in the namespace.  By default, bind_to_entry is
     *  passed in false and the client agent will bind to the object itself.
     *  The auth_info is specified as an argument as opposed to using default
     *  information as sec_acl_bind() does.
     */

    void sec_acl_bind_auth (
        [in]        unsigned char *             entry_name,
        [in]        boolean32                   bind_to_entry,
        [in]        sec_acl_bind_auth_info_t    *auth_info,
        [out]       sec_acl_handle_t            *h,
        [out]       error_status_t              *status
    );


    /*  s e c _ a c l _ b i n d _ t o _ a d d r
     *
     *  Debug interface bind, which returns a handle to an acl manager without
     *  needing to do any pathname resolution.
     *
     */

    void sec_acl_bind_to_addr (
        [in]        unsigned char *	        site_addr,
        [in]        sec_acl_component_name_t    component_name,
        [out]       sec_acl_handle_t            *h,
        [out]       error_status_t              *status
    );


    /*  s e c _ a c l _ l o o k u p
     *
     *  retrieve an acl associated with the object referred to in the handle
     *  parameter.
     *
     *  Comparable to POSIX acl_read()
     */

    void sec_acl_lookup (
        [in]        sec_acl_handle_t        h,
        [in, ref]   uuid_t                  *manager_type,   
        [in]        sec_acl_type_t          sec_acl_type,
        [out]       sec_acl_list_t          *sec_acl_list,
        [out, ref]  error_status_t          *st
    );

    /*  s e c _ a c l _ r e p l a c e
     *
     * Replace the acl associated with the object referred to in the handle.
     * ACLs are immutable, the replace operation takes the new acl and throws
     * away the old acl associated with the object.
     *
     * Comparable to POSIX acl_write()
     */
    void sec_acl_replace (
        [in]        sec_acl_handle_t        h,
        [in, ref]   uuid_t                  *manager_type,   
        [in]        sec_acl_type_t          sec_acl_type,
        [in]        sec_acl_list_t          *sec_acl_list,
        [out, ref]  error_status_t          *st
    );

    /* s e c _ a c l _ g e t _ a c c e s s
     *
     *  Determine the caller's access to the specified object.  This is 
     *  useful for implenting operations like the conventional UNIX access
     *  function.
     */
    void sec_acl_get_access (
        [in]        sec_acl_handle_t        h,
        [in, ref]   uuid_t                  *manager_type,
        [out, ref]  sec_acl_permset_t       *net_rights,
        [out]       error_status_t          *st
    );

    /* s e c _ a c l _ t e s t _ a c c e s s
     *
     * Determine if the caller has the requested access.
     */
     boolean32 sec_acl_test_access (
        [in]        sec_acl_handle_t        h,
        [in, ref]   uuid_t                  *manager_type,   
        [in]        sec_acl_permset_t       desired_permset,
        [out, ref]  error_status_t          *st
    );

    /* s e c _ a c l _ t e s t _ a c c e s s _ o n _ b e h a l f
     *
     * Determine if the subject has the requested access.  This function
     * returns true if the accecss is available to both the caller and
     * the subject identified in the call.
     */
     boolean32 sec_acl_test_access_on_behalf (
        [in]        sec_acl_handle_t        h,
        [in, ref]   uuid_t                  *manager_type,   
        [in, ptr]   sec_id_pac_t            *subject,
        [in]        sec_acl_permset_t       desired_permset,
        [out, ref]  error_status_t          *st
    );


    /* s e c _ a c l _ g e t _ m a n a g e r _ t y p e s
     *
     * Determine the types of acls protecting an object. ACL editors/browsers
     * use this operation to determine the acl manager types that a particular
     * reference monitor is using to protect a selected entity.
     *
     * num_types is the total number of acl manager types supported by this
     * entity - if it is greater than the size avail, this function should be
     * invoked again with a buffer of the appropriate size.
     *
     * If num_types is greater than 1, the object is polymorphic - i.e., the
     * named object supports acl manager types for each form of the selected
     * entity.
     *
     * If the acl for the target object contains more than 32 permission
     * bits, multiple manager types can be used - one for each 32 bit wide
     * slice of permissions.  The manager_types array does not include all
     * the manager types that are chained together in this way - it only
     * includes the root of each chain.  The chain is obtained via calls to
     * sec_acl_get_printstring.
     */
    void sec_acl_get_manager_types (
        [in]        sec_acl_handle_t        h,
        [in]        sec_acl_type_t          sec_acl_type,
        [in]        unsigned32              size_avail,
        [out]       unsigned32              *size_used,
        [out]       unsigned32              *num_types,
        [out, size_is(size_avail), length_is(*size_used)]
                    uuid_t                  manager_types[],
        [out, ref]  error_status_t          *st
    );


    /*  s e c _ a c l _ c a l c _ m a s k
     *
     *  Calculate and set the sec_acl_e_type_mask_obj entry of the specified
     *  ACL list.  The value of the sec_acl_e_type_mask_obj entry shall be the
     *  union of the permissions of all ACL entries that refer to members of
     *  the File Group Class.
     *
     *  This operation is performed locally, within the sec_acl client agent.
     *  No checking is done internal to this function to determine if the
     *  manager that this ACL list will be submitted to, supports the entry
     *  type sec_acl_e_type_mask_obj.  It is up to the calling application to
     *  determine whether to call this routine, after obtaining the required
     *  if any, POSIX semantics, via sec_acl_get_mgr_types_semantics(...).
     *
     * Errors: 
     *  sec_acl_cant_allocate_memory
     *
     *  Comparable to POSIX acl_calc_mask()
     */
    void sec_acl_calc_mask (
        [in, out]   sec_acl_list_t          *sec_acl_list,
        [out, ref]  error_status_t          *st
    );


    /*  s e c _ a c l _ g e t _ p r i n t s t r i n g
     *
     * Retrieve printable representations for each permission bit that the 
     * sec_acl manager will support.  There may be aliases for common
     * permission combinations - by convention simple entries should
     * appear at the beginning of the array, and combinations should at the
     * appear at the end.  When false the tokenize flag indicates that
     * permission printstrings are unambiguous and therefore printstrings
     * for variouspermissions can be concatenated.  When true, however,
     * this property does not hold and the strings should be tokenized
     * before input or output. The manager_info string provides a name and
     * help info for the manager type as well as the complete set of
     * supported permission bits. total_num_printstrings is the total
     * number of acl printstrings supported by this acl manager type - if
     * it is greater than the size avail, this function should be invoked
     * again with a buffer of the appropriate size.
     *
     * If the acl for the target object contains more than 32 permission
     * bits, multiple manager types can be used - one for each 32 bit wide
     * slice of permissions.  When this is the case the manager_type_chain
     * parameter is set to the uuid of the next manager type in the set.  The
     * final result for the chain returns uuid_nil in the manager_type_chain
     * parameter.
     */
     void sec_acl_get_printstring (
        [in]        sec_acl_handle_t        h,
        [in, ref]   uuid_t                  *manager_type,   
        [in]        unsigned32              size_avail,
        [out]       uuid_t                  *manager_type_chain,
        [out]       sec_acl_printstring_t   *manager_info,
        [out, ref]  boolean32               *tokenize,
        [out]       unsigned32              *total_num_printstrings,
        [out, ref]  unsigned32              *size_used,
        [out, size_is(size_avail), length_is(*size_used)]
                    sec_acl_printstring_t   printstrings[],
        [out, ref]  error_status_t          *st
    );

    /* s e c _ a c l _ r e l e a s e
     *
     * Release any storage associated with the acl object.  This is generally
     * implemented as a local operation - since it is getting rid of the local
     * storage allocated for the acl.  It never has an effect on the remote
     * object.
     */
     void sec_acl_release (
        [in]            sec_acl_handle_t    h,
        [in, out, ref]  sec_acl_t           *sec_acl,
        [out, ref]      error_status_t      *st
    );

    /* s e c _ a c l _ g e t _ e r r o r _ i n f o
     *
     * Errors received from the NCS runtime or other APIs are saved in the
     * sec_acl_handle_t and a corresponding sec_acl error is passed back
     * from the sec_acl_ API.  sec_acl_get_error_info returns the actual
     * error code, last stored in the acl handle, for those clients that
     * need to know exactly what went wrong.
     */
     error_status_t sec_acl_get_error_info(
        [in]            sec_acl_handle_t    h
     );

    /* s e c _ a c l _ r e l e a s e _ h a n d l e
     *
     * Dispose of an acl handle.
     */
     void sec_acl_release_handle (
        [in, out]       sec_acl_handle_t    *h,
        [out, ref]      error_status_t      *st
    );


    /* s e c _ a c l _ g e t _ m g r _ t y p e s _ s e m a n t i c s
     *
     * Determine the types of acls protecting an object. ACL editors/browsers
     * use this operation to determine the acl manager types that a particular
     * reference monitor is using to protect a selected entity.
     *
     * num_types is the total number of acl manager types supported by this
     * entity - if it is greater than the size avail, this function should be
     * invoked again with a buffer of the appropriate size.
     *
     * If num_types is greater than 1, the object is polymorphic - i.e., the
     * named object supports acl manager types for each form of the selected
     * entity.
     *
     * If the acl for the target object contains more than 32 permission
     * bits, multiple manager types can be used - one for each 32 bit wide
     * slice of permissions.  The manager_types array does not include all
     * the manager types that are chained together in this way - it only
     * includes the root of each chain.  The chain is obtained via calls to
     * sec_acl_get_printstring.
     *
     * For each manager_type, determine which, if any, POSIX semantics the
     * manager supports.
     */
    void sec_acl_get_mgr_types_semantics (
        [in]        sec_acl_handle_t            h,
        [in]        sec_acl_type_t              sec_acl_type,
        [in]        unsigned32                  size_avail,
        [out]       unsigned32                  *size_used,
        [out]       unsigned32                  *num_types,
        [out, size_is(size_avail), length_is(*size_used)]
                    uuid_t                      manager_types[],
        [out, size_is(size_avail), length_is(*size_used)]
                    sec_acl_posix_semantics_t   posix_semantics[],
        [out, ref]  error_status_t              *st
    );
}
