VMS Help DCE_SECURITY, API Routines, sec_acl_test_access_on_behalf  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   sec_acl_test_access_on_behalf - Tests access to an object on behalf of
                                   another process

 SYNOPSIS

   #include <dce/daclif.h>

   boolean32 sec_acl_test_access_on_behalf(
           sec_acl_handle_t h,
           uuid_t *manager_type,
           sec_id_pac_t *subject,
           sec_acl_permset_t desired_permset,
           error_status_t *status);

 PARAMETERS

   Input

   h      A handle referring to the target object.  Use sec_acl_bind() to
          create this handle.

   manager_type
          A pointer to the UUID identifying the type of the ACL manager
          in question. There may be more than one type of ACL manager
          protecting the object whose ACL is bound to the input handle.
          Use this parameter to distinguish them.  Use
          sec_acl_get_manager_types() to acquire a list of the manager
          types protecting a given object.

   subject
          A Privilege Attribute Certificate (PAC) for the subject process.
          The PAC contains the name and UUID of the principal and cell of
          the subject process, as well as a list of any groups to which it
          belongs.  The PAC also contains a flag (named authenticated).
          When set, it indicates that the certificate was obtained from an
          authenticated source.  When not set, the certificate must not be
          trusted.  (The field is FALSE when it was obtained from the
          rpc_auth layer and the protect level was set to
          rpc_c_protect_level_none.  This indicates that no authentication
          protocol was actually used in the remote procedure call; the
          identity was simply transmitted from the caller to the callee.
          If an authentication protocol was used, then the flag is set to
          TRUE.)  If a null PAC is passed, the subject is treated as an
          "anonymous user", matching only the any_other and unauthenticated
          entries (if they exist) on the ACL.  A server uses
          rpc_binding_inq_auth_client() to acquire a certificate for the
          client process.

   desired_permset
          A permission set in sec_acl_permset_t form containing the desired
          privileges. This is a 32-bit set of permission flags supported by
          the manager type.

   Output

   status
          A pointer to the completion status.  On successful completion,
          the routine returns error_status_ok.  Otherwise, it returns an
          error.

 DESCRIPTION

   The sec_acl_test_access_on_behalf() routine determines if the specified
   ACL contains entries that grant the privileges specified in
   desired_permset to the subject process.  An application generally
   inquires about only the minimum set of privileges needed to accomplish
   a specific task.

   Permissions Required

   The sec_acl_test_access_on_behalf() routine requires at least one
   permission of any kind on the object for which the privileges are to
   be tested.  Both the calling process and the identified subject must
   have permission on the object.

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

 RETURN VALUES

   If the routine completes successfully (with a completion status of
   error_status_ok) it returns a value of

     +  TRUE if the caller has any access (at least one permission of any
        kind), and the subject has the desired_permset privileges.

     +  FALSE if both the caller and the subject have any access, but the
        subject does not have the desired_permset privileges.

   If the routine does not complete successfully, it returns a bad
   completion status code and a return value of FALSE.

 ERRORS

   sec_acl_unknown_manager_type
                The manager type selected is not an available option.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_acl_bind
              sec_acl_test_access
              rpc_binding_inq_auth_client