Share via

3.1.4.1 BackuprKey(Opnum 0)

  • Article

This section specifies the BackuprKey method.

 NET_API_STATUS BackuprKey(
   [in] handle_t h,
   [in] GUID* pguidActionAgent,
   [in, size_is(cbDataIn)] byte* pDataIn,
   [in] DWORD cbDataIn,
   [out, size_is(,*pcbDataOut)] byte** ppDataOut,
   [out] DWORD* pcbDataOut,
   [in] DWORD dwParam
 );

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

pguidActionAgent: A GUID RPC structure, as specified in [MS-DTYP] section 2.3.4. This MUST be set to one of the following values. The BACKUPKEY_BACKUP_GUID and BACKUPKEY_RESTORE_GUID_WIN2K values indicate the ServerWrap subprotocol, while the BACKUPKEY_RETRIEVE_BACKUP_KEY_GUID and BACKUPKEY_RESTORE_GUID values indicate the ClientWrap subprotocol. A server MUST support at least one of these subprotocols completely, and all server implementations SHOULD support all four values. In addition, if a server supports the wrapping operation of either subprotocol, it MUST also support the corresponding unwrap operation. Thus, if a server supports BACKUPKEY_BACKUP_GUID, then it MUST also support BACKUPKEY_RESTORE_GUID_WIN2K. Similarly, if a server supports BACKUPKEY_RETRIEVE_BACKUP_KEY_GUID, it MUST also support BACKUPKEY_RESTORE_GUID.<9>

Value

Meaning

BACKUPKEY_BACKUP_GUID

7F752B10-178E-11D1-AB8F-00805F14DB40

Requests server-side wrapping. On input, pDataIn MUST point to a BLOB containing the secret to be wrapped. The server MUST treat pDataIn as opaque binary data. On output, ppDataOut MUST contain the wrapped secret in the format specified in section 2.2.4. For details, see section 3.1.4.1.1.

BACKUPKEY_RESTORE_GUID_WIN2K

7FE94D50-178E-11D1-AB8F-00805F14DB40

Requests unwrapping of a server-side-wrapped secret. On input, pDataIn MUST point to a BLOB containing the wrapped key, in the format specified in section 2.2.4. On output, ppDataOut MUST contain a pointer to the unwrapped secret, as supplied by the client to the BACKUPKEY_BACKUP_GUID call. For details, see section 3.1.4.1.2.

BACKUPKEY_RETRIEVE_BACKUP_KEY_GUID

018FF48A-EABA-40C6-8F6D-72370240E967

Requests the public key part of the server's ClientWrap key pair. The server MUST ignore the pDataIn and cbDataIn parameters. On output, ppDataOut MUST contain a pointer to the server's public key in the format specified in section 2.2.1. For details, see section 3.1.4.1.3.

BACKUPKEY_RESTORE_GUID

47270C64-2FC7-499B-AC5B-0E37CDCE899A

Request unwrapping of a secret that was client-side-wrapped with the server's public key. On input, pDataIn MUST point to a client-side wrapped key, formatted as specified in section 2.2.2. On output, ppDataOut MUST contain a pointer to the unwrapped secret, formatted as specified in section 2.2.3. For details, see section 3.1.4.1.4.

pDataIn: This is the input data supplied by the client. Its format depends on pguidActionAgent as specified in this section.

cbDataIn: This MUST be an unsigned 32-bit integer, encoded in little-endian format. It MUST be equal to the length, in bytes, of the data supplied in pDataIn.

ppDataOut: This is the output data returned to the client. Its format depends on pguidActionAgent as specified in this section.

pcbDataOut: This MUST be an unsigned 32-bit integer, encoded in little-endian format. It MUST be equal to the length, in bytes, of the data returned in pDataOut.

dwParam: This parameter is unused. It MUST be ignored by the server.

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

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

Upon receiving a BackuprKey message, the server MUST check the pguidActionAgent parameter. If the server does not support the value specified for this parameter, the server MUST return ERROR_INVALID_PARAMETER (0x57). Otherwise, the server MUST continue processing as specified in the appropriate subsection below.