|
6 | 6 |
|
7 | 7 | Add a new collection. |
8 | 8 |
|
| 9 | +## Overview |
| 10 | + |
| 11 | +This subcommand adds a package collection hosted on the web (HTTPS required): |
| 12 | + |
| 13 | +```bash |
| 14 | +$ swift package-collection add https://www.example.com/packages.json |
| 15 | +Added "Sample Package Collection" to your package collections. |
| 16 | +``` |
| 17 | + |
| 18 | +Or found in the local file system: |
| 19 | + |
| 20 | +```bash |
| 21 | +$ swift package-collection add file:///absolute/path/to/packages.json |
| 22 | +Added "Sample Package Collection" to your package collections. |
| 23 | +``` |
| 24 | + |
| 25 | +The optional `order` hint can be used to order collections and may potentially influence ranking in search results: |
| 26 | + |
| 27 | +```bash |
| 28 | +$ swift package-collection add https://www.example.com/packages.json [--order N] |
| 29 | +Added "Sample Package Collection" to your package collections. |
| 30 | +``` |
| 31 | + |
| 32 | +### Signed package collections |
| 33 | + |
| 34 | +Package collection publishers may [sign a collection to protect its contents](<doc:PackageCollections#Signing-and-protecting-package-collections>) from being tampered with. |
| 35 | +If a collection is signed, SwiftPM will check that the |
| 36 | +signature is valid before importing it and return an error if any of these fails: |
| 37 | +- The file's contents, signature excluded, must match what was used to generate the signature. |
| 38 | +In other words, this checks to see if the collection has been altered since it was signed. |
| 39 | +- The signing certificate must meet all the [requirements](<doc:PackageCollections#Requirements-on-signing-certificate>). |
| 40 | + |
| 41 | +```bash |
| 42 | +$ swift package-collection add https://www.example.com/bad-packages.json |
| 43 | +The collection's signature is invalid. If you would like to continue please rerun command with '--skip-signature-check'. |
| 44 | +``` |
| 45 | +
|
| 46 | +Users may continue adding the collection despite the error or preemptively skip the signature check on a package collection by passing the `--skip-signature-check` flag: |
| 47 | +
|
| 48 | +```bash |
| 49 | +$ swift package-collection add https://www.example.com/packages.json --skip-signature-check |
| 50 | +``` |
| 51 | +
|
| 52 | +For package collections hosted on the web, publishers may ask SwiftPM to [enforce the signature requirement](<doc:PackageCollections#Protecting-package-collections>). If a package collection is |
| 53 | +expected to be signed but it isn't, user will see the following error message: |
| 54 | + |
| 55 | +```bash |
| 56 | +$ swift package-collection add https://www.example.com/bad-packages.json |
| 57 | +The collection is missing required signature, which means it might have been compromised. |
| 58 | +``` |
| 59 | + |
| 60 | +Users should NOT add the package collection in this case. |
| 61 | + |
| 62 | +##### Trusted root certificates |
| 63 | + |
| 64 | +Since generating a collection signature requires a certificate, part of the signature check involves validating the certificate and its chain and making sure that the root certificate is trusted. |
| 65 | + |
| 66 | +On Apple platforms, all root certificates that come preinstalled with the OS are automatically trusted. Users may include additional certificates to trust by placing |
| 67 | +them in the `~/.swiftpm/config/trust-root-certs` directory. |
| 68 | + |
| 69 | +On non-Apple platforms, there are no trusted root certificates by default other than those shipped with the [certificate-pinning configuration](<doc:PackageCollections#Protecting-package-collections>). Only those |
| 70 | +found in `~/.swiftpm/config/trust-root-certs` are trusted. This means that the signature check will always fail unless the `trust-root-certs` directory is set up: |
| 71 | + |
| 72 | +```bash |
| 73 | +$ swift package-collection add https://www.example.com/packages.json |
| 74 | +The collection's signature cannot be verified due to missing configuration. |
| 75 | +``` |
| 76 | +
|
| 77 | +Users can explicitly specify they trust a publisher and any collections they publish, by obtaining that publisher's root certificate and saving it to `~/.swiftpm/config/trust-root-certs`. The |
| 78 | +root certificates must be DER-encoded. Since SwiftPM trusts all certificate chains under a root, depending on what roots are installed, some publishers may already be trusted implicitly and |
| 79 | +users don't need to explicitly specify each one. |
| 80 | +
|
| 81 | +#### Unsigned package collections |
| 82 | +
|
| 83 | +Users will get an error when trying to add an unsigned package collection: |
| 84 | +
|
| 85 | +```bash |
| 86 | +$ swift package-collection add https://www.example.com/packages.json |
| 87 | +The collection is not signed. If you would still like to add it please rerun 'add' with '--trust-unsigned'. |
| 88 | +``` |
| 89 | +
|
| 90 | +To continue user must confirm their trust by passing the `--trust-unsigned` flag: |
| 91 | +
|
| 92 | +```bash |
| 93 | +$ swift package-collection add https://www.example.com/packages.json --trust-unsigned |
| 94 | +``` |
| 95 | +
|
| 96 | +The `--skip-signature-check` flag has no effects on unsigned collections. |
| 97 | +
|
| 98 | +
|
| 99 | +## Usage |
| 100 | +
|
9 | 101 | ``` |
10 | 102 | package-collection add <collection-url> [--order=<order>] [--trust-unsigned] [--skip-signature-check] [--package-path=<package-path>] [--cache-path=<cache-path>] [--config-path=<config-path>] [--security-path=<security-path>] [--scratch-path=<scratch-path>] [--swift-sdks-path=<swift-sdks-path>] [--toolset=<toolset>...] [--pkg-config-path=<pkg-config-path>...] [--enable-dependency-cache|disable-dependency-cache] [--enable-build-manifest-caching|disable-build-manifest-caching] [--manifest-cache=<manifest-cache>] [--enable-experimental-prebuilts|disable-experimental-prebuilts] [--verbose] [--very-verbose|vv] [--quiet] [--color-diagnostics|no-color-diagnostics] [--disable-sandbox] [--netrc] [--enable-netrc|disable-netrc] [--netrc-file=<netrc-file>] [--enable-keychain|disable-keychain] [--resolver-fingerprint-checking=<resolver-fingerprint-checking>] [--resolver-signing-entity-checking=<resolver-signing-entity-checking>] [--enable-signature-validation|disable-signature-validation] [--enable-prefetching|disable-prefetching] [--force-resolved-versions|disable-automatic-resolution|only-use-versions-from-resolved-file] [--skip-update] [--disable-scm-to-registry-transformation] [--use-registry-identity-for-scm] [--replace-scm-with-registry] [--default-registry-url=<default-registry-url>] [--configuration=<configuration>] [--=<Xcc>...] [--=<Xswiftc>...] [--=<Xlinker>...] [--=<Xcxx>...] [--triple=<triple>] [--sdk=<sdk>] [--toolchain=<toolchain>] [--swift-sdk=<swift-sdk>] [--sanitize=<sanitize>...] [--auto-index-store|enable-index-store|disable-index-store] [--enable-parseable-module-interfaces] [--jobs=<jobs>] [--use-integrated-swift-driver] [--explicit-target-dependency-import-check=<explicit-target-dependency-import-check>] [--experimental-explicit-module-build] [--build-system=<build-system>] [--=<debug-info-format>] [--enable-dead-strip|disable-dead-strip] [--disable-local-rpath] [--version] [--help] |
11 | 103 | ``` |
|
0 commit comments