| // Copyright 2012 The Chromium Authors |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef CHROMEOS_DBUS_PERMISSION_BROKER_PERMISSION_BROKER_CLIENT_H_ |
| #define CHROMEOS_DBUS_PERMISSION_BROKER_PERMISSION_BROKER_CLIENT_H_ |
| |
| #include <stdint.h> |
| |
| #include <string> |
| |
| #include "base/component_export.h" |
| #include "base/files/scoped_file.h" |
| #include "base/functional/callback.h" |
| |
| namespace dbus { |
| class Bus; |
| } |
| |
| namespace chromeos { |
| |
| // PermissionBrokerClient is used to communicate with the permission broker, a |
| // process that allows requesting permission to access specific device nodes. |
| // For example, one place that this client is used is within the USB extension |
| // API code, where it is used to request explicit access to USB peripherals |
| // which the user the browser runs under normally wouldn't have access to. For |
| // more details on the permission broker see: |
| // http://git.chromium.org/gitweb/?p=chromiumos/platform/permission_broker.git |
| class COMPONENT_EXPORT(PERMISSION_BROKER) PermissionBrokerClient { |
| public: |
| // The ResultCallback's boolean parameter represents the result of the |
| // operation that it was submitted alongside. |
| using ResultCallback = base::OnceCallback<void(bool)>; |
| |
| // An OpenPathCallback callback is run when an OpenPath request is completed. |
| using OpenPathCallback = base::OnceCallback<void(base::ScopedFD)>; |
| |
| // An OpenPathAndRegisterClientCallback callback is run when an |
| // OpenPathAndRegisterClient request is completed. |
| using OpenPathAndRegisterClientCallback = |
| base::OnceCallback<void(const std::string& client_id, base::ScopedFD)>; |
| |
| // An ErrorCallback callback is run when an error is returned by the |
| // permission broker. |
| using ErrorCallback = base::OnceCallback<void(const std::string& error_name, |
| const std::string& message)>; |
| |
| // Creates and initializes the global instance. |bus| must not be null. |
| static void Initialize(dbus::Bus* bus); |
| |
| // Creates and initializes a fake global instance if not already created. |
| static void InitializeFake(); |
| |
| // Destroys the global instance which must have been initialized. |
| static void Shutdown(); |
| |
| // Returns the global instance if initialized. May return null. |
| static PermissionBrokerClient* Get(); |
| |
| PermissionBrokerClient(const PermissionBrokerClient&) = delete; |
| PermissionBrokerClient& operator=(const PermissionBrokerClient&) = delete; |
| |
| // CheckPathAccess requests a hint from the permission broker about whether |
| // a later call to RequestPathAccess will be successful. It presumes that |
| // the |interface_id| value passed to RequestPathAccess will be |
| // UsbDevicePermissionsData::ANY_INTERFACE). |
| virtual void CheckPathAccess(const std::string& path, |
| ResultCallback callback) = 0; |
| |
| // OpenPath requests that the permission broker open the device node |
| // identified by |path| and return the resulting file descriptor. One of |
| // |callback| or |error_callback| is called. |
| virtual void OpenPath(const std::string& path, |
| OpenPathCallback callback, |
| ErrorCallback error_callback) = 0; |
| |
| // ClaimDevicePath requests that the permission broker open |
| // the device node identified by |path| and set of USB interfaces that can be |
| // claimed |allowed_interfaces_mask|, returning the resulting file descriptor. |
| // The interface number 0 corresponds to the LSB of |allowed_interfaces_mask|. |
| // For example, a device which has an ADB interface and other interfaces for |
| // Camera or Storage may be opened purely as an ADB device using a mask that |
| // zeros out the Camera and Storage interface number bit positions. |
| // One of |callback| or |error_callback| is called. |lifeline_fd| is the |
| // read side of a pipe that is is watched by permission broker. When this |
| // pipe closes, any kernel drivers removed from the device are reattached. |
| virtual void ClaimDevicePath(const std::string& path, |
| uint32_t allowed_interfaces_mask, |
| int lifeline_fd, |
| OpenPathCallback callback, |
| ErrorCallback error_callback) = 0; |
| |
| // This API is for a client to register with the Permission Broker to |
| // make requests to detach/reattach USB device interfaces in the future. |
| // The |drop_privileges_mask| is a bit mask indicating which interface |
| // numbers of a USB device are allowed. The interface number 0 corresponds |
| // to the LSB of the mask. A device which has an ADB interface and other |
| // interfaces for Camera or Storage may be opened purely as an ADB device |
| // using a mask that zeros out the Camera and Storage interface number |
| // bit positions. |
| // The |path| is the USB device path the client wants to access. |
| // The |lifeline_fd| is a file descriptor for monitoring the client's |
| // lifetime and reattaching detached interfaces when the client terminates. |
| // The method returns |fd| which is a file descriptor opened at |path|, |
| // and |client_id| which is an unique id for a registered client. |
| virtual void OpenPathAndRegisterClient( |
| const std::string& path, |
| uint32_t allowed_interfaces_mask, |
| int lifeline_fd, |
| OpenPathAndRegisterClientCallback callback, |
| ErrorCallback error_callback) = 0; |
| |
| // This API is for the client with |client_id| to detach the interface |
| // |iface_num| at the USB device associated with it. |
| virtual void DetachInterface(const std::string& client_id, |
| uint8_t iface_num, |
| ResultCallback callback) = 0; |
| |
| // This API is for the client with |client_id| to reattach the interface |
| // |iface_num| at the USB device associated with it. |
| virtual void ReattachInterface(const std::string& client_id, |
| uint8_t iface_num, |
| ResultCallback callback) = 0; |
| |
| // Requests the |port| be opened on the firewall for incoming TCP/IP |
| // connections received on |interface| (an empty string indicates all |
| // interfaces). One end of an open pipe must be passed as |lifeline_fd| so |
| // that the permission broker can monitor the lifetime of the calling process |
| // by being notified when the other end is closed. This method duplicates |
| // |lifeline_fd| so it's OK to close it without waiting for the result. |
| virtual void RequestTcpPortAccess(uint16_t port, |
| const std::string& interface, |
| int lifeline_fd, |
| ResultCallback callback) = 0; |
| |
| // Requests the |port| be opened on the firewall for incoming UDP packets |
| // received on |interface| (an empty string indicates all interfaces). One end |
| // of an open pipe must be passed as |lifeline_fd| so that the permission |
| // broker can monitor the lifetime of the calling process by being notified |
| // when the other end is closed. This method duplicates |lifeline_fd| so it's |
| // OK to close it without waiting for the result. |
| virtual void RequestUdpPortAccess(uint16_t port, |
| const std::string& interface, |
| int lifeline_fd, |
| ResultCallback callback) = 0; |
| |
| // Releases a request for an open firewall port for TCP/IP connections. The |
| // |port| and |interface| parameters must be the same as a previous call to |
| // RequestTcpPortAccess. |
| virtual void ReleaseTcpPort(uint16_t port, |
| const std::string& interface, |
| ResultCallback callback) = 0; |
| |
| // Releases a request for an open firewall port for UDP packets. The |port| |
| // and |interface| parameters must be the same as a previous call to |
| // RequestUdpPortAccess. |
| virtual void ReleaseUdpPort(uint16_t port, |
| const std::string& interface, |
| ResultCallback callback) = 0; |
| |
| // Requests that |in_port| on |in_interface| be opened for and forward TCP |
| // traffic to |dst_ip| on |dst_port|. One end of an open pipe must be passed |
| // as |lifeline_fd| so that the permission broker can monitor the lifetime of |
| // the calling process by being notified when the other end is closed. This |
| // method duplicates |lifeline_fd| so it's OK to close it without waiting for |
| // the result. |
| // See PortTracker::ValidatePortRule in permission_broker for the restrictions |
| // on port forwarding requests. |
| virtual void RequestTcpPortForward(uint16_t in_port, |
| const std::string& in_interface, |
| const std::string& dst_ip, |
| uint16_t dst_port, |
| int lifeline_fd, |
| ResultCallback callback) = 0; |
| |
| // Requests that |in_port| on |in_interface| be opened for and forward UDP |
| // traffic to |dst_ip| on |dst_port|. One end of an open pipe must be passed |
| // as |lifeline_fd| so that the permission broker can monitor the lifetime of |
| // the calling process by being notified when the other end is closed. This |
| // method duplicates |lifeline_fd| so it's OK to close it without waiting for |
| // the result. |
| // See PortTracker::ValidatePortRule in permission_broker for the restrictions |
| // on port forwarding requests. |
| virtual void RequestUdpPortForward(uint16_t in_port, |
| const std::string& in_interface, |
| const std::string& dst_ip, |
| uint16_t dst_port, |
| int lifeline_fd, |
| ResultCallback callback) = 0; |
| |
| // Releases a request for an open forwarding rule for TCP packets. The |
| // |in_port| and |in_interface| parameters must be the same as a previous call |
| // to RequestUdpPortForward. |
| virtual void ReleaseTcpPortForward(uint16_t in_port, |
| const std::string& in_interface, |
| ResultCallback callback) = 0; |
| |
| // Releases a request for an open forwarding rule for UDP packets. The |
| // |in_port| and |in_interface| parameters must be the same as a previous call |
| // to RequestUdpPortForward. |
| virtual void ReleaseUdpPortForward(uint16_t in_port, |
| const std::string& in_interface, |
| ResultCallback callback) = 0; |
| |
| protected: |
| // Initialize/Shutdown should be used instead. |
| PermissionBrokerClient(); |
| virtual ~PermissionBrokerClient(); |
| }; |
| |
| } // namespace chromeos |
| |
| #endif // CHROMEOS_DBUS_PERMISSION_BROKER_PERMISSION_BROKER_CLIENT_H_ |