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.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   enum Mode {
  59     MODE_NONE = MODE_NO_FLAG,
  60     MODE_SERVER = MODE_SERVER_FLAG,
  61     MODE_CLIENT = MODE_CLIENT_FLAG,
  62     // Channels on Windows are named by default and accessible from other
  63     // processes. On POSIX channels are anonymous by default and not accessible
  64     // from other processes. Named channels work via named unix domain sockets.
  65     // On Windows MODE_NAMED_SERVER is equivalent to MODE_SERVER and
  66     // MODE_NAMED_CLIENT is equivalent to MODE_CLIENT.
  67     MODE_NAMED_SERVER = MODE_SERVER_FLAG | MODE_NAMED_FLAG,
  68     MODE_NAMED_CLIENT = MODE_CLIENT_FLAG | MODE_NAMED_FLAG,
  69 #if defined(OS_POSIX)
  70     // An "open" named server accepts connections from ANY client.
  71     // The caller must then implement their own access-control based on the
  72     // client process' user Id.
  73     MODE_OPEN_NAMED_SERVER = MODE_OPEN_ACCESS_FLAG | MODE_SERVER_FLAG |
  74                              MODE_NAMED_FLAG
  75 #endif
  76   };
  77
  78   // The Hello message is internal to the Channel class.  It is sent
  79   // by the peer when the channel is connected.  The message contains
  80   // just the process id (pid).  The message has a special routing_id
  81   // (MSG_ROUTING_NONE) and type (HELLO_MESSAGE_TYPE).
  82   enum {
  83     HELLO_MESSAGE_TYPE = kuint16max  // Maximum value of message type (uint16),
  84                                      // to avoid conflicting with normal
  85                                      // message types, which are enumeration
  86                                      // constants starting from 0.
  87   };
  88
  89   // The maximum message size in bytes. Attempting to receive a message of this
  90   // size or bigger results in a channel error.
  91   static const size_t kMaximumMessageSize = 128 * 1024 * 1024;
  92
  93   // Amount of data to read at once from the pipe.
  94   static const size_t kReadBufferSize = 4 * 1024;
  95
  96   // Initialize a Channel.
  97   //
  98   // |channel_handle| identifies the communication Channel. For POSIX, if
  99   // the file descriptor in the channel handle is != -1, the channel takes
 100   // ownership of the file descriptor and will close it appropriately, otherwise
 101   // it will create a new descriptor internally.
 102   // |mode| specifies whether this Channel is to operate in server mode or
 103   // client mode.  In server mode, the Channel is responsible for setting up the
 104   // IPC object, whereas in client mode, the Channel merely connects to the
 105   // already established IPC object.
 106   // |listener| receives a callback on the current thread for each newly
 107   // received message.
 108   //
 109   Channel(const IPC::ChannelHandle &channel_handle, Mode mode,
 110           Listener* listener);
 111
 112   virtual ~Channel();
 113
 114   // Connect the pipe.  On the server side, this will initiate
 115   // waiting for connections.  On the client, it attempts to
 116   // connect to a pre-existing pipe.  Note, calling Connect()
 117   // will not block the calling thread and may complete
 118   // asynchronously.
 119   bool Connect() WARN_UNUSED_RESULT;
 120
 121   // Close this Channel explicitly.  May be called multiple times.
 122   // On POSIX calling close on an IPC channel that listens for connections will
 123   // cause it to close any accepted connections, and it will stop listening for
 124   // new connections. If you just want to close the currently accepted
 125   // connection and listen for new ones, use ResetToAcceptingConnectionState.
 126   void Close();
 127
 128   // Get the process ID for the connected peer.
 129   //
 130   // Returns base::kNullProcessId if the peer is not connected yet. Watch out
 131   // for race conditions. You can easily get a channel to another process, but
 132   // if your process has not yet processed the "hello" message from the remote
 133   // side, this will fail. You should either make sure calling this is either
 134   // in response to a message from the remote side (which guarantees that it's
 135   // been connected), or you wait for the "connected" notification on the
 136   // listener.
 137   base::ProcessId peer_pid() const;
 138
 139   // Send a message over the Channel to the listener on the other end.
 140   //
 141   // |message| must be allocated using operator new.  This object will be
 142   // deleted once the contents of the Message have been sent.
 143   virtual bool Send(Message* message) OVERRIDE;
 144
 145 #if defined(OS_POSIX)
 146   // On POSIX an IPC::Channel wraps a socketpair(), this method returns the
 147   // FD # for the client end of the socket.
 148   // This method may only be called on the server side of a channel.
 149   // This method can be called on any thread.
 150   int GetClientFileDescriptor() const;
 151
 152   // Same as GetClientFileDescriptor, but transfers the ownership of the
 153   // file descriptor to the caller.
 154   // This method can be called on any thread.
 155   int TakeClientFileDescriptor();
 156
 157   // On POSIX an IPC::Channel can either wrap an established socket, or it
 158   // can wrap a socket that is listening for connections. Currently an
 159   // IPC::Channel that listens for connections can only accept one connection
 160   // at a time.
 161
 162   // Returns true if the channel supports listening for connections.
 163   bool AcceptsConnections() const;
 164
 165   // Returns true if the channel supports listening for connections and is
 166   // currently connected.
 167   bool HasAcceptedConnection() const;
 168
 169   // Returns true if the peer process' effective user id can be determined, in
 170   // which case the supplied client_euid is updated with it.
 171   bool GetClientEuid(uid_t* client_euid) const;
 172
 173   // Closes any currently connected socket, and returns to a listening state
 174   // for more connections.
 175   void ResetToAcceptingConnectionState();
 176 #endif  // defined(OS_POSIX) && !defined(OS_NACL)
 177
 178   // Returns true if a named server channel is initialized on the given channel
 179   // ID. Even if true, the server may have already accepted a connection.
 180   static bool IsNamedServerInitialized(const std::string& channel_id);
 181
 182 #if !defined(OS_NACL)
 183   // Generates a channel ID that's non-predictable and unique.
 184   static std::string GenerateUniqueRandomChannelID();
 185
 186   // Generates a channel ID that, if passed to the client as a shared secret,
 187   // will validate that the client's authenticity. On platforms that do not
 188   // require additional this is simply calls GenerateUniqueRandomChannelID().
 189   // For portability the prefix should not include the \ character.
 190   static std::string GenerateVerifiedChannelID(const std::string& prefix);
 191 #endif
 192
 193 #if defined(OS_LINUX)
 194   // Sandboxed processes live in a PID namespace, so when sending the IPC hello
 195   // message from client to server we need to send the PID from the global
 196   // PID namespace.
 197   static void SetGlobalPid(int pid);
 198 #endif
 199
 200  protected:
 201   // Used in Chrome by the TestSink to provide a dummy channel implementation
 202   // for testing. TestSink overrides the "interesting" functions in Channel so
 203   // no actual implementation is needed. This will cause un-overridden calls to
 204   // segfault. Do not use outside of test code!
 205   Channel() : channel_impl_(0) { }
 206
 207  private:
 208   // PIMPL to which all channel calls are delegated.
 209   class ChannelImpl;
 210   ChannelImpl *channel_impl_;
 211 };
 212
 213 }  // namespace IPC
 214
 215 #endif  // IPC_IPC_CHANNEL_H_