diff options
author | Ryan Dahl <ry@tinyclouds.org> | 2010-12-09 00:22:12 +0300 |
---|---|---|
committer | Ryan Dahl <ry@tinyclouds.org> | 2010-12-09 00:22:12 +0300 |
commit | 9a7fb3c98891a0d40565ecb90bf3a26c0a302327 (patch) | |
tree | c48d105be63da5495f8cbe9d564e5b6cd47c3161 /doc | |
parent | dac4d486ecb27baeedef7fd8d14d52c98629de56 (diff) |
Add tls.Server docs
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/_toc.markdown | 1 | ||||
-rw-r--r-- | doc/api/tls.markdown | 123 |
2 files changed, 124 insertions, 0 deletions
diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown index 6c72559dc9f..3546a19e4bd 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 00000000000..3565f2074ce --- /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. |