Public/New-PWSHYBKPIVKey.ps1
|
function New-PWSHYBKPIVKey { <# .SYNOPSIS Generates a new key pair in a PIV slot of a locally attached YubiKey. .DESCRIPTION Wraps "yubico-piv-tool.exe --action generate". Generating a key overwrites any key already present in the target slot with no way to recover it, so this cmdlet supports -WhatIf/-Confirm with ConfirmImpact 'High'. Accepts the "generate" action's config-declared options (-Slot, -Algorithm, -PinPolicy, -TouchPolicy, -Output, -ManagementKey, -Reader) as dynamic parameters built from Config\Posh-YBKPIV.json. .PARAMETER Slot The PIV slot to generate the key in, e.g. '9a'. .PARAMETER Algorithm Key algorithm to generate: RSA1024, RSA2048, RSA3072, RSA4096, ECCP256, ECCP384, ED25519, or X25519. Defaults to RSA2048 when omitted. .PARAMETER PinPolicy PIN policy to apply to the generated key: never, once, always, matchonce, or matchalways. .PARAMETER TouchPolicy Touch policy to apply to the generated key: never, always, or cached. .PARAMETER Output Path to write the generated public key to. Defaults to '-' (stdout) when omitted. .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 String[]. yubico-piv-tool.exe's raw output - the generated public key, unless -Output redirects it to a file. .NOTES -Slot, -Algorithm, -PinPolicy, -TouchPolicy, -Output, -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 New-PWSHYBKPIVKey -Syntax` for the authoritative, current parameter list. .EXAMPLE New-PWSHYBKPIVKey -Slot '9a' -Algorithm ECCP256 Generates an ECCP256 key pair in slot 9a after confirmation. .LINK https://developers.yubico.com/yubico-piv-tool/Actions/ .LINK Remove-PWSHYBKPIVKey .LINK Move-PWSHYBKPIVKey .LINK Import-PWSHYBKPIVKey #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] [OutputType([string[]])] param() DynamicParam { $dynamicConfig = Read-PWSHYBKPIVConfigFile Get-PWSHYBKPIVActionParameter -Action 'generate' -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 { $slotDescription = "PIV slot $($PSBoundParameters['Slot'])" if (-not $PSCmdlet.ShouldProcess($slotDescription, 'Generate key')) { return } try { $result = Invoke-PWSHYBKPIVTool -ExePath $exePath -Action 'generate' ` -CmdletWrapping $config.cmdletWrapping -BoundParameters $PSBoundParameters Write-PWSHYBKPIVLog -Config $config -Level Information -CmdletName $MyInvocation.MyCommand.Name ` -Message "Key generated in $slotDescription" $result.Output } catch { Write-PWSHYBKPIVLog -Config $config -Level Error -CmdletName $MyInvocation.MyCommand.Name -Message "Key generation failed: $_" throw } } } |