Fuchsia package URLs

A Fuchsia package URL looks like the following:

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

It consists of the following components, which form the full package URL:

URL scheme

The fuchsia-pkg URL scheme combines identifying characteristics to establish a means for referring to a repository, a package, or a resource, depending on which parts are included.

Syntax

Required

fuchsia-pkg://<repository>[/<package-name>[?hash=<package-hash>][#<resource-path>]]

The scheme of a Fuchsia package are the case-insensitive characters, fuchsia-pkg://.

Although the canonical form is lower-case, URL scheme encoding is case-insensitive therefore the system handles all cases.

Repository

The package URL contains a repository hostname to identify the package's source. RFC 1123 and RFC 5890 specified that a hostname is a sequence of dot (.)-delimited IDNA A-labels, each of which consists of 1 to 63 of the following latin-1 characters in any order:

  • Digits (0 to 9)
  • Lower-case letters (a to z)
  • Hyphen (-)

No other characters are permitted.

The total maximum length of a hostname is 253 characters including the dots.

Repository root verification (known sources)

The repository's root role (a quorum of one or more public or private key pairs) establishes a chain of trust such that package authenticity, integrity, and freshness can be verified cryptographically. The root role signs keys for more limited roles which are then used to sign package metadata and the targets themselves. See TUF Security and TUF roles and metadata for more details.

To verify that a package is authentic, you must verify that the repository from which it is being downloaded is authentic.

This will be implemented by maintaining a list of known source repositories with their public keys on the device. Packages from unknown sources will be rejected, although, on certain build types, new repositories can be added at runtime.

Syntax

Required

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

Examples

fuchsia-pkg://fuchsia.com

Package name

A package name is a symbolic label that identifies a package. The package name is used to locate package metadata within a repository. Package metadata must be signed by a role which is trusted by the repository root.

A package name consists of a sequence of up to 255 of the following latin-1 characters in any order:

  • Digits (0 to 9)
  • Lower-case letters (a to z)
  • Hyphen (-)
  • Underscore (_)
  • Period (.)

No other characters are permitted.

Each package name must be unique among all packages in a repository. Packages within different repositories are considered distinct even if they have the same name.

Syntax

Required

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

There must be a single / character between the repository and package name.

Examples

  • fuchsia-pkg://fuchsia.com/fuchsia-shell-utils
  • fuchsia-pkg://fuchsia.com/fuchsia-shell-fonts
  • fuchsia-pkg://fuchsia.com/fuchsia-shell-scenic

Package hash

A package hash is the merkleroot of the package's meta.far. Because the package's metadata encodes the content addresses of the package's files, any changes to the package's metadata or content will produce a different package hash, thereby making it possible to distinguish each unique revision of the package.

If the package hash is missing, the package resolver fetches the resources from the newest revision of the package available to the client.

A package hash is represented as a hex-encoded string consisting of exactly 64 of the following latin-1 characters: digits (0 to 9) and lower-case letters (a to f). No other characters are permitted.

Syntax

Optional

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

Only valid if a package name is specified.

Must begin with the string ?hash= followed by the package hash.

Examples

fuchsia-pkg://google.com/chrome?hash=80e8721f4eba5437c8b6e1604f6ee384f42aed2b6dfbfd0b616a864839cd7b4a#meta/webview.component

Resource path

A resource path is a UTF-8 string that identifies a resource within a package. This is a file path, consisting of a sequence of single / delimited path segments, each of which is a non-empty sequence of non-zero UTF-8 characters not equal to ., .., or /. Must begin with single # character.

This must be relative to the root of the package.

URL components containing reserved characters are percent-encoded according to RFC 3986. This definition is compatible with the definition of Fuchsia filesystem paths but it imposes a UTF-8 encoding rather than admitting arbitrary binary strings since such strings cannot always be encoded as valid URLs.

For example, hello/unicode/%F0%9F%98%81 decodes to hello/unicode/😁.

Syntax

Optional

Only valid if a package was specified.

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

Examples

  • fuchsia-pkg://fuchsia.com/fuchsia-shell-utils#bin/ls
  • fuchsia-pkg://google.com/chrome#meta/webview.component
  • fuchsia-pkg://google.com/chrome#lib/mylibrary.so

Build a package URL

You can use the editable variables to build your package URL and then copy it:

fuchsia-pkg://repository/package-name?hash=package-hash#resource-path