OLD | NEW |
(Empty) | |
| 1 // Copyright 2014 The Crashpad Authors. All rights reserved. |
| 2 // |
| 3 // Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 // you may not use this file except in compliance with the License. |
| 5 // You may obtain a copy of the License at |
| 6 // |
| 7 // http://www.apache.org/licenses/LICENSE-2.0 |
| 8 // |
| 9 // Unless required by applicable law or agreed to in writing, software |
| 10 // distributed under the License is distributed on an "AS IS" BASIS, |
| 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 // See the License for the specific language governing permissions and |
| 13 // limitations under the License. |
| 14 |
| 15 #ifndef CRASHPAD_UTIL_MACH_CHILD_PORT_HANDSHAKE_H_ |
| 16 #define CRASHPAD_UTIL_MACH_CHILD_PORT_HANDSHAKE_H_ |
| 17 |
| 18 #include <mach/mach.h> |
| 19 |
| 20 #include <string> |
| 21 |
| 22 #include "base/basictypes.h" |
| 23 #include "base/files/scoped_file.h" |
| 24 #include "util/mach/child_port_server.h" |
| 25 |
| 26 namespace crashpad { |
| 27 |
| 28 namespace test { |
| 29 namespace { |
| 30 class ChildPortHandshakeTest; |
| 31 } // namespace |
| 32 } // namespace test |
| 33 |
| 34 //! \brief Implements a handshake protocol that allows a parent process to |
| 35 //! obtain a Mach port right from a child process. |
| 36 //! |
| 37 //! Ordinarily, there is no way for parent and child processes to exchange port |
| 38 //! rights, outside of the rights that children inherit from their parents. |
| 39 //! These include task-special ports and exception ports, but all of these have |
| 40 //! system-defined uses, and cannot reliably be replaced: in a multi-threaded |
| 41 //! parent, it is impossible to temporarily change one an inheritable port while |
| 42 //! maintaining a guarantee that another thread will not attempt to use it, and |
| 43 //! in children, it difficult to guarantee that nothing will attempt to use an |
| 44 //! inheritable port before it can be replaced with the correct one. This latter |
| 45 //! concern is becoming increasingly more pronounced as system libraries perform |
| 46 //! more operations that rely on an inheritable port in module initializers. |
| 47 //! |
| 48 //! The protocol implemented by this class involves a server that runs in the |
| 49 //! parent process. The server is published with the bootstrap server, which the |
| 50 //! child has access to because the bootstrap port is one of the inherited |
| 51 //! task-special ports. The parent and child also share a pipe, which the parent |
| 52 //! can write to and the child can read from. After launching a child process, |
| 53 //! the parent will write a random token to this pipe, along with the name under |
| 54 //! which its server has been registered with the bootstrap server. The child |
| 55 //! can then obtain a send right to this server with `bootstrap_look_up()`, and |
| 56 //! send a check-in message containing the token value and the port right of its |
| 57 //! choice by calling `child_port_check_in()`. |
| 58 //! |
| 59 //! The inclusion of the token authenticates the child to its parent. This is |
| 60 //! necessary because the service is published with the bootstrap server, which |
| 61 //! opens up access to it to more than the child process. Because the token is |
| 62 //! passed to the child by a shared pipe, it constitutes a shared secret not |
| 63 //! known by other processes that may have incidental access to the server. The |
| 64 //! ChildPortHandshake server considers its randomly-generated token valid until |
| 65 //! a client checks in with it. This mechanism is used instead of examining the |
| 66 //! request message’s audit trailer to verify the sender’s process ID because in |
| 67 //! some process architectures, it may be impossible to verify the child’s |
| 68 //! process ID. This may happen when the child disassociates from the parent |
| 69 //! with a double fork(), and the actual client is the parent’s grandchild. In |
| 70 //! this case, the child would not check in, but the grandchild, in possession |
| 71 //! of the token, would check in. |
| 72 //! |
| 73 //! The shared pipe serves another purpose: the server monitors it for an |
| 74 //! end-of-file (no readers) condition. Once detected, it will stop its blocking |
| 75 //! wait for a client to check in. This mechanism was chosen over monitoring a |
| 76 //! child process directly for exit to account for the possibility that the |
| 77 //! child might disassociate with a double fork(). |
| 78 //! |
| 79 //! This class can be used to allow a child process to provide its parent with |
| 80 //! a send right to its task port, in cases where it is desirable for the parent |
| 81 //! to have such access. It can also be used to allow a child process to |
| 82 //! establish its own server and provide its parent with a send right to that |
| 83 //! server, for cases where a service is provided and it is undesirable or |
| 84 //! impossible to provide it via the bootstrap or launchd interfaces. |
| 85 class ChildPortHandshake : public ChildPortServer::Interface { |
| 86 public: |
| 87 //! \brief Initializes the server. |
| 88 //! |
| 89 //! This creates the pipe so that the “read” side can be obtained by calling |
| 90 //! ReadPipeFD(). |
| 91 ChildPortHandshake(); |
| 92 |
| 93 ~ChildPortHandshake(); |
| 94 |
| 95 //! \brief Obtains the “read” side of the pipe, to be used by the client. |
| 96 //! |
| 97 //! Callers must obtain this file descriptor and arrange for the caller to |
| 98 //! have access to it before calling RunServer(). |
| 99 //! |
| 100 //! \return The file descriptor that the client should read from. |
| 101 int ReadPipeFD() const; |
| 102 |
| 103 //! \brief Runs the server. |
| 104 //! |
| 105 //! This method performs these tasks: |
| 106 //! - Closes the “read” side of the pipe in-process, so that the client |
| 107 //! process holds the only file descriptor that can read from the pipe. |
| 108 //! - Creates a random token and sends it via the pipe. |
| 109 //! - Checks its service in with the bootstrap server, and sends the name |
| 110 //! of its bootstrap service mapping via the pipe. |
| 111 //! - Simultaneously receives messages on its Mach server and monitors the |
| 112 //! pipe for end-of-file. This is a blocking operation. |
| 113 //! - When a Mach message is received, calls HandleChildPortCheckIn() to |
| 114 //! interpret and validate it, and if the message is valid, returns the |
| 115 //! port right extracted from the message. If the message is not valid, |
| 116 //! this method will continue waiting for a valid message. Valid messages |
| 117 //! are properly formatted and have the correct token. If a valid message |
| 118 //! carries a send or send-once right, it will be returned. If a valid |
| 119 //! message contains a receive right, it will be destroyed and |
| 120 //! `MACH_PORT_NULL` will be returned. If a message is not valid, this |
| 121 //! method will continue waiting for pipe EOF or a valid message. |
| 122 //! - When notified of pipe EOF, returns `MACH_PORT_NULL`. |
| 123 //! - Regardless of return value, destroys the server’s receive right and |
| 124 //! closes the pipe. |
| 125 //! |
| 126 //! \return On success, the send or send-once right to the port provided by |
| 127 //! the client. The caller takes ownership of this right. On failure, |
| 128 //! `MACH_PORT_NULL`, indicating that the client did not check in properly |
| 129 //! before terminating, where termination is detected by noticing that the |
| 130 //! read side of the shared pipe has closed. On failure, a message |
| 131 //! indiciating the nature of the failure will be logged. |
| 132 mach_port_t RunServer(); |
| 133 |
| 134 // ChildPortServer::Interface: |
| 135 kern_return_t HandleChildPortCheckIn(child_port_server_t server, |
| 136 child_port_token_t token, |
| 137 mach_port_t port, |
| 138 mach_msg_type_name_t right_type, |
| 139 bool* destroy_complex_request) override; |
| 140 |
| 141 //! \brief Runs the client. |
| 142 //! |
| 143 //! This function performs these tasks: |
| 144 //! - Reads the token from the pipe. |
| 145 //! - Reads the bootstrap service name from the pipe. |
| 146 //! - Obtains a send right to the server by calling `bootstrap_look_up()`. |
| 147 //! - Sends a check-in message to the server by calling |
| 148 //! `child_port_check_in()`, providing the token and the user-supplied port |
| 149 //! right. |
| 150 //! - Deallocates the send right to the server, and closes the pipe. |
| 151 //! |
| 152 //! There is no return value because `child_port_check_in()` is a MIG |
| 153 //! `simpleroutine`, and the server does not send a reply. This allows |
| 154 //! check-in to occur without blocking to wait for a reply. |
| 155 //! |
| 156 //! \param[in] pipe_read The “read” side of the pipe shared with the server |
| 157 //! process. |
| 158 //! \param[in] port The port that will be passed to the server by |
| 159 //! `child_port_check_in()`. |
| 160 //! \param[in] right_type The right type to furnish the parent with. If \a |
| 161 //! port is a send right, this can be `MACH_MSG_TYPE_COPY_SEND` or |
| 162 //! `MACH_MSG_TYPE_MOVE_SEND`. If \a port is a send-once right, this can |
| 163 //! be `MACH_MSG_TYPE_MOVE_SEND_ONCE`. If \a port is a receive right, |
| 164 //! this can be `MACH_MSG_TYPE_MAKE_SEND`. `MACH_MSG_TYPE_MOVE_RECEIVE` |
| 165 //! is supported by the client interface but will be silently rejected by |
| 166 //! server run by RunServer(), which expects to receive only send or |
| 167 //! send-once rights. |
| 168 static void RunClient(int pipe_read, |
| 169 mach_port_t port, |
| 170 mach_msg_type_name_t right_type); |
| 171 |
| 172 private: |
| 173 //! \brief Runs the read-from-pipe portion of the client’s side of the |
| 174 //! handshake. This is an implementation detail of RunClient and is only |
| 175 //! exposed for testing purposes. |
| 176 //! |
| 177 //! \param[in] pipe_read The “read” side of the pipe shared with the server |
| 178 //! process. |
| 179 //! \param[out] token The token value read from \a pipe_read. |
| 180 //! \param[out] service_name The service name as registered with the bootstrap |
| 181 //! server, read from \a pipe_read. |
| 182 static void RunClientInternal_ReadPipe(int pipe_read, |
| 183 child_port_token_t* token, |
| 184 std::string* service_name); |
| 185 |
| 186 //! \brief Runs the check-in portion of the client’s side of the handshake. |
| 187 //! This is an implementation detail of RunClient and is only exposed for |
| 188 //! testing purposes. |
| 189 //! |
| 190 //! \param[in] service_name The service name as registered with the bootstrap |
| 191 //! server, to be looked up with `bootstrap_look_up()`. |
| 192 //! \param[in] token The token value to provide during check-in. |
| 193 //! \param[in] port The port that will be passed to the server by |
| 194 //! `child_port_check_in()`. |
| 195 //! \param[in] right_type The right type to furnish the parent with. |
| 196 static void RunClientInternal_SendCheckIn(const std::string& service_name, |
| 197 child_port_token_t token, |
| 198 mach_port_t port, |
| 199 mach_msg_type_name_t right_type); |
| 200 |
| 201 // Communicates the token from RunServer(), where it’s generated, to |
| 202 // HandleChildPortCheckIn(), where it’s validated. |
| 203 child_port_token_t token_; |
| 204 |
| 205 base::ScopedFD pipe_read_; |
| 206 base::ScopedFD pipe_write_; |
| 207 |
| 208 // Communicates the port received from the client from |
| 209 // HandleChildPortCheckIn(), where it’s received, to RunServer(), where it’s |
| 210 // returned. This is strongly-owned, but ownership is transferred to |
| 211 // RunServer()’s caller. |
| 212 mach_port_t child_port_; |
| 213 |
| 214 // Communicates that a check-in with a valid token was received by |
| 215 // HandleChildPortCheckIn(), and that the value of child_port_ should be |
| 216 // returned to RunServer()’s caller. |
| 217 bool checked_in_; |
| 218 |
| 219 friend class test::ChildPortHandshakeTest; |
| 220 |
| 221 DISALLOW_COPY_AND_ASSIGN(ChildPortHandshake); |
| 222 }; |
| 223 |
| 224 } // namespace crashpad |
| 225 |
| 226 #endif // CRASHPAD_UTIL_MACH_CHILD_PORT_HANDSHAKE_H_ |
OLD | NEW |