/* @(#)93       1.7  src/security/idl/sec_cred.idl, security.src, os2dce21.dss, 960602a.1  5/17/95  09:51:09 */
/*
 * COMPONENT_NAME:  security.src
 *
 * FUNCTIONS:
 *
 * ORIGINS: 72
 *
 */
/*
 * 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_cred.idl,v $
 * Revision 1.1.2.6  1994/09/21  22:01:28  burati
 * 	CR11980 Make anonymous cell, principal and group uuids available
 * 	[1994/09/21  21:14:59  burati]
 *
 * Revision 1.1.2.5  1994/08/04  16:13:02  mdf
 * 	Hewlett Packard Security Code Drop
 * 	[1994/07/28  17:15:38  mdf]
 * 
 * Revision 1.1.2.4  1994/07/15  15:00:22  mdf
 * 	Hewlett Packard Security Code Drop
 * 	[1994/07/14  17:17:35  mdf]
 * 
 * Revision 1.1.2.3  1994/06/17  18:42:32  devsrc
 * 	cr10872 - fix copyright
 * 	[1994/06/17  18:10:37  devsrc]
 * 
 * Revision 1.1.2.2  1994/06/02  21:28:44  mdf
 * 	hp_sec_to_osf_3 drop, merge up with latest.
 * 	[1994/05/24  15:16:27  mdf]
 * 
 * 	hp_sec_to_osf_3 drop
 * 
 * Revision 1.1.2.1  1994/01/28  23:10:59  burati
 * 	Initial version (dlg_bl1)
 * 	[1994/01/18  20:54:28  burati]
 * 
 * $EndLog$
 */

/* sec_cred.idl -
 *  API for retrieval of Privilege Attribute information from Extended PACs
 *
 * Copyright (c) Hewlett-Packard Company 1993
 * Unpublished work. All Rights Reserved.
 */

[ local ]

interface sec_cred {
 
 import "dce/rgynbase.idl";
 import "dce/secsts.idl";
 import "dce/lbase.idl";
 import "dce/id_epac.idl";
 import "dce/rpcbase.idl";

/* Anonymous Cell, Principal and Group IDs */
const char * SEC_ANONYMOUS_PRINC = "fad18d52-ac83-11cc-b72d-0800092784e9";
const char * SEC_ANONYMOUS_GROUP = "fc6ed07a-ac83-11cc-97af-0800092784e9";
const char * SEC_ANONYMOUS_CELL  = "6761d66a-cff2-11cd-ab92-0800097086e0";

/* The sec_cred module provides accessor functions for extracting privilege
 * attributes. This module insulates applications from dealing directly with
 * PAC or EPAC formats.
 */

/* sec_cred_is_authenticated
 *
 * Retruns true if the caller privilege attributes are authenicated,
 * false otherwise. 
 *
 * Semantics of arguments
 *   callers_identity - specifies the identity of the server's RPC client as
 *                      obtained from the RPC runtime.
 *   error_status -     error status.
 */
boolean32 sec_cred_is_authenticated (
    [in]rpc_authz_cred_handle_t callers_identity,
    [out]error_status_t	        *error_status
);

/* sec_cred_inquire_auth_service_info
 *
 * returns info regarding the authentication/authorization
 * services used in an authenticated RPC.
 *
 * Semantics of arguments
 *   callers_identity - specifies the identity of the server's RPC client as
 *                      obtained from the RPC runtime.
 *   server_princ_name - Server name that caller authenticated to.
 *   authn_svc - the authentication service  
 *   authz_svc - the authorization service
 *   
 *   error_status -     error status.
 */

void  sec_cred_inq_auth_service_info (
    [in] rpc_authz_cred_handle_t callers_identity,
    [out] unsigned_char_p_t      *server_princ_name,
    [out] unsigned32             *authn_svc,
    [out] unsigned32             *authz_svc,
    [out] error_status_t	 *error_status
);

/* sec_cred_get_client_princ_name
 *
 * This function is used to extract the principal name of a server's
 * RPC client, if the authorization service can provide it.
 * If not, a sec_cred_s_authz_cannot_comply status is returned
 *
 * Semantics of arguments
 *   callers_identity - specifies the identity of the server's RPC client as
 *                      obtained from the RPC runtime.
 *   error_status -     error status.
 */
void sec_cred_get_client_princ_name (
    [in] rpc_authz_cred_handle_t callers_identity,
    [out] unsigned_char_p_t      *client_princ_name,
    [out] error_status_t	 *error_status
);

/* sec_cred_get_initiator
 *
 * This function is used to extract the initiator's privilege attributes from
 * the RPC runtime.
 * Semantics of arguments
 *   callers_identity - specifies the identity of the server's RPC client as
 *                      obtained from the RPC runtime.
 *   error_status -     error status.
 */

sec_cred_pa_handle_t sec_cred_get_initiator (
    [in]rpc_authz_cred_handle_t callers_identity,
    [out]error_status_t	        *error_status
);


/* sec_cred_get_delegate
 *
 * This function is used to iterate through and extract the privilege
 * attributes of the delegates involved in this operation from the RPC runtime.
 * Semantics of arguments
 *   callers_identity - specifies the identity of the server's RPC client as 
 *                      obtained from the RPC runtime.
 *   cursor -           an input/output cursor used to iterate through the set 
 *                      of delegates involved in this operation.
 *   error_status -     error status.
 */

sec_cred_pa_handle_t sec_cred_get_delegate (
    [in]rpc_authz_cred_handle_t callers_identity,
    [in,out]sec_cred_cursor_t   *cursor,
    [out]error_status_t         *error_status
);

/* sec_cred_get_authz_session_info
 * 
 * This functions is used to retrieve a session specific info that represents
 * the authenticated clients credentials.  The session_info is meant to aid
 * application servers in the construction of identity-based caches.
 *
 * Semantics of arguments
 *   callers_identity - specifies the identity of the server's RPC client as 
 *                      obtained from the RPC runtime.
 *   session_id - the client session specific uuid.  If not been set (NIL-uuid),
 *                it means client session has not started it (No authenticated
 *                credentials for this client's session yet.
 *   session_expiration - the expiration time of the authenticated client creds.
 *   stp - error statuses.
 */

void sec_cred_get_authz_session_info (
    [in]  rpc_authz_cred_handle_t callers_identity,     
    [out] uuid_t                  *session_id,         
    [out] sec_timeval_sec_t       *session_expiration, 
    [out] error_status_t          *stp                 
);



/* sec_cred_get_v1_pac
 *
 * This function is used to extract a version 1 DCE PAC from a privilege
 * attribute handle.
 * Semantics of arguments
 *   callers_pas - specifies the handle to a set of privilege attributes.
 *   error_status - error statuses.
 */

sec_id_pac_t *sec_cred_get_v1_pac (
    [in]sec_cred_pa_handle_t    callers_pas,
    [out]error_status_t         *error_status
);


/* sec_cred_get_pa_data
 * 
 * This function is used to extract identity information from a privilege
 * attribute handle.
 * Semantics of arguments
 *   callers_pas - specifies the handle to a set of privilege attributes.
 *   error_status - error statuses.
 */

sec_id_pa_t *sec_cred_get_pa_data (
    [in]sec_cred_pa_handle_t    callers_pas,
    [out]error_status_t         *error_status
);


/* sec_cred_get_extended_attrs
 * 
 * This function is used to extract extended attributes from a privilege
 * attribute handle.
 * Semantics of arguments
 *   callers_pas - specifies the handle to a set of privilege attributes.
 *   cursor - an input/output cursor used to iterate through the set
 *            of extended attributes.
 *   attr -   the next available extended attribute (these attributes use the
 *            same syntax and are the same datatype as the extended registry
 *            attributes defined in DCE RFC 6.).
 *   error_status -  error statuses.
 */

void sec_cred_get_extended_attrs (
    [in]sec_cred_pa_handle_t        callers_pas,
    [in,out]sec_cred_attr_cursor_t  *cursor,
    [out]sec_attr_t                 *attr,
    [out]error_status_t             *error_status
);


/* sec_cred_initialize_attr_cursor
 *
 * This function is used to initialize a sec_cred_attr_cursor_t for use in
 * calls to the iterative routine sec_cred_get_extended_attributes.
 * Semantics of arguments
 *   cursor - an input/output cursor used to iterate through the set of
 *            extended attributes.
 *   error_status - error status.
 */

void sec_cred_initialize_attr_cursor (
    [in,out]sec_cred_attr_cursor_t      *cursor,
    [out]error_status_t	                *error_status
);


/* sec_cred_initialize_cursor
 *
 * This function is used to initialize a sec_cred_cursor_t for use in calls to
 * the iterative routine sec_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_cred_initialize_cursor (
    [in,out]sec_cred_cursor_t   *cursor,
    [out]error_status_t         *error_status
);


/* Sec_cred_get_delegation_type
 *
 * This function is used to extract the allowed delegation type from the
 * privilege attribute handle.
 * Semantics of arguments
 *   callers_pas -   specifies the handle to a set of privilege attributes.
 *   error_status -  error status.
 */

sec_id_delegation_type_t sec_cred_get_delegation_type (
    [in]sec_cred_pa_handle_t    callers_pas,
    [out]error_status_t         *error_status
);


/* sec_cred_get_tgt_restrictions
 *
 * This function is used to extract target restrictions from a privilege
 * attribute handle.
 * Semantics of arguments
 *   callers_pas -   specifies the handle to a set of privilege attributes.
 *   error_status -  error status.
 */

sec_id_restriction_set_t *sec_cred_get_tgt_restrictions (
    [in]sec_cred_pa_handle_t    callers_pas,
    [out]error_status_t         *error_status
);


/* sec_cred_get_deleg_restrictions
 *
 * This function is used to extract delegate restrictions from a privilege
 * attribute handle.
 * Semantics of arguments
 *   callers_pas -   specifies the handle to a set of privilege attributes.
 *   error_status -  error status.
 */

sec_id_restriction_set_t *sec_cred_get_deleg_restrictions (
    [in]sec_cred_pa_handle_t    callers_pas,
    [out]error_status_t         *error_status
);


/* sec_cred_get_opt_restrictions
 *
 * This function is used to extract optional restrictions from a privilege
 * attribute handle.
 * Semantics of arguments
 *   callers_pas -   specifies the handle to a set of privilege attributes.
 *   error_status -  error status.
 */

sec_id_opt_req_t *sec_cred_get_opt_restrictions (
    [in]sec_cred_pa_handle_t    callers_pas,
    [out]error_status_t         *error_status
);


/* sec_cred_get_req_restrictions
 * 
 * This function is used to extract required restrictions from a privilege
 * attribute handle.
 * Semantics of arguments
 *   callers_pas -   specifies the handle to a set of privilege attributes.
 *   error_status -  error status.
 */

sec_id_opt_req_t *sec_cred_get_req_restrictions (
    [in]sec_cred_pa_handle_t    callers_pas,
    [out]error_status_t         *error_status
);

/* sec_cred_free_cursor
 *
 * Free the local resources associated with a delegate cursor
 */
void sec_cred_free_cursor (
    [in, out] sec_cred_cursor_t  *cursor,
    [out] error_status_t         *error_status
);

/* sec_cred_free_attr cursor
 *
 * Free the local resources associated with an aqttribute cursor
 */
void sec_cred_free_attr_cursor (
    [in, out] sec_cred_attr_cursor_t *cursor,
    [out] error_status_t             *error_status
);

/* sec_cred_free_pa_handle
 *
 * Free the local resources associated with a privilege attribute
 * handle returned by sec_cred_get_initiator()  or sec_cred_get_delegate()
 */
void sec_cred_free_pa_handle (
    [in, out] sec_cred_pa_handle_t  *pa_handle,
    [out] error_status_t        *error_status
);


/*
 * ROCKS:  
 * The following concept is borrowed shamelessly from Transarc/CMU.
 * 
 * In order to make it easier to do application-specific authorization
 * efficiently, we provide "rocks" as places for the application to "hide" 
 * things under.  
 * 
 * This allows the application to implement a cache of "pre-cooked" 
 * authorization information or related data.
 * 
 * The cached data may be deleted at *any* time when the server is 
 * not executing manager routines on behalf of that identity.
 */

/*
 * Private data destructor: callback function invoked when RPC runtime is 
 * done with the rpc_authz_cred_handle_t.
 * Must not fail.
 * 
 */

typedef void (*sec_cred_destruct_fn_t) (
    [in] void *app_private_data
);

/* sec_cred_get_key
 * 
 * Return a unique integer key used by an application server to associate 
 * application-specific data with an rpc_authz_cred_handle_t.
 * 
 * Semantics of arguments 
 * 	app_id - application's subsystem uuid.  If this application
 *               subsystem uuid is already associated with an
 *               existing key, that existing key is returned.
 *               Otherwise a new key is created and associated
 *               with this application subsystem uuid.
 *      destructor_fn - A destructor function that is called to cleanup
 *			the data associated with the returned key.  May
 * 			be NULL, if no destructive action is required.
 *	error_status - sec_s_no_mem
 *
 * Return Values
 * 	A newly created unique cred key or previously used unique key.
 *
 */

unsigned32 sec_cred_get_key (
    [in] uuid_t			*app_id,
    [in] sec_cred_destruct_fn_t destructor_fn,
    [out] error_status_t	*error_status
);



/* sec_cred_set_app_private_data
 *
 * Associate an application-specific <key, data> pair with a 
 * credential handle.  A credential handle may contain only
 * one reference to a given key.  If the credential handle already
 * contans a reference to the specified key, the data associated
 * with that key is replaced with the specified app_private_data.  
 *
 * Semantics of arguments 
 *      callers_identity - the credential handle in which the 
 *                         <key, data> pair should be stored
 *      key - the cred key to be stored in the callers_identity
 *      app_private_data - the application-specific data associated with
 *                         the cred key
 *	error_status - sec_cred_s_invalid_auth_handle
 *                     sec_cred_s_invalid_key		       
 *                     sec_s_no_mem
 */



void sec_cred_set_app_private_data (
    [in] rpc_authz_cred_handle_t	callers_identity,
    [in] unsigned32			key,
    [in] void				*app_private_data,
    [out] error_status_t		*error_status
);


/* sec_cred_get_app_private_data
 *
 * Retrieve an application-specific <key, data> pair from a  
 * credential handle.  
 *
 * Semantics of arguments
 *      callers_identity - the credential handle in which the 
 *                         <key, data> pair is stored
 *      key - the cred key of the data to be retrieved from the 
 *            callers_identity 
 *	app_private_data -  the application-specific data associated with
 * 			    the cred key.  If it's NULL, the data has
 *                          not been set yet.
 *      error_status - sec_cred_s_invalid_auth_handle
 *                     sec_cred_s_invalid_key
 *                     sec_cred_s_key_not_found
 */

void sec_cred_get_app_private_data (
    [in] rpc_authz_cred_handle_t	callers_identity,
    [in] unsigned32			key,
    [out] void				**app_private_data,
    [out] error_status_t		*error_status
); 



}

