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