Public/Set-PWSHYBKPIVManagementKey.ps1
|
function Set-PWSHYBKPIVManagementKey { <# .SYNOPSIS Sets the management key of a locally attached YubiKey's PIV application. .DESCRIPTION Wraps "yubico-piv-tool.exe --action set-mgm-key". Changes a credential that guards key and certificate management on the device, and losing it locks out future management operations, so this cmdlet supports -WhatIf/-Confirm with ConfirmImpact 'High'. If -NewManagementKey is not supplied, yubico-piv-tool.exe generates a random key and prints it to its output - this cmdlet returns that raw output so the generated key is not lost. Accepts the "set-mgm-key" action's config-declared options (-NewManagementKey, -NewManagementKeyAlgorithm, -TouchPolicy, -ManagementKey, -Reader) as dynamic parameters built from Config\Posh-YBKPIV.json. .PARAMETER NewManagementKey The new management key to set, as a SecureString. When omitted, yubico-piv-tool.exe generates a random key and prints it in the output. .PARAMETER NewManagementKeyAlgorithm Algorithm for the new management key: TDES, AES128, AES192, or AES256. Defaults to TDES when omitted. .PARAMETER TouchPolicy Touch policy to apply to the management key: never, always, or cached. .PARAMETER ManagementKey The current management key authorizing the operation, as a SecureString. Defaults to yubico-piv-tool.exe's built-in default management key when omitted. .PARAMETER Reader Name of the smart card reader to target, when more than one is attached. If omitted, yubico-piv-tool.exe uses its own default reader selection. .INPUTS None. This cmdlet does not accept pipeline input. .OUTPUTS String[]. yubico-piv-tool.exe's raw output, which includes the generated management key when -NewManagementKey was not supplied. .NOTES -NewManagementKey, -NewManagementKeyAlgorithm, -TouchPolicy, -ManagementKey, and -Reader are declared dynamically from Config\Posh-YBKPIV.json and therefore do not appear in Get-Help's PARAMETERS/SYNTAX sections. Run `Get-Command Set-PWSHYBKPIVManagementKey -Syntax` for the authoritative, current parameter list. .EXAMPLE Set-PWSHYBKPIVManagementKey Generates and sets a new random management key after confirmation, returning it. .LINK https://developers.yubico.com/yubico-piv-tool/Actions/ #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] [OutputType([string[]])] param() DynamicParam { $dynamicConfig = Read-PWSHYBKPIVConfigFile Get-PWSHYBKPIVActionParameter -Action 'set-mgm-key' -CmdletWrapping $dynamicConfig.cmdletWrapping } begin { $config = Read-PWSHYBKPIVConfigFile Write-PWSHYBKPIVLog -Config $config -Level Debug -CmdletName $MyInvocation.MyCommand.Name ` -Message 'Cmdlet invoked' -BoundParameters $PSBoundParameters $architecture = Resolve-PWSHYBKPIVArchitecture -Architecture $config.installation.architecture $exePath = Get-PWSHYBKPIVInstallPath -Installation $config.installation -Architecture $architecture if (-not (Test-Path -Path $exePath -PathType Leaf)) { throw "yubico-piv-tool.exe was not found at '$exePath'. Run Install-PWSHYBKPIVTool first." } } end { if (-not $PSCmdlet.ShouldProcess('YubiKey PIV application', 'Set management key')) { return } try { $result = Invoke-PWSHYBKPIVTool -ExePath $exePath -Action 'set-mgm-key' ` -CmdletWrapping $config.cmdletWrapping -BoundParameters $PSBoundParameters Write-PWSHYBKPIVLog -Config $config -Level Information -CmdletName $MyInvocation.MyCommand.Name ` -Message 'Management key set successfully' $result.Output } catch { Write-PWSHYBKPIVLog -Config $config -Level Error -CmdletName $MyInvocation.MyCommand.Name -Message "Management key change failed: $_" throw } } } |