Share via

3.1.4.2.14 Receiving an EfsRpcAddUsersToFileEx Message (Opnum 15)

  • Article

The EfsRpcAddUsersToFileEx method is used to grant the possessors of the private keys corresponding to certain X.509 certificates the ability to decrypt the object.

 DWORD EfsRpcAddUsersToFileEx(
   [in] handle_t binding_h,
   [in] DWORD dwFlags,
   [in, unique] EFS_RPC_BLOB* Reserved,
   [in, string] wchar_t* FileName,
   [in] ENCRYPTION_CERTIFICATE_LIST* EncryptionCertificates
 );

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

dwFlags: This MUST be set to a bitwise OR of 0 or more of the following flags. The descriptions of the flags are specified in the following table. If the EFSRPC_ADDUSERFLAG_REPLACE_DDF flag is used, then the EncryptionCertificates parameter MUST contain exactly one certificate.

Name

Value

EFSRPC_ADDUSERFLAG_ADD_POLICY_KEYTYPE

0x00000002

EFSRPC_ADDUSERFLAG_REPLACE_DDF

0x00000004

Reserved: This parameter is not used. It MUST be set to NULL by the client and ignored by the server.

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

EncryptionCertificates: A list of certificates, represented by an ENCRYPTION_CERTIFICATE_LIST structure, which are to be given access to the object.

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, or if it exists and is not encrypted, the server MUST return a nonzero value.

If the EFSRPC_ADDUSERFLAG_REPLACE_DDF flag is set in the dwFlags parameter, and the EncryptionCertificates parameter contains more than one certificate, the server MUST return a nonzero value.

If the EFSRPC_ADDUSERFLAG_REPLACE_DDF flag is set in the dwFlags parameter, and the calling user does not have the ability to decrypt the object, the server MUST return a nonzero value.

If the EFSRPC_ADDUSERFLAG_REPLACE_DDF flag is set in the dwFlags parameter, and the user certificate in the EncryptionCertificates parameter already has access to the object, then the server MUST return a zero value.

If the EFSRPC_ADDUSERFLAG_ADD_POLICY_KEYTYPE flag is specified in the dwFlags parameter, then for each certificate specified in the EncryptionCertificates parameter, the server MUST check whether the private key for the certificate is stored on a smart card. If the key is stored, the server MUST return a nonzero value; otherwise, the server MUST ignore this flag.

If the EFSRPC_ADDUSERFLAG_REPLACE_DDF flag is set in the dwFlags parameter, and the calling user has the ability to decrypt the object, then the certificate in the EncryptionCertificates parameter is to be given access to the object, replacing one of the calling user's user certificates through which he currently has access.