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