Win32_EncryptableVolume Class

The Win32_EncryptableVolume WMI provider class represents an area of storage on a hard disk that can be protected by using BitLocker Drive Encryption. Only NTFS volumes can be encrypted. It can be a volume that contains an operating system, or it can be a data volume on the local disk. It cannot be a network drive.

To realize the benefits of BitLocker, you must specify a protection method for the volume's encryption key and then fully encrypt the volume.

To protect the volume's encryption key, add key protectors by using these methods:

Each type of key protector provides a different authentication experience for unlocking access to the encrypted data. External keys and numerical passwords can provide authentication during recovery scenarios. For TPM-based key protectors, you may first need to properly initialize the TPM. For more information, see the Win32_Tpm WMI provider class.

Use the Encrypt or EncryptAfterHardwareTest method to begin encryption. Key protectors must be added prior to starting the encryption, or else you must use the DisableKeyProtectors method to expose an unprotected clear key. If the computer turns off while encryption is in progress, encryption will automatically resume when the computer restarts.

You can use the GetConversionStatus and GetProtectionStatus methods to check on the status of an accessible volume.

Syntax

class Win32_EncryptableVolume
{
  string DeviceID;
  string PersistentVolumeID;
  string DriveLetter;
  uint32 ProtectionStatus;
};

Methods

The Win32_EncryptableVolume class defines the following methods.

MethodDescription

BackupRecoveryInformationToActiveDirectory

Removes all external keys and related information saved onto the currently running operating system volume that are used to automatically unlock data volumes.

ChangeExternalKey

Changes the external key associated with an encrypted volume.

ChangePassphrase

Uses the new passphrase to obtain a new derived key.

ChangePIN

Changes a PIN associated with an encrypted volume.

ClearAllAutoUnlockKeys

Removes all external keys and related information saved onto the currently running operating system volume that are used to automatically unlock data volumes.

Decrypt

Begins decryption of a fully encrypted volume or resumes decryption of a partially encrypted volume.

DeleteKeyProtector

Deletes a given key protector for the volume.

DeleteKeyProtectors

Deletes all key protectors for the volume.

DisableAutoUnlock

Removes the external key saved on the currently running operating system volume so that the volume is not automatically unlocked when it is mounted.

DisableKeyProtectors

Disables all key protectors associated with this volume.

EnableAutoUnlock

Allows a data volume to be automatically unlocked when the volume is mounted.

EnableKeyProtectors

Enables all disabled key protectors.

Encrypt

Begins encryption of a fully decrypted volume or resumes encryption of a partially encrypted volume.

EncryptAfterHardwareTest

Begins encryption of a fully decrypted volume after a hardware test.

FindValidCertificates

Enumerates all certificates on the system that match the indicated criteria and returns a list of thumbprints.

GetConversionStatus

Indicates the status of the encryption or decryption on the volume.

GetEncryptionMethod

Indicates the encryption algorithm and key size used on the volume.

GetExternalKeyFileName

Returns the name of the file that contains the external key.

GetExternalKeyFromFile

Returns the external key from a file.

GetHardwareTestStatus

Returns status information on a hardware test.

GetIdentificationField

Returns the identifier string that is available in the volume's metadata.

GetKeyPackage

Returns information that make help salvage encrypted data when the drive is severely damaged.

GetKeyProtectorCertificate

Retrieves the public key and certificate thumbprint for a public key protector.

GetKeyProtectorExternalKey

Retrieves the external key for a given key protector of the appropriate type.

GetKeyProtectorFriendlyName

Retrieves the display name used to identify a given key protector.

GetKeyProtectorNumericalPassword

Retrieves the numerical password for a given key protector of the appropriate type.

GetKeyProtectorPlatformValidationProfile

Retrieves the platform validation profile for a given key protector of the appropriate type.

GetKeyProtectors

Lists the protectors used to secure the volume's encryption key.

GetKeyProtectorType

Indicates the type of a given key protector.

GetLockStatus

Indicates whether the contents of the volume are accessible from the currently running operating system.

GetProtectionStatus

Indicates whether the volume and its encryption key (if any) are secured.

GetVersion

Indicates the FVE metadata version of the volume.

IsAutoUnlockEnabled

Indicates whether the volume is automatically unlocked when mounted.

IsAutoUnlockKeyStored

Indicates whether there exists in the currently running operating system volume any external keys and related information that may be used to automatically unlock data volumes.

IsKeyProtectorAvailable

Indicates whether protectors are available for the volume.

IsNumericalPasswordValid

Indicates whether the numerical password meets the special format requirements.

Lock

Dismounts the volume and removes the volume's encryption key from system memory.

PauseConversion

Pauses the encryption or decryption of a volume.

PrepareVolume

Creates a BitLocker volume with the specified file system type of the discovery volume.

ProtectKeyWithCertificateFile

Validates the Enhanced Key Usage (EKU) object identifier (OID) of the provided certificate file.

ProtectKeyWithCertificateThumbprint

Validates the Enhanced Key Usage (EKU) object identifier (OID) of the provided certificate thumbprint.

ProtectKeyWithExternalKey

Secures the volume's encryption key with a 256-bit external key.

ProtectKeyWithNumericalPassword

Secures the volume's encryption key with a specially formatted 48-digit password.

ProtectKeyWithPassphrase

Uses the passphrase to obtain the derived key.

ProtectKeyWithTPM

Secures the volume's encryption key by using the Trusted Platform Module (TPM) Security Hardware on the computer, if available.

ProtectKeyWithTPMAndPIN

Secures the volume's encryption key by using the Trusted Platform Module (TPM) Security Hardware on the computer, if available, enhanced by a user-specified personal identification number (PIN) that must be provided to the computer at startup.

ProtectKeyWithTPMAndPINAndStartupKey

Secures the volume's encryption key by using the Trusted Platform Module (TPM) Security Hardware on the computer, if available, enhanced by a user-specified personal identification number (PIN) and by an external key that must be provided to the computer at startup.

ProtectKeyWithTPMAndStartupKey

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 provided to the computer at startup.

ResumeConversion

Resumes the encryption or decryption of a volume.

SaveExternalKeyToFile

Writes the external key associated with the specified volume key protector to a specified file location.

SetIdentificationField

Sets the specified identifier string in the volume's metadata.

UnlockWithCertificateFile

Uses the provided certificate file to obtain the derived key and unlock the encrypted volume.

UnlockWithCertificateThumbprint

Uses the provided certificate thumbprint to obtain the derived key and unlock the encrypted volume.

UnlockWithExternalKey

Uses a provided external key to access the contents of a data volume.

UnlockWithNumericalPassword

Uses a provided numerical password to access the contents of a data volume.

UnlockWithPassphrase

Uses the passphrase to obtain the derived key. After the derived key is calculated, the derived key is used to unlock the encrypted volume's master key.

UpgradeVolume

Upgrades a volume from the Windows Vista format to the Windows 7 format.

 

Properties

The Win32_EncryptableVolume class defines the following properties.

DeviceID
Data type: string
Access type: Read-only
Qualifiers: Key

A unique identifier for the volume on this system. Use this to associate a volume with other WMI provider classes, for example, Win32_Volume.

DriveLetter
Data type: string
Access type: Read-only

The drive letter of the volume. This identifier can be used to associate a volume with other WMI provider classes, for example Win32_Volume.

For volumes without drive letters, this value is NULL.

PersistentVolumeID
Data type: string
Access type: Read-only

A persistent identifier for the volume on this system. This identifier is exclusive to Win32_EncryptableVolume.

This identifier is an empty string if the volume is a standard fully decrypted NTFS volume; otherwise, it has a unique value.

ProtectionStatus
Data type: uint32
Access type: Read-only

The status of the volume, whether or not BitLocker is protecting the volume. This value is stored when the class is instantiated. It is possible for the protection status to change state between instantiation and when you check the value. To check the value of the ProtectionStatus property in real time, use the GetProtectionStatus method.

ValueMeaning
0

PROTECTION OFF

The volume is not encrypted, partially encrypted, or the volume's encryption key for the volume is available in the clear on the hard disk.

1

PROTECTION ON

The volume is fully encrypted and the encryption key for the volume is not available in the clear on the hard disk.

2

PROTECTION UNKNOWN

The volume protection status cannot be determined. One potential cause is that the volume is in a locked state.

 

The Win32_EncryptableVolume WMI provider class relies on the WMI namespace security and on the BitLocker Drive Encryption subsystem for access control.

To use the Win32_EncryptableVolume methods, the following conditions must be met:

To enable remote connections, remote WMI traffic must be allowed. For more information about enabling WMI traffic, see Connecting to WMI Remotely Starting with Vista.

The default namespace security setting includes an entry to allow editing by default. For more information about WMI namespace auditing, see Access to WMI Namespaces.

Remarks

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 clientWindows Vista Enterprise, Windows Vista Ultimate
Minimum supported serverWindows Server 2008
MOFWin32_encryptablevolume.mof
Namespace\\.\root\CIMV2\Security\MicrosoftVolumeEncryption

Send comments about this topic to Microsoft

Build date: 11/16/2009

Tags :


Community Content

snibchi
example c++ Win32_EncryptableVolume and Method
#define _WIN32_DCOM
#include <iostream>

using namespace std;

#include <comdef.h>
#include <Wbemidl.h>

#pragma comment(lib, "wbemuuid.lib")

BOOL wmi_run();
BOOL wmi_checkVolumeBitlocker();
BOOL wmi_close();

IWbemLocator *pLoc = NULL;
IWbemServices *pSvc = NULL;

int main(int argc, char **argv)
{
wmi_run();
wmi_checkVolumeBitlocker();
system("pause");
wmi_close();
}


//
// get Win32_EncryptableVolume Class
BOOL wmi_checkVolumeBitlocker()
{
HRESULT hres;
IEnumWbemClassObject* pEnumerator = NULL;

// get volumes
hres = pSvc->ExecQuery(
bstr_t("WQL"),
bstr_t("SELECT * FROM Win32_EncryptableVolume"),
WBEM_FLAG_FORWARD_ONLY | WBEM_FLAG_RETURN_IMMEDIATELY,
NULL,
&pEnumerator);

if (FAILED(hres)) {
cout << "Query for processes failed. "
<< "Error code = 0x"
<< hex << hres << endl;
pSvc->Release();
pLoc->Release();
CoUninitialize();
return FALSE; // Program has failed.
}

else {

IWbemClassObject *pclsObj;
ULONG uReturn = 0;

while (pEnumerator) {
hres = pEnumerator->Next(WBEM_INFINITE, 1,
&pclsObj, &uReturn);

if(0 == uReturn)
break;

VARIANT vtProp;
hres = pclsObj->Get(_bstr_t(L"DeviceID"), 0, &vtProp, 0, 0);

// out the VolumeID
printf("\nVolume: %ls\n", vtProp.bstrVal);

// fit string
wstring tmp = vtProp.bstrVal;
tmp = tmp.substr(4);
wstring wstrQuery = L"Win32_EncryptableVolume.DeviceID='\\\\?\\";
wstrQuery += tmp;
wstrQuery += L"\'";

//
// GET CONVERSION STATUS METHOD
// http://msdn.microsoft.com/en-us/library/aa376433(VS.85).aspx

IWbemClassObject *pclsObj1 = NULL;
hres = pSvc->ExecMethod(
bstr_t(wstrQuery.c_str()),
bstr_t(L"GetConversionStatus"),
0,
NULL,
NULL,
&pclsObj1,
NULL );

if ( FAILED(hres) ) {
cout << "Query for processes failed. "
<< "Error code = 0x"
<< hex << hres << endl;

pSvc->Release();
pLoc->Release();
CoUninitialize();
return FALSE; // Program has failed.
}

else {

VARIANT vtProp1;
hres = pclsObj1->Get(_bstr_t(L"ConversionStatus"), 0, &vtProp1, 0, 0);

if(hres == 2150694912)
printf("Volume is locked");

else {
printf("ConversionStatus:\t");
switch((int)vtProp1.bstrVal) {

case 0:
printf("FULLY DECRYPTED");
break;

case 1:
printf("FULLY ENCRYPTED");
break;

case 2:
printf("ENCRYPTION IN PROGRESS");
break;

case 3:
printf("DECRYPTION IN PROGRESS");
break;

case 4:
printf("ENCRYPTION PAUSED");
break;

case 5:
printf("DECRYPTION PAUSED");
break;

default:
printf("unknown");
break;
}
}
printf("\n");
VariantClear( &vtProp1 );
}

//
// GET ENCRYPTION METHOD
// http://msdn.microsoft.com/en-us/library/aa376434(VS.85).aspx

hres = pSvc->ExecMethod(
bstr_t(wstrQuery.c_str()),
bstr_t(L"GetEncryptionMethod"),
0,
NULL,
NULL,
&pclsObj1,
NULL );

if ( FAILED(hres) ) {
cout << "Query for processes failed. "
<< "Error code = 0x"
<< hex << hres << endl;
pSvc->Release();
pLoc->Release();
CoUninitialize();
return FALSE; // Program has failed.
}

else {

VARIANT vtProp1;
hres = pclsObj1->Get(_bstr_t(L"EncryptionMethod"), 0, &vtProp1, 0, 0);
printf("EncryptionMethod:\t");
switch((int)vtProp1.bstrVal) {
case 0:
printf("NONE");
break;

case 1:
printf("AES 128 WITH DIFFUSER");
break;

case 2:
printf("AES 256 WITH DIFFUSER");
break;

case 3:
printf("AES 128");
break;

case 4:
printf("AES 256");
break;

default:
printf("unknown");
break;
}
printf("\n");
VariantClear( &vtProp1 );
}
VariantClear( &vtProp );
}
pEnumerator->Release();
}
return TRUE;
}

//
// Step 1-5 at:
// http://msdn.microsoft.com/en-us/library/aa390423(VS.85).aspx
BOOL wmi_run()
{
HRESULT hres;

// Step 1: --------------------------------------------------
// Initialize COM. ------------------------------------------
hres = CoInitializeEx(0, COINIT_MULTITHREADED);

if (FAILED(hres)) {
cout << "Failed to initialize COM library. Error code = 0x"
<< hex << hres << endl;
return 1; // Program has failed.
}

// Step 2: --------------------------------------------------
// Set general COM security levels --------------------------
// Note: If you are using Windows 2000, you need to specify -
// the default authentication credentials for a user by using
// a SOLE_AUTHENTICATION_LIST structure in the pAuthList ----
// parameter of CoInitializeSecurity ------------------------
hres = CoInitializeSecurity(
NULL,
-1,
// COM authentication
NULL,
// Authentication services
NULL,
// Reserved
RPC_C_AUTHN_LEVEL_DEFAULT,
// Default authentication
RPC_C_IMP_LEVEL_IMPERSONATE,
// Default Impersonation
NULL,
// Authentication info
EOAC_NONE,
// Additional capabilities
NULL
// Reserved
);

if (FAILED( hres )) {
cout << "Failed to initialize security. Error code = 0x"
<< hex << hres << endl;
CoUninitialize();
return 1; // Program has failed.
}

// Step 3: ---------------------------------------------------
// Obtain the initial locator to WMI -------------------------
//IWbemLocator *pLoc = NULL;
hres = CoCreateInstance(
CLSID_WbemLocator,
0,
CLSCTX_INPROC_SERVER,
IID_IWbemLocator,
(LPVOID *) &pLoc);

if (FAILED( hres )) {
cout << "Failed tocreate IWbemLocator object."
<< " Err code = 0x"
<< hex << hres << endl;
CoUninitialize();
return 1; // Program has failed.
}
// Step 4: -----------------------------------------------------
// Connect to WMI through the IWbemLocator::ConnectServer method
//IWbemServices *pSvc = NULL;
// Connect to the root\cimv2 namespace with
// the current user and obtain pointer pSvc
// to make IWbemServices calls.
// Security MUST RUN AS ADMINISTRATOR
hres = pLoc->ConnectServer(
_bstr_t(L"ROOT\\CIMV2\\Security\\MicrosoftVolumeEncryption"),
// Object path of WMI namespace
NULL,
// User name. NULL = current user
NULL,
// User password. NULL = current
0,
// Locale. NULL indicates current
NULL,
// Security flags.
0,
// Authority (e.g. Kerberos)
0,
// Context object
&pSvc
// pointer to IWbemServices proxy
);

if (FAILED(hres)) {
cout << "Could not connect. Error code = 0x"
<< hex << hres << endl;
pLoc->Release();
CoUninitialize();
return 1; // Program has failed.
}
cout << "Connected to ROOT\\CIMV2 WMI namespace" << endl;

// Step 5: --------------------------------------------------
// Set security levels on the proxy -------------------------
hres = CoSetProxyBlanket(
pSvc,
// Indicates the proxy to set
RPC_C_AUTHN_WINNT,
// RPC_C_AUTHN_xxx
RPC_C_AUTHZ_NONE,
// RPC_C_AUTHZ_xxx
NULL,
// Server principal name
RPC_C_AUTHN_LEVEL_CALL,
// RPC_C_AUTHN_LEVEL_xxx
RPC_C_IMP_LEVEL_IMPERSONATE,
// RPC_C_IMP_LEVEL_xxx
NULL,
// client identity
EOAC_NONE
// proxy capabilities
);

if (FAILED(hres)) {
cout << "Could not set proxy blanket. Error code = 0x"
<< hex << hres << endl;
pSvc->Release();
pLoc->Release();
CoUninitialize();
return 1; // Program has failed.
}
return 0;
}

//
// WMI Session close
BOOL wmi_close()
{
// Cleanup
// ========
pSvc->Release();
pLoc->Release();
CoUninitialize();
return TRUE; // Program successfully completed.
}

Page view tracker