classification
Title: Winreg's documentation lacks mentioning required permission at some points
Type: enhancement Stage: patch review
Components: Documentation, Windows Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: ZackerySpytz, docs@python, eryksun, georgefischhof, paul.moore, steve.dower, tim.golden, xtreak, zach.ware
Priority: normal Keywords: patch

Created on 2018-10-19 09:14 by georgefischhof, last changed 2021-03-28 02:30 by eryksun.

Pull Requests
URL Status Linked Edit
PR 24547 open ZackerySpytz, 2021-02-15 23:35
Messages (3)
msg328034 - (view) Author: George Fischhof (georgefischhof) Date: 2018-10-19 09:14
Winreg's documentation lacks mentioning required permission at some points

Hi there,

on page 
https://docs.python.org/3/library/winreg.html
it is not mentioned in the description of the following functions:
winreg.DeleteKey
winreg.DeleteKeyEx
winreg.DeleteValue

that they require KEY_SET_VALUE when the registry key is opened.

It is mentioned for example at:
winreg.SetValue

with the following text:
The key identified by the key parameter must have been opened with KEY_SET_VALUE access.


BR,
George
msg328122 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python committer) Date: 2018-10-20 04:43
Thanks for the report. I am adding windows component since it's a windows specific doc issue.

RegDeleteValueW

> A handle to an open registry key. The key must have been opened with the KEY_SET_VALUE access right. For more information, see Registry Key Security and Access Rights.

https://docs.microsoft.com/en-us/windows/desktop/api/winreg/nf-winreg-regdeletevaluew#parameters

RegDeleteKeyExA

https://docs.microsoft.com/en-us/windows/desktop/api/winreg/nf-winreg-regdeletekeyexa#parameters
msg387081 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2021-02-16 01:03
winreg.DeleteKey[Ex] does not require any particular access on the `key` handle. This handle is used only as the native NT API RootDirectory [1] when opening `subkey` with DELETE access via NtOpenKeyEx [2].

The extra access with winreg.DeleteKeyEx [3] is just to allow explicitly using the 32-bit or 64-bit registry view (i.e. KEY_WOW64_32KEY or KEY_WOW64_64KEY) when traversing the registry. I think this should be clarified in the docs. For example, if you have the predefined handle HKEY_LOCAL_MACHINE as the `key` handle, then deleting r"Software\Spam" will default to traversing the process 32- or 64-bit view of the "Software" key, but you can override the default view. (Note that if you start from a handle for the "Software" key, then setting an explicit view in the access mode doesn't matter since "Software" isn't traversed to reach "Spam" in this case.) 

winreg.DeleteKeyEx uses KEY_WOW64_64KEY as the default `access` mode. I think this is a mistake. It should default to 0, and thus implicitly traverse the process view from the path of the `key` handle. A 32-bit process should not default to traversing the 64-bit registry view.

---
[1] https://docs.microsoft.com/en-us/windows/win32/api/ntdef/ns-ntdef-_object_attributes
[2] https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwopenkeyex
[3] https://docs.microsoft.com/en-us/windows/win32/api/winreg/nf-winreg-regdeletekeyexw
History
Date User Action Args
2021-03-28 02:30:06eryksunsetversions: + Python 3.8, Python 3.9, Python 3.10, - Python 3.7
2021-02-16 01:03:01eryksunsetnosy: + eryksun
messages: + msg387081
2021-02-15 23:35:20ZackerySpytzsetkeywords: + patch
nosy: + ZackerySpytz

pull_requests: + pull_request23330
stage: patch review
2018-10-20 04:43:09xtreaksetnosy: + xtreak, paul.moore, tim.golden, zach.ware, steve.dower
messages: + msg328122
components: + Windows
2018-10-19 09:14:10georgefischhofcreate