Skip to content

Amend SE-0292 #1410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Sep 14, 2021
Merged

Amend SE-0292 #1410

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2037e19
Update 0292-package-registry-service.md
mattt Jul 20, 2021
2fb368f
Add discussion about attack vector introduced by source archives
mattt Jul 21, 2021
ff3f830
Fix typo
mattt Jul 26, 2021
529312e
Amend rules for package names
mattt Jul 28, 2021
0b91406
Remove unused <url> argument in package-registry unset subcommand
mattt Aug 4, 2021
7932803
Replace .swiftpm/config with .swiftpm/configuration
mattt Aug 30, 2021
120e544
update amendment information and previous versions
tomerd Sep 14, 2021
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
71 changes: 42 additions & 29 deletions proposals/0292-package-registry-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@
[1](https://forums.swift.org/t/se-0292-package-registry-service/)
[2](https://forums.swift.org/t/se-0292-2nd-review-package-registry-service/)
[3](https://forums.swift.org/t/se-0292-3rd-review-package-registry-service/)
[Amendment](https://forums.swift.org/t/amendment-se-0292-package-registry-service/)
* Previous Revision:
[1](https://github.com/apple/swift-evolution/blob/b48527526b5748a60b0b23846d5880e9cc2c4711/proposals/0292-package-registry-service.md)
[2](https://github.com/apple/swift-evolution/blob/53bd6d3813c40ebd07701727c8cfb6fedd751e2a/proposals/0292-package-registry-service.md)
[3](https://github.com/apple/swift-evolution/blob/971d1f43bce718a45227432782a312cc5de99870/proposals/0292-package-registry-service.md)

## Introduction

Expand Down Expand Up @@ -157,19 +159,17 @@ A valid package scope matches the following regular expression pattern:
```

A package's *name* uniquely identifies a package in a scope.
The maximum length of a package name is 128 characters.
A valid package name matches the following regular expression pattern:
A package name consists of alphanumeric characters, underscores, and hyphens.
Hyphens and underscores may not occur at the beginning or end,
nor consecutively within a name.
The maximum length of a package name is 100 characters.
A valid package scope matches the following regular expression pattern:

```regexp
\A\p{XID_Start}\p{XID_Continue}{0,127}\z
\A[a-zA-Z0-9](?:[a-zA-Z0-9]|[-_](?=[a-zA-Z0-9])){0,99}\z
```

> For more information,
> see [Unicode Identifier and Pattern Syntax][UAX31].

Package names are compared using
[Normalization Form Compatible Composition (NFKC)][UAX15]
with locale-independent case folding.
Package scopes and names are compared using locale-independent case folding.

#### New `PackageDescription` API

Expand Down Expand Up @@ -403,12 +403,16 @@ $ swift package archive-source --output="LinkedList-1.2.0.zip"
```

The `archive-source` subcommand has the equivalent behavior of
[`git-archive(1)`] using the `zip` format at its default compression level.
[`git-archive(1)`] using the `zip` format at its default compression level,
with entries prefixed by the basename of the generated archive's filename.
Therefore, the following command produces
equivalent output to the previous example:

```console
$ git archive --format zip --output LinkedList-1.2.0.zip 1.2.0
$ git archive --format zip \
--prefix LinkedList-1.2.0
--output LinkedList-1.2.0.zip \
1.2.0
```

If desired, this behavior could be changed in future tool versions.
Expand Down Expand Up @@ -453,7 +457,7 @@ OPTIONS:

Running the `package-registry set` subcommand
in the root directory of a package
creates or updates the `.swiftpm/config/registries.json` file
creates or updates the `.swiftpm/configuration/registries.json` file
with a new top-level `registries` key
that's associated with an object containing the specified registry URLs.
The default, unscoped registry is associated with the key `[default]`.
Expand All @@ -466,7 +470,7 @@ using an internal registry service.

```console
$ swift package-registry set https://internal.example.com/
$ cat .swiftpm/config/registries.json
$ cat .swiftpm/configuration/registries.json
```

```json
Expand Down Expand Up @@ -503,7 +507,7 @@ to a private registry.

```console
$ swift package-registry set https://internal.example.com/ --scope example
$ cat .swiftpm/config/registries.json
$ cat .swiftpm/configuration/registries.json
```

```json
Expand Down Expand Up @@ -531,15 +535,15 @@ to complement the `package-registry set` subcommand.

```manpage
SYNOPSIS
swift package-registry unset <url> [options]
swift package-registry unset [options]
OPTIONS:
--global Apply settings to all projects for this user
--scope Removes the registry's association to a given scope
```

Running the `package-registry unset` subcommand
in the root directory of a package
updates the `.swiftpm/config/registries.json` file
updates the `.swiftpm/configuration/registries.json` file
to remove the `default` entry in the top-level `registries` key, if present.
If a `--scope` option is passed,
only the entry for the specified scope is removed, if present.
Expand All @@ -548,15 +552,15 @@ only the entry for the specified scope is removed, if present.

The user can pass the `--global` option to the `set` or `unset` subcommands
to update the user-level configuration file located at
`~/.swiftpm/config/registries.json`.
`~/.swiftpm/configuration/registries.json`.

Any default or scoped registries configured locally in a project directory
override any values configured globally for the user.
For example,
consider the following global and local registry configuration files:

```jsonc
// Global configuration (~/.swiftpm/config/registries.json)
// Global configuration (~/.swiftpm/configuration/registries.json)
{
"registries": {
"[default]": {
Expand All @@ -569,7 +573,7 @@ consider the following global and local registry configuration files:
"version": 1
}

// Local configuration (.swiftpm/config/registries.json)
// Local configuration (.swiftpm/configuration/registries.json)
{
"registries": {
"foo": {
Expand All @@ -594,8 +598,8 @@ in descending order of precedence:

* The package manifest in the current directory (`./Package.swift`)
* Any existing lock file (`./Package.resolved`)
* Any local configuration (`./.swiftpm/config/registries.json`)
* Any global configuration file (`~/.swiftpm/config/registries.json`)
* Any local configuration (`./.swiftpm/configuration/registries.json`)
* Any global configuration file (`~/.swiftpm/configuration/registries.json`)

#### Specifying credentials for a custom registry

Expand All @@ -622,7 +626,7 @@ machine internal.example.com
login jappleseed
password alpine

$ cat .swiftpm/config/registries.json
$ cat .swiftpm/configuration/registries.json

{
"registries": {
Expand Down Expand Up @@ -664,7 +668,7 @@ $ swift package config set-mirror \
This proposal updates the `swift package config set-mirror` subcommand
to accept a `--package-identifier` option in place of an `--original-url`.
Running this subcommand with a `--package-identifier` option
creates or updates the `.swiftpm/config/mirrors.json` file,
creates or updates the `.swiftpm/configuration/mirrors.json` file,
modifying the array associated with the top-level `object` key
to add a new entry or update an existing entry
for the specified package identifier,
Expand Down Expand Up @@ -788,6 +792,17 @@ A registry can further improve on this model by implementing a
or another comparable, tamper-proof system
for authenticating package contents.

Distribution of packages through Zip files
introduces new potential attack vectors.
For example,
an attacker could maliciously tamper with a generated source archive
in an attempt to exploit
a known vulnerability like [Zip Slip],
or a common software weakness like susceptibility to a [Zip bomb].
Swift Package Manager should take care to
identify and protect against these kinds of attacks
in its implementation of source archive decompression.
Comment on lines +802 to +804
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@robertlacroix What we have right now with ZipArchiver delegates to unzip:

https://github.com/apple/swift-tools-support-core/blob/435a2708a6e486d69ea7d7aaa3f4ad243bc3b408/Sources/TSCUtility/Archiver.swift#L65

Right now, we're using this only for user-specified source files in binary targets. Do you think we should do anything differently in support of archives sent from the package registry?


### Repudiation

A compromised host could serve a malicious package with a valid checksum
Expand Down Expand Up @@ -856,7 +871,7 @@ when displaying feedback to the user.
### Denial of service

An attacker could scrape public code repositories
for `.swiftpm/config/registries.json` files
for `.swiftpm/configuration/registries.json` files
that declare one or more custom registries
and launch a denial-of-service attack
in an attempt to reduce the availability of those resources.
Expand All @@ -878,7 +893,7 @@ but could be used in a targeted way
against resources known to be important or expensive to distribute.

This kind of attack can be mitigated on an individual basis
by adding `.swiftpm/config` to a project's `.gitignore` file.
by adding `.swiftpm/configuration` to a project's `.gitignore` file.

### Escalation of privilege

Expand Down Expand Up @@ -1242,12 +1257,10 @@ RegEx (github.com/mona/RegEx) - Expressions on the reg.
[TOFU]: https://en.wikipedia.org/wiki/Trust_on_first_use "Trust on First Use"
[transparent log]: https://research.swtch.com/tlog
[typosquatting]: https://en.wikipedia.org/wiki/Typosquatting
[UAX15]: http://www.unicode.org/reports/tr15/ "Unicode Technical Report #15: Unicode Normalization Forms"
[UAX18]: http://www.unicode.org/reports/tr18/ "Unicode Technical Report #18: Unicode Regular Expressions"
[UAX31]: http://www.unicode.org/reports/tr31/ "Unicode Technical Report #31: Unicode Identifier and Pattern Syntax"
[UAX36]: http://www.unicode.org/reports/tr36/ "Unicode Technical Report #36: Unicode Security Considerations"
[UTI]: https://en.wikipedia.org/wiki/Uniform_Type_Identifier
[version-specific-manifest-selection]: https://github.com/apple/swift-package-manager/blob/main/Documentation/Usage.md#version-specific-manifest-selection "Swift Package Manager - Version-specific Manifest Selection"
[version-specific-tag-selection]: https://github.com/apple/swift-package-manager/blob/main/Documentation/Usage.md#version-specific-tag-selection "Swift Package Manager - Version-specific Tag Selection"
[XCFramework]: https://developer.apple.com/videos/play/wwdc2019/416/ "WWDC 2019 Session 416: Binary Frameworks in Swift"
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[Zip bomb]: https://en.wikipedia.org/wiki/Zip_bomb "Zip bomb"
[Zip Slip]: https://snyk.io/research/zip-slip-vulnerability "Zip Slip Vulnerability"