Share via

3.1.4.27 NetrpGetFileSecurity (Opnum 39)

  • Article

The NetrpGetFileSecurity method returns to the caller a copy of the security descriptor that protects a file or directory.

 DWORD NetrpGetFileSecurity(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string, unique] WCHAR* ShareName,
   [in, string] WCHAR* lpFileName,
   [in] SECURITY_INFORMATION RequestedInformation,
   [out] PADT_SECURITY_DESCRIPTOR* SecurityDescriptor
 );

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) pointer that identifies the server. The client MUST map this structure to an RPC binding handle (see [C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

ShareName: A pointer to a null-terminated UTF-16 string that specifies the share name on which the file is found.

lpFileName: A pointer to a null-terminated UTF-16 string that specifies the name of the file or directory whose security is being retrieved. The name MUST specify the full path to the file from the ShareName parameter.

RequestedInformation: The type of security information being requested, as specified in [MS-DTYP] section 2.4.7.

SecurityDescriptor: A pointer to a PADT_SECURITY_DESCRIPTOR structure, where the desired information is returned.

Return Values: The method returns 0x00000000 (NERR_Success) to indicate success; otherwise, it returns a nonzero error code. The method can take any specific error code value, as specified in [MS-ERREF] section 2.2.

In response to a NetrpGetFileSecurity message, the server MUST return to the caller a copy of the security descriptor that protects a file or directory, or return an error code. The security descriptor is always returned in the self-relative format.

The ShareName parameter specifies a local share name on the server. The server MUST locate a Share from ShareList, where ShareName matches Share.ShareName. If no share is found, the server MUST fail the call with NERR_NetNameNotFound. The server MUST then combine Share.LocalPath with the lpFileName parameter in order to create a fully qualified path name that is local to the server. If the file does not exist, the server SHOULD<104> fail the call with ERROR_FILE_NOT_FOUND. The server MUST then obtain the security descriptor with the information that the client requires, as specified in the RequestedInformation parameter, for the local file that the path name obtained specifies, and return it to the client in the out parameter SecurityDescriptor. The security descriptor itself is stored in the Buffer member of the SecurityDescriptor parameter; the length of the security descriptor is stored in the Length member.

The server SHOULD<105> enforce security measures to verify that the caller has the required permissions to execute this call. If the caller does not have the required credentials, the server SHOULD<106> fail the call.