From 9a7fb3c98891a0d40565ecb90bf3a26c0a302327 Mon Sep 17 00:00:00 2001
From: Ryan Dahl <ry@tinyclouds.org>
Date: Wed, 8 Dec 2010 13:22:12 -0800
Subject: [PATCH] Add tls.Server docs

---
 doc/api/_toc.markdown |   1 +
 doc/api/tls.markdown  | 123 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 124 insertions(+)
 create mode 100644 doc/api/tls.markdown

diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown
index 6c72559dc9..3546a19e4b 100644
--- a/doc/api/_toc.markdown
+++ b/doc/api/_toc.markdown
@@ -12,6 +12,7 @@
 * [Streams](streams.html)
 * [Crypto](crypto.html)
   * [Secure Streams](securepair.html)
+* [TLS/SSL](tls.html)
 * [String Decoder](string_decoder.html)
 * [File System](fs.html)
 * [Path](path.html)
diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown
new file mode 100644
index 0000000000..3565f2074c
--- /dev/null
+++ b/doc/api/tls.markdown
@@ -0,0 +1,123 @@
+## TLS (SSL)
+
+Use `require('tls')` to access this module.
+
+The `tls` module uses OpenSSL to provide Transport Layer Security and/or
+Secure Socket Layer: encrypted stream communication.
+
+TLS/SSL is a public/private key infrastructure. Each client and each
+server must have a private key. A private key is created like this
+
+    openssl genrsa -out ryans-key.pem 1024
+
+All severs and some clients need to have a certificate. Certificates are public
+keys signed by a Certificate Authority or self-signed. The first step to
+getting a certificate is to create a "Certificate Signing Request" (CSR)
+file. This is done with:
+
+    openssl req -new -key ryans-key.pem -out ryans-csr.pem
+
+To create a self-signed certificate with the CSR, do this:
+
+    openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
+
+Alternatively you can send the CSR to a Certificate Authority for signing.
+
+(TODO: docs on creating a CA, for now interested users should just look at
+`test/fixtures/keys/Makefile` in the Node source code)
+
+
+
+### tls.Server
+
+This class is a subclass of `net.Server` and has the same methods on it.
+Instead of accepting just raw TCP connections, this accepts encrypted
+connections using TLS or SSL.
+
+Here is a simple example echo server:
+
+    var tls = require('tls');
+    var fs = require('fs');
+
+    var options = {
+      key: fs.readFileSync('server-key.pem'),
+      cert: fs.readFileSync('server-cert.pem')
+    };
+
+    tls.createServer(options, function (s) {
+      s.write("welcome!\n");
+      s.pipe(s);
+    }).listen(8000);
+
+
+You can test this server by connecting to it with `openssl s_client`:
+
+
+    openssl s_client -connect 127.0.0.1:8000
+
+#### tls.createServer(options, secureConnectionListener)
+
+This is a constructor for the `tls.Server` class. The options object
+has these possibilities:
+
+  - `key`: A string or `Buffer` containing the private key of the server in
+    PEM format. (Required)
+
+  - `cert`: A string or `Buffer` containing the certificate key of the server in
+    PEM format. (Required)
+
+  - `ca`: An array of strings or `Buffer`s of trusted certificates. If this is
+    omitted several well known "root" CAs will be used, like VeriSign.
+    These are used to authorize connections.
+
+  - `requestCert`: If `true` the server will request a certificate from
+    clients that connect and attempt to verify that certificate. Default:
+    `false`.
+
+  - `rejectUnauthorized`: If `true` the server will reject any connection
+    which is not authorized with the list of supplied CAs. This option only
+    has an effect if `requestCert` is `true`. Default: `false`.
+
+
+#### Event: 'secureConnection'
+
+`function (cleartextStream) {}`
+
+This event is emitted after a new connection has been successfully
+handshaked. The argument is a duplex instance of `stream.Stream`. It has all
+the common stream methods and events.
+
+`cleartextStream.authorized` is a boolean value which indicates if the
+client has verified by one of the supplied cerificate authorities for the
+server. If `cleartextStream.authorized` is false, then
+`cleartextStream.authorizationError` is set to describe how authorization
+failed. Implied but worth mentioning: depending on the settings of the TLS
+server, you unauthorized connections may be accepted.
+
+
+#### server.listen(port, [host], [callback])
+
+Begin accepting connections on the specified `port` and `host`.  If the
+`host` is omitted, the server will accept connections directed to any
+IPv4 address (`INADDR_ANY`).
+
+This function is asynchronous. The last parameter `callback` will be called
+when the server has been bound.
+
+See `net.Server` for more information.
+
+
+#### server.close()
+
+Stops the server from accepting new connections. This function is
+asynchronous, the server is finally closed when the server emits a `'close'`
+event.
+
+
+#### server.maxConnections
+
+Set this property to reject connections when the server's connection count gets high.
+
+#### server.connections
+
+The number of concurrent connections on the server.