3.1.4.2.12 Receiving an EfsRpcFileKeyInfo Message (Opnum 12)

The EfsRpcFileKeyInfo method is used to query and modify information about the keys used to encrypt a given object.

 DWORD EfsRpcFileKeyInfo(
   [in] handle_t binding_h,
   [in, string] wchar_t* FileName,
   [in] DWORD InfoClass,
   [out] EFS_RPC_BLOB** KeyInfo
 );

binding_h: This is an RPC binding handle parameter, as specified in [C706] and [MS-RPCE] section 2.

FileName: An EFSRPC identifier, as specified in section 2.2.1.

InfoClass: One of the values in the following table. With the exception of UPDATE_KEY_USED (0x00000100), a server SHOULD support all of these values. A server MAY choose to support UPDATE_KEY_USED.<46>

Value	Meaning
BASIC_KEY_INFO 0x00000001	Request information about the keys used to encrypt the object's contents. On success, the server will return the information in an EFS_KEY_INFO (2.2.14)structure in the KeyInfo parameter.
CHECK_COMPATIBILITY_INFO 0x00000002	Requests the EfsVersion for the encrypted file. On success, the server will return the information in an EFS_COMPATIBILITY_INFO structure in the KeyInfo parameter.
UPDATE_KEY_USED 0x00000100	Update the user certificates used to give a specific user access to an object. The server will populate the KeyInfo parameter with a zero-terminated, wide character Unicode string that contains a newline-separated list of names of objects successfully updated.
CHECK_DECRYPTION_STATUS 0x00000200	Request a hint from the server as to whether the given object could be successfully decrypted without further user intervention or higher-level events. The server will return this information in an EFS_DECRYPTION_STATUS_INFO structure in the KeyInfo parameter.
CHECK_ENCRYPTION_STATUS 0x00000400	Request a hint from the server as to whether the given object could be successfully encrypted without further user intervention or higher-level events. The server will return this information in an EFS_ENCRYPTION_STATUS_INFO structure in the KeyInfo parameter.

KeyInfo: Returned by the server, as previously specified.

Return Values: The server MUST return 0 if it successfully processes the message received from the client. The server MUST return a nonzero value if processing fails.

If no object exists on the server with the specified name the server MUST return a nonzero value.

If the InfoClass parameter is not equal to CHECK_ENCRYPTION_STATUS and the object with the specified name is not encrypted, the server MUST return a nonzero value.

If the value in the InfoClass parameter is unsupported by the server, the server MUST return a nonzero value.

If the value in the InfoClass parameter is equal to BASIC_KEY_INFO, the server SHOULD read the EFSRPC Metadata of the object referred to by the FileName argument and return information about its FEK in an EFS_KEY_INFO structure within the KeyInfo argument.

If the value in the InfoClass parameter is equal to UPDATE_KEY_USED, the implementation supports this value, and the FileName parameter does not satisfy the implementation-specific requirements for this operation<47>, the server MUST return a nonzero value.

If the value in the InfoClass parameter is equal to UPDATE_KEY_USED, the implementation supports this value, and the FileName parameter does satisfy all implementation-specific requirements, the server MUST update the EFSRPC Metadata of all the data objects referred by FileName in an implementation-specific way<48>, and return a newline-separated list of EFSRPC Identifiers thus updated in the KeyInfo parameter.

If the value in the InfoClass parameter is equal to CHECK_ENCRYPTION_STATUS, the server MUST return an EFS_ENCRYPTION_STATUS_INFO structure in the KeyInfo parameter, which provides a hint to the client what error code would be returned if encryption was attempted on this object without any further user interaction or higher-level events.

If the value in the InfoClass parameter is equal to CHECK_DECRYPTION_STATUS, the server SHOULD return ERROR_REQUIRES_INTERACTIVE_WINDOWSTATION ([MS-ERREF] section 2.2). The server MAY, instead, return an EFS_DECRYPTION_STATUS_INFO structure in the KeyInfo parameter, which provides a hint to the client what error code would be returned if decryption were attempted on this object without any further user interaction or higher-level events.

If the value of the InfoClass parameter is equal to CHECK_COMPATIBILITY_INFO, the server MUST return an EFS_COMPATIBILITY_INFO structure in the KeyInfo parameter, which provides the EFSVersion of the EFSRPC metadata associated with the file.