Win32_EncryptableVolume class
Applies to: desktop apps only
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:
- ProtectKeyWithCertificateFile
- ProtectKeyWithCertificateThumbprint
- ProtectKeyWithExternalKey
- ProtectKeyWithNumericalPassword
- ProtectKeyWithPassphrase
- ProtectKeyWithTPM
- ProtectKeyWithTPMAndPIN
- ProtectKeyWithTPMAndPINAndStartupKey
- ProtectKeyWithTPMAndStartupKey
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;
};
Members
The Win32_EncryptableVolume class has these types of members:
Methods
The Win32_EncryptableVolume class has these methods.
| Method | Description |
|---|---|
| BackupRecoveryInformationToActiveDirectory |
Saves all external keys and related information that is needed for recovery to the Active Directory. |
| 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 has these 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.
Value Meaning - 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.
Security Considerations
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:
- You must have administrator privileges.
- Connection encryption must be able to connect to the provider.
For more information about creating an encrypted connection, see Requiring an Encrypted Connection to a Namespace.
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 client | Windows Vista Enterprise, Windows Vista Ultimate |
|---|---|
|
Minimum supported server | Windows Server 2008 |
|
Namespace |
\\.\root\CIMV2\Security\MicrosoftVolumeEncryption |
|
MOF |
|
Send comments about this topic to Microsoft
Build date: 2/3/2012
- 4/21/2012
- bptdev
strComputer = "."
Set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\CIMV2\Security\MicrosoftVolumeEncryption")
Set colItems = objWMIService.ExecQuery("SELECT * FROM Win32_EncryptableVolume",,48)
Dim arEncryptionMethod
arEncryptionMethod = Array("None", "AES 128 With Diffuser", "AES 256 With Diffuser", "AES 128", "AES 256")
Dim arProtectionStatus
arProtectionStatus = Array("Protection Off", "Protection On", "Protection Unknown")
Dim arConversionStatus
arConversionStatus = Array("Fully Decrypted", "Fully Encrypted", "Encryption In Progress", "Decryption In Progress", "Encryption Paused", "Decryption Paused")
Dim arLockStatus
arLockStatus = Array("Unlocked", "Locked")
For Each objItem in colItems
Dim EncryptionMethod
Dim ProtectionStatus
Dim ConversionStatus
Dim EncryptionPercentage 'Percentage of the volume that is encrypted
Dim VolumeKeyProtectorID
Dim LockStatus
objItem.GetEncryptionMethod EncryptionMethod
objItem.GetProtectionStatus ProtectionStatus
objItem.GetConversionStatus ConversionStatus, EncryptionPercentage
objItem.GetKeyProtectors 0,VolumeKeyProtectorID
objItem.GetLockStatus LockStatus
WScript.Echo "DeviceID: " & objItem.DeviceID
Wscript.Echo "DriveLetter: " & objItem.DriveLetter
Wscript.Echo "EncryptionMethod: " & arEncryptionMethod(EncryptionMethod)
Wscript.Echo "ProtectionStatus: " & arProtectionStatus(ProtectionStatus)
Wscript.Echo "ConversionStatus: " & arConversionStatus(ConversionStatus)
Wscript.Echo "EncryptionPercentage: " & EncryptionPercentage & "%"
Wscript.Echo "LockStatus: " & arLockStatus(LockStatus)
For Each objId in VolumeKeyProtectorID
Dim VolumeKeyProtectorFriendlyName
objItem.GetKeyProtectorFriendlyName objId, VolumeKeyProtectorFriendlyName
If VolumeKeyProtectorFriendlyName <> "" Then
Wscript.Echo "KeyProtectors: " & VolumeKeyProtectorFriendlyName
End If
Next
Next
- 9/28/2010
- Norman Bauer
I am trying to find out whether a volume is BitLocker encrypted or not, using the following code (WMI with C#):
var path = new ManagementPath();
path.NamespacePath = "\\ROOT\\CIMV2\\Security\\MicrosoftVolumeEncryption";
path.ClassName = "Win32_EncryptableVolume";
var scope = new ManagementScope(path, new ConnectionOptions() { Impersonation = ImpersonationLevel.Impersonate });
var management = new ManagementClass(scope, path, new ObjectGetOptions());
foreach (var vol in management.GetInstances())
Console.WriteLine("{0} - {1}", vol["DriveLetter"], (uint)vol["ProtectionStatus"] == 1 ? "Active" : "Inactive");
But this requires admin credentials. How do I get the same information as standard user?
[tfl - 24 06 10] Hi - and thanks for your post. You should post questions like this to the MSDN Forums at http://forums.microsoft.com/msdn or the MSDN Newsgroups at http://www.microsoft.com/communities/newsgroups/en-us/. You are much more likely get a quicker response using the forums than through the Community Content. For specific help about:
.NET Framework : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.dotnet.framework
PowerShell : http://groups.google.com/group/microsoft.public.windows.powershell/topics?pli=1
SQL Server : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.sqlserver%2C&
Visual Studio : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.vstudio%2C&
Windows : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.windows%2C&
All Public : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public%2C&
- 6/22/2010
- soumyasch
- 6/24/2010
- Thomas Lee
#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.
}