Share via

3.1.4.2 EFSRPC Interface

  • Article

This protocol MUST instruct the RPC runtime to perform a strict NDR data consistency check at target level 6.0, as specified in [MS-RPCE] section 3.

This protocol MUST indicate to the RPC runtime that it is to support both NDR and NDR64 transfer syntaxes, in addition to the negotiation mechanism that determines which transfer syntax will be used, as described in [MS-RPCE] section 3.

This protocol MUST instruct the RPC runtime to reject a NULL unique or full pointer with a nonzero-conforming value, as defined in [MS-RPCE] section 3.

The server SHOULD use the RPC protocol to retrieve the identity of the caller, as described in [MS-RPCE] section 3.3.3.4.3, and to enforce appropriate security measures to ensure that the caller has required permissions to execute the following routines. If the caller does not have the required permissions to execute a specific method, the server SHOULD fail the method call with ERROR_ACCESS_DENIED (specified in [MS-ERREF]).

This subsection specifies the syntax of the methods specified by the EFSRPC protocol and how to receive each one. These calls are received at the well-known endpoint of the named pipe \pipe\lsarpc or \pipe\efsrpc. The server interface for \pipe\lsarpc MUST be identified by UUID [c681d488-d850-11d0-8c52-00c04fd90f7e], version 1.0. The server interface for \pipe\efsrpc MUST be identified by UUID [df1941c5-fe89-4e79-bf10-463657acf44d], version 1.0.<36>

The following table specifies the opnum associated with each RPC method in this protocol. An EFSRPC server SHOULD support all of the methods specified in this table.<37><38>

Methods in RPC Opnum Order

Method

Description

EfsRpcOpenFileRaw

Used to open an encrypted object on the server for backup or restore.

Opnum: 0

EfsRpcReadFileRaw

Used by a client to obtain marshaled data for an encrypted object from the server.

Opnum: 1

EfsRpcWriteFileRaw

Used to create an encrypted object on the server, from marshaled data provided by the client.

Opnum: 2

EfsRpcCloseRaw

Called to release any resources allocated by the EfsRpcOpenFileRaw method, or by subsequent calls to the EfsRpcReadFileRaw or EfsRpcWriteFileRaw methods.

Opnum: 3

EfsRpcEncryptFileSrv

Used to convert a given object on the server to an encrypted state in the server's data store.

Opnum: 4

EfsRpcDecryptFileSrv

Used to convert an existing encrypted object to the plaintext state in the server's data store.

Opnum: 5

EfsRpcQueryUsersOnFile

Used by the client to query the metadata of an encrypted object for the X.509 certificates whose associated private keys can be used to decrypt the object.

Opnum: 6

EfsRpcQueryRecoveryAgents

Used to query the object's metadata for the X.509 certificates of the data recovery agents whose associated private keys can be used to decrypt it.

Opnum: 7

EfsRpcRemoveUsersFromFile

Used to revoke a user's access to an encrypted object. This method revokes the ability of the private key corresponding to a given X.509 certificate to decrypt the object.

Opnum: 8

EfsRpcAddUsersToFile

Used to grant users the ability to decrypt the object with their X.509 certificates.

Opnum: 9

Opnum10NotUsedOnWire

Reserved for local use.

Opnum: 10

EfsRpcNotSupported

Deprecated. Used to act in an identical manner to EfsRpcDuplicateEncryptionInfoFile (3.1.4.2.13).

Opnum: 11

EfsRpcFileKeyInfo

Used to query and modify information about the keys used to encrypt a given object.

Opnum: 12

EfsRpcDuplicateEncryptionInfoFile

Used to duplicate the EFSRPC Metadata of one object and attach it to another object.

Opnum: 13

Opnum14NotUsedOnWire

Reserved for local use.

Opnum: 14

EfsRpcAddUsersToFileEx

Used to grant users the ability to decrypt an object using an X.509 certificate.

Opnum: 15

EfsRpcFileKeyInfoEx

Deprecated. Used to act similarly to EfsRpcFileKeyInfo, except for the dwFileKeyInfoFlags and Reserved parameters.

Opnum: 16

Opnum17NotUsedOnWire

Reserved for local use.

Opnum: 17

EfsRpcGetEncryptedFileMetadata

Deprecated. Used to retrieve the EFSRPC Metadata associated with an object.

Opnum: 18

EfsRpcSetEncryptedFileMetadata

Deprecated. Used to set the EFSRPC Metadata on an object.

Opnum: 19

EfsRpcFlushEfsCache

Causes EFS to flush the logical cache that holds all the sensitive information required to perform EFSRPC operations for the calling user.

Opnum: 20

EfsRpcEncryptFileExSrv

Used to convert a given object on the server to an encrypted state in the server's data store. Allows use of DPAPI-NG and EFSRPC Metadata Version 3.

Opnum: 21

EfsRpcQueryProtectors

Used by the client to query the metadata of an encrypted object for the DPAPI-NG protectors or RMS templates whose associated private keys can be used to decrypt the object.

Opnum: 22

Opnum23NotUsedOnWire

Reserved for local use.

Opnum: 23

Opnum24NotUsedOnWire

Reserved for local use.

Opnum: 24

Opnum25NotUsedOnWire

Reserved for local use.

Opnum: 25

Opnum26NotUsedOnWire

Reserved for local use.

Opnum: 26

Opnum27NotUsedOnWire

Reserved for local use.

Opnum: 27

Opnum28NotUsedOnWire

Reserved for local use.

Opnum: 28

Opnum29NotUsedOnWire

Reserved for local use.

Opnum: 29

Opnum30NotUsedOnWire

Reserved for local use.

Opnum: 30

Opnum31NotUsedOnWire

Reserved for local use.

Opnum: 31

Opnum32NotUsedOnWire

Reserved for local use.

Opnum: 32

Opnum33NotUsedOnWire

Reserved for local use.

Opnum: 33

Opnum34NotUsedOnWire

Reserved for local use.

Opnum: 34

Opnum35NotUsedOnWire

Reserved for local use.

Opnum: 35

Opnum36NotUsedOnWire

Reserved for local use.

Opnum: 36

Opnum37NotUsedOnWire

Reserved for local use.

Opnum: 37

Opnum38NotUsedOnWire

Reserved for local use.

Opnum: 38

Opnum39NotUsedOnWire

Reserved for local use.

Opnum: 39

Opnum40NotUsedOnWire

Reserved for local use.

Opnum: 40

Opnum41NotUsedOnWire

Reserved for local use.

Opnum: 41

Opnum42NotUsedOnWire

Reserved for local use.

Opnum: 42

Opnum43NotUsedOnWire

Reserved for local use.

Opnum: 43

Opnum44NotUsedOnWire

Reserved for local use.

Opnum: 44

In the previous table, the term "Reserved for local use" means that the client MUST NOT send the opnum, and the server behavior is undefined<39> because it does not affect interoperability. When a method marked as "Deprecated" is received, the server SHOULD ignore the parameters of the method and return a nonzero value.<40>

All methods in this protocol MUST return 0 on success, and a nonzero value on failure. Servers SHOULD use the values specified in [MS-ERREF] for all nonzero error codes. The client MUST treat all nonzero return values identically.

When the server receives a message from an EFSRPC client, it SHOULD first check the value of the EfsDisabled field. If it is True, the server SHOULD<41> return ERROR_EFS_DISABLED (specified in [MS-ERREF]) and perform no further processing. Otherwise, it SHOULD perform any necessary steps to read its configuration, validate its input parameters (such as any EFSRPC identifiers that refer to local data objects), authenticate the client, and perform any access checks prescribed by the implementation.

This protocol MUST indicate to the RPC runtime by way of the strict_context_handle attribute that it is to reject use of context handles created by a method of an RPC interface other than this one, as specified in [MS-RPCE] section 3.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].