Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

ProtectKeyWithTPM method of the Win32_EncryptableVolume class

The ProtectKeyWithTPM 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.

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

This method is only applicable for the volume that contains the currently running operating system, and if a key protector does not already exist on the volume.

Syntax


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

Parameters

FriendlyName [in, optional]

Type: string

A string that specifies 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 disk volume's encryption key.

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 Core Root of Trust of Measurement (CRTM), BIOS, and Platform Extensions (PCR 0), Option ROM Code (PCR 2), the Master Boot Record (MBR) Code (PCR 4), the Master Boot Record (MBR) Partition Table (PCR 5), the NTFS Boot Sector (PCR 8), the NTFS Boot Code (PCR 9), the Boot Manager (PCR 10), and the BitLocker Drive Encryption Access Control (PCR 11). For the security of your computer, we recommend the default profile. Unified Extensible Firmware Interface (UEFI)–based computers do not use PCR 5 by default. 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 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.

ValueMeaning
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 Code

10

Boot Manager

11

BitLocker Drive Encryption 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 trusted operating system

20

Used by trusted operating system

21

Used by trusted operating system

22

Used by trusted operating system

23

Application support

 

VolumeKeyProtectorID [out]

Type: string

A string that uniquely identifies the created protector and which 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.

Return code/valueDescription
S_OK
0 (0x0)

The method was successful.

FVE_E_LOCKED_VOLUME
2150694912 (0x80310000)

The volume is locked.

TBS_E_SERVICE_NOT_RUNNING
2150121480 (0x80284008)

No compatible TPM is found on this computer.

FVE_E_FOREIGN_VOLUME
2150694947 (0x80310023)

The TPM cannot secure the volume's encryption key because the volume does not contain the currently running operating system.

E_INVALIDARG
2147942487 (0x80070057)

The PlatformValidationProfile parameter is provided but its values are not within the known range, or it does not match the Group Policy setting currently in effect.

 

Security Considerations

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.

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

Remarks

At most one key protector of type "TPM" 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" key protector, you must first remove the existing key protector and then call ProtectKeyWithTPM to create a new one.

For PCR indices 0 through 5, the current measurements in the registers are used to protect the encryption key. For PCR values 8 through 11, the measurements used are the ones expected to exist on the next start cycle.

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. Use ProtectKeyWithExternalKey or ProtectKeyWithNumericalPassword to create one or more key protectors for recovering an otherwise locked volume.

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

Minimum supported client

Windows Vista Enterprise, Windows Vista Ultimate [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Namespace

\\.\root\CIMV2\Security\MicrosoftVolumeEncryption

MOF

Win32_encryptablevolume.mof

See also

Win32_EncryptableVolume
Win32_Tpm

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.