Doc improvements

related to #1472.

doc/api/tls.markdown

@@ -42,49 +42,56 @@ defaults to `localhost`.) `options` should be an object which specifies
     omitted several well known "root" CAs will be used, like VeriSign.
     These are used to authorize connections.
 
-`tls.connect()` returns a cleartext `CryptoStream` object.
+`tls.connect()` returns a [CleartextStream](#tls.CleartextStream) object.
 
 After the TLS/SSL handshake the `callback` is called. The `callback` will be
 called no matter if the server's certificate was authorized or not. It is up
-to the user to test `s.authorized` to see if the server certificate was
-signed by one of the specified CAs. If `s.authorized === false` then the error
-can be found in `s.authorizationError`.
+to the user to test `s.authorized` to see if the server certificate was signed
+by one of the specified CAs. If `s.authorized === false` then the error can be
+found in `s.authorizationError`.
 
 
 ### STARTTLS
 
 In the v0.4 branch no function exists for starting a TLS session on an
 already existing TCP connection.  This is possible it just requires a bit of
 work. The technique is to use `tls.createSecurePair()` which returns two
-streams: an encrypted stream and a plaintext stream. The encrypted stream is then
-piped to the socket, the plaintext stream is what the user interacts with thereafter.
+streams: an encrypted stream and a cleartext stream. The encrypted stream is
+then piped to the socket, the cleartext stream is what the user interacts with
+thereafter.
 
 [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.
+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.
+ - `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.
+ - `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.
+ - `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.
+`tls.createSecurePair()` returns a SecurePair object with
+[cleartext](#tls.CleartextStream) and `encrypted` stream properties.
 
 #### Event: 'secure'
 
-The event is emitted from the SecurePair once the pair has successfully established a secure connection.
+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.
+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
 
@@ -143,8 +150,9 @@ has these possibilities:
 `function (cleartextStream) {}`
 
 This event is emitted after a new connection has been successfully
-handshaked. The argument is a duplex instance of `stream.Stream`. It has all
-the common stream methods and events.
+handshaked. The argument is a instance of
+[CleartextStream](#tls.CleartextStream). It has all the common stream methods
+and events.
 
 `cleartextStream.authorized` is a boolean value which indicates if the
 client has verified by one of the supplied certificate authorities for the
@@ -175,8 +183,57 @@ event.
 
 #### server.maxConnections
 
-Set this property to reject connections when the server's connection count gets high.
+Set this property to reject connections when the server's connection count
+gets high.
 
 #### server.connections
 
 The number of concurrent connections on the server.
+
+
+### tls.CleartextStream
+
+This is a stream on top of the *Encrypted* stream that makes it possible to
+read/write an encrypted data as a cleartext data.
+
+This instance implements a duplex [Stream](streams.html#streams) interfaces.
+It has all the common stream methods and events.
+
+#### cleartextStream.authorized
+
+A boolean that is `true` if the peer certificate was signed by one of the
+specified CAs, otherwise `false`
+
+#### cleartextStream.authorizationError
+
+The reason why the peer's certificate has not been verified. This property
+becomes available only when `cleartextStream.authorized === false`.
+
+#### cleartextStream.getPeerCertificate()
+
+Returns an object representing the peer's certicicate. The returned object has
+some properties corresponding to the field of the certificate.
+
+Example:
+
+    { subject: 
+       { C: 'UK',
+         ST: 'Acknack Ltd',
+         L: 'Rhys Jones',
+         O: 'node.js',
+         OU: 'Test TLS Certificate',
+         CN: 'localhost' },
+      issuer: 
+       { C: 'UK',
+         ST: 'Acknack Ltd',
+         L: 'Rhys Jones',
+         O: 'node.js',
+         OU: 'Test TLS Certificate',
+         CN: 'localhost' },
+      valid_from: 'Nov 11 09:52:22 2009 GMT',
+      valid_to: 'Nov  6 09:52:22 2029 GMT',
+      fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
+
+If the peer does not provide a certificate, it returns `null` or an empty
+object.
+