From 23c4278e0694c6c2cca3dc4f917f9ce74be64f40 Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Fri, 17 Feb 2012 23:58:42 +0100 Subject: [PATCH] docs: fix tls markdown --- doc/api/tls.markdown | 62 +++++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index f3222170c322..023c34be6494 100644 --- a/doc/api/tls.markdown +++ b/doc/api/tls.markdown @@ -48,7 +48,18 @@ To test your server, connect to it with `openssl s_client -connect address:port` and tap `R` (that's the letter `R` followed by a carriage return) a few times. -#### tls.createServer(options, [secureConnectionListener]) + +### NPN and SNI + +NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS +handshake extensions allowing you: + + * NPN - to use one TLS server for multiple protocols (HTTP, SPDY) + * SNI - to use one TLS server for multiple hostnames with different SSL + certificates. + + +## tls.createServer(options, [secureConnectionListener]) Creates a new [tls.Server](#tls.Server). The `connectionListener` argument is automatically set as a listener for the @@ -127,7 +138,7 @@ You can test this server by connecting to it with `openssl s_client`: openssl s_client -connect 127.0.0.1:8000 -#### tls.connect(port, [host], [options], [secureConnectListener]) +## tls.connect(port, [host], [options], [secureConnectListener]) Creates a new client connection to the given `port` and `host`. (If `host` defaults to `localhost`.) `options` should be an object which specifies @@ -190,16 +201,7 @@ Here is an example of a client of echo server as described previously: }); -### NPN and SNI - -NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS -handshake extensions allowing you: - - * NPN - to use one TLS server for multiple protocols (HTTP, SPDY) - * SNI - to use one TLS server for multiple hostnames with different SSL - certificates. - -### pair = tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized]) +## tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized]) Creates a new secure pair object with two streams, one of which reads/writes encrypted data, and one reads/writes cleartext data. @@ -221,7 +223,7 @@ and the cleartext one is used as a replacement for the initial encrypted stream. `tls.createSecurePair()` returns a SecurePair object with [cleartext](#tls.CleartextStream) and `encrypted` stream properties. -#### Event: 'secure' +### Event: 'secure' The event is emitted from the SecurePair once the pair has successfully established a secure connection. @@ -230,13 +232,13 @@ Similarly to the checking for the server 'secureConnection' event, pair.cleartext.authorized should be checked to confirm whether the certificate used properly authorized. -### tls.Server +## 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. -#### Event: 'secureConnection' +### Event: 'secureConnection' `function (cleartextStream) {}` @@ -256,7 +258,7 @@ server, you unauthorized connections may be accepted. SNI. -#### Event: 'clientError' +### Event: 'clientError' `function (exception) { }` @@ -264,7 +266,7 @@ When a client connection emits an 'error' event before secure connection is established - it will be forwarded here. -#### server.listen(port, [host], [callback]) +### 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 @@ -276,35 +278,35 @@ when the server has been bound. See `net.Server` for more information. -#### server.close() +### 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.address() +### server.address() Returns the bound address and port of the server as reported by the operating system. See [net.Server.address()](net.html#server.address) for more information. -#### server.addContext(hostname, credentials) +### server.addContext(hostname, credentials) Add secure context that will be used if client request's SNI hostname is matching passed `hostname` (wildcards can be used). `credentials` can contain `key`, `cert` and `ca`. -#### server.maxConnections +### server.maxConnections Set this property to reject connections when the server's connection count gets high. -#### server.connections +### server.connections The number of concurrent connections on the server. -### tls.CleartextStream +## tls.CleartextStream This is a stream on top of the *Encrypted* stream that makes it possible to read/write an encrypted data as a cleartext data. @@ -312,7 +314,7 @@ read/write an encrypted data as a cleartext data. This instance implements a duplex [Stream](streams.html#streams) interfaces. It has all the common stream methods and events. -#### Event: 'secureConnect' +### Event: 'secureConnect' `function () {}` @@ -324,17 +326,17 @@ If `cleartextStream.authorized === false` then the error can be found in `cleartextStream.authorizationError`. Also if NPN was used - you can check `cleartextStream.npnProtocol` for negotiated protocol. -#### cleartextStream.authorized +### cleartextStream.authorized A boolean that is `true` if the peer certificate was signed by one of the specified CAs, otherwise `false` -#### cleartextStream.authorizationError +### cleartextStream.authorizationError The reason why the peer's certificate has not been verified. This property becomes available only when `cleartextStream.authorized === false`. -#### cleartextStream.getPeerCertificate() +### cleartextStream.getPeerCertificate() Returns an object representing the peer's certificate. The returned object has some properties corresponding to the field of the certificate. @@ -362,17 +364,17 @@ Example: If the peer does not provide a certificate, it returns `null` or an empty object. -#### cleartextStream.address() +### cleartextStream.address() Returns the bound address and port of the underlying socket as reported by the operating system. Returns an object with two properties, e.g. `{"address":"192.168.57.1", "port":62053}` -#### cleartextStream.remoteAddress +### cleartextStream.remoteAddress The string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. -#### cleartextStream.remotePort +### cleartextStream.remotePort The numeric representation of the remote port. For example, `443`.