ProtectKeyWithCertificateFile method of the Win32_EncryptableVolume class

The ProtectKeyWithCertificateFile method of the Win32_EncryptableVolume class validates the Enhanced Key Usage (EKU) object identifier (OID) of the provided certificate.

Syntax

uint32 ProtectKeyWithCertificateFile(
  [in, optional] string FriendlyName,
  [in]           string FileName,
  [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, the FriendlyName parameter is created by using the Subject Name in the certificate.

FileName [in]

Type: string

A string that specifies the location and name of the .cer file used to enable BitLocker. An encryption certificate must be exported in .cer format (Distinguished Encoding Rules (DER)-encoded binary X.509 or Base-64 encoded X.509). The encryption certificate may be generated from Microsoft PKI, third-party PKI, or self-signed.

VolumeKeyProtectorID [out]

Type: string

A string that uniquely identifies the created key protector that can be used to manage this 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/value Description
S_OK
0 (0x0)
The method was successful.
FVE_E_NON_BITLOCKER_OID
2150695022 (0x8031006E)
The EKU attribute of the specified certificate does not permit it to be used for BitLocker Drive Encryption. BitLocker does not require that a certificate have an EKU attribute, but if one is configured, it must be set to an OID that matches the OID configured for BitLocker.
FVE_E_POLICY_USER_CERTIFICATE_NOT_ALLOWED
2150695026 (0x80310072)
Group Policy does not permit user certificates, such as smart cards, to be used with BitLocker.
FVE_E_POLICY_USER_CERT_MUST_BE_HW
2150695028 (0x80310074)
Group Policy requires that you supply a smart card to use BitLocker.
FVE_E_POLICY_PROHIBITS_SELFSIGNED
2150695046 (0x80310086)
Group Policy does not permit the use of self-signed certificates.
ERROR_FILE_NOT_FOUND
0000000002 (0x2)
The system cannot find the specified file.

 

Remarks

If the OID does not match the one associated with the service controller in the registry, this method fails. This prevents the user from setting data recovery agent (DRA) protectors manually on the volume. DRAs are only to be set by the service.

Requirements

Requirement Value
Minimum supported client
Windows 7 Enterprise, Windows 7 Ultimate [desktop apps only]
Minimum supported server
Windows Server 2008 R2 [desktop apps only]
Namespace
Root\CIMV2\Security\MicrosoftVolumeEncryption
MOF
Win32_encryptablevolume.mof

See also

Win32_EncryptableVolume