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