Public/Set-PWSHYBKPIVRetryCount.ps1
|
function Set-PWSHYBKPIVRetryCount { <# .SYNOPSIS Sets the PIN and PUK retry counters of a locally attached YubiKey's PIV application. .DESCRIPTION Wraps "yubico-piv-tool.exe --action pin-retries". yubico-piv-tool.exe resets the PIN and PUK to their factory default values as a side effect of changing the retry counters, so this cmdlet supports -WhatIf/-Confirm with ConfirmImpact 'High'. Throws on failure rather than returning a value, matching Set- verb convention. Accepts the "pin-retries" action's config-declared options (-PinRetries, -PukRetries, -ManagementKey, -Reader) as dynamic parameters built from Config\Posh-YBKPIV.json. .PARAMETER PinRetries The number of PIN retries to allow before the PIN is blocked. .PARAMETER PukRetries The number of PUK retries to allow before the PUK is blocked. .PARAMETER ManagementKey The 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 None. Throws a terminating error on failure; produces no output on success. .NOTES -PinRetries, -PukRetries, -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-PWSHYBKPIVRetryCount -Syntax` for the authoritative, current parameter list. .EXAMPLE Set-PWSHYBKPIVRetryCount -PinRetries 3 -PukRetries 5 Sets the PIN and PUK retry counters after confirmation, resetting the PIN and PUK to their factory defaults. .LINK https://developers.yubico.com/yubico-piv-tool/Actions/ .LINK Set-PWSHYBKPIVPin .LINK Set-PWSHYBKPIVPuk #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param() DynamicParam { $dynamicConfig = Read-PWSHYBKPIVConfigFile Get-PWSHYBKPIVActionParameter -Action 'pin-retries' -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 PIN/PUK retries (resets PIN and PUK to factory defaults)')) { return } try { $null = Invoke-PWSHYBKPIVTool -ExePath $exePath -Action 'pin-retries' ` -CmdletWrapping $config.cmdletWrapping -BoundParameters $PSBoundParameters Write-PWSHYBKPIVLog -Config $config -Level Information -CmdletName $MyInvocation.MyCommand.Name ` -Message 'PIN/PUK retries set successfully' } catch { Write-PWSHYBKPIVLog -Config $config -Level Error -CmdletName $MyInvocation.MyCommand.Name -Message "PIN/PUK retries change failed: $_" throw } } } |