From 3056c2ca76c37ff03b24deb10e8dd538c70600f2 Mon Sep 17 00:00:00 2001 From: Logan Smyth Date: Tue, 2 Aug 2011 22:17:16 -0400 Subject: [PATCH] Add documentation for SecurePair and its 'secure' event. Fixes #1443. --- doc/api/tls.markdown | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/api/tls.markdown b/doc/api/tls.markdown index e4ded41a77..6cfb29b923 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