Set-AzVMDiskEncryptionExtension

Reference

Module:: Az.Compute

Enables encryption on a running IaaS virtual machine in Azure.

Syntax

Set-AzVMDiskEncryptionExtension
   [-ResourceGroupName] <String>
   [-VMName] <String>
   [-DiskEncryptionKeyVaultUrl] <String>
   [-DiskEncryptionKeyVaultId] <String>
   [[-KeyEncryptionKeyUrl] <String>]
   [[-KeyEncryptionKeyVaultId] <String>]
   [[-KeyEncryptionAlgorithm] <String>]
   [[-VolumeType] <String>]
   [[-SequenceVersion] <String>]
   [[-TypeHandlerVersion] <String>]
   [[-Name] <String>]
   [[-Passphrase] <String>]
   [-Force]
   [-DisableAutoUpgradeMinorVersion]
   [-SkipVmBackup]
   [-ExtensionType <String>]
   [-ExtensionPublisherName <String>]
   [-EncryptFormatAll]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Set-AzVMDiskEncryptionExtension
   [-ResourceGroupName] <String>
   [-VMName] <String>
   [-AadClientID] <String>
   [-AadClientSecret] <String>
   [-DiskEncryptionKeyVaultUrl] <String>
   [-DiskEncryptionKeyVaultId] <String>
   [[-KeyEncryptionKeyUrl] <String>]
   [[-KeyEncryptionKeyVaultId] <String>]
   [[-KeyEncryptionAlgorithm] <String>]
   [[-VolumeType] <String>]
   [[-SequenceVersion] <String>]
   [[-TypeHandlerVersion] <String>]
   [[-Name] <String>]
   [[-Passphrase] <String>]
   [-Force]
   [-DisableAutoUpgradeMinorVersion]
   [-SkipVmBackup]
   [-ExtensionType <String>]
   [-ExtensionPublisherName <String>]
   [-EncryptFormatAll]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Set-AzVMDiskEncryptionExtension
   [-ResourceGroupName] <String>
   [-VMName] <String>
   [-AadClientID] <String>
   [-AadClientCertThumbprint] <String>
   [-DiskEncryptionKeyVaultUrl] <String>
   [-DiskEncryptionKeyVaultId] <String>
   [[-KeyEncryptionKeyUrl] <String>]
   [[-KeyEncryptionKeyVaultId] <String>]
   [[-KeyEncryptionAlgorithm] <String>]
   [[-VolumeType] <String>]
   [[-SequenceVersion] <String>]
   [[-TypeHandlerVersion] <String>]
   [[-Name] <String>]
   [[-Passphrase] <String>]
   [-Force]
   [-DisableAutoUpgradeMinorVersion]
   [-SkipVmBackup]
   [-ExtensionType <String>]
   [-ExtensionPublisherName <String>]
   [-EncryptFormatAll]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Set-AzVMDiskEncryptionExtension
   [-ResourceGroupName] <String>
   [-VMName] <String>
   [[-KeyEncryptionAlgorithm] <String>]
   [[-VolumeType] <String>]
   [[-SequenceVersion] <String>]
   [[-TypeHandlerVersion] <String>]
   [[-Name] <String>]
   [[-Passphrase] <String>]
   [-Force]
   [-DisableAutoUpgradeMinorVersion]
   [-SkipVmBackup]
   [-ExtensionType <String>]
   [-ExtensionPublisherName <String>]
   [-EncryptFormatAll]
   [-Migrate]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Set-AzVMDiskEncryptionExtension
   [-ResourceGroupName] <String>
   [-VMName] <String>
   [[-KeyEncryptionAlgorithm] <String>]
   [[-VolumeType] <String>]
   [[-SequenceVersion] <String>]
   [[-TypeHandlerVersion] <String>]
   [[-Name] <String>]
   [[-Passphrase] <String>]
   [-Force]
   [-DisableAutoUpgradeMinorVersion]
   [-SkipVmBackup]
   [-ExtensionType <String>]
   [-ExtensionPublisherName <String>]
   [-EncryptFormatAll]
   [-MigrationRecovery]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The Set-AzVMDiskEncryptionExtension cmdlet enables encryption on a running infrastructure as a service (IaaS) virtual machine in Azure. It enables encryption by installing the disk encryption extension on the virtual machine.

This cmdlet requires confirmation from the users as one of the steps to enable encryption requires a restart of the virtual machine.

It is advised that you save your work on the virtual machine before you run this cmdlet.

Linux: The VolumeType parameter is required when encrypting Linux virtual machines, and must be set to a value ("Os", "Data", or "All") supported by the Linux distribution.

Windows: The VolumeType parameter may be omitted, in which case the operation defaults to All; if the VolumeType parameter is present for a Windows virtual machine, it must be set to either All or OS.

Examples

Example 1: Enable encryption

$RGName = "MyResourceGroup"
$VMName = "MyTestVM"
$VaultName= "MyKeyVault"
$KeyVault = Get-AzKeyVault -VaultName $VaultName -ResourceGroupName $RGName
$DiskEncryptionKeyVaultUrl = $KeyVault.VaultUri
$KeyVaultResourceId = $KeyVault.ResourceId
$VolumeType = "All"
Set-AzVMDiskEncryptionExtension -ResourceGroupName $RGName -VMName $VMName -DiskEncryptionKeyVaultUrl $DiskEncryptionKeyVaultUrl -DiskEncryptionKeyVaultId $KeyVaultResourceId -VolumeType $VolumeType

This example enables encryption on a VM without specifying AD credentials.

Example 2: Enable encryption with pipelined input

$params = New-Object PSObject -Property @{
    ResourceGroupName = "[resource-group-name]"
    VMName = "[vm-name]"
    DiskEncryptionKeyVaultId = "/subscriptions/[subscription-id-guid]/resourceGroups/[resource-group-name]/providers/Microsoft.KeyVault/vaults/[keyvault-name]"
    DiskEncryptionKeyVaultUrl = "https://[keyvault-name].vault.azure.net"
    KeyEncryptionKeyVaultId = "/subscriptions/[subscription-id-guid]/resourceGroups/[resource-group-name]/providers/Microsoft.KeyVault/vaults/[keyvault-name]"
    KeyEncryptionKeyUrl = "https://[keyvault-name].vault.azure.net/keys/[kekname]/[kek-unique-id]"
    VolumeType = "All"
}

$params | Set-AzVMDiskEncryptionExtension

This example sends parameters using pipelined input to enable encryption on a VM, without specifying AD credentials.

Example 3: Enable encryption using Microsoft Entra Client ID and Client Secret

$RGName = "MyResourceGroup"
$VMName = "MyTestVM"
$AADClientID = "<clientID of your Azure AD app>"
$AADClientSecret = "<clientSecret of your Azure AD app>"
$VaultName= "MyKeyVault"
$KeyVault = Get-AzKeyVault -VaultName $VaultName -ResourceGroupName $RGName
$DiskEncryptionKeyVaultUrl = $KeyVault.VaultUri
$KeyVaultResourceId = $KeyVault.ResourceId
$VolumeType = "All"
Set-AzVMDiskEncryptionExtension -ResourceGroupName $RGName -VMName $VMName -AadClientID $AADClientID -AadClientSecret $AADClientSecret -DiskEncryptionKeyVaultUrl $DiskEncryptionKeyVaultUrl -DiskEncryptionKeyVaultId $KeyVaultResourceId -VolumeType $VolumeType

This example uses Microsoft Entra client ID and client secret to enable encryption on a VM.

Example 4: Enable encryption using Microsoft Entra client ID and client certification thumbprint

$RGName = "MyResourceGroup"
$VMName = "MyTestVM"
#The KeyVault must have enabledForDiskEncryption property set on it
$VaultName= "MyKeyVault"
$KeyVault = Get-AzKeyVault -VaultName $VaultName -ResourceGroupName $RGName
$DiskEncryptionKeyVaultUrl = $KeyVault.VaultUri
$KeyVaultResourceId = $KeyVault.ResourceId
$VolumeType = "All"

# create Azure AD application and associate the certificate
$CertPath = "C:\certificates\examplecert.pfx"
$CertPassword = "Password"
$Cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath, $CertPassword)
$CertValue = [System.Convert]::ToBase64String($cert.GetRawCertData())
$AzureAdApplication = New-AzADApplication -DisplayName "<Your Application Display Name>" -HomePage "<https://YourApplicationHomePage>" -IdentifierUris "<https://YouApplicationUri>" -CertValue $CertValue 
$ServicePrincipal = New-AzADServicePrincipal -ApplicationId $AzureAdApplication.ApplicationId

$AADClientID = $AzureAdApplication.ApplicationId
$aadClientCertThumbprint= $cert.Thumbprint

#Upload pfx to KeyVault 
$KeyVaultSecretName = "MyAADCert"
$FileContentBytes = Get-Content $CertPath -Encoding Byte
$FileContentEncoded = [System.Convert]::ToBase64String($fileContentBytes)
$JSONObject = @"
    { 
        "data" : "$filecontentencoded", 
        "dataType" : "pfx", 
        "password" : "$CertPassword" 
    } 
"@
$JSONObjectBytes = [System.Text.Encoding]::UTF8.GetBytes($jsonObject)
$JSONEncoded = [System.Convert]::ToBase64String($jsonObjectBytes)

$Secret = ConvertTo-SecureString -String $JSONEncoded -AsPlainText -Force
Set-AzKeyVaultSecret -VaultName $VaultName -Name $KeyVaultSecretName -SecretValue $Secret
Set-AzKeyVaultAccessPolicy -VaultName $VaultName -ResourceGroupName $RGName -EnabledForDeployment

#deploy cert to VM
$CertUrl = (Get-AzKeyVaultSecret -VaultName $VaultName -Name $KeyVaultSecretName).Id
$SourceVaultId = (Get-AzKeyVault -VaultName $VaultName -ResourceGroupName $RGName).ResourceId
$VM = Get-AzVM -ResourceGroupName $RGName -Name $VMName 
$VM = Add-AzVMSecret -VM $VM -SourceVaultId $SourceVaultId -CertificateStore "My" -CertificateUrl $CertUrl
Update-AzVM -VM $VM -ResourceGroupName $RGName 

#Enable encryption on the virtual machine using Azure AD client ID and client cert thumbprint
Set-AzVMDiskEncryptionExtension -ResourceGroupName $RGName -VMName $VMName -AadClientID $AADClientID -AadClientCertThumbprint $AADClientCertThumbprint -DiskEncryptionKeyVaultUrl $DiskEncryptionKeyVaultUrl -DiskEncryptionKeyVaultId $KeyVaultResourceId -VolumeType $VolumeType

This example uses Microsoft Entra client ID and client certification thumbprints to enable encryption on a VM.

Example 5: Enable encryption using Microsoft Entra client ID, client secret, and wrap disk encryption key by using key encryption key

$RGName = "MyResourceGroup"
$VMName = "MyTestVM"

$AADClientID = "<clientID of your Azure AD app>"
$AADClientSecret = "<clientSecret of your Azure AD app>"

$VaultName= "MyKeyVault"
$KeyVault = Get-AzKeyVault -VaultName $VaultName -ResourceGroupName $RGName
$DiskEncryptionKeyVaultUrl = $KeyVault.VaultUri
$KeyVaultResourceId = $KeyVault.ResourceId
$VolumeType = "All"

$KEKName = "MyKeyEncryptionKey"
$KEK = Add-AzKeyVaultKey -VaultName $VaultName -Name $KEKName -Destination "Software"
$KeyEncryptionKeyUrl = $KEK.Key.kid

Set-AzVMDiskEncryptionExtension -ResourceGroupName $RGName -VMName $VMName -AadClientID $AADClientID -AadClientSecret $AADClientSecret -DiskEncryptionKeyVaultUrl $DiskEncryptionKeyVaultUrl -DiskEncryptionKeyVaultId $KeyVaultResourceId -KeyEncryptionKeyUrl $KeyEncryptionKeyUrl -KeyEncryptionKeyVaultId $KeyVaultResourceId -VolumeType $VolumeType

This example uses Microsoft Entra client ID and client secret to enable encryption on a VM, and wraps the disk encryption key using a key encryption key.

Example 6: Enable encryption using Microsoft Entra client ID, client cert thumbprint, and wrap disk encryptionkey by using key encryption key

$RGName = "MyResourceGroup"
$VMName = "MyTestVM"
#The KeyVault must have enabledForDiskEncryption property set on it
$VaultName= "MyKeyVault"
$KeyVault = Get-AzKeyVault -VaultName $VaultName -ResourceGroupName $RGName
$DiskEncryptionKeyVaultUrl = $KeyVault.VaultUri
$KeyVaultResourceId = $KeyVault.ResourceId
$KEKName = "MyKeyEncryptionKey"
$KEK = Add-AzKeyVaultKey -VaultName $VaultName -Name $KEKName -Destination "Software"
$KeyEncryptionKeyUrl = $KEK.Key.kid
$VolumeType = "All"

# create Azure AD application and associate the certificate
$CertPath = "C:\certificates\examplecert.pfx"
$CertPassword = "Password"
$Cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath, $CertPassword)
$CertValue = [System.Convert]::ToBase64String($cert.GetRawCertData())
$AzureAdApplication = New-AzADApplication -DisplayName "<Your Application Display Name>" -HomePage "<https://YourApplicationHomePage>" -IdentifierUris "<https://YouApplicationUri>" -CertValue $CertValue
$ServicePrincipal = New-AzADServicePrincipal -ApplicationId $AzureAdApplication.ApplicationId

$AADClientID = $AzureAdApplication.ApplicationId
$AADClientCertThumbprint= $Cert.Thumbprint

#Upload pfx to KeyVault 
$KeyVaultSecretName = "MyAADCert"
$FileContentBytes = Get-Content $CertPath -Encoding Byte
$FileContentEncoded = [System.Convert]::ToBase64String($FileContentBytes)
$JSONObject = @"
    { 
        "data" : "$filecontentencoded", 
        "dataType" : "pfx", 
        "password" : "$CertPassword" 
    } 
"@
$JSONObjectBytes = [System.Text.Encoding]::UTF8.GetBytes($JSONObject)
$JsonEncoded = [System.Convert]::ToBase64String($JSONObjectBytes)
$Secret = ConvertTo-SecureString -String $JSONEncoded -AsPlainText -Force
Set-AzKeyVaultSecret -VaultName $VaultName-Name $KeyVaultSecretName -SecretValue $Secret
Set-AzKeyVaultAccessPolicy -VaultName $VaultName -ResourceGroupName $RGName -EnabledForDeployment

#deploy cert to VM
$CertUrl = (Get-AzKeyVaultSecret -VaultName $VaultName -Name $KeyVaultSecretName).Id
$SourceVaultId = (Get-AzKeyVault -VaultName $VaultName -ResourceGroupName $RGName).ResourceId
$VM = Get-AzVM -ResourceGroupName $RGName -Name $VMName 
$VM = Add-AzVMSecret -VM $VM -SourceVaultId $SourceVaultId -CertificateStore "My" -CertificateUrl $CertUrl 
Update-AzVM -VM $VM -ResourceGroupName $RGName 

#Enable encryption on the virtual machine using Azure AD client ID and client cert thumbprint
Set-AzVMDiskEncryptionExtension -ResourceGroupName $RGname -VMName $VMName -AadClientID $AADClientID -AadClientCertThumbprint $AADClientCertThumbprint -DiskEncryptionKeyVaultUrl $DiskEncryptionKeyVaultUrl -DiskEncryptionKeyVaultId $KeyVaultResourceId -KeyEncryptionKeyUrl $KeyEncryptionKeyUrl -KeyEncryptionKeyVaultId $KeyVaultResourceId -VolumeType $VolumeType

This example uses Microsoft Entra client ID and client cert thumbprint to enable encryption on a VM, and wraps the disk encryption key using a key encryption key.

Parameters

-AadClientCertThumbprint

Specifies the thumbprint of the Microsoft Entra application client certificate that has permissions to write secrets to KeyVault. As a prerequisite, the Microsoft Entra client certificate must be previously deployed to the virtual machine's local computer my certificate store. The Add-AzVMSecret cmdlet can be used to deploy a certificate to a virtual machine in Azure. For more details, see the Add-AzVMSecret cmdlet help. The certificate must be previously deployed to the virtual machine local computer my certificate store.

Type:	String
Position:	3
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-AadClientID

Specifies the client ID of the Microsoft Entra application that has permissions to write secrets to KeyVault.

Type:	String
Position:	2
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-AadClientSecret

Specifies the client secret of the Microsoft Entra application that has permissions to write secrets to KeyVault.

Type:	String
Position:	3
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with Azure.

Type:	IAzureContextContainer
Aliases:	AzContext, AzureRmContext, AzureCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisableAutoUpgradeMinorVersion

Indicates that this cmdlet disables auto-upgrade of the minor version of the extension.

Type:	SwitchParameter
Position:	14
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-DiskEncryptionKeyVaultId

Specifies the resource ID of the KeyVault to which the virtual machine encryption keys should be uploaded.

Type:	String
Position:	5
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-DiskEncryptionKeyVaultUrl

Specifies the KeyVault URL to which the virtual machine encryption keys should be uploaded.

Type:	String
Position:	4
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-EncryptFormatAll

Encrypt-Format all data drives that are not already encrypted

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ExtensionPublisherName

The extension publisher name. Specify this parameter only to override the default value of "Microsoft.Azure.Security".

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ExtensionType

The extension type. Specify this parameter to override its default value of "AzureDiskEncryption" for Windows VMs and "AzureDiskEncryptionForLinux" for Linux VMs.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Force

Forces the command to run without asking for user confirmation.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-KeyEncryptionAlgorithm

Specifies the algorithm that is used to wrap and unwrap the key encryption key of the virtual machine. The default value is RSA-OAEP.

Type:	String
Accepted values:	RSA-OAEP, RSA1_5
Position:	8
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-KeyEncryptionKeyUrl

Specifies the URL of the key encryption key that is used to wrap and unwrap the virtual machine encryption key. This must be the full versioned URL.

Type:	String
Position:	6
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-KeyEncryptionKeyVaultId

Specifies the resource ID of the KeyVault that contains key encryption key that is used to wrap and unwrap the virtual machine encryption key. This must be a full versioned URL.

Type:	String
Position:	7
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Migrate

Initiates migration of the VM to latest Azure Disk Encryption extension version (ADE without Microsoft Entra credentials).

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-MigrationRecovery

Initiates migration recovery for failures during migration of ADE extension version with Microsoft Entra ID to ADE extension version without Microsoft Entra ID.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-Name

Specifies the name of the Azure Resource Manager resource that represents the extension. If the Name parameter is omitted, the installed extension will be named AzureDiskEncryption on Windows virtual machines and AzureDiskEncryptionForLinux on Linux virtual machines.

Type:	String
Aliases:	ExtensionName
Position:	12
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-Passphrase

Specifies the passphrase used for encrypting Linux virtual machines only. This parameter is not used for virtual machines that run the Windows operating system.

Type:	String
Position:	13
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ResourceGroupName

Specifies the name of the resource group of the virtual machine.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-SequenceVersion

Specifies the sequence number of the encryption operations for a virtual machine. This is unique per each encryption operation performed on the same virtual machine. The Get-AzVMExtension cmdlet can be used to retrieve the previous sequence number that was used.

Type:	String
Position:	10
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-SkipVmBackup

Skip backup creation for Linux VMs

Type:	SwitchParameter
Position:	15
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-TypeHandlerVersion

Specifies the version of the encryption extension.

Type:	String
Aliases:	HandlerVersion, Version
Position:	11
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-VMName

Specifies the name of the virtual machine.

Type:	String
Aliases:	ResourceName
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-VolumeType

Specifies the type of virtual machine volumes on which to perform encryption operation: OS, Data, or All.