Public/Test-PWSHYBKPIVPin.ps1
|
function Test-PWSHYBKPIVPin { <# .SYNOPSIS Tests whether a PIN is valid for a locally attached YubiKey's PIV application. .DESCRIPTION Wraps "yubico-piv-tool.exe --action verify-pin". Follows Test- verb convention: returns $true/$false rather than throwing on a wrong PIN. A failed attempt still consumes one of the YubiKey's limited PIN retries, a real side effect on the device, so this cmdlet supports -WhatIf/-Confirm like other state-changing cmdlets in this module. A wrong PIN still returns $false, matching Test-Path/Test-Connection semantics, but this cmdlet also writes a Write-Warning (independent of the module's opt-in Logging config) when yubico-piv-tool.exe's failure text indicates the retry count is low or has hit zero - the PIN is now blocked and the PIV application needs Unblock-PWSHYBKPIVPin (with the PUK) or Reset-PWSHYBKPIVDevice before it will accept a PIN again. That distinction would otherwise be indistinguishable from an ordinary wrong-PIN $false. Accepts the "verify-pin" action's config-declared options (-Pin, -Reader) as dynamic parameters built from Config\Posh-YBKPIV.json, so a JSON edit that adds or changes options for this action is picked up automatically. .PARAMETER Pin The PIN to verify, as a SecureString. Converted to plain text only immediately before invoking yubico-piv-tool.exe, and never logged. .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 Boolean. $true if the PIN verified successfully, $false otherwise. .NOTES -Reader is declared dynamically from Config\Posh-YBKPIV.json and therefore does not appear in Get-Help's PARAMETERS/SYNTAX sections. Run `Get-Command Test-PWSHYBKPIVPin -Syntax` for the authoritative, current parameter list. .EXAMPLE Test-PWSHYBKPIVPin -Pin (Read-Host -AsSecureString -Prompt 'PIN') Prompts for a PIN and returns whether it verified successfully. .LINK https://developers.yubico.com/yubico-piv-tool/Actions/ .LINK Set-PWSHYBKPIVPin .LINK Unblock-PWSHYBKPIVPin #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Low')] [OutputType([bool])] param() DynamicParam { $dynamicConfig = Read-PWSHYBKPIVConfigFile Get-PWSHYBKPIVActionParameter -Action 'verify-pin' -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', 'Verify PIN')) { return } try { $null = Invoke-PWSHYBKPIVTool -ExePath $exePath -Action 'verify-pin' ` -CmdletWrapping $config.cmdletWrapping -BoundParameters $PSBoundParameters Write-PWSHYBKPIVLog -Config $config -Level Information -CmdletName $MyInvocation.MyCommand.Name ` -Message 'PIN verified successfully' $true } catch { Write-PWSHYBKPIVLog -Config $config -Level Warning -CmdletName $MyInvocation.MyCommand.Name ` -Message "PIN verification failed: $_" Write-PWSHYBKPIVPinRetryWarning -Message $_.Exception.Message $false } } } |