ProtectKeyWithTPMAndStartupKey method of the Win32_EncryptableVolume class

The ProtectKeyWithTPMAndStartupKey method of the Win32_EncryptableVolume class secures the volume's encryption key by using the Trusted Platform Module (TPM) Security Hardware on the computer, if available, enhanced by an external key that must be presented to the computer at startup.

Both validation by the TPM and input of a USB memory device that contains the external key are necessary to access the volume's encryption key and unlock the volume contents. Use the SaveExternalKeyToFile method to save this external key to a file on a USB memory device for usage as a startup key.

This method is only applicable for the volume that contains the currently running operating system.

A key protector of type "TPM And Startup Key" is created for the volume, if one does not already exist.

Syntax

uint32 ProtectKeyWithTPMAndStartupKey(
  [in, optional] string FriendlyName,
  [in, optional] uint8  PlatformValidationProfile[],
  [in, optional] uint8  ExternalKey[],
  [out]          string VolumeKeyProtectorID
);

Parameters

FriendlyName [in, optional]

Type: string

A user-assigned string identifier for this key protector. If this parameter is not specified, a blank value is used.

PlatformValidationProfile [in, optional]

Type: uint8[]

An array of integers that specifies how the computer's Trusted Platform Module (TPM) Security Hardware secures the encryption key of the disk volume.

A platform validation profile consists of a set of Platform Configuration Register (PCR) indices ranging from 0 to 23, inclusive. Repeat values in the parameter are ignored. Each PCR index is associated with services that run when the operating system starts. Each time the computer starts, the TPM will check that the services you specified in the platform validation profile have not changed. If any of these services change while BitLocker Drive Encryption (BDE) protection remains on, the TPM will not release the encryption key to unlock the disk volume, and the computer will enter into recovery mode.

If this parameter is specified while the corresponding Group Policy setting has been enabled, it must match the Group Policy setting.

If this parameter is not specified, the default of 0, 2, 4, 5, 8, 9, 10, and 11 is used. The default platform validation profile secures the encryption key against changes to the following elements:

• Core Root of Trust of Measurement (CRTM)
• BIOS
• Platform Extensions (PCR 0)
• Option ROM Code (PCR 2)
• Master Boot Record (MBR) Code (PCR 4)
• Master Boot Record (MBR) Partition Table (PCR 5)
• NTFS Boot Sector (PCR 8)
• NTFS Boot Block (PCR 9)
• Boot Manager (PCR 10)
• BitLocker Access Control (PCR 11)

For the security of your computer, we recommend the default profile. For additional protection against early startup configuration changes, use a profile of PCRs 0, 1, 2, 3, 4, 5, 8, 9, 10, 11. Unified Extensible Firmware Interface (UEFI)–based computers do not use PCR 5 by default.

Changing from the default profile affects the security and manageability of your computer. The sensitivity of BitLocker to platform modifications (malicious or authorized) is increased or decreased depending upon the inclusion or exclusion, respectively, of the PCRs. For BitLocker protection to be enabled, the platform validation profile must include PCR 11.

Value	Meaning
0	Core Root of Trust of Measurement (CRTM), BIOS, and Platform Extensions
1	Platform and Motherboard Configuration and Data
2	Option ROM Code
3	Option ROM Configuration and Data
4	Master Boot Record (MBR) Code
5	Master Boot Record (MBR) Partition Table
6	State Transition and Wake Events
7	Computer Manufacturer-Specific
8	NTFS Boot Sector
9	NTFS Boot Block
10	Boot Manager
11	BitLocker Access Control
12	Defined for use by the static operating system
13	Defined for use by the static operating system
14	Defined for use by the static operating system
15	Defined for use by the static operating system
16	Used for debugging
17	Dynamic CRTM
18	Platform defined
19	Used by a trusted operating system
20	Used by a trusted operating system
21	Used by a trusted operating system
22	Used by a trusted operating system
23	Application support

 

ExternalKey [in, optional]

Type: uint8[]

An array of bytes that specifies the 256-bit external key used to unlock the volume when the computer starts.

If no external key is specified, one is randomly generated. Use the GetKeyProtectorExternalKey method to obtain the randomly generated key.

VolumeKeyProtectorID [out]

Type: string

A string that is the unique identifier associated with the created key protector that can be used to manage the key protector.

If the drive supports hardware encryption and BitLocker has not taken band ownership, the ID string is set to "BitLocker" and the key protector is written to per band metadata.

Return value

Type: uint32

This method returns one of the following codes or another error code if it fails.

Security Considerations

For the security of your computer, we recommend the default profile. For additional protection against early startup code changes, use a profile of PCRs 0, 2, 4, 5, 8, 9, 10, and 11. For additional protection against early startup configuration changes, use a profile of PCRs 0, 1, 2, 3, 4, 5, 8, 9, 10, 11.

Changing from the default profile affects the security or usability of your computer.

Remarks

At most one key protector of type "TPM And Startup Key" can exist for a volume at any time. If you want to change the display name or the platform validation profile used by an existing "TPM plus Startup Key" key protector, you must first remove the existing key protector and then call ProtectKeyWithTPMAndStartupKey to create a new one. Additional key protectors should be specified to unlock the volume in recovery scenarios where access to the volume's encryption key cannot be obtained; for example, when the TPM cannot successfully validate against the platform validation profile or when USB memory that contains the external key is lost.

Use ProtectKeyWithExternalKey or ProtectKeyWithNumericalPassword to create one or more key protectors for recovering an otherwise locked volume.

While it is possible to have both a key protector of the type "TPM" and another of the type "TPM And Startup Key", the presence of the "TPM" key protector type negates the effects of other TPM-based key protectors.

Managed Object Format (MOF) files contain the definitions for Windows Management Instrumentation (WMI) classes. MOF files are not installed as part of the Windows SDK. They are installed on the server when you add the associated role by using the Server Manager. For more information about MOF files, see Managed Object Format (MOF).

Requirements

See also

Win32_EncryptableVolume

Win32_Tpm