doc, tls: deprecate createSecurePair

createSecurePair uses tls_legacy and the legacy Connection from
node_crypto.cc. Deprecate them in favor of TLSSocket.

PR-URL: https://github.com/nodejs/node/pull/6063
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/tls.md

@@ -168,6 +168,8 @@ the total bytes written to the socket, *including the TLS overhead*.
 
 ## Class: SecurePair
 
+    Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
+
 Returned by tls.createSecurePair.
 
 ### Event: 'secure'
@@ -379,9 +381,9 @@ Construct a new TLSSocket object from an existing TCP socket.
 
   - `server`: An optional [`net.Server`][] instance
 
-  - `requestCert`: Optional, see [`tls.createSecurePair()`][]
+  - `requestCert`: Optional, see [`tls.createServer()`][]
 
-  - `rejectUnauthorized`: Optional, see [`tls.createSecurePair()`][]
+  - `rejectUnauthorized`: Optional, see [`tls.createServer()`][]
 
   - `NPNProtocols`: Optional, see [`tls.createServer()`][]
 
@@ -745,6 +747,8 @@ publicly trusted list of CAs as given in
 
 ## tls.createSecurePair([context][, isServer][, requestCert][, rejectUnauthorized][, options])
 
+    Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead.
+
 Creates a new secure pair object with two streams, one of which reads and writes
 the encrypted data and the other of which reads and writes the cleartext data.
 Generally, the encrypted stream is piped to/from an incoming encrypted data
@@ -770,6 +774,23 @@ stream.
 
 NOTE: `cleartext` has the same API as [`tls.TLSSocket`][]
 
+**Deprecated** `tls.createSecurePair()` is now deprecated in favor of
+`tls.TLSSocket()`. For example:
+
+```js
+pair = tls.createSecurePair( ... );
+pair.encrypted.pipe(socket);
+socket.pipe(pair.encrypted);
+```
+
+can be replaced with:
+
+```js
+secure_socket = tls.TLSSocket(socket, options);
+```
+
+where `secure_socket` has the same API as `pair.cleartext`.
+
 ## tls.createServer(options[, secureConnectionListener])
 
 Creates a new [tls.Server][].  The `connectionListener` argument is