123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218 |
- // Copyright (c) 2012 The Chromium Authors. All rights reserved.
- // 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/callback.h"
- #include "base/component_export.h"
- #include "base/files/scoped_file.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
- // TODO(https://crbug.com/1164001): remove when moved to ash.
- namespace ash {
- using ::chromeos::PermissionBrokerClient;
- } // namespace ash
- #endif // CHROMEOS_DBUS_PERMISSION_BROKER_PERMISSION_BROKER_CLIENT_H_
|