permission_broker_client.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  1. // Copyright (c) 2012 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef CHROMEOS_DBUS_PERMISSION_BROKER_PERMISSION_BROKER_CLIENT_H_
  5. #define CHROMEOS_DBUS_PERMISSION_BROKER_PERMISSION_BROKER_CLIENT_H_
  6. #include <stdint.h>
  7. #include <string>
  8. #include "base/callback.h"
  9. #include "base/component_export.h"
  10. #include "base/files/scoped_file.h"
  11. namespace dbus {
  12. class Bus;
  13. }
  14. namespace chromeos {
  15. // PermissionBrokerClient is used to communicate with the permission broker, a
  16. // process that allows requesting permission to access specific device nodes.
  17. // For example, one place that this client is used is within the USB extension
  18. // API code, where it is used to request explicit access to USB peripherals
  19. // which the user the browser runs under normally wouldn't have access to. For
  20. // more details on the permission broker see:
  21. // http://git.chromium.org/gitweb/?p=chromiumos/platform/permission_broker.git
  22. class COMPONENT_EXPORT(PERMISSION_BROKER) PermissionBrokerClient {
  23. public:
  24. // The ResultCallback's boolean parameter represents the result of the
  25. // operation that it was submitted alongside.
  26. using ResultCallback = base::OnceCallback<void(bool)>;
  27. // An OpenPathCallback callback is run when an OpenPath request is completed.
  28. using OpenPathCallback = base::OnceCallback<void(base::ScopedFD)>;
  29. // An OpenPathAndRegisterClientCallback callback is run when an
  30. // OpenPathAndRegisterClient request is completed.
  31. using OpenPathAndRegisterClientCallback =
  32. base::OnceCallback<void(const std::string& client_id, base::ScopedFD)>;
  33. // An ErrorCallback callback is run when an error is returned by the
  34. // permission broker.
  35. using ErrorCallback = base::OnceCallback<void(const std::string& error_name,
  36. const std::string& message)>;
  37. // Creates and initializes the global instance. |bus| must not be null.
  38. static void Initialize(dbus::Bus* bus);
  39. // Creates and initializes a fake global instance if not already created.
  40. static void InitializeFake();
  41. // Destroys the global instance which must have been initialized.
  42. static void Shutdown();
  43. // Returns the global instance if initialized. May return null.
  44. static PermissionBrokerClient* Get();
  45. PermissionBrokerClient(const PermissionBrokerClient&) = delete;
  46. PermissionBrokerClient& operator=(const PermissionBrokerClient&) = delete;
  47. // CheckPathAccess requests a hint from the permission broker about whether
  48. // a later call to RequestPathAccess will be successful. It presumes that
  49. // the |interface_id| value passed to RequestPathAccess will be
  50. // UsbDevicePermissionsData::ANY_INTERFACE).
  51. virtual void CheckPathAccess(const std::string& path,
  52. ResultCallback callback) = 0;
  53. // OpenPath requests that the permission broker open the device node
  54. // identified by |path| and return the resulting file descriptor. One of
  55. // |callback| or |error_callback| is called.
  56. virtual void OpenPath(const std::string& path,
  57. OpenPathCallback callback,
  58. ErrorCallback error_callback) = 0;
  59. // ClaimDevicePath requests that the permission broker open
  60. // the device node identified by |path| and set of USB interfaces that can be
  61. // claimed |allowed_interfaces_mask|, returning the resulting file descriptor.
  62. // The interface number 0 corresponds to the LSB of |allowed_interfaces_mask|.
  63. // For example, a device which has an ADB interface and other interfaces for
  64. // Camera or Storage may be opened purely as an ADB device using a mask that
  65. // zeros out the Camera and Storage interface number bit positions.
  66. // One of |callback| or |error_callback| is called. |lifeline_fd| is the
  67. // read side of a pipe that is is watched by permission broker. When this
  68. // pipe closes, any kernel drivers removed from the device are reattached.
  69. virtual void ClaimDevicePath(const std::string& path,
  70. uint32_t allowed_interfaces_mask,
  71. int lifeline_fd,
  72. OpenPathCallback callback,
  73. ErrorCallback error_callback) = 0;
  74. // This API is for a client to register with the Permission Broker to
  75. // make requests to detach/reattach USB device interfaces in the future.
  76. // The |drop_privileges_mask| is a bit mask indicating which interface
  77. // numbers of a USB device are allowed. The interface number 0 corresponds
  78. // to the LSB of the mask. A device which has an ADB interface and other
  79. // interfaces for Camera or Storage may be opened purely as an ADB device
  80. // using a mask that zeros out the Camera and Storage interface number
  81. // bit positions.
  82. // The |path| is the USB device path the client wants to access.
  83. // The |lifeline_fd| is a file descriptor for monitoring the client's
  84. // lifetime and reattaching detached interfaces when the client terminates.
  85. // The method returns |fd| which is a file descriptor opened at |path|,
  86. // and |client_id| which is an unique id for a registered client.
  87. virtual void OpenPathAndRegisterClient(
  88. const std::string& path,
  89. uint32_t allowed_interfaces_mask,
  90. int lifeline_fd,
  91. OpenPathAndRegisterClientCallback callback,
  92. ErrorCallback error_callback) = 0;
  93. // This API is for the client with |client_id| to detach the interface
  94. // |iface_num| at the USB device associated with it.
  95. virtual void DetachInterface(const std::string& client_id,
  96. uint8_t iface_num,
  97. ResultCallback callback) = 0;
  98. // This API is for the client with |client_id| to reattach the interface
  99. // |iface_num| at the USB device associated with it.
  100. virtual void ReattachInterface(const std::string& client_id,
  101. uint8_t iface_num,
  102. ResultCallback callback) = 0;
  103. // Requests the |port| be opened on the firewall for incoming TCP/IP
  104. // connections received on |interface| (an empty string indicates all
  105. // interfaces). One end of an open pipe must be passed as |lifeline_fd| so
  106. // that the permission broker can monitor the lifetime of the calling process
  107. // by being notified when the other end is closed. This method duplicates
  108. // |lifeline_fd| so it's OK to close it without waiting for the result.
  109. virtual void RequestTcpPortAccess(uint16_t port,
  110. const std::string& interface,
  111. int lifeline_fd,
  112. ResultCallback callback) = 0;
  113. // Requests the |port| be opened on the firewall for incoming UDP packets
  114. // received on |interface| (an empty string indicates all interfaces). One end
  115. // of an open pipe must be passed as |lifeline_fd| so that the permission
  116. // broker can monitor the lifetime of the calling process by being notified
  117. // when the other end is closed. This method duplicates |lifeline_fd| so it's
  118. // OK to close it without waiting for the result.
  119. virtual void RequestUdpPortAccess(uint16_t port,
  120. const std::string& interface,
  121. int lifeline_fd,
  122. ResultCallback callback) = 0;
  123. // Releases a request for an open firewall port for TCP/IP connections. The
  124. // |port| and |interface| parameters must be the same as a previous call to
  125. // RequestTcpPortAccess.
  126. virtual void ReleaseTcpPort(uint16_t port,
  127. const std::string& interface,
  128. ResultCallback callback) = 0;
  129. // Releases a request for an open firewall port for UDP packets. The |port|
  130. // and |interface| parameters must be the same as a previous call to
  131. // RequestUdpPortAccess.
  132. virtual void ReleaseUdpPort(uint16_t port,
  133. const std::string& interface,
  134. ResultCallback callback) = 0;
  135. // Requests that |in_port| on |in_interface| be opened for and forward TCP
  136. // traffic to |dst_ip| on |dst_port|. One end of an open pipe must be passed
  137. // as |lifeline_fd| so that the permission broker can monitor the lifetime of
  138. // the calling process by being notified when the other end is closed. This
  139. // method duplicates |lifeline_fd| so it's OK to close it without waiting for
  140. // the result.
  141. // See PortTracker::ValidatePortRule in permission_broker for the restrictions
  142. // on port forwarding requests.
  143. virtual void RequestTcpPortForward(uint16_t in_port,
  144. const std::string& in_interface,
  145. const std::string& dst_ip,
  146. uint16_t dst_port,
  147. int lifeline_fd,
  148. ResultCallback callback) = 0;
  149. // Requests that |in_port| on |in_interface| be opened for and forward UDP
  150. // traffic to |dst_ip| on |dst_port|. One end of an open pipe must be passed
  151. // as |lifeline_fd| so that the permission broker can monitor the lifetime of
  152. // the calling process by being notified when the other end is closed. This
  153. // method duplicates |lifeline_fd| so it's OK to close it without waiting for
  154. // the result.
  155. // See PortTracker::ValidatePortRule in permission_broker for the restrictions
  156. // on port forwarding requests.
  157. virtual void RequestUdpPortForward(uint16_t in_port,
  158. const std::string& in_interface,
  159. const std::string& dst_ip,
  160. uint16_t dst_port,
  161. int lifeline_fd,
  162. ResultCallback callback) = 0;
  163. // Releases a request for an open forwarding rule for TCP packets. The
  164. // |in_port| and |in_interface| parameters must be the same as a previous call
  165. // to RequestUdpPortForward.
  166. virtual void ReleaseTcpPortForward(uint16_t in_port,
  167. const std::string& in_interface,
  168. ResultCallback callback) = 0;
  169. // Releases a request for an open forwarding rule for UDP packets. The
  170. // |in_port| and |in_interface| parameters must be the same as a previous call
  171. // to RequestUdpPortForward.
  172. virtual void ReleaseUdpPortForward(uint16_t in_port,
  173. const std::string& in_interface,
  174. ResultCallback callback) = 0;
  175. protected:
  176. // Initialize/Shutdown should be used instead.
  177. PermissionBrokerClient();
  178. virtual ~PermissionBrokerClient();
  179. };
  180. } // namespace chromeos
  181. // TODO(https://crbug.com/1164001): remove when moved to ash.
  182. namespace ash {
  183. using ::chromeos::PermissionBrokerClient;
  184. } // namespace ash
  185. #endif // CHROMEOS_DBUS_PERMISSION_BROKER_PERMISSION_BROKER_CLIENT_H_