Modules/AzureDevOpsDsc.Common/Api/Functions/Private/Helper/Write-AzDoCacheFile.ps1

<#
.SYNOPSIS
    Writes an object to a file under the cache directory, encrypted where the platform can.
 
.DESCRIPTION
    The one place a cache file is written. The object is serialized as CLIXML, exactly as
    Export-Clixml would, and then:
 
      - on Windows the CLIXML is encrypted with DPAPI for the current account
        (Protect-AzDoCacheData) and written after a short marker (Get-AzDoCacheFileHeader). Only
        the account that wrote the file, on the machine it was written on, can read it back;
      - elsewhere there is no DPAPI, so the CLIXML is written as it is.
 
    On every platform the file is then restricted to its owner (Protect-AzDoCachePath). Outside
    Windows that is the only protection the file has.
 
    If DPAPI cannot encrypt (for example the account's profile is not loaded), the file is written
    as plain CLIXML and a warning says so. A cache that cannot be written would fail every
    resource that changes something, after the change has already been made in Azure DevOps.
 
    The cache holds no secrets (Protect-AzDoCacheSecret). It is encrypted because it describes the
    organization - projects, identities, descriptors, ACLs - which is worth keeping from anyone
    who gets hold of a copy of the disk or a backup.
 
.PARAMETER Path
    The file to write.
 
.PARAMETER InputObject
    The object to serialize.
 
.PARAMETER Depth
    The serialization depth. Default 6, as Export-CacheObject uses.
 
.NOTES
    Read the file back with Read-AzDoCacheFile, not Import-Clixml.
#>

function Write-AzDoCacheFile
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Path,

        # Untyped, so binding does not enumerate or copy a whole cache.
        [Parameter()]
        [AllowNull()]
        [AllowEmptyCollection()]
        [System.Object]
        $InputObject,

        [Parameter()]
        [System.Int32]
        $Depth = 6
    )

    $encrypted = $false

    if (Test-AzDoIsWindows)
    {
        try
        {
            $xml       = [System.Management.Automation.PSSerializer]::Serialize($InputObject, $Depth)
            $protected = Protect-AzDoCacheData -Data ([System.Text.Encoding]::UTF8.GetBytes($xml))
            $header    = Get-AzDoCacheFileHeader

            $bytes = [System.Byte[]]::new($header.Length + $protected.Length)
            [System.Array]::Copy($header, 0, $bytes, 0, $header.Length)
            [System.Array]::Copy($protected, 0, $bytes, $header.Length, $protected.Length)

            [System.IO.File]::WriteAllBytes($Path, $bytes)
            $encrypted = $true
        }
        catch
        {
            Write-Warning "[Write-AzDoCacheFile] Could not encrypt '$Path'; writing it unencrypted, readable by its owner only. $($_.Exception.Message)"
        }
    }

    if (-not $encrypted)
    {
        # Must use -InputObject (not the pipeline): piping an empty collection writes a null file.
        Export-Clixml -InputObject $InputObject -Depth $Depth -LiteralPath $Path
    }

    Protect-AzDoCachePath -Path $Path
}