lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: add `added:` information for tls 

Ref: https://github.com/nodejs/node/issues/6578
PR-URL: https://github.com/nodejs/node/pull/7018
Reviewed-By: Anna Henningsen <anna@addaleax.net>
v6.x
Italo A. Casas 9 years ago
committed by Jeremiah Senkpiel
parent
ec515c5d3b
commit
7a0718bdc6
1 changed files with 137 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 137
      doc/api/tls.md

137
doc/api/tls.md
View File

@ -186,11 +186,17 @@ of an application. The `--tls-cipher-list` switch should by used only if
absolutely necessary. absolutely necessary.
## Class: tls.Server ## Class: tls.Server
<!-- YAML
added: v0.3.2
-->
The `tls.Server` class is a subclass of `net.Server` that accepts encrypted The `tls.Server` class is a subclass of `net.Server` that accepts encrypted
connections using TLS or SSL. connections using TLS or SSL.
### Event: 'tlsClientError' ### Event: 'tlsClientError'
<!-- YAML
added: v6.0.0
-->
The `'tlsClientError'` event is emitted when an error occurs before a secure The `'tlsClientError'` event is emitted when an error occurs before a secure
connection is established. The listener callback is passed two arguments when connection is established. The listener callback is passed two arguments when
@ -201,6 +207,9 @@ called:
error originated. error originated.
### Event: 'newSession' ### Event: 'newSession'
<!-- YAML
added: v0.9.2
-->
The `'newSession'` event is emitted upon creation of a new TLS session. This may The `'newSession'` event is emitted upon creation of a new TLS session. This may
be used to store sessions in external storage. The listener callback is passed be used to store sessions in external storage. The listener callback is passed
@ -215,6 +224,9 @@ three arguments when called:
established after the addition of the event listener. established after the addition of the event listener.
### Event: 'OCSPRequest' ### Event: 'OCSPRequest'
<!-- YAML
added: v0.11.13
-->
The `'OCSPRequest'` event is emitted when the client sends a certificate status The `'OCSPRequest'` event is emitted when the client sends a certificate status
request. The listener callback is passed three arguments when called: request. The listener callback is passed three arguments when called:
@ -259,6 +271,9 @@ established after the addition of the event listener.
*Note*: An npm module like [asn1.js] may be used to parse the certificates. *Note*: An npm module like [asn1.js] may be used to parse the certificates.
### Event: 'resumeSession' ### Event: 'resumeSession'
<!-- YAML
added: v0.9.2
-->
The `'resumeSession'` event is emitted when the client requests to resume a The `'resumeSession'` event is emitted when the client requests to resume a
previous TLS session. The listener callback is passed two arguments when previous TLS session. The listener callback is passed two arguments when
@ -291,6 +306,9 @@ server.on('resumeSession', (id, cb) => {
``` ```
### Event: 'secureConnection' ### Event: 'secureConnection'
<!-- YAML
added: v0.3.2
-->
The `'secureConnection'` event is emitted after the handshaking process for a The `'secureConnection'` event is emitted after the handshaking process for a
new connection has successfully completed. The listener callback is passed a new connection has successfully completed. The listener callback is passed a
@ -315,6 +333,9 @@ The `tlsSocket.servername` property is a string containing the server name
requested via SNI. requested via SNI.
### server.addContext(hostname, context) ### server.addContext(hostname, context)
<!-- YAML
added: v0.5.3
-->
* `hostname` {string} A SNI hostname or wildcard (e.g. `'*'`) * `hostname` {string} A SNI hostname or wildcard (e.g. `'*'`)
* `context` {Object} An object containing any of the possible properties * `context` {Object} An object containing any of the possible properties
@ -325,12 +346,18 @@ The `server.addContext()` method adds a secure context that will be used if
the client request's SNS hostname matches the supplied `hostname` (or wildcard). the client request's SNS hostname matches the supplied `hostname` (or wildcard).
### server.address() ### server.address()
<!-- YAML
added: v0.6.0
-->
Returns the bound address, the address family name, and port of the Returns the bound address, the address family name, and port of the
server as reported by the operating system. See [`net.Server.address()`][] for server as reported by the operating system. See [`net.Server.address()`][] for
more information. more information.
### server.close([callback]) ### server.close([callback])
<!-- YAML
added: v0.3.2
-->
* `callback` {Function} An optional listener callback that will be registered to * `callback` {Function} An optional listener callback that will be registered to
listen for the server instance's `'close'` event. listen for the server instance's `'close'` event.
@ -341,15 +368,24 @@ This function operates asynchronously. The `'close'` event will be emitted
when the the server is finally closed. when the the server is finally closed.
### server.connections ### server.connections
<!-- YAML
added: v0.3.2
-->
Returns the current number of concurrent connections on the server. Returns the current number of concurrent connections on the server.
### server.getTicketKeys() ### server.getTicketKeys()
<!-- YAML
added: v3.0.0
-->
Returns a `Buffer` instance holding the keys currently used for Returns a `Buffer` instance holding the keys currently used for
encryption/decryption of the [TLS Session Tickets][] encryption/decryption of the [TLS Session Tickets][]
### server.listen(port[, hostname][, callback]) ### server.listen(port[, hostname][, callback])
<!-- YAML
added: v0.3.2
-->
* `port` {number} The TCP/IP port on which to begin listening for connections. * `port` {number} The TCP/IP port on which to begin listening for connections.
A value of `0` (zero) will assign a random port. A value of `0` (zero) will assign a random port.
@ -369,6 +405,9 @@ called when the server has started listening.
See `net.Server` for more information. See `net.Server` for more information.
### server.setTicketKeys(keys) ### server.setTicketKeys(keys)
<!-- YAML
added: v3.0.0
-->
* `keys` {Buffer} The keys used for encryption/decryption of the * `keys` {Buffer} The keys used for encryption/decryption of the
[TLS Session Tickets][]. [TLS Session Tickets][].
@ -385,6 +424,9 @@ previous keys.
## Class: tls.TLSSocket ## Class: tls.TLSSocket
<!-- YAML
added: v0.11.4
-->
The `tls.TLSSocket` is a subclass of [`net.Socket`][] that performs transparent The `tls.TLSSocket` is a subclass of [`net.Socket`][] that performs transparent
encryption of written data and all required TLS negotiation. encryption of written data and all required TLS negotiation.
@ -396,6 +438,9 @@ Instances of `tls.TLSSocket` implement the duplex [Stream][] interface.
connection is open. connection is open.
### new tls.TLSSocket(socket[, options]) ### new tls.TLSSocket(socket[, options])
<!-- YAML
added: v0.11.4
-->
* `socket` {net.Socket} An instance of [`net.Socket`][] * `socket` {net.Socket} An instance of [`net.Socket`][]
* `options` {Object} * `options` {Object}
@ -417,6 +462,9 @@ connection is open.
Construct a new `tls.TLSSocket` object from an existing TCP socket. Construct a new `tls.TLSSocket` object from an existing TCP socket.
### Event: 'OCSPResponse' ### Event: 'OCSPResponse'
<!-- YAML
added: v0.11.13
-->
The `'OCSPResponse'` event is emitted if the `requestOCSP` option was set The `'OCSPResponse'` event is emitted if the `requestOCSP` option was set
when the `tls.TLSSocket` was created and an OCSP response has been received. when the `tls.TLSSocket` was created and an OCSP response has been received.
@ -428,6 +476,9 @@ Typically, the `response` is a digitally signed object from the server's CA that
contains information about server's certificate revocation status. contains information about server's certificate revocation status.
### Event: 'secureConnect' ### Event: 'secureConnect'
<!-- YAML
added: v0.11.4
-->
The `'secureConnect'` event is emitted after the handshaking process for a new The `'secureConnect'` event is emitted after the handshaking process for a new
connection has successfully completed. The listener callback will be called connection has successfully completed. The listener callback will be called
@ -440,6 +491,9 @@ the `tlsSocket.alpnProtocol` or `tlsSocket.npnProtocol` properties can be
checked to determine the negotiated protocol. checked to determine the negotiated protocol.
### tlsSocket.address() ### tlsSocket.address()
<!-- YAML
added: v0.11.4
-->
Returns the bound address, the address family name, and port of the Returns the bound address, the address family name, and port of the
underlying socket as reported by the operating system. Returns an underlying socket as reported by the operating system. Returns an
@ -447,21 +501,33 @@ object with three properties, e.g.,
`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`
### tlsSocket.authorized ### tlsSocket.authorized
<!-- YAML
added: v0.11.4
-->
Returns `true` if the peer certificate was signed by one of the CAs specified Returns `true` if the peer certificate was signed by one of the CAs specified
when creating the `tls.TLSSocket` instance, otherwise `false`. when creating the `tls.TLSSocket` instance, otherwise `false`.
### tlsSocket.authorizationError ### tlsSocket.authorizationError
<!-- YAML
added: v0.11.4
-->
Returns the reason why the peer's certificate was not been verified. This Returns the reason why the peer's certificate was not been verified. This
property is set only when `tlsSocket.authorized === false`. property is set only when `tlsSocket.authorized === false`.
### tlsSocket.encrypted ### tlsSocket.encrypted
<!-- YAML
added: v0.11.4
-->
Always returns `true`. This may be used to distinguish TLS sockets from regular Always returns `true`. This may be used to distinguish TLS sockets from regular
`net.Socket` instances. `net.Socket` instances.
### tlsSocket.getCipher() ### tlsSocket.getCipher()
<!-- YAML
added: v0.11.4
-->
Returns an object representing the cipher name and the SSL/TLS protocol version Returns an object representing the cipher name and the SSL/TLS protocol version
that first defined the cipher. that first defined the cipher.
@ -473,6 +539,9 @@ https://www.openssl.org/docs/manmaster/ssl/SSL_CIPHER_get_name.html for more
information. information.
### tlsSocket.getEphemeralKeyInfo() ### tlsSocket.getEphemeralKeyInfo()
<!-- YAML
added: v5.0.0
-->
Returns an object representing the type, name, and size of parameter of Returns an object representing the type, name, and size of parameter of
an ephemeral key exchange in [Perfect Forward Secrecy][] on a client an ephemeral key exchange in [Perfect Forward Secrecy][] on a client
@ -484,6 +553,9 @@ if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The
For Example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }` For Example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }`
### tlsSocket.getPeerCertificate([ detailed ]) ### tlsSocket.getPeerCertificate([ detailed ])
<!-- YAML
added: v0.11.4
-->
* `detailed` {boolean} Specify `true` to request that the full certificate * `detailed` {boolean} Specify `true` to request that the full certificate
chain with the `issuer` property be returned; `false` to return only the chain with the `issuer` property be returned; `false` to return only the
@ -522,6 +594,9 @@ If the peer does not provide a certificate, `null` or an empty object will be
returned. returned.
### tlsSocket.getProtocol() ### tlsSocket.getProtocol()
<!-- YAML
added: v5.7.0
-->
Returns a string containing the negotiated SSL/TLS protocol version of the Returns a string containing the negotiated SSL/TLS protocol version of the
current connection. The value `'unknown'` will be returned for connected current connection. The value `'unknown'` will be returned for connected
@ -540,12 +615,18 @@ See https://www.openssl.org/docs/manmaster/ssl/SSL_get_version.html for more
information. information.
### tlsSocket.getSession() ### tlsSocket.getSession()
<!-- YAML
added: v0.11.4
-->
Returns the ASN.1 encoded TLS session or `undefined` if no session was Returns the ASN.1 encoded TLS session or `undefined` if no session was
negotiated. Can be used to speed up handshake establishment when reconnecting negotiated. Can be used to speed up handshake establishment when reconnecting
to the server. to the server.
### tlsSocket.getTLSTicket() ### tlsSocket.getTLSTicket()
<!-- YAML
added: v0.11.4
-->
Returns the TLS session ticket or `undefined` if no session was negotiated. Returns the TLS session ticket or `undefined` if no session was negotiated.
@ -553,27 +634,45 @@ Returns the TLS session ticket or `undefined` if no session was negotiated.
session reuse provide `session` option to [`tls.connect()`][]. session reuse provide `session` option to [`tls.connect()`][].
### tlsSocket.localAddress ### tlsSocket.localAddress
<!-- YAML
added: v0.11.4
-->
Returns the string representation of the local IP address. Returns the string representation of the local IP address.
### tlsSocket.localPort ### tlsSocket.localPort
<!-- YAML
added: v0.11.4
-->
Returns the numeric representation of the local port. Returns the numeric representation of the local port.
### tlsSocket.remoteAddress ### tlsSocket.remoteAddress
<!-- YAML
added: v0.11.4
-->
Returns the string representation of the remote IP address. For example, Returns 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'`.
### tlsSocket.remoteFamily ### tlsSocket.remoteFamily
<!-- YAML
added: v0.11.4
-->
Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`. Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`.
### tlsSocket.remotePort ### tlsSocket.remotePort
<!-- YAML
added: v0.11.4
-->
Returns the numeric representation of the remote port. For example, `443`. Returns the numeric representation of the remote port. For example, `443`.
### tlsSocket.renegotiate(options, callback) ### tlsSocket.renegotiate(options, callback)
<!-- YAML
added: v0.11.8
-->
* `options` {Object} * `options` {Object}
* `rejectUnauthorized` {boolean} * `rejectUnauthorized` {boolean}
@ -592,6 +691,9 @@ secure connection has been established.
after `handshakeTimeout` timeout. after `handshakeTimeout` timeout.
### tlsSocket.setMaxSendFragment(size) ### tlsSocket.setMaxSendFragment(size)
<!-- YAML
added: v0.11.11
-->
* `size` {number} The maximum TLS fragment size. Defaults to `16384`. The * `size` {number} The maximum TLS fragment size. Defaults to `16384`. The
maximum value is `16384`. maximum value is `16384`.
@ -608,6 +710,9 @@ decrease overall server throughput.
## tls.connect(options[, callback]) ## tls.connect(options[, callback])
<!-- YAML
added: v0.11.3
-->
* `options` {Object} * `options` {Object}
* `host` {string} Host the client should connect to. * `host` {string} Host the client should connect to.
@ -677,6 +782,9 @@ The `callback` function, if specified, will be added as a listener for the
`tls.connect()` returns a [`tls.TLSSocket`][] object. `tls.connect()` returns a [`tls.TLSSocket`][] object.
## tls.connect(port[, host][, options][, callback]) ## tls.connect(port[, host][, options][, callback])
<!-- YAML
added: v0.11.3
-->
* `port` {number} * `port` {number}
* `host` {string} * `host` {string}
@ -805,6 +913,9 @@ socket.on('end', () => {
## tls.createSecureContext(options) ## tls.createSecureContext(options)
<!-- YAML
added: v0.11.13
-->
* `options` {Object} * `options` {Object}
* `pfx` {string|Buffer} A string or `Buffer` holding the PFX or PKCS12 encoded * `pfx` {string|Buffer} A string or `Buffer` holding the PFX or PKCS12 encoded
@ -838,6 +949,9 @@ publicly trusted list of CAs as given in
## tls.createServer(options[, secureConnectionListener]) ## tls.createServer(options[, secureConnectionListener])
<!-- YAML
added: v0.3.2
-->
* `options` {Object} * `options` {Object}
* `pfx` {string|Buffer} A string or `Buffer` containing the private key, * `pfx` {string|Buffer} A string or `Buffer` containing the private key,
@ -1019,6 +1133,9 @@ openssl s_client -connect 127.0.0.1:8000
``` ```
## tls.getCiphers() ## tls.getCiphers()
<!-- YAML
added: v0.10.2
-->
Returns an array with the names of the supported SSL ciphers. Returns an array with the names of the supported SSL ciphers.
@ -1031,6 +1148,10 @@ console.log(tls.getCiphers()); // ['AES128-SHA', 'AES256-SHA', ...]
## Deprecated APIs ## Deprecated APIs
### Class: CryptoStream ### Class: CryptoStream
<!-- YAML
added: v0.3.4
deprecated: v0.11.3
-->
Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
@ -1038,18 +1159,30 @@ The `tls.CryptoStream` class represents a stream of encrypted data. This class
has been deprecated and should no longer be used. has been deprecated and should no longer be used.
#### cryptoStream.bytesWritten #### cryptoStream.bytesWritten
<!-- YAML
added: v0.3.4
deprecated: v0.11.3
-->
The `cryptoStream.bytesWritten` property returns the total number of bytes The `cryptoStream.bytesWritten` property returns the total number of bytes
written to the underlying socket *including* the bytes required for the written to the underlying socket *including* the bytes required for the
implementation of the TLS protocol. implementation of the TLS protocol.
### Class: SecurePair ### Class: SecurePair
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
-->
Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
Returned by `tls.createSecurePair()`. Returned by `tls.createSecurePair()`.
#### Event: 'secure' #### Event: 'secure'
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
-->
The `'secure'` event is emitted by the `SecurePair` object once a secure The `'secure'` event is emitted by the `SecurePair` object once a secure
connection has been established. connection has been established.
@ -1059,6 +1192,10 @@ event, `pair.cleartext.authorized` should be inspected to confirm whether the
certificate used is properly authorized. certificate used is properly authorized.
## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options]) ## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])
<!-- YAML
added: v0.3.2
deprecated: v0.11.3
-->
Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.

Write Preview
Loading…
Cancel
Save