<trclass="memitem:a727e01831df67754b0ff439735f41608"><tdclass="memItemLeft"align="right"valign="top">enum  </td><tdclass="memItemRight"valign="bottom"><aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a727e01831df67754b0ff439735f41608">PortRightType</a><trclass="memdesc:a727e01831df67754b0ff439735f41608"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Controls whether a receive or send right is expected to be obtained from the client by the server’s call to <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#af1400270cdc498e9c05391389e7bddad"title="Runs the server. ">RunServer()</a>. <ahref="classcrashpad_1_1ChildPortHandshake.html#a727e01831df67754b0ff439735f41608">More...</a><br/></td></tr>
<trclass="memdesc:a9298ec6d6ba1c3ca38157322fdd0c135"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Obtains the “read” side of the pipe, to be used by the client. <ahref="#a9298ec6d6ba1c3ca38157322fdd0c135">More...</a><br/></td></tr>
<trclass="memdesc:a13c305bc7f510f7ec0696ea3257fef35"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Obtains the “write” side of the pipe, to be used by the server. <ahref="#a13c305bc7f510f7ec0696ea3257fef35">More...</a><br/></td></tr>
<trclass="memdesc:af1400270cdc498e9c05391389e7bddad"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Runs the server. <ahref="#af1400270cdc498e9c05391389e7bddad">More...</a><br/></td></tr>
<trclass="memdesc:a94543dc329a5a7d869cc1cb76e23fc20"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Runs the client. <ahref="#a94543dc329a5a7d869cc1cb76e23fc20">More...</a><br/></td></tr>
<trclass="memdesc:a0f73b816d441e5e7f6650c8c5601e654"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Runs the server. <ahref="#a0f73b816d441e5e7f6650c8c5601e654">More...</a><br/></td></tr>
<trclass="memdesc:a3f8c5aa2a2354ae65dcd9323554cdc2a"><tdclass="mdescLeft"> </td><tdclass="mdescRight">Runs the client. <ahref="#a3f8c5aa2a2354ae65dcd9323554cdc2a">More...</a><br/></td></tr>
<divclass="textblock"><p>Implements a handshake protocol that allows processes to exchange port rights. </p>
<p>Ordinarily, there is no way for parent and child processes to exchange port rights, outside of the rights that children inherit from their parents. These include task-special ports and exception ports, but all of these have system-defined uses, and cannot reliably be replaced: in a multi-threaded parent, it is impossible to temporarily change an inheritable port while maintaining a guarantee that another thread will not attempt to use it, and in children, it difficult to guarantee that nothing will attempt to use an inheritable port before it can be replaced with the correct one. This latter concern is becoming increasingly more pronounced as system libraries perform more operations that rely on an inherited port in module initializers.</p>
<p>The protocol implemented by this class involves a server that runs in one process. The server is published with the bootstrap server, which the other process has access to because the bootstrap port is one of the inherited task-special ports. The two processes also share a pipe, which the server can write to and the client can read from. The server will write a random token to this pipe, along with the name under which its service has been registered with the bootstrap server. The client can then obtain a send right to this service with <code>bootstrap_look_up()</code>, and send a check-in message containing the token value and the port right of its choice by calling <code>child_port_check_in()</code>.</p>
<p>The inclusion of the token authenticates the client to the server. This is necessary because the service is published with the bootstrap server, which opens up access to it to more than the intended client. Because the token is passed to the client by a shared pipe, it constitutes a shared secret not known by other processes that may have incidental access to the server. The <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html"title="Implements a handshake protocol that allows processes to exchange port rights. ">ChildPortHandshake</a> server considers its randomly-generated token valid until a client checks in with it. This mechanism is used instead of examining the request message’s audit trailer to verify the sender’s process ID because in some process architectures, it may be impossible to verify the client’s process ID.</p>
<p>The shared pipe serves another purpose: the server monitors it for an end-of-file (no readers) condition. Once detected, it will stop its blocking wait for a client to check in. This mechanism was also chosen for its ability to function properly in diverse process architectures.</p>
<p>This class can be used to allow a child process to provide its parent with a send right to its task port, in cases where it is desirable for the parent to have such access. It can also be used to allow a parent process to transfer a receive right to a child process that implements the server for that right, or for a child process to establish its own server and provide its parent with a send right to that server, for cases where a service is provided and it is undesirable or impossible to provide it via the bootstrap or launchd interfaces.</p>
<p>Example parent process, running a client that sends a receive right to its child: </p><divclass="fragment"><divclass="line">ChildPortHandshake child_port_handshake;</div><divclass="line">base::ScopedFD server_write_fd = child_port_handshake.ServerWriteFD();</div><divclass="line">std::string server_write_fd_string =</div><divclass="line"> base::StringPrintf(<spanclass="stringliteral">"%d"</span>, server_write_fd.get());</div><divclass="line"></div><divclass="line">pid_t pid = fork();</div><divclass="line"><spanclass="keywordflow">if</span> (pid == 0) {</div><divclass="line"><spanclass="comment">// Child</span></div><divclass="line"></div><divclass="line"><spanclass="comment">// Close all file descriptors above STDERR_FILENO except for</span></div><divclass="line"><spanclass="comment">// server_write_fd. Let the child know what file descriptor to use for</span></div><divclass="line"><spanclass="comment">// server_write_fd by passing it as argv[1]. Example code for the child</span></div><divclass="line"><spanclass="comment">// process is below.</span></div><divclass="line"><aclass="code"href="namespacecrashpad.html#a003f563ef0fe26081b4520012e0c1ef8">CloseMultipleNowOrOnExec</a>(STDERR_FILENO + 1, server_write_fd.get());</div><divclass="line"> execlp(<spanclass="stringliteral">"./child"</span>, <spanclass="stringliteral">"child"</span>, server_write_fd_string.c_str(), <spanclass="keyword">nullptr</span>);</div><divclass="line">}</div><divclass="line"></div><divclass="line"><spanclass="comment">// Parent</span></div><divclass="line"></div><divclass="line"><spanclass="comment">// Close the child’s end of the pipe.</span></div><divclass="line">server_write_fd.reset();</div><divclass="line"></div><divclass="line"><spanclass="comment">// Make a new Mach receive right.</span></div><divclass="line">base::mac::ScopedMachReceiveRight</div><divclass="line"> receive_right(<aclass="code"href="namespacecrashpad.html#a9c9bc6ad9973f794c425707617b63278">NewMachPort</a>(MACH_PORT_RIGHT_RECEIVE));</div><divclass="line"></div><divclass="line"><spanclass="comment">// Make a send right corresponding to the receive right.</span></div><divclass="line">mach_port_t send_right;</div><divclass="line">mach_msg_type_name_t send_right_type;</div><divclass="line">mach_port_extract_right(mach_task_self(),</div><divclass="line"> receive_right.get(),</div><divclass="line"> MACH_MSG_TYPE_MAKE_SEND,</div><divclass="line">&send_right,</div><divclass="line">&send_right_type);</div><divclass="line">base::mac::ScopedMachSendRight send_right_owner(send_right);</div><divclass="line"></div><divclass="line"><spanclass="comment">// Send the receive right to the child process, retaining the send right</span></div><divclass="line"><spanclass="comment">// for use in the parent process.</span></div><divclass="line"><spanclass="keywordflow">if</span> (child_port_handshake.RunClient(receive_right.get(),</div><divclass="line"> MACH_MSG_TYPE_MOVE_RECEIVE)) {</div><divclass="line"> ignore_result(receive_right.release());</div><divclass="line">}</div></div><!-- fragment --><p>Example child process, running a server that receives a receive right from its parent: </p><divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> main(<spanclass="keywordtype">int</span> argc, <spanclass="keywordtype">char</span>* argv[]) {</div><divclass="line"><spanclass="comment">// The parent passed server_write_fd in argv[1].</span></div><divclass="line"> base::ScopedFD server_write_fd(atoi(argv[1]));</div><divclass="line"></div><divclass="line"><spanclass="comment">// Obtain a receive right from the parent process.</span></div><divclass="line"> base::mac::ScopedMachReceiveRight receive_right(</div><divclass="line"><aclass="code"href="classcrashpad_1_1ChildPortHandshake.html#a0f73b816d441e5e7f6650c8c5601e6
<p>Controls whether a receive or send right is expected to be obtained from the client by the server’s call to <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#af1400270cdc498e9c05391389e7bddad"title="Runs the server. ">RunServer()</a>. </p>
<tr><thcolspan="2">Enumerator</th></tr><tr><tdclass="fieldname"><aid="a727e01831df67754b0ff439735f41608aca4dfdef124043305e6880e006032603"></a>kReceiveRight </td><tdclass="fielddoc"><p>The server expects to receive a receive right. </p>
<tr><tdclass="fieldname"><aid="a727e01831df67754b0ff439735f41608a765e48f6fd1bb0f18dab2cb92f6f6613"></a>kSendRight </td><tdclass="fielddoc"><p>The server expects to receive a send or send-once right. </p>
<p>Obtains the “read” side of the pipe, to be used by the client. </p>
<p>This file descriptor must be passed to <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a3f8c5aa2a2354ae65dcd9323554cdc2a"title="Runs the client. ">RunClientForFD()</a>.</p>
<dlclass="section return"><dt>Returns</dt><dd>The file descriptor that the client should read from. </dd></dl>
<p>This method closes the “write” side of the pipe in-process, so that the server process holds the only file descriptor that can write to the pipe. It then calls <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a3f8c5aa2a2354ae65dcd9323554cdc2a"title="Runs the client. ">RunClientForFD()</a> using the “read” side of the pipe. If <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a13c305bc7f510f7ec0696ea3257fef35"title="Obtains the “write” side of the pipe, to be used by the server. ">ServerWriteFD()</a> has already been called in the client process, the caller must ensure that the file descriptor returned by <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a13c305bc7f510f7ec0696ea3257fef35"title="Obtains the “write” side of the pipe, to be used by the server. ">ServerWriteFD()</a> is closed prior to calling this method.</p>
<dlclass="section return"><dt>Returns</dt><dd><code>true</code> on success, <code>false</code> on failure with a message logged. </dd></dl>
<p>If a <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html"title="Implements a handshake protocol that allows processes to exchange port rights. ">ChildPortHandshake</a> object is available, don’t call this static function. Instead, call <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a94543dc329a5a7d869cc1cb76e23fc20"title="Runs the client. ">RunClient()</a>, which wraps this function. When using this function, the caller is responsible for ensuring that the server “write” side of the pipe is closed in the client process prior to calling this function.</p>
<p>This function performs these tasks:</p><ul>
<li>Reads the token from the pipe.</li>
<li>Reads the bootstrap service name from the pipe.</li>
<li>Obtains a send right to the server by calling <code>bootstrap_look_up()</code>.</li>
<li>Sends a check-in message to the server by calling <code>child_port_check_in()</code>, providing the token and the user-supplied port right.</li>
<li>Deallocates the send right to the server, and closes the pipe.</li>
</ul>
<p>There is no return value because <code>child_port_check_in()</code> is a MIG <code>simpleroutine</code>, and the server does not send a reply. This allows check-in to occur without blocking to wait for a reply.</p>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">client_read_fd</td><td>The “read”side of the pipe shared with the server process. This function takes ownership of this file descriptor, and will close it prior to returning. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">port</td><td>The port right that will be passed to the server by <code>child_port_check_in()</code>. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">right_type</td><td>The right type to furnish the server with. If <em>port</em> is a send right, this can be <code>MACH_MSG_TYPE_COPY_SEND</code> or <code>MACH_MSG_TYPE_MOVE_SEND</code>. If <em>port</em> is a send-once right, this can be <code>MACH_MSG_TYPE_MOVE_SEND_ONCE</code>. If <em>port</em> is a receive right, this can be <code>MACH_MSG_TYPE_MAKE_SEND</code>, <code>MACH_MSG_TYPE_MAKE_SEND_ONCE</code>, or <code>MACH_MSG_TYPE_MOVE_RECEIVE</code>.</td></tr>
<dlclass="section return"><dt>Returns</dt><dd><code>true</code> on success, <code>false</code> on failure with a message logged. On failure, the port right corresponding to a <em>right_type</em> of <code>MACH_MSG_TYPE_MOVE_*</code> is not consumed, and the caller must dispose of the right if necessary. </dd></dl>
<p>This method closes the “read” side of the pipe in-process, so that the client process holds the only file descriptor that can read from the pipe. It then calls <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a0f73b816d441e5e7f6650c8c5601e654"title="Runs the server. ">RunServerForFD()</a> using the “write” side of the pipe. If <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a9298ec6d6ba1c3ca38157322fdd0c135"title="Obtains the “read” side of the pipe, to be used by the client. ">ClientReadFD()</a> has already been called in the server process, the caller must ensure that the file descriptor returned by <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a9298ec6d6ba1c3ca38157322fdd0c135"title="Obtains the “read” side of the pipe, to be used by the client. ">ClientReadFD()</a> is closed prior to calling this method. </p>
<p>If a <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html"title="Implements a handshake protocol that allows processes to exchange port rights. ">ChildPortHandshake</a> object is available, don’t call this static function. Instead, call <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#af1400270cdc498e9c05391389e7bddad"title="Runs the server. ">RunServer()</a>, which wraps this function. When using this function, the caller is responsible for ensuring that the client “read” side of the pipe is closed in the server process prior to calling this function.</p>
<li>Creates a random token and sends it via the pipe.</li>
<li>Checks its service in with the bootstrap server, and sends the name of its bootstrap service mapping via the pipe.</li>
<li>Simultaneously receives messages on its Mach server and monitors the pipe for end-of-file. This is a blocking operation.</li>
<li>When a Mach message is received, calls HandleChildPortCheckIn() to interpret and validate it, and if the message is valid, returns the port right extracted from the message. If the message is not valid, this method will continue waiting for a valid message. Valid messages are properly formatted and have the correct token. The right carried in a valid message will be returned. If a message is not valid, this method will continue waiting for pipe EOF or a valid message.</li>
<li>When notified of pipe EOF, returns <code>MACH_PORT_NULL</code>.</li>
<li>Regardless of return value, destroys the server’s receive right and closes the pipe.</li>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">server_write_fd</td><td>The writeside of the pipe shared with the client process. This function takes ownership of this file descriptor, and will close it prior to returning. </td></tr>
<tr><tdclass="paramdir">[in]</td><tdclass="paramname">port_right_type</td><td>The port right type expected to be received from the client. If the port right received from the client does not match the expected type, the received port right will be destroyed, and <code>MACH_PORT_NULL</code> will be returned.</td></tr>
<dlclass="section return"><dt>Returns</dt><dd>On success, the port right provided by the client. The caller takes ownership of this right. On failure, <code>MACH_PORT_NULL</code>, indicating that the client did not check in properly before terminating, where termination is detected by detecting that the read side of the shared pipe has closed. On failure, a message indicating the nature of the failure will be logged. </dd></dl>
<p>Obtains the “write” side of the pipe, to be used by the server. </p>
<p>This file descriptor must be passed to <aclass="el"href="classcrashpad_1_1ChildPortHandshake.html#a0f73b816d441e5e7f6650c8c5601e654"title="Runs the server. ">RunServerForFD()</a>.</p>
<dlclass="section return"><dt>Returns</dt><dd>The file descriptor that the server should write to. </dd></dl>
