Add documentation for SecurePair and its 'secure' event.

Fixes #1443.

1 files changed, 22 insertions, 0 deletions

diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown
index e4ded41a7..6cfb29b92 100644
--- a/doc/api/tls.markdown
+++ b/doc/api/tls.markdown
@@ -61,8 +61,30 @@ piped to the socket, the plaintext stream is what the user interacts with therea
 
 [Here is some code that does it.](http://gist.github.com/848444)
 
+### pair = 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.
+Generally the encrypted one is piped to/from an incoming encrypted data stream, and the cleartext one
+is used as a replacement for the initial encrypted stream.
 
+ - `credentials`: A credentials object from crypto.createCredentials( ... )
+
+ - `isServer`: A boolean indicating whether this tls connection should be opened as a server or a client.
+
+ - `requestCert`: A boolean indicating whether a server should request a certificate from
+   a connecting client. Only applies to server connections.
+
+ - `rejectUnauthorized`: A boolean indicating whether a server should automatically
+   reject clients with invalid certificates. Only applies to servers with `requestCert` enabled.
+
+`tls.createSecurePair()` returns a SecurePair object with `cleartext` and `encrypted` stream properties.
+
+#### Event: 'secure'
+
+The event is emitted from the SecurePair once the pair has successfully established a secure connection.
+
+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