passenger 2.2.15 → 3.0.0.pre1

data/ext/common/MessageChannel.h

@@ -1,6 +1,6 @@
 /*
  *  Phusion Passenger - http://www.modrails.com/
- *  Copyright (c) 2008, 2009 Phusion
+ *  Copyright (c) 2010 Phusion
  *
  *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
  *
@@ -26,6 +26,7 @@
 #define _PASSENGER_MESSAGE_CHANNEL_H_
 
 #include <oxt/system_calls.hpp>
+#include <oxt/macros.hpp>
 
 #include <algorithm>
 #include <string>
@@ -34,24 +35,22 @@
 
 #include <sys/types.h>
 #include <sys/socket.h>
+#include <sys/uio.h>
 #include <arpa/inet.h>
 #include <errno.h>
 #include <unistd.h>
 #include <cstdarg>
-#ifdef __OpenBSD__
-	// OpenBSD needs this for 'struct iovec'. Apparently it isn't
-	// always included by unistd.h and sys/types.h.
-	#include <sys/uio.h>
-#endif
 #if !APR_HAVE_IOVEC
 	// We don't want apr_want.h to redefine 'struct iovec'.
-	// http://tinyurl.com/b6aatw
+	// http://groups.google.com/group/phusion-passenger/browse_thread/thread/7e162f60df212e9c
 	#undef APR_HAVE_IOVEC
 	#define APR_HAVE_IOVEC 1
 #endif
 
+#include "StaticString.h"
 #include "Exceptions.h"
-#include "Utils.h"
+#include "Utils/Timer.h"
+#include "Utils/MemZeroGuard.h"
 
 namespace Passenger {
 
@@ -65,6 +64,7 @@ using namespace oxt;
  *  - sending and receiving raw data over a file descriptor.
  *  - sending and receiving messages over a file descriptor.
  *  - file descriptor passing over a Unix socket.
+ *  - data size limit enforcement and time constraint enforcement.
  * All of these methods use exceptions for error reporting.
  *
  * There are two kinds of messages:
@@ -110,6 +110,10 @@ using namespace oxt;
  *    receiving side does things in the wrong order then bad things will
  *    happen.
  * @note MessageChannel is not thread-safe, but is reentrant.
+ * @note Some methods throw SecurityException and TimeoutException. When these
+ *    exceptions are thrown, the channel will be left in an inconsistent state
+ *    because only parts of the data have been read. You should close the channel
+ *    after having caught these exceptions.
  *
  * @ingroup Support
  */
@@ -141,20 +145,36 @@ public:
 		this->fd = fd;
 	}
 	
+	/**
+	 * Returns the underlying file descriptor. -1 if it has already been closed.
+	 */
+	int filenum() const {
+		return fd;
+	}
+	
+	/**
+	 * Returns whether close() has been called.
+	 */
+	bool connected() const {
+		return fd != -1;
+	}
+	
 	/**
 	 * Close the underlying file descriptor. If this method is called multiple
 	 * times, the file descriptor will only be closed the first time.
 	 *
 	 * @throw SystemException
 	 * @throw boost::thread_interrupted
+	 * @post filenum() == -1
+	 * @post !connected()
 	 */
 	void close() {
 		if (fd != -1) {
 			int ret = syscalls::close(fd);
+			fd = -1;
 			if (ret == -1) {
 				throw SystemException("Cannot close file descriptor", errno);
 			}
-			fd = -1;
 		}
 	}
 
@@ -221,22 +241,17 @@ public:
 	
 	/**
 	 * Send an array message, which consists of the given strings, over the underlying
-	 * file descriptor.
+	 * file descriptor. Like <tt>write(const char *name, ...)</tt> but takes a va_list
+	 * instead.
 	 *
-	 * @param name The first element of the message to send.
-	 * @param ... Other elements of the message. These *must* be strings, i.e. of type char*.
-	 *            It is also required to terminate this list with a NULL.
 	 * @throws SystemException An error occured while writing the data to the file descriptor.
 	 * @throws boost::thread_interrupted
 	 * @pre None of the message elements may contain a NUL character (<tt>'\\0'</tt>).
-	 * @see read(), write(const list<string> &)
 	 */
-	void write(const char *name, ...) {
+	void write(const char *name, va_list &ap) {
 		list<string> args;
 		args.push_back(name);
 		
-		va_list ap;
-		va_start(ap, name);
 		while (true) {
 			const char *arg = va_arg(ap, const char *);
 			if (arg == NULL) {
@@ -245,12 +260,50 @@ public:
 				args.push_back(arg);
 			}
 		}
-		va_end(ap);
 		write(args);
 	}
 	
 	/**
-	 * Send a scalar message over the underlying file descriptor.
+	 * Send an array message, which consists of the given strings, over the underlying
+	 * file descriptor.
+	 *
+	 * @param name The first element of the message to send.
+	 * @param ... Other elements of the message. These *must* be strings, i.e. of type char*.
+	 *            It is also required to terminate this list with a NULL.
+	 * @throws SystemException An error occured while writing the data to the file descriptor.
+	 * @throws boost::thread_interrupted
+	 * @pre None of the message elements may contain a NUL character (<tt>'\\0'</tt>).
+	 * @see read(), write(const list<string> &)
+	 */
+	void write(const char *name, ...) {
+		va_list ap;
+		va_start(ap, name);
+		try {
+			write(name, ap);
+			va_end(ap);
+		} catch (...) {
+			va_end(ap);
+			throw;
+		}
+	}
+	
+	/**
+	 * Write a 32-bit big-endian unsigned integer to the underlying file descriptor.
+	 *
+	 * @throws SystemException An error occurred while writing the data to the file descriptor.
+	 * @throws boost::thread_interrupted
+	 */
+	void writeUint32(unsigned int value) {
+		uint32_t l = htonl(value);
+		writeRaw((const char *) &l, sizeof(uint32_t));
+	}
+	
+	/**
+	 * Write a scalar message to the underlying file descriptor.
+	 *
+	 * @note Security guarantee: this method will not copy the data in memory,
+	 *       so it's safe to use this method to write passwords to the underlying
+	 *       file descriptor.
 	 *
 	 * @param str The scalar message's content.
 	 * @throws SystemException An error occured while writing the data to the file descriptor.
@@ -262,7 +315,11 @@ public:
 	}
 	
 	/**
-	 * Send a scalar message over the underlying file descriptor.
+	 * Write a scalar message to the underlying file descriptor.
+	 *
+	 * @note Security guarantee: this method will not copy the data in memory,
+	 *       so it's safe to use this method to write passwords to the underlying
+	 *       file descriptor.
 	 *
 	 * @param data The scalar message's content.
 	 * @param size The number of bytes in <tt>data</tt>.
@@ -272,8 +329,7 @@ public:
 	 * @see readScalar(), writeScalar(const string &)
 	 */
 	void writeScalar(const char *data, unsigned int size) {
-		uint32_t l = htonl(size);
-		writeRaw((const char *) &l, sizeof(uint32_t));
+		writeUint32(size);
 		writeRaw(data, size);
 	}
 	
@@ -281,6 +337,10 @@ public:
 	 * Send a block of data over the underlying file descriptor.
 	 * This method blocks until everything is sent.
 	 *
+	 * @note Security guarantee: this method will not copy the data in memory,
+	 *       so it's safe to use this method to write passwords to the underlying
+	 *       file descriptor.
+	 *
 	 * @param data The data to send.
 	 * @param size The number of bytes in <tt>data</tt>.
 	 * @pre <tt>data != NULL</tt>
@@ -305,6 +365,10 @@ public:
 	 * Send a block of data over the underlying file descriptor.
 	 * This method blocks until everything is sent.
 	 *
+	 * @note Security guarantee: this method will not copy the data in memory,
+	 *       so it's safe to use this method to write passwords to the underlying
+	 *       file descriptor.
+	 *
 	 * @param data The data to send.
 	 * @pre <tt>data != NULL</tt>
 	 * @throws SystemException An error occured while writing the data to the file descriptor.
@@ -443,36 +507,83 @@ public:
 		return true;
 	}
 	
+	/**
+	 * Read a 32-bit big-endian unsigned integer from the underlying file descriptor.
+	 *
+	 * @param value Upon success, the read value will be stored in here.
+	 * @param timeout A pointer to an integer, representing the maximum number of
+	 *                milliseconds to spend on reading the entire integer.
+	 *                A TimeoutException will be thrown if the timeout expires.
+	 *                If no exception is thrown, the the amount of time spent on waiting
+	 *                will be deducted from <tt>*timeout</tt>.
+	 *                Pass NULL if you do not want to enforce any time limits.
+	 * @return True if a value was read, false if EOF was reached before all data can be
+	 *         read.
+	 * @throws SystemException An error occurred while reading data from the file descriptor.
+	 * @throws boost::thread_interrupted
+	 */
+	bool readUint32(unsigned int &value, unsigned long long *timeout = NULL) {
+		uint32_t temp;
+		
+		if (!readRaw(&temp, sizeof(uint32_t), timeout)) {
+			return false;
+		} else {
+			value = ntohl(temp);
+			return true;
+		}
+	}
+	
 	/**
 	 * Read a scalar message from the underlying file descriptor.
 	 *
 	 * @param output The message will be put in here.
+	 * @param maxSize The maximum number of bytes that may be read. If the
+	 *                scalar to read is larger than this, then a SecurityException
+	 *                will be thrown. Set to 0 for no size limit.
+	 * @param timeout A pointer to an integer, representing the maximum number of
+	 *                milliseconds to spend on reading the entire scalar.
+	 *                A TimeoutException will be thrown if unable to read the entire
+	 *                scalar within this time period.
+	 *                If no exception is thrown, the the amount of time spent on waiting
+	 *                will be deducted from <tt>*timeout</tt>.
+	 *                Pass NULL if you do not want to enforce any time limits.
 	 * @returns Whether end-of-file was reached during reading.
-	 * @throws SystemException An error occured while writing the data to the file descriptor.
+	 * @throws SystemException An error occured while reading data from the file descriptor.
+	 * @throws SecurityException There is more data to read than allowed by maxSize.
+	 * @throws TimeoutException Unable to read the entire scalar within <tt>timeout</tt>
+	 *                          milliseconds.
 	 * @throws boost::thread_interrupted
 	 * @see writeScalar()
 	 */
-	bool readScalar(string &output) {
-		uint32_t size;
+	bool readScalar(string &output, unsigned int maxSize = 0, unsigned long long *timeout = NULL) {
+		unsigned int size;
 		unsigned int remaining;
 		
-		if (!readRaw(&size, sizeof(uint32_t))) {
+		if (!readUint32(size, timeout)) {
 			return false;
 		}
-		size = ntohl(size);
+		
+		if (maxSize != 0 && size > maxSize) {
+			throw SecurityException("There is more data available than is allowed by the size limit.");
+		}
 		
 		output.clear();
 		output.reserve(size);
 		remaining = size;
-		while (remaining > 0) {
+		if (OXT_LIKELY(remaining > 0)) {
 			char buf[1024 * 32];
-			unsigned int blockSize = min((unsigned int) sizeof(buf), remaining);
+			// Wipe the buffer when we're done; it might contain sensitive data.
+			MemZeroGuard g(buf, sizeof(buf));
 			
-			if (!readRaw(buf, blockSize)) {
-				return false;
+			while (remaining > 0) {
+				unsigned int blockSize = min((unsigned int) sizeof(buf), remaining);
+				
+				if (!readRaw(buf, blockSize, timeout)) {
+					return false;
+				}
+				output.append(buf, blockSize);
+				remaining -= blockSize;
 			}
-			output.append(buf, blockSize);
-			remaining -= blockSize;
 		}
 		return true;
 	}
@@ -487,17 +598,30 @@ public:
 	 * @param buf The buffer to place the read data in. This buffer must be at least
 	 *            <tt>size</tt> bytes long.
 	 * @param size The number of bytes to read.
+	 * @param timeout A pointer to an integer, which specifies the maximum number of
+	 *                milliseconds that may be spent on reading the <tt>size</tt> bytes
+	 *                of data. If the timeout expired then TimeoutException will be
+	 *                thrown.
+	 *                If this function returns without throwing an exception, then the
+	 *                total number of milliseconds spent on reading will be deducted
+	 *                from <tt>timeout</tt>.
+	 *                Pass NULL if you do not want to enforce a timeout.
 	 * @return Whether reading was successful or whether EOF was reached.
 	 * @pre buf != NULL
 	 * @throws SystemException Something went wrong during reading.
+	 * @throws TimeoutException Unable to read <tt>size</tt> bytes of data within
+	 *                          <tt>timeout</tt> milliseconds.
 	 * @throws boost::thread_interrupted
 	 * @see writeRaw()
 	 */
-	bool readRaw(void *buf, unsigned int size) {
+	bool readRaw(void *buf, unsigned int size, unsigned long long *timeout = NULL) {
 		ssize_t ret;
 		unsigned int alreadyRead = 0;
 		
 		while (alreadyRead < size) {
+			if (timeout != NULL && !waitUntilReadable(timeout)) {
+				throw TimeoutException("Cannot read enough data within the specified timeout.");
+			}
 			ret = syscalls::read(fd, (char *) buf + alreadyRead, size - alreadyRead);
 			if (ret == -1) {
 				throw SystemException("read() failed", errno);
@@ -510,6 +634,44 @@ public:
 		return true;
 	}
 	
+	/**
+	 * Waits at most <tt>*timeout</tt> milliseconds for the file descriptor to become readable.
+	 * Returns true if it become readable within the timeout, false if the timeout expired.
+	 *
+	 * <tt>*timeout</tt> may be 0, in which case this method will check whether the file
+	 * descriptor is readable, and immediately returns without waiting.
+	 *
+	 * If no exception is thrown, this method deducts the number of milliseconds that has
+	 * passed from <tt>*timeout</tt>.
+	 *
+	 * @throws SystemException
+	 * @throws boost::thread_interrupted
+	 */
+	bool waitUntilReadable(unsigned long long *timeout) {
+		fd_set fds;
+		struct timeval tv;
+		int ret;
+		
+		FD_ZERO(&fds);
+		FD_SET(fd, &fds);
+		tv.tv_sec  = *timeout / 1000;
+		tv.tv_usec = *timeout % 1000 * 1000;
+		
+		Timer timer;
+		ret = syscalls::select(fd + 1, &fds, NULL, NULL, &tv);
+		if (ret == -1) {
+			throw SystemException("select() failed", errno);
+		} else {
+			unsigned long long elapsed = timer.elapsed();
+			if (elapsed > *timeout) {
+				*timeout = 0;
+			} else {
+				*timeout -= elapsed;
+			}
+			return ret != 0;
+		}
+	}
+	
 	/**
 	 * Receive a file descriptor, which had been passed over the underlying
 	 * file descriptor.

data/ext/common/MessageClient.h

@@ -0,0 +1,297 @@
+/*
+ *  Phusion Passenger - http://www.modrails.com/
+ *  Copyright (c) 2010 Phusion
+ *
+ *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ *  THE SOFTWARE.
+ */
+#ifndef _PASSENGER_MESSAGE_CLIENT_H_
+#define _PASSENGER_MESSAGE_CLIENT_H_
+
+#include <boost/shared_ptr.hpp>
+#include <string>
+
+#include "StaticString.h"
+#include "MessageChannel.h"
+#include "Exceptions.h"
+#include "Utils/IOUtils.h"
+
+
+namespace Passenger {
+
+using namespace std;
+using namespace boost;
+
+class MessageClient {
+protected:
+	FileDescriptor fd;
+	MessageChannel channel;
+	bool shouldAutoDisconnect;
+	
+	/* sendUsername() and sendPassword() exist and are virtual in order to facilitate unit testing. */
+	
+	virtual void sendUsername(MessageChannel &channel, const string &username) {
+		channel.writeScalar(username);
+	}
+	
+	virtual void sendPassword(MessageChannel &channel, const StaticString &userSuppliedPassword) {
+		channel.writeScalar(userSuppliedPassword.c_str(), userSuppliedPassword.size());
+	}
+	
+	/**
+	 * Authenticate to the server with the given username and password.
+	 *
+	 * @throws SystemException An error occurred while reading data from or sending data to the server.
+	 * @throws IOException An error occurred while reading data from or sending data to the server.
+	 * @throws SecurityException The server denied authentication.
+	 * @throws boost::thread_interrupted
+	 * @pre <tt>channel</tt> is connected.
+	 */
+	void authenticate(const string &username, const StaticString &userSuppliedPassword) {
+		vector<string> args;
+		
+		sendUsername(channel, username);
+		sendPassword(channel, userSuppliedPassword);
+		
+		if (!channel.read(args)) {
+			throw IOException("The message server did not send an authentication response.");
+		} else if (args.size() != 1) {
+			throw IOException("The authentication response that the message server sent is not valid.");
+		} else if (args[0] != "ok") {
+			throw SecurityException("The message server denied authentication: " + args[0]);
+		}
+	}
+	
+	void autoDisconnect() {
+		if (shouldAutoDisconnect) {
+			// Closes the connection without throwing close exceptions.
+			fd = FileDescriptor();
+			channel = MessageChannel();
+		}
+	}
+	
+public:
+	/**
+	 * Create a new MessageClient object. It doesn't actually connect to the server until
+	 * you call connect().
+	 */
+	MessageClient() {
+		/* The reason why we don't connect right away is because we want to make
+		 * certain methods virtual for unit testing purposes. We can't call
+		 * virtual methods in the constructor. :-(
+		 */
+		shouldAutoDisconnect = true;
+	}
+	
+	virtual ~MessageClient() { }
+	
+	/**
+	 * Connect to the given MessageServer. If a connection was already established,
+	 * then the old connection will be closed and a new connection will be established.
+	 *
+	 * If this MessageClient was in a connected state, and this method throws an exception,
+	 * then old connection will be broken.
+	 *
+	 * @param serverAddress The address of the server to connect to, in the format
+	 *                      as specified by getSocketAddressType().
+	 * @param username The username to use for authenticating with the server.
+	 * @param userSuppliedPassword The password to use for authenticating with the server.
+	 * @return this
+	 * @throws SystemException Something went wrong while connecting to the server.
+	 * @throws IOException Something went wrong while connecting to the server.
+	 * @throws RuntimeException Something went wrong.
+	 * @throws SecurityException Unable to authenticate to the server with the given username and password.
+	 *                           You may call connect() again with a different username/password.
+	 * @throws boost::thread_interrupted
+	 * @post connected()
+	 */
+	MessageClient *connect(const string &serverAddress, const string &username,
+		const StaticString &userSuppliedPassword)
+	{
+		TRACE_POINT();
+		try {
+			fd = connectToServer(serverAddress.c_str());
+			channel = MessageChannel(fd);
+			
+			vector<string> args;
+			if (!read(args)) {
+				throw IOException("The message server closed the connection before sending a version identifier.");
+			}
+			if (args.size() != 2 || args[0] != "version") {
+				throw IOException("The message server didn't sent a valid version identifier.");
+			}
+			if (args[1] != "1") {
+				string message = string("Unsupported message server protocol version ") +
+					args[1] + ".";
+				throw IOException(message);
+			}
+			
+			authenticate(username, userSuppliedPassword);
+			return this;
+		} catch (const RuntimeException &) {
+			autoDisconnect();
+			throw;
+		} catch (const SystemException &) {
+			autoDisconnect();
+			throw;
+		} catch (const IOException &) {
+			autoDisconnect();
+			throw;
+		} catch (const boost::thread_interrupted &) {
+			autoDisconnect();
+			throw;
+		}
+	}
+	
+	void disconnect() {
+		fd.close();
+		fd = FileDescriptor();
+		channel = MessageChannel();
+	}
+	
+	bool connected() const {
+		return fd != -1;
+	}
+	
+	void setAutoDisconnect(bool value) {
+		shouldAutoDisconnect = value;
+	}
+	
+	FileDescriptor getConnection() const {
+		return fd;
+	}
+	
+	/**
+	 * @throws SystemException
+	 * @throws boost::thread_interrupted
+	 */
+	bool read(vector<string> &args) {
+		try {
+			return channel.read(args);
+		} catch (const SystemException &e) {
+			autoDisconnect();
+			throw;
+		}
+	}
+	
+	/**
+	 * @throws SystemException
+	 * @throws SecurityException
+	 * @throws TimeoutException
+	 * @throws boost::thread_interrupted
+	 */
+	bool readScalar(string &output, unsigned int maxSize = 0, unsigned long long *timeout = NULL) {
+		try {
+			return channel.readScalar(output, maxSize, timeout);
+		} catch (const SystemException &) {
+			autoDisconnect();
+			throw;
+		} catch (const SecurityException &) {
+			autoDisconnect();
+			throw;
+		} catch (const TimeoutException &) {
+			autoDisconnect();
+			throw;
+		}
+	}
+	
+	/**
+	 * @throws SystemExeption
+	 * @throws IOException
+	 * @throws boost::thread_interrupted
+	 */
+	int readFileDescriptor(bool negotiate = true) {
+		try {
+			return channel.readFileDescriptor(negotiate);
+		} catch (const SystemException &) {
+			autoDisconnect();
+			throw;
+		} catch (const IOException &) {
+			autoDisconnect();
+			throw;
+		}
+	}
+	
+	/**
+	 * @throws SystemException
+	 * @throws boost::thread_interrupted
+	 */
+	void write(const char *name, ...) {
+		va_list ap;
+		va_start(ap, name);
+		try {
+			try {
+				channel.write(name, ap);
+			} catch (const SystemException &) {
+				autoDisconnect();
+				throw;
+			}
+			va_end(ap);
+		} catch (...) {
+			va_end(ap);
+			throw;
+		}
+	}
+	
+	/**
+	 * @throws SystemException
+	 * @throws boost::thread_interrupted
+	 */
+	void writeScalar(const char *data, unsigned int size) {
+		try {
+			channel.writeScalar(data, size);
+		} catch (const SystemException &) {
+			autoDisconnect();
+			throw;
+		}
+	}
+	
+	/**
+	 * @throws SystemException
+	 * @throws boost::thread_interrupted
+	 */
+	void writeScalar(const StaticString &data) {
+		try {
+			channel.writeScalar(data.c_str(), data.size());
+		} catch (const SystemException &) {
+			autoDisconnect();
+			throw;
+		}
+	}
+	
+	/**
+	 * @throws SystemException
+	 * @throws boost::thread_interrupted
+	 */
+	void writeFileDescriptor(int fileDescriptor, bool negotiate = true) {
+		try {
+			channel.writeFileDescriptor(fileDescriptor, negotiate);
+		} catch (const SystemException &) {
+			autoDisconnect();
+			throw;
+		}
+	}
+};
+
+typedef shared_ptr<MessageClient> MessageClientPtr;
+
+} // namespace Passenger
+
+#endif /* _PASSENGER_MESSAGE_CLIENT_H_ */