1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: fix tls markdown

Browse Source
This commit is contained in:
Ben Noordhuis 2012-02-17 23:58:42 +01:00
parent dfed2cef75
commit 23c4278e06
1 changed files with 32 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
doc/api/tls.markdown
View File

@ -48,7 +48,18 @@ To test your server, connect to it with `openssl s_client -connect address:port`
and tap `R<CR>` (that's the letter `R` followed by a carriage return) a few and tap `R<CR>` (that's the letter `R` followed by a carriage return) a few
times. 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). Creates a new [tls.Server](#tls.Server).
The `connectionListener` argument is automatically set as a listener for the 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 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` Creates a new client connection to the given `port` and `host`. (If `host`
defaults to `localhost`.) `options` should be an object which specifies 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 ## tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])
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])
Creates a new secure pair object with two streams, one of which reads/writes Creates a new secure pair object with two streams, one of which reads/writes
encrypted data, and one reads/writes cleartext data. 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 `tls.createSecurePair()` returns a SecurePair object with
[cleartext](#tls.CleartextStream) and `encrypted` stream properties. [cleartext](#tls.CleartextStream) and `encrypted` stream properties.
#### Event: 'secure' ### Event: 'secure'
The event is emitted from the SecurePair once the pair has successfully The event is emitted from the SecurePair once the pair has successfully
established a secure connection. 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 pair.cleartext.authorized should be checked to confirm whether the certificate
used properly authorized. used properly authorized.
### tls.Server ## tls.Server
This class is a subclass of `net.Server` and has the same methods on it. 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 Instead of accepting just raw TCP connections, this accepts encrypted
connections using TLS or SSL. connections using TLS or SSL.
#### Event: 'secureConnection' ### Event: 'secureConnection'
`function (cleartextStream) {}` `function (cleartextStream) {}`
@ -256,7 +258,7 @@ server, you unauthorized connections may be accepted.
SNI. SNI.
#### Event: 'clientError' ### Event: 'clientError'
`function (exception) { }` `function (exception) { }`
@ -264,7 +266,7 @@ When a client connection emits an 'error' event before secure connection is
established - it will be forwarded here. 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 Begin accepting connections on the specified `port` and `host`. If the
`host` is omitted, the server will accept connections directed to any `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. See `net.Server` for more information.
#### server.close() ### server.close()
Stops the server from accepting new connections. This function is Stops the server from accepting new connections. This function is
asynchronous, the server is finally closed when the server emits a `'close'` asynchronous, the server is finally closed when the server emits a `'close'`
event. event.
#### server.address() ### server.address()
Returns the bound address and port of the server as reported by the operating Returns the bound address and port of the server as reported by the operating
system. system.
See [net.Server.address()](net.html#server.address) for more information. 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 Add secure context that will be used if client request's SNI hostname is
matching passed `hostname` (wildcards can be used). `credentials` can contain matching passed `hostname` (wildcards can be used). `credentials` can contain
`key`, `cert` and `ca`. `key`, `cert` and `ca`.
#### server.maxConnections ### server.maxConnections
Set this property to reject connections when the server's connection count Set this property to reject connections when the server's connection count
gets high. gets high.
#### server.connections ### server.connections
The number of concurrent connections on the server. 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 This is a stream on top of the *Encrypted* stream that makes it possible to
read/write an encrypted data as a cleartext data. 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. This instance implements a duplex [Stream](streams.html#streams) interfaces.
It has all the common stream methods and events. It has all the common stream methods and events.
#### Event: 'secureConnect' ### Event: 'secureConnect'
`function () {}` `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.authorizationError`. Also if NPN was used - you can check
`cleartextStream.npnProtocol` for negotiated protocol. `cleartextStream.npnProtocol` for negotiated protocol.
#### cleartextStream.authorized ### cleartextStream.authorized
A boolean that is `true` if the peer certificate was signed by one of the A boolean that is `true` if the peer certificate was signed by one of the
specified CAs, otherwise `false` specified CAs, otherwise `false`
#### cleartextStream.authorizationError ### cleartextStream.authorizationError
The reason why the peer's certificate has not been verified. This property The reason why the peer's certificate has not been verified. This property
becomes available only when `cleartextStream.authorized === false`. becomes available only when `cleartextStream.authorized === false`.
#### cleartextStream.getPeerCertificate() ### cleartextStream.getPeerCertificate()
Returns an object representing the peer's certificate. The returned object has Returns an object representing the peer's certificate. The returned object has
some properties corresponding to the field of the certificate. 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 If the peer does not provide a certificate, it returns `null` or an empty
object. object.
#### cleartextStream.address() ### cleartextStream.address()
Returns the bound address and port of the underlying socket as reported by the Returns the bound address and port of the underlying socket as reported by the
operating system. Returns an object with two properties, e.g. operating system. Returns an object with two properties, e.g.
`{"address":"192.168.57.1", "port":62053}` `{"address":"192.168.57.1", "port":62053}`
#### cleartextStream.remoteAddress ### cleartextStream.remoteAddress
The string representation of the remote IP address. For example, The string representation of the remote IP address. For example,
`'74.125.127.100'` or `'2001:4860:a005::68'`. `'74.125.127.100'` or `'2001:4860:a005::68'`.
#### cleartextStream.remotePort ### cleartextStream.remotePort
The numeric representation of the remote port. For example, `443`. The numeric representation of the remote port. For example, `443`.