3.1.4.2.1 Receiving an EfsRpcOpenFileRaw Message (Opnum 0)

  • Article

 

The EfsRpcOpenFileRaw method is used to open an encrypted object on the server for backup or restore. It allocates resources that MUST be released by calling the EfsRpcCloseRaw method.<42>

 long EfsRpcOpenFileRaw(
   [in] handle_t binding_h,
   [out] PEXIMPORT_CONTEXT_HANDLE* hContext,
   [in, string] wchar_t* FileName,
   [in] long Flags
 );

binding_h: An explicit binding handle created by the client. This is an RPC binding handle parameter, as specified in [C706] and [MS-RPCE] section 2.

hContext: An implementation-specific context handle that is used in subsequent calls by the client to the EfsRpcReadFileRaw method, EfsRpcWriteFileRaw method, or EfsRpcCloseRaw method.

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

Flags: This MUST be set to some combination of the following values. All servers and clients MUST support the CREATE_FOR_IMPORT flag. Servers that implement a hierarchical encrypted store, such as the NTFS file system, SHOULD also support the CREATE_FOR_DIR flag. Servers SHOULD support the OVERWRITE_HIDDEN flag, and MAY interpret it in implementation-specific ways. A client MUST ensure that all the flags it does not support are set to zero. A server MUST ignore all flags it does not support. Flag values are specified in the following table.

Value

Meaning

CREATE_FOR_IMPORT

0x00000001

Open the object for writing (that is, restore). If this flag is not set, open the object for reading (that is, backup).

CREATE_FOR_DIR

0x00000002

This flag is only intended for use in conjunction with the CREATE_FOR_IMPORT flag. It indicates that the object being restored is a container for other objects.<43>

OVERWRITE_HIDDEN

0x00000004

This flag is only intended for use in conjunction with the CREATE_FOR_IMPORT flag. This flag indicates a request from the client for the server to overwrite an existing object even if the existing object is "hidden". The meaning of "hidden" is specific to the implementation of the data store, and this meaning does not affect protocol behavior.

EFS_DROP_ALTERNATE_STREAMS  

0x00000010

This flag indicates that content from any alternate data streams, if present and implemented by the storage system, will be ignored.

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.

First, the server SHOULD perform any additional access checks prescribed by the implementation. If any of these checks fail, it MUST return a nonzero value.

EFSRPC servers SHOULD return an error unless at least one of the following conditions is true:

  • The calling user has a private key that grants the user authorized access to the file.

  • The CREATE_FOR_IMPORT flag is set, and the user has restore rights on the server.

  • The CREATE_FOR_IMPORT flag is not set, and the user has backup rights on the server.

If the CREATE_FOR_IMPORT flag is set, the server MUST attempt to create an object with the given name and prepare it for writing data received in future EfsRpcWriteFileRaw calls. The server MUST return a nonzero value if this fails.

If the CREATE_FOR_IMPORT flag is not set, the server MUST attempt to locate the object requested and prepare it for reading data to be sent through future EfsRpcReadFileRaw calls. The server MUST return a nonzero value if it fails.

If the server supports the CREATE_FOR_DIR flag, and this flag is set:

  • If the CREATE_FOR_IMPORT flag is not set:

    • If the data object referred to by FileName exists on the server and is not a container for other objects, the server SHOULD return a nonzero value.

    • Otherwise, the server SHOULD ignore the CREATE_FOR_DIR flag.

  • If the CREATE_FOR_IMPORT flag is set, the server MUST attempt to create a container with the given name and prepare it for writing data received in future EfsRpcWriteFileRaw calls. The server MUST return a nonzero value if this fails.

If the server supports the OVERWRITE_HIDDEN flag, and this flag is set:

  • If the CREATE_FOR_IMPORT flag is not set, the server SHOULD ignore this flag.

  • If the CREATE_FOR_IMPORT flag is set, the server SHOULD overwrite an existing object even if the object is "hidden". The meaning of "hidden" is specific to the implementation of the data store, and this meaning does not affect protocol behavior.

The server MUST ignore any flags that it does not support.

On success, the server MUST create an appropriate context handle and return it to the client.