Implements a handshake protocol that allows a parent process to obtain a Mach port right from a child process. More...

#include "util/mach/child_port_handshake.h"

Inheritance diagram for crashpad::ChildPortHandshake:

Public Member Functions
	ChildPortHandshake ()
	Initializes the server. More...

int	ReadPipeFD () const
	Obtains the “read” side of the pipe, to be used by the client. More...

mach_port_t	RunServer ()
	Runs the server. More...

kern_return_t	HandleChildPortCheckIn (child_port_server_t server, child_port_token_t token, mach_port_t port, mach_msg_type_name_t right_type, const mach_msg_trailer_t trailer, bool destroy_request) override
	Handles check-ins sent by `child_port_check_in()`. More...

Static Public Member Functions
static void	RunClient (int pipe_read, mach_port_t port, mach_msg_type_name_t right_type)
	Runs the client. More...

Friends
class	test::ChildPortHandshakeTest

Detailed Description

Implements a handshake protocol that allows a parent process to obtain a Mach port right from a child process.

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 one 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 inheritable port in module initializers.

The protocol implemented by this class involves a server that runs in the parent process. The server is published with the bootstrap server, which the child has access to because the bootstrap port is one of the inherited task-special ports. The parent and child also share a pipe, which the parent can write to and the child can read from. After launching a child process, the parent will write a random token to this pipe, along with the name under which its server has been registered with the bootstrap server. The child can then obtain a send right to this server with bootstrap_look_up(), and send a check-in message containing the token value and the port right of its choice by calling child_port_check_in().

The inclusion of the token authenticates the child to its parent. This is necessary because the service is published with the bootstrap server, which opens up access to it to more than the child process. Because the token is passed to the child by a shared pipe, it constitutes a shared secret not known by other processes that may have incidental access to the server. The ChildPortHandshake 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 child’s process ID. This may happen when the child disassociates from the parent with a double fork(), and the actual client is the parent’s grandchild. In this case, the child would not check in, but the grandchild, in possession of the token, would check in.

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 chosen over monitoring a child process directly for exit to account for the possibility that the child might disassociate with a double fork().

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 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.

Constructor & Destructor Documentation

crashpad::ChildPortHandshake::ChildPortHandshake ( )

Initializes the server.

This creates the pipe so that the “read” side can be obtained by calling ReadPipeFD().

Member Function Documentation

kern_return_t crashpad::ChildPortHandshake::HandleChildPortCheckIn	(	child_port_server_t	server,
		child_port_token_t	token,
		mach_port_t	port,
		mach_msg_type_name_t	right_type,
		const mach_msg_trailer_t *	trailer,
		bool *	destroy_request
	)

overridevirtual

Handles check-ins sent by child_port_check_in().

This behaves equivalently to a handle_child_port_check_in() function used with child_port_server().

Parameters

[in]	trailer	The trailer received with the request message.
[out]	destroy_request	`true` if the request message is to be destroyed even when this method returns success. See MachMessageServer::Interface.

Implements crashpad::ChildPortServer::Interface.

int crashpad::ChildPortHandshake::ReadPipeFD ( ) const

Obtains the “read” side of the pipe, to be used by the client.

Callers must obtain this file descriptor and arrange for the caller to have access to it before calling RunServer().

Returns: The file descriptor that the client should read from.

void crashpad::ChildPortHandshake::RunClient	(	int	pipe_read,
		mach_port_t	port,
		mach_msg_type_name_t	right_type
	)

static

Runs the client.

This function performs these tasks:

Reads the token from the pipe.
Reads the bootstrap service name from the pipe.
Obtains a send right to the server by calling bootstrap_look_up().
Sends a check-in message to the server by calling child_port_check_in(), providing the token and the user-supplied port right.
Deallocates the send right to the server, and closes the pipe.

There is no return value because child_port_check_in() is a MIG simpleroutine, and the server does not send a reply. This allows check-in to occur without blocking to wait for a reply.

Parameters

[in]	pipe_read	The “read” side of the pipe shared with the server process.
[in]	port	The port that will be passed to the server by `child_port_check_in()`.
[in]	right_type	The right type to furnish the parent with. If port is a send right, this can be `MACH_MSG_TYPE_COPY_SEND` or `MACH_MSG_TYPE_MOVE_SEND`. If port is a send-once right, this can be `MACH_MSG_TYPE_MOVE_SEND_ONCE`. If port is a receive right, this can be `MACH_MSG_TYPE_MAKE_SEND`. `MACH_MSG_TYPE_MOVE_RECEIVE` is supported by the client interface but will be silently rejected by server run by RunServer(), which expects to receive only send or send-once rights.

mach_port_t crashpad::ChildPortHandshake::RunServer ( )

Runs the server.

This method performs these tasks:

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.
Creates a random token and sends it via the pipe.
Checks its service in with the bootstrap server, and sends the name of its bootstrap service mapping via the pipe.
Simultaneously receives messages on its Mach server and monitors the pipe for end-of-file. This is a blocking operation.
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. If a valid message carries a send or send-once right, it will be returned. If a valid message contains a receive right, it will be destroyed and MACH_PORT_NULL will be returned. If a message is not valid, this method will continue waiting for pipe EOF or a valid message.
When notified of pipe EOF, returns MACH_PORT_NULL.
Regardless of return value, destroys the server’s receive right and closes the pipe.

Returns: On success, the send or send-once right to the port provided by the client. The caller takes ownership of this right. On failure, MACH_PORT_NULL, indicating that the client did not check in properly before terminating, where termination is detected by noticing that the read side of the shared pipe has closed. On failure, a message indiciating the nature of the failure will be logged.

The documentation for this class was generated from the following files:

util/mach/child_port_handshake.h
util/mach/child_port_handshake.cc

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation