| // Copyright 2018 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.pkg; |
| |
| using zx; |
| |
| /// Manages package repositories. |
| /// |
| /// This interface is intended to be implemented by package resolver components, and used by |
| /// repository administration tools. |
| [Discoverable] |
| protocol RepositoryManager { |
| /// Add a repository. This will overwrite the repository if it already exists. |
| /// |
| /// Arguments: |
| /// * `repo` is repository to add to the resolver. |
| /// |
| /// Return Values: |
| /// * `ZX_OK` if the repository was added. |
| /// * `ZX_ERR_ACCESS_DENIED` if editing repositories is permanently disabled. |
| /// * `ZX_ERR_ALREADY_EXISTS` if the repository already exists. |
| /// * `ZX_ERR_INVALID_ARGS` if the repository is malformed. |
| Add(RepositoryConfig repo) -> (zx.status status); |
| |
| /// Remove a repository. |
| /// |
| /// Removing a repository will prevent future packages from being cached from this repository, |
| /// but in-flight downloads may not be interrupted. |
| /// |
| /// Arguments: |
| /// * `repo_url` is the URL of the repository we want to remove. |
| /// |
| /// Return Values: |
| /// * `ZX_OK` if the repository was removed. |
| /// * `ZX_ERR_ACCESS_DENIED` if editing repositories is permanently disabled or the |
| /// `repo_url` matches a static repository. |
| /// * `ZX_ERR_INVALID_ARGS` if the `repo_url` is malformed. |
| /// * `ZX_ERR_NOT_FOUND` if the repository does not exist. |
| Remove(string repo_url) -> (zx.status status); |
| |
| /// Add a mirror to a repository. This will overwrite the mirror if it already exists. |
| /// |
| /// Arguments: |
| /// * `repo_url` is repository that corresponds with this mirror. |
| /// * `mirror_url` is mirror URL to add to the resolver. |
| /// |
| /// Return Values: |
| /// * `ZX_OK` if the mirror was removed. |
| /// * `ZX_ERR_ALREADY_EXISTS` if the mirror for this repository already exists. |
| /// * `ZX_ERR_INVALID_ARGS` if the `repo_url` or the `mirror` is malformed. |
| /// * `ZX_ERR_NOT_FOUND` if the repository does not exist. |
| AddMirror(string repo_url, MirrorConfig mirror) -> (zx.status status); |
| |
| /// Remove a mirror from a repository. |
| /// |
| /// Removing a mirror will prevent future packages from being cached from that mirror, but |
| /// in-flight downloads may not be interrupted. |
| /// |
| /// Arguments: |
| /// * `repo_url` the URL of the mirror's repository. |
| /// * `mirror_url` the URL of the mirror we want to remove. |
| /// |
| /// Return Values: |
| /// * `ZX_OK` if the mirror was removed. |
| /// * `ZX_ERR_INVALID_ARGS` if the `repo_url` or the `mirror_url` is malformed. |
| /// * `ZX_ERR_NOT_FOUND` if the repository or mirror does not exist. |
| RemoveMirror(string repo_url, string mirror_url) -> (zx.status status); |
| |
| /// Return an iterator over all repositories. |
| /// |
| /// Arguments: |
| /// `iterator` is a request for an iterator. |
| List(request<RepositoryIterator> iterator); |
| }; |
| |
| /// Describes the configuration necessary to connect to a repository and it's mirrors. |
| table RepositoryConfig { |
| /// A fuchsia-pkg URL identifying the repository. Required. |
| /// |
| /// Example: fuchsia-pkg://example.com/ |
| 1: string repo_url; |
| |
| /// A vector of public keys that have signed the initial trusted root |
| /// metadata. Required. |
| /// |
| /// These keys must match one of the trusted keys known to the system. |
| 2: vector<RepositoryKeyConfig> root_keys; |
| |
| /// The repository mirrors that serve the package contents. Required. |
| 3: vector<MirrorConfig> mirrors; |
| |
| /// The package URL of the system update package. Optional. |
| /// |
| /// Only used for the fuchsia-pkg://fuchsia.com/ repo. |
| 4: string update_package_url; |
| |
| /// The initial trusted root metadata version. Optional, defaulting to 1. |
| /// |
| /// This value describes the initial root metadata version the resolver will |
| /// fetch to initialize trust, once it's signatures has been verified by the |
| /// `root_keys`. It will then walk the chain of N+1, N+2, and etc to the |
| /// latest version before the resolver fetches any targets. |
| /// |
| /// It is recommended that this `root_version` number and `root_keys ` are |
| /// kept reasonably in sync with the most recent published version of the |
| /// root metadata, as that avoids the risk of an old and unused root key |
| /// being used to compromise resolvers during the trust initialization. |
| 5: uint32 root_version; |
| |
| /// The number of `root_keys` that need to have signed the root metadata for it |
| /// to be considered trusted. This value must be greater than or equal to 1. |
| /// Optional, defaulting to 1. |
| 6: uint32 root_threshold; |
| }; |
| |
| /// Describes the keys used by the repository to authenticate it's packages. |
| /// |
| /// The only supported algorithm at the moment is ed25519. |
| flexible union RepositoryKeyConfig { |
| /// The raw ed25519 public key as binary data. |
| 1: bytes ed25519_key; |
| }; |
| |
| /// Describes a key used to decrypt blobs. |
| /// |
| /// The only supported algorithm at the moment is aes. |
| flexible union RepositoryBlobKey { |
| /// A raw aes key as binary data. |
| 1: bytes aes_key; |
| }; |
| |
| /// Describes the configuration necessary to connect to a mirror. |
| table MirrorConfig { |
| /// The base URL of the TUF metadata on this mirror. Required. |
| 1: string mirror_url; |
| |
| /// Whether or not to automatically monitor the mirror for updates. Required. |
| 2: bool subscribe; |
| |
| /// The private (or symmetric) key used to decrypt blobs fetched from this mirror. Optional. |
| 3: RepositoryBlobKey blob_key; |
| |
| /// The URL where blobs from this mirror should be fetched. Optional. |
| /// Defaults to `mirror_url + "/blobs"`. |
| 4: string blob_mirror_url; |
| }; |
| |
| /// The iterator over all the repositories defined in a `PackageResolver`. |
| protocol RepositoryIterator { |
| /// Advance the iterator and return the next batch of repositories. |
| /// |
| /// Return Values: |
| /// * a vector of `RepositoryConfig` repositories. Will return an empty vector when there are |
| /// no more repositories. |
| Next() -> (vector<RepositoryConfig> repos); |
| }; |