Add SecureServer for secure TLS connections

Author: clue

README.md

@@ -13,6 +13,7 @@ and [`Stream`](https://github.com/reactphp/stream) components.
 * [Quickstart example](#quickstart-example)
 * [Usage](#usage)
   * [Server](#server)
+  * [SecureServer](#secureserver)
   * [ConnectionInterface](#connectioninterface)
     * [getRemoteAddress()](#getremoteaddress)
 * [Install](#install)
@@ -77,10 +78,60 @@ instance implementing [`ConnectionInterface`](#connectioninterface):
 
 ```php
 $server->on('connection', function (ConnectionInterface $connection) {
+    echo 'Plaintext connection from ' . $connection->getRemoteAddress() . PHP_EOL;
+    
+    $connection->write('hello there!' . PHP_EOL);
     …
 });
 ```
 
+### SecureServer
+
+The `SecureServer` class implements the `ServerInterface` and is responsible
+for providing a secure TLS (formerly known as SSL) server.
+
+It does so by wrapping a [`Server`](#server) instance which waits for plaintext
+TCP/IP connections and then performs a TLS handshake for each connection.
+It thus requires valid [TLS context options](http://php.net/manual/en/context.ssl.php),
+which in its most basic form may look something like this if you're using a
+PEM encoded certificate file:
+
+```php
+$server = new Server($loop);
+
+$server = new SecureServer($server, $loop, array(
+    'local_cert' => 'server.pem'
+));
+
+$server->listen(8000);
+```
+
+> Note that the certificate file will not be loaded on instantiation but when an
+incoming connection initializes its TLS context.
+This implies that any invalid certificate file paths or contents will only cause
+an `error` event at a later time.
+
+Whenever a client completes the TLS handshake, it will emit a `connection` event
+with a connection instance implementing [`ConnectionInterface`](#connectioninterface):
+
+```php
+$server->on('connection', function (ConnectionInterface $connection) {
+    echo 'Secure connection from' . $connection->getRemoteAddress() . PHP_EOL;
+    
+    $connection->write('hello there!' . PHP_EOL);
+    …
+});
+```
+
+Whenever a client fails to perform a successful TLS handshake, it will emit an
+`error` event and then close the underlying TCP/IP connection:
+
+```php
+$server->on('error', function (Exception $e) {
+    echo 'Error' . $e->getMessage() . PHP_EOL;
+});
+```
+
 ### ConnectionInterface
 
 The `ConnectionInterface` is used to represent any incoming connection.

composer.json

@@ -7,7 +7,8 @@
         "php": ">=5.3.0",
         "evenement/evenement": "~2.0|~1.0",
         "react/event-loop": "0.4.*|0.3.*",
-        "react/stream": "^0.4.2"
+        "react/stream": "^0.4.5",
+        "react/promise": "^2.0 || ^1.1"
     },
     "require-dev": {
         "react/socket-client": "^0.5.1",

examples/01-echo.php

@@ -5,23 +5,39 @@
 //
 // $ php examples/01-echo.php 8000
 // $ telnet localhost 8000
+//
+// You can also run a secure TLS echo server like this:
+//
+// $ php examples/01-echo.php 8000 examples/localhost.pem
+// $ openssl s_client -connect localhost:8000
 
 use React\EventLoop\Factory;
 use React\Socket\Server;
 use React\Socket\ConnectionInterface;
+use React\Socket\SecureServer;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
 $server = new Server($loop);
+
+// secure TLS mode if certificate is given as second parameter
+if (isset($argv[2])) {
+    $server = new SecureServer($server, $loop, array(
+        'local_cert' => $argv[2]
+    ));
+}
+
 $server->listen(isset($argv[1]) ? $argv[1] : 0);
 
 $server->on('connection', function (ConnectionInterface $conn) use ($loop) {
     echo '[connected]' . PHP_EOL;
     $conn->pipe($conn);
 });
 
-echo 'Listening on ' . $server->getPort() . PHP_EOL;
+$server->on('error', 'printf');
+
+echo 'bound to ' . $server->getPort() . PHP_EOL;
 
 $loop->run();

examples/02-chat-server.php

@@ -5,16 +5,30 @@
 //
 // $ php examples/02-chat-server.php 8000
 // $ telnet localhost 8000
+//
+// You can also run a secure TLS chat server like this:
+//
+// $ php examples/02-chat-server.php 8000 examples/localhost.pem
+// $ openssl s_client -connect localhost:8000
 
 use React\EventLoop\Factory;
 use React\Socket\Server;
 use React\Socket\ConnectionInterface;
+use React\Socket\SecureServer;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
 $server = new Server($loop);
+
+// secure TLS mode if certificate is given as second parameter
+if (isset($argv[2])) {
+    $server = new SecureServer($server, $loop, array(
+        'local_cert' => $argv[2]
+    ));
+}
+
 $server->listen(isset($argv[1]) ? $argv[1] : 0, '0.0.0.0');
 
 $clients = array();
@@ -44,6 +58,8 @@
     });
 });
 
+$server->on('error', 'printf');
+
 echo 'Listening on ' . $server->getPort() . PHP_EOL;
 
 $loop->run();

examples/03-benchmark.php

@@ -8,16 +8,32 @@
 // $ telnet localhost 8000
 // $ echo hello world | nc -v localhost 8000
 // $ dd if=/dev/zero bs=1M count=1000 | nc -v localhost 8000
+//
+// You can also run a secure TLS benchmarking server like this:
+//
+// $ php examples/03-benchmark.php 8000 examples/localhost.pem
+// $ openssl s_client -connect localhost:8000
+// $ echo hello world | openssl s_client -connect localhost:8000
+// $ dd if=/dev/zero bs=1M count=1000 | openssl s_client -connect localhost:8000
 
 use React\EventLoop\Factory;
 use React\Socket\Server;
 use React\Socket\ConnectionInterface;
+use React\Socket\SecureServer;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = Factory::create();
 
 $server = new Server($loop);
+
+// secure TLS mode if certificate is given as second parameter
+if (isset($argv[2])) {
+    $server = new SecureServer($server, $loop, array(
+        'local_cert' => $argv[2]
+    ));
+}
+
 $server->listen(isset($argv[1]) ? $argv[1] : 0);
 
 $server->on('connection', function (ConnectionInterface $conn) use ($loop) {

examples/10-generate-self-signed.php

@@ -0,0 +1,31 @@
+<?php
+
+// A very simple helper script used to generate self-signed certificates.
+// Accepts the CN and an optional passphrase to encrypt the private key.
+//
+// $ php 10-generate-self-signed.php localhost swordfish > secret.pem
+
+// certificate details (Distinguished Name)
+// (OpenSSL applies defaults to missing fields)
+$dn = array(
+    "commonName" => isset($argv[1]) ? $argv[1] : "localhost",
+//     "countryName" => "AU",
+//     "stateOrProvinceName" => "Some-State",
+//     "localityName" => "London",
+//     "organizationName" => "Internet Widgits Pty Ltd",
+//     "organizationalUnitName" => "R&D",
+//     "emailAddress" => "[email protected]"
+);
+
+// create certificate which is valid for ~10 years
+$privkey = openssl_pkey_new();
+$cert = openssl_csr_new($dn, $privkey);
+$cert = openssl_csr_sign($cert, null, $privkey, 3650);
+
+// export public and (optionally encrypted) private key in PEM format
+openssl_x509_export($cert, $out);
+echo $out;
+
+$passphrase = isset($argv[2]) ? $argv[2] : null;
+openssl_pkey_export($privkey, $out, $passphrase);
+echo $out;

examples/localhost.pem

@@ -0,0 +1,49 @@
+-----BEGIN CERTIFICATE-----
+MIIDfTCCAmWgAwIBAgIBADANBgkqhkiG9w0BAQUFADBZMRIwEAYDVQQDDAkxMjcu
+MC4wLjExCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQK
+DBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwHhcNMTYxMjMwMTQ1OTA2WhcNMjYx
+MjI4MTQ1OTA2WjBZMRIwEAYDVQQDDAkxMjcuMC4wLjExCzAJBgNVBAYTAkFVMRMw
+EQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0
+eSBMdGQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC8SZWNS+Ktg0Py
+W8dx5uXZ+ZUawd3wnzLMHW7EhoUpIrIdp3kDU9NezF68dOhPMJY/Kh+6btRCxWXN
+2OVTqS5Xi826j3TSE07iF83JRLeveW0PcodjUBd+RzdwCWWo2pfMJz4v7x1wu1c9
+zNi6JxxpDAXTFSB4GiWsI4tFu2XmMRhfm6LRK4WPfsZIJKokdiG5fKSPDn7nrVj0
+UUXr2eBsEAzdwL14U9+mwbLdaAkz3qK3fqi8sEC09lEWm95gKMOhkQf5qvXODtT4
+wdVrrKDTyehLv0xaItnUDnXzrkMBU5QS9TQzzqSW6ZaBsSxtONEFUiXiN9dtyXsY
+YCUE54G/AgMBAAGjUDBOMB0GA1UdDgQWBBQ2GRz3QsQzdXaTMnPVCKfpigA10DAf
+BgNVHSMEGDAWgBQ2GRz3QsQzdXaTMnPVCKfpigA10DAMBgNVHRMEBTADAQH/MA0G
+CSqGSIb3DQEBBQUAA4IBAQA77iZ4KrpPY18Ezjt0mngYAuAxunKddXYdLZ2khywN
+0uI/VzYnkFVtrsC7y2jLHSxlmE2/viPPGZDUplENV2acN6JNW+tlt7/bsrQHDQw3
+7VCF27EWiDxHsaghhLkqC+kcop5YR5c0oDQTdEWEKSbow2zayUXDYbRRs76SClTe
+824Yul+Ts8Mka+AX2PXDg47iZ84fJRN/nKavcJUTJ2iS1uYw0GNnFMge/uwsfMR3
+V47qN0X5emky8fcq99FlMCbcy0gHAeSWAjClgr2dd2i0LDatUbj7YmdmFcskOgII
+IwGfvuWR2yPevYGAE0QgFeLHniN3RW8zmpnX/XtrJ4a7
+-----END CERTIFICATE-----
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC8SZWNS+Ktg0Py
+W8dx5uXZ+ZUawd3wnzLMHW7EhoUpIrIdp3kDU9NezF68dOhPMJY/Kh+6btRCxWXN
+2OVTqS5Xi826j3TSE07iF83JRLeveW0PcodjUBd+RzdwCWWo2pfMJz4v7x1wu1c9
+zNi6JxxpDAXTFSB4GiWsI4tFu2XmMRhfm6LRK4WPfsZIJKokdiG5fKSPDn7nrVj0
+UUXr2eBsEAzdwL14U9+mwbLdaAkz3qK3fqi8sEC09lEWm95gKMOhkQf5qvXODtT4
+wdVrrKDTyehLv0xaItnUDnXzrkMBU5QS9TQzzqSW6ZaBsSxtONEFUiXiN9dtyXsY
+YCUE54G/AgMBAAECggEBAKiO/3FE1CMddkCLZVtUp8ShqJgRokx9WI5ecwFApAkV
+ZHsjqDQQYRNmxhDUX/w0tOzLGyhde2xjJyZG29YviKsbHwu6zYwbeOzy/mkGOaK/
+g6DmmMmRs9Z6juifoQCu4GIFZ6il2adIL2vF7OeJh+eKudQj/7NFRSB7mXzNrQWK
+tZY3eux5zXWmio7pgZrx1HFZQiiL9NVLwT9J7oBnaoO3fREiu5J2xBpljG9Cr0j1
+LLiVLhukWJYRlHDtGt1CzI9w8iKo44PCRzpKyxpbsOrQxeSyEWUYQRv9VHA59LC7
+tVAJTbnTX1BNHkGZkOkoOpoZLwBaM2XbbDtcOGCAZMECgYEA+mTURFQ85/pxawvk
+9ndqZ+5He1u/bMLYIJDp0hdB/vgD+vw3gb2UyRwp0I6Wc6Si4FEEnbY7L0pzWsiR
+43CpLs+cyLfnD9NycuIasxs5fKb/1s1nGTkRAp7x9x/ZTtEf8v4YTmmMXFHzdo7V
+pv+czO89ppEDkxEtMf/b5SifhO8CgYEAwIDIUvXLduGhL+RPDwjc2SKdydXGV6om
+OEdt/V8oS801Z7k8l3gHXFm7zL/MpHmh9cag+F9dHK42kw2RSjDGsBlXXiAO1Z0I
+2A34OdPw/kow8fmIKWTMu3+28Kca+3RmUqeyaq0vazQ/bWMO9px+Ud3YfLo1Tn5I
+li0MecAx8DECgYEAvsLceKYYtL83c09fg2oc1ctSCCgw4WJcGAtvJ9DyRZacKbXH
+b/+H/+OF8879zmKqd+0hcCnqUzAMTCisBLPLIM+o6b45ufPkqKObpcJi/JWaKgLY
+vf2c+Psw6o4IF6T5Cz4MNIjzF06UBknxecYZpoPJ20F1kLCwVvxPgfl99l8CgYAb
+XfOcv67WTstgiJ+oroTfJamy+P5ClkDqvVTosW+EHz9ZaJ8xlXHOcj9do2LPey9I
+Rp250azmF+pQS5x9JKQKgv/FtN8HBVUtigbhCb14GUoODICMCfWFLmnumoMefnTR
+iV+3BLn6Dqp5vZxx+NuIffZ5/Or5JsDhALSGVomC8QKBgAi3Z/dNQrDHfkXMNn/L
++EAoLuAbFgLs76r9VGgNaRQ/q5gex2bZEGoBj4Sxvs95NUIcfD9wKT7FF8HdxARv
+y3o6Bfc8Xp9So9SlFXrje+gkdEJ0rQR67d+XBuJZh86bXJHVrMwpoNL+ahLGdVSe
+81oh1uCH1YPLM29hPyaohxL8
+-----END PRIVATE KEY-----

src/SecureServer.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace React\Socket;
+
+use Evenement\EventEmitter;
+use React\EventLoop\LoopInterface;
+use React\Socket\Server;
+use React\Socket\ConnectionInterface;
+
+/**
+ * The `SecureServer` class implements the `ServerInterface` and is responsible
+ * for providing a secure TLS (formerly known as SSL) server.
+ *
+ * It does so by wrapping a `Server` instance which waits for plaintext
+ * TCP/IP connections and then performs a TLS handshake for each connection.
+ * It thus requires valid [TLS context options],
+ * which in its most basic form may look something like this if you're using a
+ * PEM encoded certificate file:
+ *
+ * ```
+ * $context = array(
+ *     'local_cert' => __DIR__ . '/localhost.pem'
+ * );
+ * ```
+ *
+ * @see Server
+ * @link http://php.net/manual/en/context.ssl.php for TLS context options
+ */
+class SecureServer extends EventEmitter implements ServerInterface
+{
+    private $tcp;
+    private $context;
+    private $loop;
+    private $encryption;
+
+    public function __construct(Server $tcp, LoopInterface $loop, array $context)
+    {
+        $this->tcp = $tcp;
+        $this->context = $context;
+        $this->loop = $loop;
+        $this->encryption = new StreamEncryption($loop);
+
+        $that = $this;
+        $this->tcp->on('connection', function ($connection) use ($that) {
+            $that->handleConnection($connection);
+        });
+        $this->tcp->on('error', function ($error) use ($that) {
+            $that->emit('error', array($error));
+        });
+    }
+
+    public function listen($port, $host = '127.0.0.1')
+    {
+        $this->tcp->listen($port, $host);
+
+        foreach ($this->context as $name => $value) {
+            stream_context_set_option($this->tcp->master, 'ssl', $name, $value);
+        }
+    }
+
+    public function getPort()
+    {
+        return $this->tcp->getPort();
+    }
+
+    public function shutdown()
+    {
+        return $this->tcp->shutdown();
+    }
+
+    /** @internal */
+    public function handleConnection(ConnectionInterface $connection)
+    {
+        $that = $this;
+
+        $this->encryption->enable($connection)->then(
+            function ($conn) use ($that) {
+                $that->emit('connection', array($conn));
+            },
+            function ($error) use ($that, $connection) {
+                $that->emit('error', array($error));
+                $connection->end();
+            }
+        );
+    }
+}

src/Server.php

@@ -23,7 +23,13 @@ public function listen($port, $host = '127.0.0.1')
             $host = '[' . $host . ']';
         }
 
-        $this->master = @stream_socket_server("tcp://$host:$port", $errno, $errstr);
+        $this->master = @stream_socket_server(
+            "tcp://$host:$port",
+            $errno,
+            $errstr,
+            STREAM_SERVER_BIND | STREAM_SERVER_LISTEN,
+            stream_context_create()
+        );
         if (false === $this->master) {
             $message = "Could not bind to tcp://$host:$port: $errstr";
             throw new ConnectionException($message, $errno);