minor edits

1 files changed, 58 insertions, 40 deletions

diff --git a/cpp/include/IceSSL/Plugin.h b/cpp/include/IceSSL/Plugin.h
index 0587fd8f3ec..1b5738a23db 100644
--- a/cpp/include/IceSSL/Plugin.h
+++ b/cpp/include/IceSSL/Plugin.h
@@ -38,11 +38,6 @@
 typedef struct ssl_ctx_st SSL_CTX;
 
 //
-// SSL is the OpenSSL type that represents an SSL connection.
-//
-typedef struct ssl_st SSL;
-
-//
 // X509 is the OpenSSL type that represents a certificate.
 //
 typedef struct x509_st X509;
@@ -92,9 +87,9 @@ private:
 
     static const char* _name;
 };
-

-//

-// Forward declaration.

+
+//
+// Forward declaration.
 //
 class Certificate;
 typedef IceUtil::Handle<Certificate> CertificatePtr;

@@ -129,107 +124,128 @@ public:
     // ownership of the X509* struct.
     //
     Certificate(X509*);
+    ~Certificate();
+
     //
-    // The certificate is read from a PEM encoded file.
+    // Load the certificate from a file. The certificate must use the
+    // PEM encoding format. Raises CertificateReadException if the
+    // file cannot be read.
     //
     static CertificatePtr readPEMFile(const std::string&);
+
     //
-    // The certificate is decoded from a PEM encoded string.
+    // Decode a certificate from a string that uses the PEM encoding format.
+    // Raises CertificateEncodingException if an error occurs.
     //
     static CertificatePtr decodePEM(const std::string&);
-    ~Certificate();
 
     bool operator==(const Certificate&) const;
     bool operator!=(const Certificate&) const;
 
     //
-    // Gets the certificate public key.
+    // Get the certificate's public key.
     //
     PublicKeyPtr getPublicKey() const;
+
     //
-    // Validate that this certificate was signed by the given public
+    // Verify that this certificate was signed by the given public
     // key. Returns true if signed, false otherwise.
     //
     bool verify(const PublicKeyPtr&) const;
+
     //
     // Return a string encoding of the certificate in PEM form.
     //
     std::string getPEMEncoding() const;
+
     //
-    // Checks that the certificate is currently valid. That is the current date falls
-    // between the validity period given in the certificate.
+    // Checks that the certificate is currently valid, that is, the current
+    // date falls between the validity period given in the certificate.
     //
     bool checkValidity() const;
+
     //
     // Checks that the certificate is valid at the given time.
     //
     bool checkValidity(const IceUtil::Time&) const;
+
     //
     // Get the not-after validity time.
     //
     IceUtil::Time getNotAfter() const;
+
     //
     // Get the not-before validity time.
     //
     IceUtil::Time getNotBefore() const;
+
     //
-    // Get the serial number. This is an arbitrarly large number.
+    // Get the serial number. This is an arbitrarily large number.
     //
     std::string getSerialNumber() const;
+
     //
-    // Get the signature algorithm name used to sign the the certificate.
+    // Get the signature algorithm name used to sign the certificate.
     //
     //std::string getSigAlgName() const;
+
     //
     // Get the signature algorithm OID string from the certificate.
     //
     //std::string getSigAlgOID() const;
+
     //
-    // Get the issuer DN.
+    // Get the issuer's distinguished name (DN).
     //
     std::string getIssuerDN() const;
+
     //
-    // This retrieves the issuer alternative names extension.
+    // Get the values in the issuer's alternative names extension.
     //
     // The returned list contains a pair of int, string.
     //
-    // otherName                       [0]     OtherName,
-    // rfc822Name                      [1]     IA5String,
-    // dNSName                         [2]     IA5String,
-    // x400Address                     [3]     ORAddress,
-    // directoryName                   [4]     Name,
-    // ediPartyName                    [5]     EDIPartyName,
-    // uniformResourceIdentifier       [6]     IA5String,
-    // iPAddress                       [7]     OCTET STRING,
-    // registeredID                    [8]     OBJECT IDENTIFIER}
+    // otherName                       [0]     OtherName
+    // rfc822Name                      [1]     IA5String
+    // dNSName                         [2]     IA5String
+    // x400Address                     [3]     ORAddress
+    // directoryName                   [4]     Name
+    // ediPartyName                    [5]     EDIPartyName
+    // uniformResourceIdentifier       [6]     IA5String
+    // iPAddress                       [7]     OCTET STRING
+    // registeredID                    [8]     OBJECT IDENTIFIER
     //
     // rfc822Name, dNSName, directoryName and
     // uniformResourceIdentifier data is returned as a string.
     //
-    // iPAddress is returned as in dotted quad notation. ipv6 is not
+    // iPAddress is returned in dotted quad notation. IPv6 is not
     // currently supported.
     //
-    // The remainder of the data will result in an empty string. To
-    // retrieve the content use the raw X509* certificate.
+    // The remainder of the data will result in an empty string. Use the raw
+    // X509* certificate to obtain these values.
     //
     std::vector<std::pair<int, std::string> > getIssuerAlternativeNames();
+
     //
-    // Get the subject DN.
+    // Get the subject's distinguished name (DN).
     //
     std::string getSubjectDN() const;
+
     //
-    // See the comment for getIssuerAlternativeNames
+    // See the comment for getIssuerAlternativeNames.
     //
     std::vector<std::pair<int, std::string> > getSubjectAlternativeNames();
+
     //
     // Retrieve the certificate version number.
     //
     int getVersion() const;
+
     //
     // Stringify the certificate. This is a human readable version of
-    // the cert, not a DER or PEM encoding.
+    // the certificate, not a DER or PEM encoding.
     //
     std::string toString() const;
+
     //
     // Retrieve the actual X509* OpenSSL structure.
     //
@@ -243,24 +259,27 @@ private:
 //
 // ConnectionInfo contains information that may be of use to a
 // CertificateVerifier or an application that wants information
-// on its peer in an application call.
+// about its peer.
 //
 struct ConnectionInfo
 {
     //
     // The certificate chain. This may be empty if the peer did not
     // supply a certificate. The last certificate in the chain is the
-    // peers certificate.
+    // peer's certificate.
     //
     std::vector<CertificatePtr> certs;
+
     //
     // The name of the negotiated cipher.
     //
     std::string cipher;
+
     //
     // The local TCP/IP host & port.
     //
     struct sockaddr_in localAddr;
+
     //
     // The remote TCP/IP host & port.
     //
@@ -364,10 +383,9 @@ private:
 };
 
 //
-// This method retrieves the ConnectionInfo associated with a
-// particular Connection. If the connection is not an SSL connection,
-// or the connection has been closed a ConnectionInvalidException is
-// thrown.
+// This function obtains a ConnectionInfo value that describes a
+// Connection. The function raises ConnectionInvalidException if the
+// connection is closed or is not an SSL connection.
 //
 ICE_SSL_API ConnectionInfo getConnectionInfo(const ::Ice::ConnectionPtr&);