ipc/ipc_channel.h

   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
   5 #ifndef IPC_IPC_CHANNEL_H_
   6 #define IPC_IPC_CHANNEL_H_
   7
   8 #include <string>
   9
  10 #if defined(OS_POSIX)
  11 #include <sys/types.h>
  12 #endif
  13
  14 #include "base/compiler_specific.h"
  15 #include "base/files/scoped_file.h"
  16 #include "base/process/process.h"
  17 #include "ipc/ipc_channel_handle.h"
  18 #include "ipc/ipc_endpoint.h"
  19 #include "ipc/ipc_message.h"
  20
  21 namespace IPC {
  22
  23 class AttachmentBroker;
  24 class Listener;
  25
  26 //------------------------------------------------------------------------------
  27 // See
  28 // http://www.chromium.org/developers/design-documents/inter-process-communication
  29 // for overview of IPC in Chromium.
  30
  31 // Channels are implemented using named pipes on Windows, and
  32 // socket pairs (or in some special cases unix domain sockets) on POSIX.
  33 // On Windows we access pipes in various processes by name.
  34 // On POSIX we pass file descriptors to child processes and assign names to them
  35 // in a lookup table.
  36 // In general on POSIX we do not use unix domain sockets due to security
  37 // concerns and the fact that they can leave garbage around the file system
  38 // (MacOS does not support abstract named unix domain sockets).
  39 // You can use unix domain sockets if you like on POSIX by constructing the
  40 // the channel with the mode set to one of the NAMED modes. NAMED modes are
  41 // currently used by automation and service processes.
  42
  43 class IPC_EXPORT Channel : public Endpoint {
  44   // Security tests need access to the pipe handle.
  45   friend class ChannelTest;
  46
  47  public:
  48   // Flags to test modes
  49   enum ModeFlags {
  50     MODE_NO_FLAG = 0x0,
  51     MODE_SERVER_FLAG = 0x1,
  52     MODE_CLIENT_FLAG = 0x2,
  53     MODE_NAMED_FLAG = 0x4,
  54 #if defined(OS_POSIX)
  55     MODE_OPEN_ACCESS_FLAG = 0x8, // Don't restrict access based on client UID.
  56 #endif
  57   };
  58
  59   // Some Standard Modes
  60   // TODO(morrita): These are under deprecation work. You should use Create*()
  61   // functions instead.
  62   enum Mode {
  63     MODE_NONE = MODE_NO_FLAG,
  64     MODE_SERVER = MODE_SERVER_FLAG,
  65     MODE_CLIENT = MODE_CLIENT_FLAG,
  66     MODE_NAMED_SERVER = MODE_SERVER_FLAG | MODE_NAMED_FLAG,
  67     MODE_NAMED_CLIENT = MODE_CLIENT_FLAG | MODE_NAMED_FLAG,
  68 #if defined(OS_POSIX)
  69     MODE_OPEN_NAMED_SERVER = MODE_OPEN_ACCESS_FLAG | MODE_SERVER_FLAG |
  70                              MODE_NAMED_FLAG
  71 #endif
  72   };
  73
  74   // Messages internal to the IPC implementation are defined here.
  75   // Uses Maximum value of message type (uint16), to avoid conflicting
  76   // with normal message types, which are enumeration constants starting from 0.
  77   enum {
  78     // The Hello message is sent by the peer when the channel is connected.
  79     // The message contains just the process id (pid).
  80     // The message has a special routing_id (MSG_ROUTING_NONE)
  81     // and type (HELLO_MESSAGE_TYPE).
  82     HELLO_MESSAGE_TYPE = kuint16max,
  83     // The CLOSE_FD_MESSAGE_TYPE is used in the IPC class to
  84     // work around a bug in sendmsg() on Mac. When an FD is sent
  85     // over the socket, a CLOSE_FD_MESSAGE is sent with hops = 2.
  86     // The client will return the message with hops = 1, *after* it
  87     // has received the message that contains the FD. When we
  88     // receive it again on the sender side, we close the FD.
  89     CLOSE_FD_MESSAGE_TYPE = HELLO_MESSAGE_TYPE - 1
  90   };
  91
  92   // The maximum message size in bytes. Attempting to receive a message of this
  93   // size or bigger results in a channel error.
  94   static const size_t kMaximumMessageSize = 128 * 1024 * 1024;
  95
  96   // Amount of data to read at once from the pipe.
  97   static const size_t kReadBufferSize = 4 * 1024;
  98
  99   // Initialize a Channel.
 100   //
 101   // |channel_handle| identifies the communication Channel. For POSIX, if
 102   // the file descriptor in the channel handle is != -1, the channel takes
 103   // ownership of the file descriptor and will close it appropriately, otherwise
 104   // it will create a new descriptor internally.
 105   // |listener| receives a callback on the current thread for each newly
 106   // received message.
 107   //
 108   // There are four type of modes how channels operate:
 109   //
 110   // - Server and named server: In these modes, the Channel is
 111   //   responsible for settingb up the IPC object
 112   // - An "open" named server: It accepts connections from ANY client.
 113   //   The caller must then implement their own access-control based on the
 114   //   client process' user Id.
 115   // - Client and named client: In these mode, the Channel merely
 116   //   connects to the already established IPC object.
 117   //
 118   // Each mode has its own Create*() API to create the Channel object.
 119   //
 120   // TODO(morrita): Replace CreateByModeForProxy() with one of above Create*().
 121   //
 122   // TODO(erikchen): Remove default parameter for |broker|. It exists only to
 123   // make the upcoming refactor decomposable into smaller CLs.
 124   // http://crbug.com/493414.
 125   static scoped_ptr<Channel> Create(const IPC::ChannelHandle& channel_handle,
 126                                     Mode mode,
 127                                     Listener* listener,
 128                                     AttachmentBroker* broker = nullptr);
 129
 130   // TODO(erikchen): Remove default parameter for |broker|. It exists only to
 131   // make the upcoming refactor decomposable into smaller CLs.
 132   // http://crbug.com/493414.
 133   static scoped_ptr<Channel> CreateClient(
 134       const IPC::ChannelHandle& channel_handle,
 135       Listener* listener,
 136       AttachmentBroker* broker = nullptr);
 137
 138   // Channels on Windows are named by default and accessible from other
 139   // processes. On POSIX channels are anonymous by default and not accessible
 140   // from other processes. Named channels work via named unix domain sockets.
 141   // On Windows MODE_NAMED_SERVER is equivalent to MODE_SERVER and
 142   // MODE_NAMED_CLIENT is equivalent to MODE_CLIENT.
 143   static scoped_ptr<Channel> CreateNamedServer(
 144       const IPC::ChannelHandle& channel_handle,
 145       Listener* listener,
 146       AttachmentBroker* broker);
 147   static scoped_ptr<Channel> CreateNamedClient(
 148       const IPC::ChannelHandle& channel_handle,
 149       Listener* listener,
 150       AttachmentBroker* broker);
 151 #if defined(OS_POSIX)
 152   // An "open" named server accepts connections from ANY client.
 153   // The caller must then implement their own access-control based on the
 154   // client process' user Id.
 155   static scoped_ptr<Channel> CreateOpenNamedServer(
 156       const IPC::ChannelHandle& channel_handle,
 157       Listener* listener,
 158       AttachmentBroker* broker);
 159 #endif
 160   // TODO(erikchen): Remove default parameter for |broker|. It exists only to
 161   // make the upcoming refactor decomposable into smaller CLs.
 162   // http://crbug.com/493414.
 163   static scoped_ptr<Channel> CreateServer(
 164       const IPC::ChannelHandle& channel_handle,
 165       Listener* listener,
 166       AttachmentBroker* broker = nullptr);
 167
 168   ~Channel() override;
 169
 170   // Connect the pipe.  On the server side, this will initiate
 171   // waiting for connections.  On the client, it attempts to
 172   // connect to a pre-existing pipe.  Note, calling Connect()
 173   // will not block the calling thread and may complete
 174   // asynchronously.
 175   virtual bool Connect() WARN_UNUSED_RESULT = 0;
 176
 177   // Close this Channel explicitly.  May be called multiple times.
 178   // On POSIX calling close on an IPC channel that listens for connections will
 179   // cause it to close any accepted connections, and it will stop listening for
 180   // new connections. If you just want to close the currently accepted
 181   // connection and listen for new ones, use ResetToAcceptingConnectionState.
 182   virtual void Close() = 0;
 183
 184   // Get its own process id. This value is told to the peer.
 185   virtual base::ProcessId GetSelfPID() const = 0;
 186
 187   // Overridden from ipc::Sender.
 188   // Send a message over the Channel to the listener on the other end.
 189   //
 190   // |message| must be allocated using operator new.  This object will be
 191   // deleted once the contents of the Message have been sent.
 192   bool Send(Message* message) override = 0;
 193
 194   // IsSendThreadSafe returns true iff it's safe to call |Send| from non-IO
 195   // threads. This is constant for the lifetime of the |Channel|.
 196   virtual bool IsSendThreadSafe() const;
 197
 198   // NaCl in Non-SFI mode runs on Linux directly, and the following functions
 199   // compiled on Linux are also needed. Please see also comments in
 200   // components/nacl_nonsfi.gyp for more details.
 201 #if defined(OS_POSIX) && !defined(OS_NACL_SFI)
 202   // On POSIX an IPC::Channel wraps a socketpair(), this method returns the
 203   // FD # for the client end of the socket.
 204   // This method may only be called on the server side of a channel.
 205   // This method can be called on any thread.
 206   virtual int GetClientFileDescriptor() const = 0;
 207
 208   // Same as GetClientFileDescriptor, but transfers the ownership of the
 209   // file descriptor to the caller.
 210   // This method can be called on any thread.
 211   virtual base::ScopedFD TakeClientFileDescriptor() = 0;
 212 #endif
 213
 214   // Returns true if a named server channel is initialized on the given channel
 215   // ID. Even if true, the server may have already accepted a connection.
 216   static bool IsNamedServerInitialized(const std::string& channel_id);
 217
 218 #if !defined(OS_NACL_SFI)
 219   // Generates a channel ID that's non-predictable and unique.
 220   static std::string GenerateUniqueRandomChannelID();
 221
 222   // Generates a channel ID that, if passed to the client as a shared secret,
 223   // will validate that the client's authenticity. On platforms that do not
 224   // require additional this is simply calls GenerateUniqueRandomChannelID().
 225   // For portability the prefix should not include the \ character.
 226   static std::string GenerateVerifiedChannelID(const std::string& prefix);
 227 #endif
 228
 229 #if defined(OS_LINUX)
 230   // Sandboxed processes live in a PID namespace, so when sending the IPC hello
 231   // message from client to server we need to send the PID from the global
 232   // PID namespace.
 233   static void SetGlobalPid(int pid);
 234 #endif
 235
 236 #if defined(OS_ANDROID)
 237   // Most tests are single process and work the same on all platforms. However
 238   // in some cases we want to test multi-process, and Android differs in that it
 239   // can't 'exec' after forking. This callback resets any data in the forked
 240   // process such that it acts similar to if it was exec'd, for tests.
 241   static void NotifyProcessForkedForTesting();
 242 #endif
 243 };
 244
 245 #if defined(OS_POSIX)
 246 // SocketPair() creates a pair of socket FDs suitable for using with
 247 // IPC::Channel.
 248 IPC_EXPORT bool SocketPair(int* fd1, int* fd2);
 249 #endif
 250
 251 }  // namespace IPC
 252
 253 #endif  // IPC_IPC_CHANNEL_H_