Public/Set-PWSHYBKPIVObject.ps1
|
function Set-PWSHYBKPIVObject { <# .SYNOPSIS Writes raw data to a data object of a locally attached YubiKey's PIV application. .DESCRIPTION Wraps "yubico-piv-tool.exe --action write-object". Overwrites any data already present at the target object ID with no way to recover it, so this cmdlet supports -WhatIf/-Confirm with ConfirmImpact 'High'. Throws on failure rather than returning a value, matching Set- verb convention. Accepts the "write-object" action's config-declared options (-ObjectId, -Input, -Format, -ManagementKey, -Reader) as dynamic parameters built from Config\Posh-YBKPIV.json. .PARAMETER ObjectId The numeric ID of the data object to write to. .PARAMETER Input Path to the file containing the data to write. .PARAMETER Format Encoding format of the input data: hex, base64, or binary. Defaults to hex 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 None. Throws a terminating error on failure; produces no output on success. .NOTES -ObjectId, -Input, -Format, -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-PWSHYBKPIVObject -Syntax` for the authoritative, current parameter list. .EXAMPLE Set-PWSHYBKPIVObject -ObjectId 0x5FC109 -Input 'C:\data\object.bin' Writes the contents of object.bin to object 0x5FC109 after confirmation. .LINK https://developers.yubico.com/yubico-piv-tool/Actions/ .LINK Get-PWSHYBKPIVObject #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] param() DynamicParam { $dynamicConfig = Read-PWSHYBKPIVConfigFile Get-PWSHYBKPIVActionParameter -Action 'write-object' -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 { $objectDescription = "object $($PSBoundParameters['ObjectId'])" if (-not $PSCmdlet.ShouldProcess($objectDescription, 'Write object')) { return } try { $null = Invoke-PWSHYBKPIVTool -ExePath $exePath -Action 'write-object' ` -CmdletWrapping $config.cmdletWrapping -BoundParameters $PSBoundParameters Write-PWSHYBKPIVLog -Config $config -Level Information -CmdletName $MyInvocation.MyCommand.Name ` -Message "Data written to $objectDescription" } catch { Write-PWSHYBKPIVLog -Config $config -Level Error -CmdletName $MyInvocation.MyCommand.Name -Message "Object write failed: $_" throw } } } |