Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions docs/specs/ClickOnce-Signing-Algorithm.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,19 +238,20 @@ Apply the application-manifest flows below only to files identified as ClickOnce
#### Deployment-manifest input

1. Read the file using [`ManifestReader.ReadManifest(...)`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.manifestreader.readmanifest?view=msbuild-17-netcore#microsoft-build-tasks-deployment-manifestutilities-manifestreader-readmanifest(system-io-stream-system-boolean)). If reading fails or the returned [`Manifest`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.manifest?view=msbuild-17-netcore) is not a [`DeployManifest`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.deploymanifest?view=msbuild-17-netcore), fail the operation without signing the file.
1. Before resolving files, require exactly one assembly dependency and no file references. The sole assembly dependency must be [`DeployManifest.EntryPoint`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.deploymanifest.entrypoint?view=msbuild-17-netcore), must represent the application manifest, and must not be a prerequisite, optional, or resource-fallback dependency. Inspect the preserved manifest XML for resource-fallback attributes because `ManifestUtilities` does not expose or preserve them in its object model. Fail with a clear error and suggest `--clickonce-signing-version 2 --no-update-clickonce-manifest` if the reference structure does not satisfy these ClickOnce runtime requirements. This fail-fast validation also prevents `ManifestUtilities` or `mage.exe` from reordering or rewriting unsupported references before signing.
1. Ensure [`Manifest.ReadOnly`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.manifest.readonly?view=msbuild-17-netcore) is `false` so the deployment manifest can be updated.
1. Call [`DeployManifest.ResolveFiles(string[])`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.manifest.resolvefiles?view=msbuild-17-netcore) with the deployment manifest's directory to resolve its references, including the application-manifest entry point.
1. Log all messages in [`Manifest.OutputMessages`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.manifest.outputmessages?view=msbuild-17-netcore). Continue when diagnostics do not prevent resolving required files; otherwise fail with a clear error.
1. Obtain the full path of the application manifest file from [`DeployManifest.EntryPoint`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.deploymanifest.entrypoint?view=msbuild-17-netcore)[`.ResolvedPath`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.basereference.resolvedpath?view=msbuild-17-netcore#microsoft-build-tasks-deployment-manifestutilities-basereference.resolvedpath). If the path is empty or the file does not exist, fail signing with an error message that identifies the expected path and suggests `--clickonce-signing-version 2 --no-update-clickonce-manifest` when the user only needs to re-sign the deployment manifest.
1. Read the application manifest file using `ManifestReader.ReadManifest(...)`. If reading fails or the returned manifest is not an [`ApplicationManifest`](https://learn.microsoft.com/dotnet/api/microsoft.build.tasks.deployment.manifestutilities.applicationmanifest?view=msbuild-17-netcore), fail with a clear error. Ensure `Manifest.ReadOnly` is `false`.
1. Identify each application-manifest `AssemblyReference` and `FileReference` that represents a physical file published with the application, following the file-extension mapping rules above and searching the application manifest's directory first, then the deployment manifest's directory as a fallback (if different). Log all `OutputMessages` produced by resolution attempts. Continue when diagnostics do not prevent locating required files; otherwise fail with a clear error.
1. Identify each application-manifest `AssemblyReference` and `FileReference` that represents a physical file published with the application, following the file-extension mapping rules above and searching the application manifest's directory first, then the deployment manifest's directory as a fallback (if different). Use these Sign CLI lookup rules directly for source discovery rather than calling `ApplicationManifest.ResolveFiles(...)`, whose lookup semantics do not account for file-extension mapping or deployment-directory fallback. A failed intermediate candidate probe is not a diagnostic when a later allowed candidate resolves the reference. Fail with a clear error if no allowed candidate locates a required file.
1. Ensure staged files preserve their manifest-relative paths without writing outside the staging directory. If Sign CLI cannot represent a referenced layout within staging, fail before copying files and report that the layout is unsupported.
1. Copy the deployment manifest, application manifest, and located payload files to a temporary directory. Stage each payload at its manifest target path relative to the staged application manifest while preserving any mapping-added suffix.
1. Temporarily remove mapping-added suffixes from the staged payloads.
1. Before signing or updating manifest metadata, ensure that the application manifest's references resolve to the corresponding staged files. No `ResolvedPath` used by `UpdateFileInfo(...)` may identify a source file outside the staging directory. How the implementation establishes the staged paths is an implementation detail. Fail if any required staged file cannot be resolved.
1. Resolve the application manifest's references against the staged application directory using `ApplicationManifest.ResolveFiles(string[])`. Log every newly produced `OutputMessage`. Warnings are non-fatal; fail without signing any payload or updating or signing the application manifest if any newly produced message is an error. Independently verify that every required physical reference's `ResolvedPath` identifies its corresponding suffix-stripped staged file and remains within the staging directory; resolution to a different file does not satisfy this postcondition.
1. Treat any `Launcher.exe` referenced by the application manifest, including as its entry point, as a payload file. It must be staged and, when selected by the user's file-matching patterns, signed with the other selected payloads before application-manifest metadata is refreshed. Separately discover applicable adjacent executables by checking if `setup.exe` or an unreferenced `Launcher.exe` exists in the same directory as the deployment manifest. A launcher or bootstrapper in a different directory or with a different name is not implicitly discovered as an adjacent executable, but it will still be signed through standard Authenticode signing if matched by the user's file patterns.
1. Apply the standard signing behavior only to payloads selected by the user's file-matching patterns; leave excluded or unsupported payloads unchanged. Include every referenced payload when refreshing application-manifest metadata.
1. Call `ApplicationManifest.UpdateFileInfo("v4.5")` to refresh payload SHA-256 hashes and sizes, then restore the mapping-added suffixes. (`UpdateFileInfo(string)` hashes each reference's current `ResolvedPath`; ensure those paths identify the staged, suffix-stripped payloads before calling it.) For each payload that was signed, make its result available and complete its coordinated signing operation. Then sign the application manifest, make its signed result available, and complete its operation.
1. Immediately before calling `ApplicationManifest.UpdateFileInfo("v4.5")`, verify again that every required physical reference's `ResolvedPath` identifies its expected suffix-stripped staged file, that the file exists, and that it remains within the staging directory. Then refresh payload SHA-256 hashes and sizes and restore the mapping-added suffixes. (`UpdateFileInfo(string)` hashes each reference's current `ResolvedPath`.) For each payload that was signed, make its result available and complete its coordinated signing operation. Then sign the application manifest, make its signed result available, and complete its operation.
1. Signing the application manifest changes its signed bytes and can change its assembly identity, including its public key token. Ensure that the deployment manifest's entry-point `ResolvedPath` identifies the signed staged application manifest, then call `DeployManifest.UpdateFileInfo("v4.5")` to refresh the entry-point reference's SHA-256 hash and size. Ensure that the entry-point identity matches the signed application manifest before signing the deployment manifest. When signing the deployment manifest with `mage.exe -update`, the `-appm` parameter performs this entry-point update. Make the signed deployment manifest available and complete its operation.
1. Apply the standard signing behavior to applicable adjacent executables selected by the user's file-matching patterns, make their signed results available, and complete their operations.
1. Copy any remaining signed files back to their original locations and clean up the staging directory.
Expand All @@ -259,13 +260,13 @@ Apply the application-manifest flows below only to files identified as ClickOnce

1. Read the file using `ManifestReader.ReadManifest(...)`. If reading fails or the returned manifest is not an `ApplicationManifest`, fail the operation without signing the file.
1. Ensure `Manifest.ReadOnly` is `false`.
1. Identify each `AssemblyReference` and `FileReference` that represents a physical file published with the application. Look for its manifest target path relative to the application manifest's directory first; if that path does not exist, look for the same path with one additional `.deploy` suffix and record that suffix as mapping-added. Log all `OutputMessages` produced by resolution attempts. Continue when diagnostics do not prevent locating required files; otherwise fail with a clear error.
1. Identify each `AssemblyReference` and `FileReference` that represents a physical file published with the application. Look for its manifest target path relative to the application manifest's directory first; if that path does not exist, look for the same path with one additional `.deploy` suffix and record that suffix as mapping-added. Use these Sign CLI lookup rules directly for source discovery rather than calling `ApplicationManifest.ResolveFiles(...)`, whose lookup semantics do not account for file-extension mapping. A failed exact-path probe is not a diagnostic when the mapped candidate resolves the reference. Fail with a clear error if neither candidate locates a required file.
1. Ensure staged files preserve their manifest-relative paths without writing outside the staging directory. If Sign CLI cannot represent a referenced layout within staging, fail before copying files and report that the layout is unsupported.
1. Copy the application manifest and located payload files to a temporary directory. Stage each payload at its manifest target path relative to the staged application manifest while preserving any mapping-added suffix.
1. Temporarily remove mapping-added suffixes from the staged payloads.
1. Before signing or updating manifest metadata, ensure that the application manifest's references resolve to the corresponding staged files. No `ResolvedPath` used by `UpdateFileInfo(...)` may identify a source file outside the staging directory. How the implementation establishes the staged paths is an implementation detail. Fail if any required staged file cannot be resolved.
1. Resolve the application manifest's references against the staged application directory using `ApplicationManifest.ResolveFiles(string[])`. Log every newly produced `OutputMessage`. Warnings are non-fatal; fail without signing any payload or updating or signing the application manifest if any newly produced message is an error. Independently verify that every required physical reference's `ResolvedPath` identifies its corresponding suffix-stripped staged file and remains within the staging directory; resolution to a different file does not satisfy this postcondition.
1. Apply the standard signing behavior only to payloads selected by the user's file-matching patterns; leave excluded or unsupported payloads unchanged. Include every referenced payload when refreshing application-manifest metadata.
1. Call `ApplicationManifest.UpdateFileInfo("v4.5")` and restore the mapping-added suffixes. For each payload that was signed, make its result available and complete its coordinated signing operation.
1. Immediately before calling `ApplicationManifest.UpdateFileInfo("v4.5")`, verify again that every required physical reference's `ResolvedPath` identifies its expected suffix-stripped staged file, that the file exists, and that it remains within the staging directory. Then update the file information and restore the mapping-added suffixes. For each payload that was signed, make its result available and complete its coordinated signing operation.
1. Sign the application manifest, make its signed result available, and complete its operation.
1. Copy any remaining signed files back to their original locations and clean up the staging directory.

Expand Down
Loading