Port contents of `Documentation/PackageSecurity.md` to DocC #8726

bripeticca · 2025-05-26T19:00:27Z

Ports the contents of Documentation/PackageSecurity.md to our DocC catalog in Sources/PackageManagerDocs/PackageSecurity.md.

bripeticca · 2025-05-26T19:00:35Z

@swift-ci please test

bripeticca · 2025-05-27T15:29:04Z

@swift-ci please test

bripeticca · 2025-05-27T17:43:23Z

@swift-ci please test windows

heckj · 2025-05-28T15:30:24Z

@swift-ci please test windows platform self hosted

heckj · 2025-05-28T15:31:35Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

@@ -0,0 +1,50 @@
+# Package Security
+
+Learn about the security features that SwiftPM implements.


Suggested change

Learn about the security features that SwiftPM implements.

Learn about the security features that the package manager implements.

(I've been taking to removing SwiftPM and replacing it with "package manager")

heckj · 2025-05-28T15:32:07Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+
+## Trust on First Use
+
+SwiftPM records **fingerprints** of downloaded package versions so that


Suggested change

SwiftPM records **fingerprints** of downloaded package versions so that

Package manager records **fingerprints** of downloaded package versions so that

heckj · 2025-05-28T15:32:25Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+SwiftPM records **fingerprints** of downloaded package versions so that
+it can perform [trust-on-first-use](https://en.wikipedia.org/wiki/Trust_on_first_use)
+(TOFU). 
+That is, when a package version is downloaded for the first time, SwiftPM trusts that 


Suggested change

That is, when a package version is downloaded for the first time, SwiftPM trusts that

That is, when a package version is downloaded for the first time, the package manager trusts that

heckj · 2025-05-28T15:33:04Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+it has downloaded the correct contents and requires subsequent downloads of the same 
+package version to have the same fingerprint. 
+If the fingerprint changes, it might be an indicator that the package has been
+compromised and SwiftPM will either warn or return an error.


Suggested change

compromised and SwiftPM will either warn or return an error.

compromised and the package manager either warns or returns an error.

Control the choice of warning or error using the build option `--resolver-fingerprint-checking`, which defaults to `strict`.

Set the value to `warn` to not error on a mismatched fingerprint.

heckj · 2025-05-28T15:35:12Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+| Git repository         | Git hash of the revision |
+| Package registry       | Checksum of the source archive |
+
+All version fingerprints of a package are kept in a single file


Suggested change

All version fingerprints of a package are kept in a single file

The package manager keeps version fingerprints for each package in a file

heckj · 2025-05-28T15:35:41Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+
+All version fingerprints of a package are kept in a single file
+under the `~/.swiftpm/security/fingerprints` directory.
+  - For a Git repository package, the fingerprint filename takes the form of `{PACKAGE_NAME}-{REPOSITORY_URL_HASH}.json` (e.g., `LinkedList-5ddbcf15.json`).


Suggested change

- For a Git repository package, the fingerprint filename takes the form of `{PACKAGE_NAME}-{REPOSITORY_URL_HASH}.json` (e.g., `LinkedList-5ddbcf15.json`).

- For a Git repository package, the fingerprint filename takes the form of `{PACKAGE_NAME}-{REPOSITORY_URL_HASH}.json` (such as `LinkedList-5ddbcf15.json`).

heckj · 2025-05-28T15:35:56Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+All version fingerprints of a package are kept in a single file
+under the `~/.swiftpm/security/fingerprints` directory.
+  - For a Git repository package, the fingerprint filename takes the form of `{PACKAGE_NAME}-{REPOSITORY_URL_HASH}.json` (e.g., `LinkedList-5ddbcf15.json`).
+  - For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (e.g., `mona.LinkedList.json`).


Suggested change

- For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (e.g., `mona.LinkedList.json`).

- For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (such as `mona.LinkedList.json`).

heckj · 2025-05-28T15:40:42Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+under the `~/.swiftpm/security/fingerprints` directory.
+  - For a Git repository package, the fingerprint filename takes the form of `{PACKAGE_NAME}-{REPOSITORY_URL_HASH}.json` (e.g., `LinkedList-5ddbcf15.json`).
+  - For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (e.g., `mona.LinkedList.json`).
+


Suggested change

For packages retrieved from a registry, the package manager expects all registries to provide consistent fingerprints for packages they host.

If registries have conflicting fingerprints, package manager reports that as an error.

heckj · 2025-05-28T15:41:32Z

Sources/PackageManagerDocs/Documentation.docc/PackageSecurity.md

+  - For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (e.g., `mona.LinkedList.json`).
+
+
+### Using fingerprints for TOFU


Everything from line 30 (heading included) is replicated content from above - I made some suggestions to cherry pick a few details in the content above, and I think everything below can be deleted. Give it a read through and verify though.

bripeticca added 2 commits May 26, 2025 14:55

Initial port of package security article

ab792d1

Format each sentence on new line for ease of review

b61f501

bripeticca added 2 commits May 27, 2025 11:19

Merge branch 'main' into pkgsecurity

24dfebc

Fix package security summary + grammar

03f3345

bripeticca marked this pull request as ready for review May 27, 2025 15:29

bripeticca requested review from jakepetroules, dschaefer2, shawnhyam, plemarquand, owenv, bkhouri, cmcgee1024 and daveyc123 as code owners May 27, 2025 15:29

bripeticca requested a review from heckj May 27, 2025 15:29

bripeticca added the documentation label May 27, 2025

heckj reviewed May 28, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Port contents of `Documentation/PackageSecurity.md` to DocC #8726

Port contents of `Documentation/PackageSecurity.md` to DocC #8726

Uh oh!

bripeticca commented May 26, 2025

Uh oh!

bripeticca commented May 26, 2025

Uh oh!

bripeticca commented May 27, 2025

Uh oh!

bripeticca commented May 27, 2025

Uh oh!

heckj commented May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

heckj May 28, 2025

Uh oh!

Uh oh!

		@@ -0,0 +1,50 @@
		# Package Security

		Learn about the security features that SwiftPM implements.

	Learn about the security features that SwiftPM implements.
	Learn about the security features that the package manager implements.


		## Trust on First Use

		SwiftPM records fingerprints of downloaded package versions so that

	SwiftPM records fingerprints of downloaded package versions so that
	Package manager records fingerprints of downloaded package versions so that

	That is, when a package version is downloaded for the first time, SwiftPM trusts that
	That is, when a package version is downloaded for the first time, the package manager trusts that

-compromised and SwiftPM will either warn or return an error.
+compromised and the package manager either warns or returns an error.
+Control the choice of warning or error using the build option `--resolver-fingerprint-checking`, which defaults to `strict`.
+Set the value to `warn` to not error on a mismatched fingerprint.

	All version fingerprints of a package are kept in a single file
	The package manager keeps version fingerprints for each package in a file

	- For a Git repository package, the fingerprint filename takes the form of `{PACKAGE_NAME}-{REPOSITORY_URL_HASH}.json` (e.g., `LinkedList-5ddbcf15.json`).
	- For a Git repository package, the fingerprint filename takes the form of `{PACKAGE_NAME}-{REPOSITORY_URL_HASH}.json` (such as `LinkedList-5ddbcf15.json`).

	- For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (e.g., `mona.LinkedList.json`).
	- For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (such as `mona.LinkedList.json`).


	For packages retrieved from a registry, the package manager expects all registries to provide consistent fingerprints for packages they host.
	If registries have conflicting fingerprints, package manager reports that as an error.

		- For a registry package, the fingerprint filename takes the form of `{PACKAGE_ID}.json` (e.g., `mona.LinkedList.json`).


		### Using fingerprints for TOFU

Port contents of Documentation/PackageSecurity.md to DocC #8726

Are you sure you want to change the base?

Port contents of Documentation/PackageSecurity.md to DocC #8726

Uh oh!

Conversation

bripeticca commented May 26, 2025

Uh oh!

bripeticca commented May 26, 2025

Uh oh!

bripeticca commented May 27, 2025

Uh oh!

bripeticca commented May 27, 2025

Uh oh!

heckj commented May 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Port contents of `Documentation/PackageSecurity.md` to DocC #8726

Port contents of `Documentation/PackageSecurity.md` to DocC #8726