Add function to smbclient to get security descriptor

[orthose]

This issue is linked with #347 and #348.

I propose adding a function to smbclient to facilitate the retrieval of a security descriptor:

def function get_security_descriptor(path, file_type: FileType = "file") -> SMB2CreateSDBuffer:
    def get_sd(fd: Open, info: int) -> SMB2CreateSDBuffer:
        """ Get the Security Descriptor for the opened file. """
        query_req = SMB2QueryInfoRequest()
        query_req['info_type'] = InfoType.SMB2_0_INFO_SECURITY
        query_req['output_buffer_length'] = 65535
        query_req['additional_information'] = info
        query_req['file_id'] = fd.file_id

        req = fd.connection.send(query_req, sid=fd.tree_connect.session.session_id, tid=fd.tree_connect.tree_connect_id)
        resp = fd.connection.receive(req)
        query_resp = SMB2QueryInfoResponse()
        query_resp.unpack(resp['data'].get_value())

        security_descriptor = SMB2CreateSDBuffer()
        security_descriptor.unpack(query_resp['buffer'].get_value())

        return security_descriptor

    with smbclient.open_file(
        path,
        mode='rb',
        buffering=0,
        file_type=file_type,
        desired_access=FilePipePrinterAccessMask.READ_CONTROL
    ) as file:
        return get_sd(file.fd, InfoAdditionalInformation.OWNER_SECURTIY_INFORMATION | InfoAdditionalInformation.DACL_SECURITY_INFORMATION)

[jborean93]

I'm not strictly against this idea but some additional thoughts around a possible implementation

We shouldn't return the SMB2CreateSDBuffer object, instead we should create a dataclass or named tuple that exposes the values in an easier and Pythonic API - see liststreams.

@dataclasses.dataclass(frozen=True)
class ACE:
    ace_type: AceType
    ace_flags: AceFlags
    mask: int
    sid: str

@dataclasses.dataclass(frozen=True)
class SecurityDescriptor:
    owner: str | None
    group: str | None
    dacl: list[ACE] | None
    sacl: list[ACE] | None

While we've been using namedtuple I think a frozen dataclass might be better today but not set on the idea. The reason for doing this is that the structures.py types aren't easy to use for end users and it ultimately opens up a lower level API we will be on the hook to maintain if we ever decide to try and get rid of it. By defining our own structures we move the public API away from the lower level one into something that's more easily maintained.

The method should also expose a way to request what SD parts we want (the InfoAdditionalInformation) values so that we can just request the owner, dacl, etc.

While it does not have to be implemented at the same time we will also need to consider what the set_sd like API would look like. Ideally it would access the same types as what get_sd returns but I haven't thought too much around that.

This does end up being a lot more code and it makes me think that maybe it should be part of it's own file like smbclient.sd or smbclient.security instead putting it within _os.py.

Finally the biggest blocker for implementing this in my mind is the fact that we are dealing with raw SID strings. There's no mechanism in SMB that we can use to translate those SIDs into human readable account/group names so it would require some external mapping implementation for the user to implement to make this really usable.

[orthose]

Thank you very much for this very detailed response. I’ve given it some thought, and I’m wondering what the use case for such a feature would be. If it’s simply to check whether a user has permission to access a file or a directory on a NAS, they might as well try to connect to it directly and let the NAS-side permission system handle it. Otherwise, it would essentially amount to reimplementing the permission system, which would likely be a waste of time.

On my side, I managed to translate SIDs into LDAP objects using the ldap3 library, but I’m not sure whether this feature should be included in smbprotocol—in which case this dependency would need to be used.

[jborean93]

Another use case would potentially be reporting but I would agree it's easier to just try and open the file or do the action needed and handle the exception if that's desired. It's hard to tell what people might use these types of APIs for but ultimately I don't want to commit to something that is limited in scope or is half baked as now I'll be on the hook for maintaining it as a public API going forward.

On my side, I managed to translate SIDs into LDAP objects using the ldap3 library, but I’m not sure whether this feature should be included in smbprotocol—in which case this dependency would need to be used.

Setting the SD could be useful if the account names could be translated to/from the SIDs but as SMB itself doesn't provide a way to do so then I wouldn't be in favour of adding a dependency on another protocol which would then have to deal with authentication and the like separately.

There is an RPC call LsarLookupSids2 which according to the protocol documentation can be used over SMB through the lsarpc named pipe. This is a pretty big undertaking and I'm not even sure if it'll handle things like resolving domain accounts or if it's just local SIDs.

Ultimately there's nothing stopping someone from translating the values themselves outside of this library as well using whatever mechanism they want.