Public/Test-PWSHYBKPIVSignature.ps1
|
function Test-PWSHYBKPIVSignature { <# .SYNOPSIS Tests that the key in a PIV slot of a locally attached YubiKey can sign and verify data. .DESCRIPTION Wraps "yubico-piv-tool.exe --action test-signature". Follows Test- verb convention: returns $true/$false rather than throwing on failure. When -Pin is supplied and is wrong, the attempt still consumes one of the YubiKey's limited PIN retries, so this cmdlet supports -WhatIf/-Confirm (ConfirmImpact 'Low', matching Test-PWSHYBKPIVPin). Accepts the "test-signature" action's config-declared options (-Slot, -Hash, -Pin, -Reader) as dynamic parameters built from Config\Posh-YBKPIV.json. .PARAMETER Slot The PIV slot holding the key to test, e.g. '9a'. .PARAMETER Hash Hash algorithm to use for the test: SHA1, SHA256, SHA384, or SHA512. Defaults to SHA256 when omitted. .PARAMETER Pin The PIN authorizing the signing operation, as a SecureString, if the slot's PIN policy requires one. .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 sign/verify round-trip succeeded, $false otherwise. .NOTES -Slot, -Hash, -Pin, 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 Test-PWSHYBKPIVSignature -Syntax` for the authoritative, current parameter list. .EXAMPLE Test-PWSHYBKPIVSignature -Slot '9a' Tests whether the key in slot 9a can sign and verify data. .LINK https://developers.yubico.com/yubico-piv-tool/Actions/ .LINK Test-PWSHYBKPIVDecryption #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Low')] [OutputType([bool])] param() DynamicParam { $dynamicConfig = Read-PWSHYBKPIVConfigFile Get-PWSHYBKPIVActionParameter -Action 'test-signature' -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("PIV slot $($PSBoundParameters['Slot'])", 'Test signature')) { return } try { $null = Invoke-PWSHYBKPIVTool -ExePath $exePath -Action 'test-signature' ` -CmdletWrapping $config.cmdletWrapping -BoundParameters $PSBoundParameters Write-PWSHYBKPIVLog -Config $config -Level Information -CmdletName $MyInvocation.MyCommand.Name ` -Message 'Signature test succeeded' $true } catch { Write-PWSHYBKPIVLog -Config $config -Level Warning -CmdletName $MyInvocation.MyCommand.Name ` -Message "Signature test failed: $_" $false } } } |