The second phase of cleanup ended up being pretty undramatic. The Jikes
problems I was seeing ended up being the fact that I have the SSL jars
as installed extensions in the jre/lib/ext, so Jikes didn't have
explicit access to them (which I would have known immediately if I had
paid attention to the initial compile errors ... oh well :-)
Anyway, this is just the filling out of the javadoc comments, so
SSLServerSocketFactory is now fully doc'ed. Since the first patch hasn't
been applied yet, I'm including a
"SSLServerSocketFactory.patch.combined" file which has the changes from
last time as well as these, against the current cvs source. I'm also
attaching "SSLServerSocketFactory.patch.javadocs", which is simply the
new javadocs fill-ins without everything in the previous patch (in case
anyone applied my previous patch to their local tree, or if anyone wants
to see just this piece by itself).
The next and final SSL patch will actually fix the multiple-entry store
problem.
- Christopher
--- catalina/src/share/org/apache/catalina/net/SSLServerSocketFactory.java Sun
Jul 22 13:25:12 2001
+++ catalina/src/share/org/apache/catalina/net/SSLServerSocketFactory-new.java Tue
+Aug 14 13:42:27 2001
@@ -66,6 +66,8 @@
import java.security.KeyStore;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
+import java.security.UnrecoverableKeyException;
+import java.security.KeyManagementException;
import java.security.Security;
import java.security.cert.CertificateException;
import javax.net.ServerSocketFactory;
@@ -146,24 +148,48 @@
*/
private String algorithm = "SunX509";
+ /**
+ * Return the current certificate encoding algorithm.
+ *
+ * @return the certificate encoding algorithm
+ */
public String getAlgorithm() {
return (this.algorithm);
}
+ /**
+ * Set the certificate encoding algorithm.
+ *
+ * @paramalgorithm the certificate encoding algorithm
+ */
public void setAlgorithm(String algorithm) {
this.algorithm = algorithm;
}
/**
- * Should we require client authentication?
+ * Require client authentication?
*/
private boolean clientAuth = false;
+
+ /**
+ * Returns whether or not client authentication required.
+ *
+ * @return <code>true</code> if client authentication is required for
+ * secure connections, otherwise <code>false</code>
+ */
public boolean getClientAuth() {
return (this.clientAuth);
}
+
+ /**
+ * Set the client authentication mode for secure connections.
+ *
+ * @param clientAuth <code>true</code> if client authentication should be
+ * required, otherwise <code>false</code>
+ */
public void setClientAuth(boolean clientAuth) {
this.clientAuth = clientAuth;
}
@@ -175,10 +201,23 @@
*/
private KeyStore keyStore = null;
- public KeyStore getKeyStore() throws IOException {
+ /**
+ * Returns a <code>KeyStore</code> object representing the containing store
+ * for this socket's certificate.
+ *
+ * @return the <code>KeyStore</code> containing this socket's
+ * authenticating certificate
+ */
+ public KeyStore getKeyStore()
+ throws KeyStoreException, IOException, NoSuchAlgorithmException,
+ CertificateException,UnrecoverableKeyException,
+ KeyManagementException
+ {
+
if (sslProxy == null)
initialize();
return (this.keyStore);
+
}
@@ -188,34 +227,66 @@
private String keystoreFile =
System.getProperty("user.home") + File.separator + ".keystore";
+
+ /**
+ * Returns the path to the keystore file containing the certificate
+ * associated with this socket.
+ *
+ * @return a string of the fully-qualified path to the keystore
+ */
public String getKeystoreFile() {
return (this.keystoreFile);
}
+
+ /**
+ * Specify the path to the keystore file containing the certificate for
+ * this socket.
+ *
+ * @param keystoreFile the fully-qualified path to the keystore
+ */
public void setKeystoreFile(String keystoreFile) {
this.keystoreFile = keystoreFile;
}
/**
- * Password for accessing the key store file.
+ * The password for accessing the certificate keystore file.
*/
private String keystorePass = "changeit";
+
+ /**
+ * Returns the password for the certificate keystore file.
+ *
+ * @return the keystore password
+ */
public String getKeystorePass() {
return (this.keystorePass);
}
+
+ /**
+ * Sets the password for the keystore certificate file.
+ *
+ * @param keystorePass the keystore password
+ */
public void setKeystorePass(String keystorePass) {
this.keystorePass = keystorePass;
}
/**
- * Storeage type of the key store file to be used.
+ * The internal format type of the keystore file to be used.
*/
private String keystoreType = "JKS";
+
+ /**
+ * Returns the format type of the keystore file.
+ *
+ * @return the internal format of the keystore
+ */
public String getKeystoreType() {
return (this.keystoreType);
}
@@ -230,10 +301,22 @@
*/
private String protocol = "TLS";
+
+ /**
+ * Returns the SSL protocol variant used by this secure socket.
+ *
+ * @return the SSL protocol variant being used
+ */
public String getProtocol() {
return (this.protocol);
}
+
+ /**
+ * Sets the SSL protocol variant used by this secure socket.
+ *
+ * @param protocol the SSL protocol variant to be used
+ */
public void setProtocol(String protocol) {
this.protocol = protocol;
}
@@ -247,16 +330,31 @@
* and is bound to a specified port. The socket is configured with the
* socket options (such as accept timeout) given to this factory.
*
- * @param port Port to listen to
+ * @param port the port to listen on
*
- * @exception IOException if an input/output or network error occurs
- */
- public ServerSocket createSocket(int port) throws IOException {
+ * @exception KeyStoreException an error instantiating the
+ * KeyStore from file
+ * @exception IOException an input/output or network error
+ * @exception NoSuchAlgorithmException unsupported algorithm, for the
+ * current provider, in the keystore
+ * @exception CertificateException an error in the certificate
+ * @exception UnrecoverableKeyException a problem with the internal keys
+ * @exception KeyManagementException a problem in the key management
+ * layer
+ * @return the requested server socket
+ */
+ public ServerSocket createSocket(int port)
+ throws KeyStoreException, IOException, NoSuchAlgorithmException,
+ CertificateException, UnrecoverableKeyException,
+ KeyManagementException
+ {
if (sslProxy == null)
initialize();
+
ServerSocket socket =
sslProxy.createServerSocket(port);
+
initServerSocket(socket);
return (socket);
@@ -269,18 +367,32 @@
* connection backlog. The socket is configured with the
* socket options (such as accept timeout) given to this factory.
*
- * @param port Port to listen to
- * @param backlog Maximum number of connections to be queued
+ * @param port the port to listen on
+ * @param backlog the maximum number of connections to be queued
*
- * @exception IOException if an input/output or network error occurs
+ * @exception KeyStoreException an error instantiating the
+ * KeyStore from file
+ * @exception IOException an input/output or network error
+ * @exception NoSuchAlgorithmException unsupported algorithm, for the
+ * current provider, in the keystore
+ * @exception CertificateException an error in the certificate
+ * @exception UnrecoverableKeyException a problem with the internal keys
+ * @exception KeyManagementException a problem in the key management
+ * layer
+ * @return the requested server socket
*/
public ServerSocket createSocket(int port, int backlog)
- throws IOException {
+ throws KeyStoreException, IOException, NoSuchAlgorithmException,
+ CertificateException, UnrecoverableKeyException,
+ KeyManagementException
+ {
if (sslProxy == null)
initialize();
+
ServerSocket socket =
sslProxy.createServerSocket(port, backlog);
+
initServerSocket(socket);
return (socket);
@@ -293,20 +405,34 @@
* connection backlog. The socket is configured with the
* socket options (such as accept timeout) given to this factory.
*
- * @param port Port to listen to
- * @param backlog Maximum number of connections to be queued
- * @param ifAddress Address of the interface to be used
+ * @param port the port to listen on
+ * @param backlog the maximum number of connections to be queued
+ * @param ifAddress the address of the interface to be used
*
- * @exception IOException if an input/output or network error occurs
+ * @exception KeyStoreException an error instantiating the
+ * KeyStore from file
+ * @exception IOException an input/output or network error
+ * @exception NoSuchAlgorithmException unsupported algorithm, for the
+ * current provider, in the keystore
+ * @exception CertificateException an error in the certificate
+ * @exception UnrecoverableKeyException a problem with the internal keys
+ * @exception KeyManagementException a problem in the key management
+ * layer
+ * @return the requested server socket
*/
public ServerSocket createSocket(int port, int backlog,
InetAddress ifAddress)
- throws IOException {
+ throws KeyStoreException, IOException, NoSuchAlgorithmException,
+ CertificateException, UnrecoverableKeyException,
+ KeyManagementException
+ {
if (sslProxy == null)
initialize();
+
ServerSocket socket =
sslProxy.createServerSocket(port, backlog, ifAddress);
+
initServerSocket(socket);
return (socket);
@@ -319,9 +445,21 @@
/**
* Initialize objects that will be required to create sockets.
*
- * @exception IOException if an input/output error occurs
- */
- private synchronized void initialize() throws IOException {
+ * @exception KeyStoreException an error instantiating the
+ * KeyStore from file
+ * @exception IOException an input/output or network error
+ * @exception NoSuchAlgorithmException unsupported algorithm, for the
+ * current provider, in the keystore
+ * @exception CertificateException an error in the certificate
+ * @exception UnrecoverableKeyException a problem with the internal keys
+ * @exception KeyManagementException a problem in the key management
+ * layer
+ */
+ private synchronized void initialize()
+ throws KeyStoreException, IOException, NoSuchAlgorithmException,
+ CertificateException, UnrecoverableKeyException,
+ KeyManagementException
+ {
initHandler();
initKeyStore();
@@ -331,7 +469,7 @@
/**
- * Register our URLStreamHandler for the "https:" protocol.
+ * Registers the URLStreamHandler for the "https:" protocol.
*/
private void initHandler() {
@@ -348,20 +486,35 @@
/**
* Initialize the internal representation of the key store file.
*
- * @exception IOException if an input/output exception occurs
- */
- private void initKeyStore() throws IOException {
+ * @exception KeyStoreException an error instantiating the
+ * KeyStore from file
+ * @exception IOException an input/output or network error
+ * @exception NoSuchAlgorithmException unsupported algorithm, for the
+ * current provider, in the keystore
+ * @exception CertificateException an error in the certificate
+ */
+ private void initKeyStore()
+ throws KeyStoreException, IOException, NoSuchAlgorithmException,
+ CertificateException
+ {
+
+ FileInputStream istream = null;
try {
keyStore = KeyStore.getInstance(keystoreType);
- FileInputStream istream = new FileInputStream(keystoreFile);
+ istream = new FileInputStream(keystoreFile);
keyStore.load(istream, keystorePass.toCharArray());
- istream.close();
- } catch (Exception e) {
- // FIXME - send to an appropriate log file?
- System.out.println("initKeyStore: " + e);
- e.printStackTrace(System.out);
- throw new IOException(e.toString());
+ } catch (KeyStoreException kse) {
+ throw kse;
+ } catch (IOException ioe) {
+ throw ioe;
+ } catch (NoSuchAlgorithmException nsae) {
+ throw nsae;
+ } catch (CertificateException ce) {
+ throw ce;
+ } finally {
+ if ( istream != null )
+ istream.close();
}
}
@@ -370,44 +523,43 @@
/**
* Initialize the SSL socket factory.
*
- * @exception IOException if an input/output error occurs
- */
- private void initProxy() throws IOException {
+ * @exception NoSuchAlgorithmException unsupported algorithm, for the
+ * current provider, in the keystore
+ * @exception UnrecoverableKeyException a problem with the internal keys
+ * @exception KeyManagementException a problem in the key management
+ * layer
+ * @exception KeyStoreException an error with the KeyStore
+ */
+ private void initProxy()
+ throws NoSuchAlgorithmException, UnrecoverableKeyException,
+ KeyManagementException, KeyStoreException
+ {
+
+ /*
+ Security.addProvider(new sun.security.provider.Sun());
+ Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
+ */
+
+ // Create an SSL context used to create an SSL socket factory
+ SSLContext context = SSLContext.getInstance(protocol);
+
+ // Create the key manager factory used to extract the server key
+ KeyManagerFactory keyManagerFactory =
+ KeyManagerFactory.getInstance(algorithm);
+ keyManagerFactory.init(keyStore, keystorePass.toCharArray());
+
+ // Create the trust manager factory used for checking certificates
+ /*
+ trustManagerFactory = TrustManagerFactory.getInstance(algorithm);
+ trustManagerFactory.init(keyStore);
+ */
+
+ // Initialize the context with the key managers
+ context.init(keyManagerFactory.getKeyManagers(), null,
+ new java.security.SecureRandom());
- try {
-
- /*
- Security.addProvider(new sun.security.provider.Sun());
- Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
- */
-
- // Create an SSL context used to create an SSL socket factory
- SSLContext context = SSLContext.getInstance(protocol);
-
- // Create the key manager factory used to extract the server key
- KeyManagerFactory keyManagerFactory =
- KeyManagerFactory.getInstance(algorithm);
- keyManagerFactory.init(keyStore, keystorePass.toCharArray());
-
- // Create the trust manager factory used for checking certificates
- /*
- trustManagerFactory = TrustManagerFactory.getInstance(algorithm);
- trustManagerFactory.init(keyStore);
- */
-
- // Initialize the context with the key managers
- context.init(keyManagerFactory.getKeyManagers(), null,
- new java.security.SecureRandom());
-
- // Create the proxy and return
- sslProxy = context.getServerSocketFactory();
-
- } catch (Exception e) {
- // FIXME - send to an appropriate log file?
- System.out.println("initProxy: " + e);
- e.printStackTrace(System.out);
- throw new IOException(e.toString());
- }
+ // Create the proxy and return
+ sslProxy = context.getServerSocketFactory();
}
@@ -415,7 +567,7 @@
/**
* Set the requested properties for this server socket.
*
- * @param ssocket The server socket to be configured
+ * @param ssocket the server socket to be configured
*/
private void initServerSocket(ServerSocket ssocket) {
@@ -429,6 +581,5 @@
socket.setNeedClientAuth(clientAuth);
}
-
}
--- catalina/src/share/org/apache/catalina/net/SSLServerSocketFactory.java Mon
Aug 13 15:14:44 2001
+++ catalina/src/share/org/apache/catalina/net/SSLServerSocketFactory-new.java Tue
+Aug 14 13:42:27 2001
@@ -148,24 +148,48 @@
*/
private String algorithm = "SunX509";
+ /**
+ * Return the current certificate encoding algorithm.
+ *
+ * @return the certificate encoding algorithm
+ */
public String getAlgorithm() {
return (this.algorithm);
}
+ /**
+ * Set the certificate encoding algorithm.
+ *
+ * @paramalgorithm the certificate encoding algorithm
+ */
public void setAlgorithm(String algorithm) {
this.algorithm = algorithm;
}
/**
- * Should we require client authentication?
+ * Require client authentication?
*/
private boolean clientAuth = false;
+
+ /**
+ * Returns whether or not client authentication required.
+ *
+ * @return <code>true</code> if client authentication is required for
+ * secure connections, otherwise <code>false</code>
+ */
public boolean getClientAuth() {
return (this.clientAuth);
}
+
+ /**
+ * Set the client authentication mode for secure connections.
+ *
+ * @param clientAuth <code>true</code> if client authentication should be
+ * required, otherwise <code>false</code>
+ */
public void setClientAuth(boolean clientAuth) {
this.clientAuth = clientAuth;
}
@@ -177,6 +201,13 @@
*/
private KeyStore keyStore = null;
+ /**
+ * Returns a <code>KeyStore</code> object representing the containing store
+ * for this socket's certificate.
+ *
+ * @return the <code>KeyStore</code> containing this socket's
+ * authenticating certificate
+ */
public KeyStore getKeyStore()
throws KeyStoreException, IOException, NoSuchAlgorithmException,
CertificateException,UnrecoverableKeyException,
@@ -196,34 +227,66 @@
private String keystoreFile =
System.getProperty("user.home") + File.separator + ".keystore";
+
+ /**
+ * Returns the path to the keystore file containing the certificate
+ * associated with this socket.
+ *
+ * @return a string of the fully-qualified path to the keystore
+ */
public String getKeystoreFile() {
return (this.keystoreFile);
}
+
+ /**
+ * Specify the path to the keystore file containing the certificate for
+ * this socket.
+ *
+ * @param keystoreFile the fully-qualified path to the keystore
+ */
public void setKeystoreFile(String keystoreFile) {
this.keystoreFile = keystoreFile;
}
/**
- * Password for accessing the key store file.
+ * The password for accessing the certificate keystore file.
*/
private String keystorePass = "changeit";
+
+ /**
+ * Returns the password for the certificate keystore file.
+ *
+ * @return the keystore password
+ */
public String getKeystorePass() {
return (this.keystorePass);
}
+
+ /**
+ * Sets the password for the keystore certificate file.
+ *
+ * @param keystorePass the keystore password
+ */
public void setKeystorePass(String keystorePass) {
this.keystorePass = keystorePass;
}
/**
- * Storeage type of the key store file to be used.
+ * The internal format type of the keystore file to be used.
*/
private String keystoreType = "JKS";
+
+ /**
+ * Returns the format type of the keystore file.
+ *
+ * @return the internal format of the keystore
+ */
public String getKeystoreType() {
return (this.keystoreType);
}
@@ -238,10 +301,22 @@
*/
private String protocol = "TLS";
+
+ /**
+ * Returns the SSL protocol variant used by this secure socket.
+ *
+ * @return the SSL protocol variant being used
+ */
public String getProtocol() {
return (this.protocol);
}
+
+ /**
+ * Sets the SSL protocol variant used by this secure socket.
+ *
+ * @param protocol the SSL protocol variant to be used
+ */
public void setProtocol(String protocol) {
this.protocol = protocol;
}
@@ -255,7 +330,7 @@
* and is bound to a specified port. The socket is configured with the
* socket options (such as accept timeout) given to this factory.
*
- * @param port Port to listen to
+ * @param port the port to listen on
*
* @exception KeyStoreException an error instantiating the
* KeyStore from file
@@ -266,6 +341,7 @@
* @exception UnrecoverableKeyException a problem with the internal keys
* @exception KeyManagementException a problem in the key management
* layer
+ * @return the requested server socket
*/
public ServerSocket createSocket(int port)
throws KeyStoreException, IOException, NoSuchAlgorithmException,
@@ -291,8 +367,8 @@
* connection backlog. The socket is configured with the
* socket options (such as accept timeout) given to this factory.
*
- * @param port Port to listen to
- * @param backlog Maximum number of connections to be queued
+ * @param port the port to listen on
+ * @param backlog the maximum number of connections to be queued
*
* @exception KeyStoreException an error instantiating the
* KeyStore from file
@@ -303,6 +379,7 @@
* @exception UnrecoverableKeyException a problem with the internal keys
* @exception KeyManagementException a problem in the key management
* layer
+ * @return the requested server socket
*/
public ServerSocket createSocket(int port, int backlog)
throws KeyStoreException, IOException, NoSuchAlgorithmException,
@@ -328,9 +405,9 @@
* connection backlog. The socket is configured with the
* socket options (such as accept timeout) given to this factory.
*
- * @param port Port to listen to
- * @param backlog Maximum number of connections to be queued
- * @param ifAddress Address of the interface to be used
+ * @param port the port to listen on
+ * @param backlog the maximum number of connections to be queued
+ * @param ifAddress the address of the interface to be used
*
* @exception KeyStoreException an error instantiating the
* KeyStore from file
@@ -341,6 +418,7 @@
* @exception UnrecoverableKeyException a problem with the internal keys
* @exception KeyManagementException a problem in the key management
* layer
+ * @return the requested server socket
*/
public ServerSocket createSocket(int port, int backlog,
InetAddress ifAddress)
@@ -391,7 +469,7 @@
/**
- * Register our URLStreamHandler for the "https:" protocol.
+ * Registers the URLStreamHandler for the "https:" protocol.
*/
private void initHandler() {
@@ -489,7 +567,7 @@
/**
* Set the requested properties for this server socket.
*
- * @param ssocket The server socket to be configured
+ * @param ssocket the server socket to be configured
*/
private void initServerSocket(ServerSocket ssocket) {
