{"id":45591,"date":"2015-05-15T07:00:00","date_gmt":"2015-05-15T21:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/20150515-00\/?p=45591\/"},"modified":"2019-03-13T12:15:27","modified_gmt":"2019-03-13T19:15:27","slug":"20150515-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20150515-00\/?p=45591","title":{"rendered":"MapGenericMask is just a convenience function for converting generic access to specific access, according to the instructions you provide"},"content":{"rendered":"

For some reason, people call the Map­Generic­Mask<\/code> function in order to calculate what access mask to pass to request access to something. That’s not what Map­Generic­Mask<\/code> is for. The Map­Generic­Mask<\/code> function is to assist the server side of the access, not the client side. <\/p>\n

As the documentation says, the Map­Generic­Mask<\/code> function maps the generic access rights in an access mask to specific and standard access rights. The function applies a mapping supplied in a GENERIC_MAPPING<\/code> structure<\/a>. <\/p>\n

This is further explained in the remarks: <\/p>\n

After calling the Map­Generic­Mask<\/b> function, the access mask pointed to by the Access­Mask<\/i> parameter has none of its generic bits (GenericRead, GenericWrite, GenericExecute, or GenericAll) or undefined bits¹ set, although it can have other bits set. If bits other than the generic bits are provided on input, this function does not clear them. <\/p><\/blockquote>\n

What this function does is take the Access­Mask<\/code> parameter and convert all of the GENERIC_*<\/code> bits into object-specific bits, as defined by the GENERIC_MAPPING<\/code>. <\/p>\n

In other words, the code for the Map­Generic­Mask<\/code> function looks basically like this: <\/p>\n

\nvoid MapGenericMask(\n  PDWORD AccessMask,\n  PGENERIC_MAPPING GenericMapping\n)\n{\n if (*AccessMask & GENERIC_READ)\n     *AccessMask |= GenericMapping->GenericRead;\n\n if (*AccessMask & GENERIC_WRITE)\n     *AccessMask |= GenericMapping->GenericWrite;\n\n if (*AccessMask & GENERIC_EXECUTE)\n     *AccessMask |= GenericMapping->GenericExecute;\n\n if (*AccessMask & GENERIC_ALL)\n     *AccessMask |= GenericMapping->GenericAll;\n\n *AccessMask &= ~(GENERIC_READ | GENERIC_WRITE |\n                  GENERIC_WRITE | GENERIC_ALL);\n}\n<\/pre>\n
The function takes the access mask and sees if any of the generic access bits are set. If so, then it replaces them with the corresponding specific access bits provided by the Generic­Mapping<\/code> parameter. <\/p>\n
Note that this function doesn’t tell you anything you don’t already know. It’s just a helper function to make access checks easier to implement: If you are a component that manages an object and you need to perform an access check, you use Map­Generic­Access<\/code> to convert all the generic access requests into specific requests according to the rules you specified in your GENERIC_MAPPING<\/code>, and the rest of your code only needs to deal with specific requests. <\/p>\n
And if you needed to do a security check on a Gizmo, you would do something like this: <\/p>\n
\nBOOL IsGizmoAccessGranted(\n HTOKEN Token,\n PSECURITY_DESCRIPTOR SecurityDescriptor,\n DWORD AccessDesired,\n PDWORD AccessAllowed)\n{\n MapGenericMask(&AccessDesired, &GizmoGenericMapping);\n\n BOOL AccessGranted = FALSE;\n PRIVILEGE_SET PrivilegeSet;\n DWORD PrivilegeSetSize = sizeof(PrivilegeSet);\n\n return AccessCheck(SecurityDescriptor,\n            Token,\n            AccessDesired,\n            &GizmoGenericMapping,\n            &PrivilegeSet,\n            &PrivilegeSetSize,\n            AccessAllowed,\n            &AccessGranted) && AccessGranted;\n}\n<\/pre>\n
When somebody wants to access a Gizmo, you use Map­Generic­Mask<\/code> to convert all the generic requests to specific requests. You then pass that request to Access­Check<\/code>, along with token for the user making the request and the security descriptor for the widget. The Access­Check<\/code> function does the heavy lifting of seeing which ACEs apply to the user specified by the token, then verifying that all the requested accesses have an Allow<\/i> ACE, and that none of the requested accesses have a Deny<\/i> ACE. It also takes care of the MAXIMMUM_ALLOWED<\/code> access request by simply returning all the accesses that are allowed and not denied. <\/p>\n
The point of the Map­Generic­Mask<\/code> function is to make life a little easier for the code that enforces security. <\/p>\n
On the other hand, the Map­Generic­Mask<\/code> function is not particularly useful on the side that is requesting access. If you are requesting generic read access, just pass GENERIC_READ<\/code>. The code that does the security check will convert the GENERIC_READ<\/code> into the access masks that are specific to the object you are trying to access. (And it will most likely use the Map­Generic­Mask<\/code> function to do it.) <\/p>\n
¹ That extra phrase “or undefined bits” is contradicted by the subsequent sentence “If bits other than the generic bits are provided on input, the function does not clear them.” The second sentence is correct; the extra phrase “or undefined bits” is incorrect and should be removed. <\/p>\n","protected":false},"excerpt":{"rendered":"
It’s useful on the server side, not the client side.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-45591","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
It’s useful on the server side, not the client side.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/45591","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=45591"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/45591\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=45591"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=45591"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=45591"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
For example, we saw some time ago that a hypothetical Gizmo object<\/a> could map GENERIC_READ<\/code> to operations that query information from a Gizmo without modifying it, map GENERIC_WRITE<\/code> to operations that alter the gizmo properties, map GENERIC_EXECUTE<\/code> to operations that enable or disable the Gizmo, and map GENERIC_ALL<\/code> to include all Gizmo operations. <\/p>\n