IEffectivePermission2::ComputeEffectivePermissionWithSecondarySecurity method (aclui.h)

Article
10/13/2021

The ComputeEffectivePermissionWithSecondarySecurity method computes the effective permissions for an object. It supports integrating secondary or custom security policies. You may choose to provide this additional security information by implementing the ISecurityInformation4 interface. This method supports compound identity, which is when a principal's access token contains user and device authorization information.

Syntax

HRESULT ComputeEffectivePermissionWithSecondarySecurity(
  [in]           PSID                                   pSid,
  [in, optional] PSID                                   pDeviceSid,
  [in, optional] PCWSTR                                 pszServerName,
  [in]           PSECURITY_OBJECT                       pSecurityObjects,
  [in]           DWORD                                  dwSecurityObjectCount,
  [in, optional] PTOKEN_GROUPS                          pUserGroups,
  [in, optional] PAUTHZ_SID_OPERATION                   pAuthzUserGroupsOperations,
  [in, optional] PTOKEN_GROUPS                          pDeviceGroups,
  [in, optional] PAUTHZ_SID_OPERATION                   pAuthzDeviceGroupsOperations,
  [in, optional] PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION pAuthzUserClaims,
  [in, optional] PAUTHZ_SECURITY_ATTRIBUTE_OPERATION    pAuthzUserClaimsOperations,
  [in, optional] PAUTHZ_SECURITY_ATTRIBUTES_INFORMATION pAuthzDeviceClaims,
  [in, optional] PAUTHZ_SECURITY_ATTRIBUTE_OPERATION    pAuthzDeviceClaimsOperations,
  [in, out]      PEFFPERM_RESULT_LIST                   pEffpermResultLists
);

Parameters

[in] pSid

A pointer to a SID structure that represents the security principal whose effective permission is being determined.

[in, optional] pDeviceSid

A pointer to a SID structure that represents the device from which the principal is accessing the object. If this is not NULL and you are using the AuthzAccessCheck function to compute the effective permissions, then the device SID may be compounded with the pSid parameter by using the AuthzInitializeCompoundContext function.

[in, optional] pszServerName

The name of the server on which the object resides. This is the same name that was returned from the ISecurityInformation::GetObjectInformation method.

[in] pSecurityObjects

An array of security objects. This array is composed of objects that were deduced by the access control editor in addition to the ones returned from the ISecurityInformation4::GetSecondarySecurity method.

[in] dwSecurityObjectCount

The number of security objects in the pSecurityObjects parameter, and the number of results lists in the pEffpermResultLists parameter.

[in, optional] pUserGroups

A pointer to additional user groups that should be used to modify the security context which was initialized from the pSid parameter. If you are using the AuthzAccessCheck function to compute the effective permissions, then the modification may be done by calling the AuthzModifySids function using AuthzContextInfoGroupsSids as the SidClass parameter.

[in, optional] pAuthzUserGroupsOperations

Pointer to an array of AUTHZ_SID_OPERATION structures that specify how the user groups in the authz context must be modified for each user group in the pUserGroups argument. This array contains as many elements as the number of groups in the pUserGroups parameter.

[in, optional] pDeviceGroups

A pointer to additional device groups that should be used to modify the security context which was initialized from the pSid parameter or one that was created by compounding the contexts that were initialized from the pSid and pDeviceSid parameters. If you are using the AuthzAccessCheck function to compute the effective permissions, then the modification may be done by calling the AuthzModifySids function using AuthzContextInfoDeviceSids as the SidClass parameter.

[in, optional] pAuthzDeviceGroupsOperations

Pointer to an array of AUTHZ_SID_OPERATION enumeration types that specify how the device groups in the authz context must be modified for each device group in the pDeviceGroups argument. This array contains as many elements as the number of groups in the pDeviceGroups parameter.

[in, optional] pAuthzUserClaims

Pointer to an AUTHZ_SECURITY_ATTRIBUTES_INFORMATION structure that contains the user claims context that should be used to modify the security context that was initialized from the pSid parameter. If you are using the AuthzAccessCheck function to compute the effective permissions, then the modification may be done by calling the AuthzModifyClaims function using AuthzContextInfoUserClaims as the ClaimClass parameter.

[in, optional] pAuthzUserClaimsOperations

Pointer to an AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration type that specifies the operations associated with the user claims context.

[in, optional] pAuthzDeviceClaims

A pointer to the device claims context that should be used to modify the security context that was initialized from the pSid parameter or one that was created by compounding the contexts that were initialized from the pSid and pDeviceSid parameters. This may be supplied by the caller, even if the pDeviceSid parameter is not. If you are using the AuthzAccessCheck function to compute the effective permissions, then the modification may be done by calling the AuthzModifyClaims function using AuthzContextInfoDeviceClaims as the ClaimClass parameter.

[in, optional] pAuthzDeviceClaimsOperations

Pointer to an AUTHZ_SECURITY_ATTRIBUTE_OPERATION enumeration type that specifies the operations associated with the device claims context.

[in, out] pEffpermResultLists

A pointer to an array of the effective permissions results of type EFFPERM_RESULT_LIST. This array is dwSecurityObjectCount elements long. The array is initialized by the caller and the implementation is expected to set all fields of each member in the array, indicating what access was granted by the corresponding security object.

If a security object was considered, the fEvaluated member should be set to TRUE. In this case, the pObjectTypeList and pGrantedAccessList members should both be cObjectTypeListLength elements long. The pObjectTypeList member must point to memory that is owned by the resource manager and must remain valid until the EditSecurity function exits. The pGrantedAccessList member is freed by the caller by using the LocalFree function. If the resource manager does not support object ACEs, then the pObjectTypeList member should point to the NULL GUID, the cObjectTypeListLength member should be 1, and the pGrantedAccessList member should be a single DWORD.

Return value

If the function is successful, the return value is S_OK.

If the function is successful but returned an approximate result, the return value is S_FALSE.

If the function fails, the return value is an HRESULT that indicates the error. For a list of common error codes, see Common HRESULT Values.

Remarks

When the Id member the SECURITY_OBJECT structure is set to SECURITY_OBJECT_ID_CENTRAL_ACCESS_RULE, the ComputeEffectivePermissionWithSecondarySecurity method should use the pData2 member first and only then evaluate access by using the pData member.

It is expected that the caller will use AuthzAccessCheck to determine the effective permissions. When possible, the implementation should initialize a remote resource manager on the supplied pszServerName member, using the AuthzInitializeRemoteResourceManager function to ensure that the groups and claims are initialized in the same manner as when the principal really accesses the object. If AuthzInitializeRemoteResourceManager fails, the implementation may fall back to using the AuthzInitializeResourceManager function and return S_FALSE to indicate that approximate results are returned.

For each of the secondary security objects whose fEvaluated member is set to TRUE, the access control editor will display which permissions and properties were limited by that object using the pwszName member.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	aclui.h