| // Copyright 2020 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.component.internal; |
| |
| using fuchsia.component; |
| using fuchsia.component.decl; |
| |
| /// The maximum size of the JobPolicyAllowlists entries. |
| /// This value is currently set arbitrarily. |
| const MAX_ALLOWLIST_SIZE uint64 = 128; |
| |
| type Config = table { |
| /// If true, component manager will be in debug mode. In this mode, component manager |
| /// provides the `EventSource` protocol and exposes this protocol. Component |
| /// manager will not start until it is resumed by a call to |
| /// `EventSource.StartComponentTree`. |
| /// |
| /// This is done so that an external component (say an integration test) can subscribe |
| /// to events before the root component has started. |
| 1: debug bool; |
| |
| /// How many children, maximum, are returned by a call to `Realm.ChildIterator.next()`. |
| 2: list_children_batch_size uint32; |
| |
| /// Security policy configuration. |
| 3: security_policy SecurityPolicy; |
| |
| /// Capabilities offered from component manager's namespace. |
| 4: namespace_capabilities vector<fuchsia.component.decl.Capability>:MAX; |
| |
| /// Capabilities offered from component manager as built-in capabilities. |
| 17: builtin_capabilities vector<fuchsia.component.decl.Capability>:MAX; |
| |
| /// If true, component_manager will serve an instance of fuchsia.process.Launcher and use this |
| /// launcher for the built-in ELF component runner. The root component can additionally |
| /// use and/or offer this service using `/builtin/fuchsia.process.Launcher` from realm. |
| /// This flag exists because the built-in process launcher *only* works when |
| /// component_manager runs under a job that has ZX_POL_NEW_PROCESS set to allow, like the root |
| /// job. Otherwise, the component_manager process cannot directly create process through |
| /// zx_process_create. When we run component_manager elsewhere, like in test environments, it |
| /// has to use the fuchsia.process.Launcher service provided through its namespace instead. |
| 5: use_builtin_process_launcher bool; |
| |
| /// If true, component_manager will maintain a UTC kernel clock and vend write handles through |
| /// an instance of `fuchsia.time.Maintenance`. This flag should only be used with the top-level |
| /// component_manager. |
| 6: maintain_utc_clock bool; |
| |
| /// The number of threads to use for running component_manager's executor. |
| /// If not present, interpreted as 1. |
| 7: num_threads uint32; |
| |
| /// Which builtin resolver to use for the fuchsia-pkg scheme. |
| /// If not present, interpreted as BuiltinPkgResolver.NONE. |
| 8: builtin_pkg_resolver BuiltinPkgResolver; |
| |
| /// Determine what content to expose through the component manager's |
| /// outgoing directory. |
| /// If not present, interpreted as OutDirContents.NONE. |
| 9: out_dir_contents OutDirContents; |
| |
| /// URL of the root component to launch. This field is used if the no URL |
| /// is passed to component manager. If value is passed in both places, then |
| /// an error is raised. |
| 10: root_component_url string:fuchsia.component.MAX_URL_SCHEME_LENGTH; |
| |
| /// Path to the component ID index. An empty value defaults to an empty index. |
| /// An invalid index causes component_manager to abort. |
| 11: component_id_index_path string:fuchsia.component.MAX_PATH_LENGTH; |
| |
| /// Where to log to. |
| 12: log_destination LogDestination; |
| |
| /// If true, component manager will log all events dispatched in the topology. |
| 13: log_all_events bool; |
| |
| /// Which builtin resolver to use for the fuchsia-boot scheme. |
| /// If not present, interpreted as BuiltinBootResolver.NONE. |
| 14: builtin_boot_resolver BuiltinBootResolver; |
| |
| /// If true, allow components to set the `OnTerminate=REBOOT` option. |
| /// |
| /// This lets a parent copmonent designate that the system should reboot if a child terminates |
| /// (except when it's shut down). |
| 15: reboot_on_terminate_enabled bool; |
| |
| /// If and how the realm builder resolver and runner will be used. Typically |
| /// these capabilities from realm builder are available to a nested |
| /// component manager that is undergoing an integration test. |
| 16: realm_builder_resolver_and_runner RealmBuilderResolverAndRunner; |
| }; |
| |
| /// The builtin resolver to use for the fuchsia-pkg scheme, if any. |
| type BuiltinPkgResolver = strict enum : uint8 { |
| /// No builtin package resolver is used. Products supply a package resolver as a component, or |
| /// can opt to not include one at all. |
| NONE = 1; |
| |
| /// Try to use the `fuchsia.sys.Loader` protocol from the namespace, typically this is provided |
| /// by `appmgr`. Test scenarios commonly use this option. |
| APPMGR_BRIDGE = 3; |
| }; |
| |
| /// The builtin resolver to use for the fuchsia-boot scheme, if any. |
| type BuiltinBootResolver = strict enum : uint8 { |
| /// No builtin boot resolver is used. |
| NONE = 1; |
| |
| /// Try to use the /boot directory from the namespace. Typically this is provided |
| /// to component manager during initialization of the system. |
| BOOT = 2; |
| }; |
| |
| /// Where to log to. |
| type LogDestination = strict enum : uint8 { |
| /// Log to syslog. |
| SYSLOG = 1; |
| |
| /// Log to klog. |
| KLOG = 2; |
| }; |
| |
| /// If and how the realm builder resolver and runner will be used. |
| type RealmBuilderResolverAndRunner = strict enum : uint8 { |
| /// The realm builder resolver and runner are not used. |
| NONE = 1; |
| |
| /// The realm builder resolver and runner will be accessed through component |
| /// manager's namespace, and made available to the root realm. |
| NAMESPACE = 2; |
| }; |
| |
| /// Runtime security policy. |
| type SecurityPolicy = table { |
| /// Allowlists for Zircon job policy. |
| 1: job_policy JobPolicyAllowlists; |
| /// Capability access policy. |
| 2: capability_policy CapabilityPolicyAllowlists; |
| /// Debug capability registration policy. |
| 3: debug_registration_policy DebugRegistrationPolicyAllowlists; |
| /// Component child options policy. |
| 4: child_policy ChildPolicyAllowlists; |
| }; |
| |
| /// A single entry in an allowlist, expressed in one of three forms: |
| /// |
| /// 1. Exact absolute moniker - Most entries should fall under this case, |
| /// where the exact absolute monikers of allowed components are listed. |
| /// For example, "/foo/bar". |
| /// 2. Realm - Realms can be allowlisted such that any descendant will be |
| /// allowed without being listed explicitly. For example, "/foo/**" |
| /// allows any descendant of "/foo" (but not foo itself). |
| /// 3. Collection - Individual collections can also be allowlisted. For |
| /// example, "/foo/bar:**" will allow any child in foo's "bar" |
| /// collection and any descendant thereof, but not foo or other |
| /// children of foo. |
| alias AllowlistEntryMoniker = string:fuchsia.component.MAX_MONIKER_LENGTH; |
| |
| /// Allowlists for Zircon job policy. |
| type JobPolicyAllowlists = table { |
| /// Allowlist entry monikers for components allowed to be given the |
| /// ZX_POL_AMBIENT_MARK_VMO_EXEC job policy. |
| /// |
| /// Components must request this policy by including "job_policy_ambient_mark_vmo_exec: true" in |
| /// their CML's `program` section and must be using the ELF runner. |
| /// This is equivalent to the v1 'deprecated-ambient-replace-as-executable' feature. |
| 1: ambient_mark_vmo_exec vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE; |
| |
| /// Allowlist entry monikers for components allowed to have their original process |
| /// marked as critical to component_manager's job. |
| /// |
| /// Components must request this critical marking by including "main_process_critical: true" in |
| /// their CML's `program` section and must be using the ELF runner. |
| 2: main_process_critical vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE; |
| |
| /// Allowlist entry monikers for components allowed to call zx_process_create directly |
| /// (e.g., do not have ZX_POL_NEW_PROCESS set to ZX_POL_ACTION_DENY). |
| /// |
| /// Components must request this policy by including "job_policy_create_raw_processes: true" in |
| /// their manifest's program object and must be using the ELF runner. |
| 3: create_raw_processes vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE; |
| }; |
| |
| /// Determine what content to expose through component manager's outgoing |
| /// directory. |
| type OutDirContents = strict enum : uint8 { |
| /// Don't expose anything through the outgoing directory. |
| NONE = 1; |
| |
| /// Expose component manager's `hub` directory. |
| HUB = 2; |
| |
| /// Expose root component's `expose/svc`. |
| SVC = 3; |
| }; |
| |
| /// Represents the class of capabilities supported to be allowlisted. |
| type AllowlistedCapability = flexible union { |
| 1: directory AllowlistedDirectory; |
| 2: event AllowlistedEvent; |
| 3: protocol AllowlistedProtocol; |
| 4: service AllowlistedService; |
| 5: storage AllowlistedStorage; |
| 6: runner AllowlistedRunner; |
| 7: resolver AllowlistedResolver; |
| }; |
| |
| type AllowlistedDirectory = table {}; |
| |
| type AllowlistedEvent = table {}; |
| |
| type AllowlistedProtocol = table {}; |
| |
| type AllowlistedService = table {}; |
| |
| type AllowlistedStorage = table {}; |
| |
| type AllowlistedRunner = table {}; |
| |
| type AllowlistedResolver = table {}; |
| |
| /// Defines a single capability policy entry in the set of capability policy |
| /// allowlists. |
| type CapabilityAllowlistEntry = table { |
| /// The `source_moniker` represents the origin of a capability. The |
| /// `source_moniker` is either an absolute moniker or '<component_manager>'. |
| 1: source_moniker string:fuchsia.component.MAX_MONIKER_LENGTH; |
| |
| /// The source name of this particular capability. |
| 2: source_name string:fuchsia.component.MAX_NAME_LENGTH; |
| |
| /// Represents the type of capability that is being restricted along |
| /// with any other properties required by a particular capability type. |
| 3: capability AllowlistedCapability; |
| |
| /// The set of components, described by either exact absolute monikers, realm, or collection, |
| /// that are allowed to use this specific capability. |
| 4: target_monikers vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE; |
| |
| /// The original source type of this capability, self or framework. |
| 5: source fuchsia.component.decl.Ref; |
| }; |
| |
| /// Defines the total set of capability allowlists. Each |
| /// `source_moniker` + `capability` pair must be unique in the vector. |
| type CapabilityPolicyAllowlists = table { |
| 1: allowlist vector<CapabilityAllowlistEntry>:MAX_ALLOWLIST_SIZE; |
| }; |
| |
| /// Represents the class of capabilities supported to be allowlisted. |
| type AllowlistedDebugRegistration = flexible union { |
| 1: protocol AllowlistedProtocol; |
| }; |
| |
| /// Defines a capability policy entry in the set of debug capability policy |
| /// allowlists. |
| type DebugRegistrationAllowlistEntry = table { |
| /// The `source_moniker` represents the origin of a capability. The |
| /// `source_moniker` is absolute moniker. |
| 1: source_moniker string:fuchsia.component.MAX_MONIKER_LENGTH; |
| |
| /// The source name of this particular capability. |
| 2: source_name string:fuchsia.component.MAX_NAME_LENGTH; |
| |
| /// Represents the type of capability that is being restricted along |
| /// with any other properties required by a particular capability type. |
| 3: debug AllowlistedDebugRegistration; |
| |
| /// The `target_moniker` represents the component which is allowed to register |
| /// this capability in its environment's debug sction. |
| 4: target_moniker string:fuchsia.component.MAX_MONIKER_LENGTH; |
| |
| /// Name of the environment where this capability can be registered. |
| 5: environment_name fuchsia.component.name; |
| }; |
| |
| /// Defines the total set of debug capability allowlists. |
| type DebugRegistrationPolicyAllowlists = table { |
| 1: allowlist vector<DebugRegistrationAllowlistEntry>:MAX_ALLOWLIST_SIZE; |
| }; |
| |
| /// Allowlists for privileged child options. |
| type ChildPolicyAllowlists = table { |
| /// Allowlist entry monikers of component instances allowed to have the |
| /// `on_terminate=REBOOT` in their `children` declaration. |
| 1: reboot_on_terminate vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE; |
| }; |