Public/Reset-PWSHYBKPIVDevice.ps1
|
function Reset-PWSHYBKPIVDevice { <# .SYNOPSIS Factory-resets the PIV application of a locally attached YubiKey. .DESCRIPTION Wraps "yubico-piv-tool.exe --action reset". This is the single most destructive action in this module: it wipes every key, certificate, and PIN/PUK/management-key value from the PIV application, restoring factory defaults. yubico-piv-tool.exe only permits it once both the PIN and PUK retry counters have been exhausted (fully blocked) - it is not a casual "start over" command. Supports -WhatIf/-Confirm with ConfirmImpact 'High'. Throws on failure rather than returning a value, matching Reset- verb convention. Accepts the "reset" action's config-declared options (-ResetGlobal, -Reader) as dynamic parameters built from Config\Posh-YBKPIV.json. .PARAMETER ResetGlobal Passes --global to yubico-piv-tool.exe's reset action, broadening the reset beyond the PIV application (see yubico-piv-tool.exe --help for the exact scope of this flag). .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 None. Throws a terminating error on failure; produces no output on success. .NOTES -ResetGlobal 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 Reset-PWSHYBKPIVDevice -Syntax` for the authoritative, current parameter list. .EXAMPLE Reset-PWSHYBKPIVDevice Factory-resets the PIV application after confirmation, once PIN and PUK are both blocked. .LINK https://developers.yubico.com/yubico-piv-tool/Actions/ .LINK Set-PWSHYBKPIVRetryCount #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param() DynamicParam { $dynamicConfig = Read-PWSHYBKPIVConfigFile Get-PWSHYBKPIVActionParameter -Action 'reset' -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', 'Factory reset (wipes all keys, certificates, and PINs)')) { return } try { $null = Invoke-PWSHYBKPIVTool -ExePath $exePath -Action 'reset' ` -CmdletWrapping $config.cmdletWrapping -BoundParameters $PSBoundParameters Write-PWSHYBKPIVLog -Config $config -Level Information -CmdletName $MyInvocation.MyCommand.Name ` -Message 'PIV application reset successfully' } catch { Write-PWSHYBKPIVLog -Config $config -Level Error -CmdletName $MyInvocation.MyCommand.Name -Message "Reset failed: $_" throw } } } |