Add KdsRootKey - PowerShell

Overview

The Add-KdsRootKey cmdlet adds a new root key to the Key Distribution Service (KDS). A KDS root key is used to encrypt and decrypt the symmetric KEK (Key Encryption Key) that is used to protect the symmetric data encryption keys (DEKs) stored in Azure Key Vault.

Syntax

Add-KdsRootKey [-Name] <String> [-Version] <Int32> [-Validity] <TimeSpan> [-Created] <DateTime> [-Activated] <DateTime> [-Expires] <DateTime> [-KeyUsage] <KeyUsage> [-KeySize] <Int32> [-Hsm] [-Enable] [-Disable] [-Force] [-Confirm] [-WhatIf]

Options/Flags

  • -Name: The name of the root key.
  • -Version: The version of the root key.
  • -Validity: The validity period of the root key.
  • -Created: The date and time when the root key was created.
  • -Activated: The date and time when the root key was activated.
  • -Expires: The date and time when the root key expires.
  • -KeyUsage: The key usage of the root key.
  • -KeySize: The key size of the root key.
  • -Hsm: Specifies whether the root key is stored in a hardware security module (HSM).
  • -Enable: Enables the root key.
  • -Disable: Disables the root key.
  • -Force: Forces the operation to complete even if it would normally fail.
  • -Confirm: Prompts the user to confirm the operation before it is performed.
  • -WhatIf: Performs a simulation of the operation without actually performing it.

Examples

Example 1: Add a new root key to the KDS

Add-KdsRootKey -Name "MyRootKey" -Version 1 -Validity 365.25:00:00

Example 2: Add a new root key to the KDS using a HSM

Add-KdsRootKey -Name "MyRootKey" -Version 1 -Validity 365.25:00:00 -Hsm

Example 3: Add a new root key to the KDS and enable it

Add-KdsRootKey -Name "MyRootKey" -Version 1 -Validity 365.25:00:00 -Enable

Common Issues

  • Error: The root key already exists. Ensure that the name of the root key is unique.
  • Error: The root key is disabled. Enable the root key using the Enable-KdsRootKey cmdlet.

Integration

The Add-KdsRootKey cmdlet can be used in combination with other PowerShell cmdlets to manage KDS root keys. For example, the following script adds a new root key to the KDS and then gets the properties of the root key:

Add-KdsRootKey -Name "MyRootKey" -Version 1 -Validity 365.25:00:00
Get-KdsRootKey -Name "MyRootKey"
  • Get-KdsRootKey
  • Remove-KdsRootKey
  • Enable-KdsRootKey
  • Disable-KdsRootKey