# VehicleHelper Windows signing runbook

Artifact version: `consent_0133`

## Outcome

Sign the final Windows release bytes with a publicly trusted RSA code-signing identity, add an RFC 3161 SHA-256 timestamp, verify the Authenticode chain, and only then create the Cloud release candidate.

Signing improves publisher trust and lets SmartScreen reputation accumulate. It does **not** guarantee that a new publisher or new file hash will immediately avoid the “unrecognized app” prompt. EV certificates no longer receive an automatic first-download SmartScreen bypass. A self-signed certificate is not suitable for public downloads.

## Choose the signing identity

1. **Microsoft Artifact Signing, Public Trust** — use this when the publisher is eligible in a currently supported region. It keeps the private key in Microsoft’s managed service and is the cleanest CI option.
2. **OV RSA code-signing certificate from a public CA** — use this when Artifact Signing Public Trust is unavailable for the publisher’s legal region. Keep the private key in the CA-provided token/HSM or remote signing service.
3. **Microsoft Store MSIX** — the strongest SmartScreen outcome when Store distribution fits the product.

Do not buy EV solely to bypass SmartScreen; Microsoft documents that OV and EV now have the same reputation-building behavior. Smart App Control currently requires RSA rather than ECC signatures.

## Build/sign/release order

1. Build the immutable `win-x64` release with a unique mnemonic version.
2. Sign every shipped PE file after its final modification. At minimum sign `VehicleHelper.exe`; also sign separately shipped/extracted helper EXEs and DLLs.
3. Timestamp with SHA-256. Artifact Signing certificates are short-lived, so a valid timestamp is mandatory.
4. Verify with both `signtool verify /pa /all /v` and `Get-AuthenticodeSignature`.
5. Record SHA-256 **after signing**.
6. Zip/package without changing the signed files, upload the candidate, then complete the existing `artheru` approval gate.
7. Test the actual downloaded file on a clean Windows 11 machine, including all code paths that launch helper binaries.

Never sign an artifact whose source, dependency lock, build log, or final hash is unknown. Never place a PFX password in a command line, repository, OA page, or CI log.

## Script: certificate in the Windows certificate store

Install the Windows SDK and make the RSA code-signing certificate available through its CSP/KSP. Then run:

```powershell
.\Sign-WindowsRelease.ps1 `
  -BinaryPath .\VehicleHelper.exe `
  -CertificateThumbprint 'YOUR_CERTIFICATE_THUMBPRINT'
```

The script intentionally accepts a certificate-store thumbprint rather than a PFX password.

## Script: Microsoft Artifact Signing

Complete public identity validation, create a Public Trust certificate profile, install the latest `Microsoft.ArtifactSigning.Client`, and create `metadata.json`:

```json
{
  "Endpoint": "https://YOUR_REGION.codesigning.azure.net",
  "CodeSigningAccountName": "YOUR_ACCOUNT",
  "CertificateProfileName": "YOUR_PROFILE"
}
```

Authenticate using an Artifact Signing-supported Azure Identity method and run:

```powershell
.\Sign-WindowsRelease.ps1 `
  -BinaryPath .\VehicleHelper.exe `
  -MetadataPath .\metadata.json `
  -DlibPath .\Microsoft.ArtifactSigning.Client\bin\x64\Azure.CodeSigning.Dlib.dll
```

The x64 SignTool and x64 dlib must match. The metadata endpoint must match the account region.

## Release verification

```powershell
signtool.exe verify /pa /all /v .\VehicleHelper.exe
Get-AuthenticodeSignature .\VehicleHelper.exe | Format-List Status,StatusMessage,SignerCertificate,TimeStamperCertificate
Get-FileHash -Algorithm SHA256 .\VehicleHelper.exe
```

Expected result: SignTool exits `0`, PowerShell reports `Status: Valid`, the publisher is the validated legal identity, a timestamp certificate is present, and the recorded hash matches the uploaded candidate.

## Microsoft references

- [SmartScreen reputation for Windows app developers](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/smartscreen-reputation)
- [Code signing options for Windows app developers](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/code-signing-options)
- [Artifact Signing setup quickstart](https://learn.microsoft.com/en-us/azure/artifact-signing/quickstart)
- [Artifact Signing integration with SignTool](https://learn.microsoft.com/en-us/azure/artifact-signing/how-to-signing-integrations)
- [SignTool command reference](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool)
- [Test signatures with Smart App Control](https://learn.microsoft.com/en-us/windows/apps/develop/smart-app-control/test-your-app-with-smart-app-control)