3.1.4.2.1 Access Checks Applied on Handle Open

  • Article

When opening a handle, the server MUST associate with it a set of ACCESS_MASK bits, as defined in section 2.2.1.1. These access bits control which type of subsequent operations the caller can perform with this handle.

All methods that open handles (as specified in section 3.1.4.1) allow the caller to specify a "desired access" bitmask. The meaning of the bits within this bitmask depends on the type of object. The bits are documented in sections 2.2.1.1.1, 2.2.1.1.2, 2.2.1.1.3, 2.2.1.1.4, and 2.2.1.1.5. All methods that open handles (as specified in section 3.1.4.1) perform an access check based on the desired access mask, whose general form is:

 IF (method specific check fails) THEN
     Return STATUS_ACCESS_DENIED
 END IF
 IF (security descriptor check fails) THEN
     Return STATUS_ACCESS_DENIED
 END IF

The method-specific checks are detailed in the sections for individual methods that open handles. The security-descriptor check is performed by using the Access Check Algorithm Pseudocode ([MS-DTYP] section 2.5.3.2). For this protocol, the input parameters of that algorithm are mapped as follows:

  • SecurityDescriptor: The security descriptor of the object to which the handle is being opened, as specified in section 3.1.1.

  • Token: This MUST be the token ([MS-DTYP] section 2.5.2) of the client, obtained by invoking GetRpcImpersonationAccessToken(NULL). The GetRpcImpersonationAccessToken interface is specified in [MS-RPCE] section 3.3.3.4.3.1.

  • Access Request mask: The DesiredAccess parameter of the method being invoked, or the DesiredAccess value specified in the method description.

  • Object Tree: This parameter MUST be NULL.

  • PrincipalSelfSubst SID: This parameter MUST be NULL.

  • GrantedAccess: The value returned by this parameter MUST be stored in a local variable LocalGrantedAccess (of type ACCESS_MASK).

In the case that the access check is successful, the server MUST NOT grant more access bits than the caller has asked for, but MUST grant only those access bits that the client has explicitly requested. The caller is permitted to request the maximum access permitted by the server by specifying the special constant MAXIMUM_ALLOWED, as specified in section 2.2.1.1.1.

If DesiredAccess contains the MAXIMUM_ALLOWED bit, the server MUST create and return an LsaContextHandle (section 3.1.1.7) via the method's LSAPR_HANDLE* output parameter, with its fields initialized as follows:

  • LsaContextHandle.HandleType = "Policy", "Account", "Secret", or "Trusted Domain", depending on the type of the database object

  • LsaContextHandle.Object = the database object

  • LsaContextHandle.GrantedAccess = LocalGrantedAccess

If DesiredAccess does not contain the MAXIMUM_ALLOWED bit, the following constraint MUST be satisfied:

  • If DesiredAccess contains bits that are not in GrantedAccess, the server MUST return STATUS_ACCESS_DENIED. Otherwise, the server MUST create and return an LsaContextHandle (section 3.1.1.7) via the method's LSAPR_HANDLE* output parameter, with its fields initialized as follows:

    • LsaContextHandle.HandleType = "Policy", "Account", "Secret", or "Trusted Domain", depending on the type of the database object

    • LsaContextHandle.Object = the database object

    • LsaContextHandle.GrantedAccess = DesiredAccess

The server MUST NOT allow the caller to add more access bits to the handle in a subsequent operation. In order to obtain more access, a new handle must be obtained.