You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/30 13:01:29 UTC
svn commit: r770159 [2/2] - in
/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net: ./
ssl/
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java Thu Apr 30 11:01:28 2009
@@ -21,49 +21,212 @@
import java.net.InetAddress;
import java.net.ServerSocket;
+/**
+ * The extension of {@code ServerSocket} which provides secure server sockets
+ * based on protocols like SSL, TLS, or others.
+ */
public abstract class SSLServerSocket extends ServerSocket {
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP server socket with the default authentication context.
+ *
+ * @throws IOException
+ * if creating the socket fails.
+ */
protected SSLServerSocket() throws IOException {
super();
}
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP server socket on the specified port with the default
+ * authentication context. The connection's default backlog size is 50
+ * connections.
+ * @param port
+ * the port to listen on.
+ * @throws IOException
+ * if creating the socket fails.
+ */
protected SSLServerSocket(int port) throws IOException {
super(port);
}
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP server socket on the specified port using the specified
+ * backlog and the default authentication context.
+ *
+ * @param port
+ * the port to listen on.
+ * @param backlog
+ * the number of pending connections to queue.
+ * @throws IOException
+ * if creating the socket fails.
+ */
protected SSLServerSocket(int port, int backlog) throws IOException {
super(port, backlog);
}
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP server socket on the specified port, using the specified
+ * backlog, listening on the specified interface, and using the default
+ * authentication context.
+ *
+ * @param port
+ * the port the listen on.
+ * @param backlog
+ * the number of pending connections to queue.
+ * @param address
+ * the address of the interface to accept connections on.
+ * @throws IOException
+ * if creating the socket fails.
+ */
protected SSLServerSocket(int port, int backlog, InetAddress address) throws IOException {
super(port, backlog, address);
}
+ /**
+ * Returns the names of the enabled cipher suites to be used for new
+ * connections.
+ *
+ * @return the names of the enabled cipher suites to be used for new
+ * connections.
+ */
public abstract String[] getEnabledCipherSuites();
+ /**
+ * Sets the names of the cipher suites to be enabled for new connections.
+ * Only cipher suites returned by {@link #getSupportedCipherSuites()} are
+ * allowed.
+ *
+ * @param suites
+ * the names of the to be enabled cipher suites.
+ * @throws IllegalArgumentException
+ * if one of the cipher suite names is not supported.
+ */
public abstract void setEnabledCipherSuites(String[] suites);
+ /**
+ * Returns the names of the supported cipher suites.
+ *
+ * @return the names of the supported cipher suites.
+ */
public abstract String[] getSupportedCipherSuites();
+ /**
+ * Returns the names of the supported protocols.
+ *
+ * @return the names of the supported protocols.
+ */
public abstract String[] getSupportedProtocols();
+ /**
+ * Returns the names of the enabled protocols to be used for new
+ * connections.
+ *
+ * @return the names of the enabled protocols to be used for new
+ * connections.
+ */
public abstract String[] getEnabledProtocols();
+ /**
+ * Sets the names of the protocols to be enabled for new connections. Only
+ * protocols returned by {@link #getSupportedProtocols()} are allowed.
+ *
+ * @param protocols
+ * the names of the to be enabled protocols.
+ * @throws IllegalArgumentException
+ * if one of the protocols is not supported.
+ */
public abstract void setEnabledProtocols(String[] protocols);
+ /**
+ * Sets whether server-mode connections will be configured to require client
+ * authentication. The client authentication is one of the following:
+ * <ul>
+ * <li>authentication required</li>
+ * <li>authentication requested</li>
+ * <li>no authentication needed</li>
+ * </ul>
+ * This method overrides the setting of {@link #setWantClientAuth(boolean)}.
+ *
+ * @param need
+ * {@code true} if client authentication is required,
+ * {@code false} if no authentication is needed.
+ */
public abstract void setNeedClientAuth(boolean need);
+ /**
+ * Returns whether server-mode connections will be configured to require
+ * client authentication.
+ *
+ * @return {@code true} if client authentication is required, {@code false}
+ * if no client authentication is needed.
+ */
public abstract boolean getNeedClientAuth();
+ /**
+ * Sets whether server-mode connections will be configured to request client
+ * authentication. The client authentication is one of the following:
+ * <ul>
+ * <li>authentication required</li>
+ * <li>authentication requested</li>
+ * <li>no authentication needed</li>
+ * </ul>
+ * This method overrides the setting of {@link #setNeedClientAuth(boolean)}.
+ *
+ * @param want
+ * {@code true} if client authentication should be requested,
+ * {@code false} if no authentication is needed.
+ */
public abstract void setWantClientAuth(boolean want);
+ /**
+ * Returns whether server-mode connections will be configured to request
+ * client authentication.
+ *
+ * @return {@code true} is client authentication will be requested,
+ * {@code false} if no client authentication is needed.
+ */
public abstract boolean getWantClientAuth();
+ /**
+ * Sets whether new connections should act in client mode when handshaking.
+ *
+ * @param mode
+ * {@code true} if new connections should act in client mode,
+ * {@code false} if not.
+ */
public abstract void setUseClientMode(boolean mode);
+ /**
+ * Returns whether new connection will act in client mode when handshaking.
+ *
+ * @return {@code true} if new connections will act in client mode when
+ * handshaking, {@code false} if not.
+ */
public abstract boolean getUseClientMode();
+ /**
+ * Sets whether new SSL sessions may be established for new connections.
+ *
+ * @param flag
+ * {@code true} if new SSL sessions may be established,
+ * {@code false} if existing SSL sessions must be reused.
+ */
public abstract void setEnableSessionCreation(boolean flag);
+ /**
+ * Returns whether new SSL sessions may be established for new connections.
+ *
+ * @return {@code true} if new SSL sessions may be established,
+ * {@code false} if existing SSL sessions must be reused.
+ */
public abstract boolean getEnableSessionCreation();
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java Thu Apr 30 11:01:28 2009
@@ -23,6 +23,9 @@
import javax.net.ServerSocketFactory;
+/**
+ * The factory for SSL server sockets.
+ */
public abstract class SSLServerSocketFactory extends ServerSocketFactory {
// TODO EXPORT CONTROL
@@ -31,6 +34,13 @@
private static String defaultName;
+ /**
+ * Returns the default {@code SSLServerSocketFactory} instance. The default
+ * implementation is defined by the security property
+ * "ssl.ServerSocketFactory.provider".
+ *
+ * @return the default {@code SSLServerSocketFactory} instance.
+ */
public static synchronized ServerSocketFactory getDefault() {
if (defaultServerSocketFactory != null) {
return defaultServerSocketFactory;
@@ -69,11 +79,25 @@
return defaultServerSocketFactory;
}
+ /**
+ * Creates a new {@code SSLServerSocketFactory} instance.
+ */
protected SSLServerSocketFactory() {
super();
}
+ /**
+ * Returns the names of the cipher suites that are enabled by default.
+ *
+ * @return the names of the cipher suites that are enabled by default
+ */
public abstract String[] getDefaultCipherSuites();
+ /**
+ * Returns the list of supported cipher suites that could be enabled for an
+ * SSL connection created by this factory.
+ *
+ * @return the list of supported cipher suites
+ */
public abstract String[] getSupportedCipherSuites();
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java Thu Apr 30 11:01:28 2009
@@ -21,47 +21,211 @@
import java.security.cert.Certificate;
import javax.security.cert.X509Certificate;
+/**
+ * The interface representing an SSL session.
+ */
public interface SSLSession {
+ /**
+ * Returns the maximum size that an application buffer can be for this
+ * session.
+ *
+ * @return the maximum application buffer size.
+ */
public int getApplicationBufferSize();
+ /**
+ * Returns the name of the cipher suite used in this session.
+ *
+ * @return the name of the cipher suite used in this session.
+ */
public String getCipherSuite();
+ /**
+ * Returns the time this session was created, in milliseconds since midnight
+ * January 1st 1970 UTC.
+ *
+ * @return the time the session was created.
+ */
public long getCreationTime();
+ /**
+ * Returns this sessions identifier.
+ *
+ * @return this sessions identifier.
+ */
public byte[] getId();
+ /**
+ * Returns the time this session was last accessed, in milliseconds since
+ * midnight January 1st 1970 UTC.
+ *
+ * @return the time this session was last accessed.
+ */
public long getLastAccessedTime();
+ /**
+ * Returns the list of certificates that were used to identify the local
+ * side to the peer during the handshake.
+ *
+ * @return the list of certificates, ordered from local certificate to
+ * CA's certificates.
+ */
public Certificate[] getLocalCertificates();
+ /**
+ * Returns the principal used to identify the local side to the peer during
+ * the handshake.
+ *
+ * @return the principal used to identify the local side.
+ */
public Principal getLocalPrincipal();
+ /**
+ * Returns the maximum size that a network buffer can be for this session.
+ *
+ * @return the maximum network buffer size.
+ */
public int getPacketBufferSize();
+ /**
+ * Returns the list of certificates the peer used to identify itself during
+ * the handshake.
+ * <p>
+ * Note: this method exists for compatility reasons, use
+ * {@link #getPeerCertificates()} instead.
+ *
+ * @return the list of certificates, ordered from the identity certificate to
+ * the CA's certificates
+ * @throws SSLPeerUnverifiedException
+ * if the identity of the peer is not verified.
+ */
public X509Certificate[] getPeerCertificateChain() throws SSLPeerUnverifiedException;
+ /**
+ * Returns the list of certificates the peer used to identify itself during
+ * the handshake.
+ *
+ * @return the list of certificates, ordered from the identity certificate to
+ * the CA's certificates.
+ * @throws SSLPeerUnverifiedException
+ * if the identity of the peer is not verified.
+ */
public Certificate[] getPeerCertificates() throws SSLPeerUnverifiedException;
+ /**
+ * Returns the host name of the peer of this session. The host name is not
+ * authenticated.
+ *
+ * @return the host name of the peer of this session, or {@code null} if no
+ * host name is available.
+ */
public String getPeerHost();
+ /**
+ * Returns the port number of the peer of this session. The port number is
+ * not authenticated.
+ *
+ * @return the port number of the peer, of {@code -1} is no port number is
+ * available.
+ */
public int getPeerPort();
+ /**
+ * Returns the principal identifying the peer during the handshake.
+ *
+ * @return the principal identifying the peer.
+ * @throws SSLPeerUnverifiedException
+ * if the identity of the peer has not been verified.
+ */
public Principal getPeerPrincipal() throws SSLPeerUnverifiedException;
+ /**
+ * Returns the protocol name that is used for all connections in this
+ * session.
+ *
+ * @return the protocol name that is used for all connections in this
+ * session.
+ */
public String getProtocol();
+ /**
+ * Returns the context of this session. If a context is available and a
+ * security manager is installed, the
+ * {@code SSLPermission("getSSLSessionContext"} is checked with the security
+ * manager.
+ *
+ * @return the context of this session or {@code null} if no context is
+ * available.
+ */
public SSLSessionContext getSessionContext();
+ /**
+ * Returns the object bound to the specified name in this session's
+ * application layer data.
+ *
+ * @param name
+ * the name of the bound value.
+ * @return the value bound to the specified name, or {@code null} if the
+ * specified name does not exist or is not accessible in the current
+ * access control context.
+ * @throws IllegalArgumentException
+ * if {@code name} is {@code null}.
+ */
public Object getValue(String name);
+ /**
+ * Returns the list of the object names bound to this session's application
+ * layer data..
+ * <p>
+ * Depending on the current access control context, the list of object names
+ * may be different.
+ *
+ * @return the list of the object names bound to this session's application
+ * layer data.
+ */
public String[] getValueNames();
+ /**
+ * Invalidates this session.
+ * <p>
+ * No new connections can be created, but any existing connection remains
+ * valid until it is closed.
+ */
public void invalidate();
+ /**
+ * Returns whether this session is valid.
+ *
+ * @return {@code true} if this session is valid, otherwise {@code false}.
+ */
public boolean isValid();
+ /**
+ * Binds the specified object under the specified name in this session's
+ * application layer data.
+ * <p>
+ * For bindings (new or existing) implementing the
+ * {@code SSLSessionBindingListener} interface the object will be notified.
+ *
+ * @param name
+ * the name to bind the object to.
+ * @param value
+ * the object to bind.
+ * @throws IllegalArgumentException
+ * if either {@code name} or {@code value} is {@code null}.
+ */
public void putValue(String name, Object value);
+ /**
+ * Removes the binding for the specified name in this session's application
+ * layer data. If the existing binding implements the
+ * {@code SSLSessionBindingListener} interface the object will be notified.
+ *
+ * @param name
+ * the binding to remove.
+ * @throws IllegalArgumentException
+ * if {@code name} is {@code null}.
+ */
public void removeValue(String name);
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java Thu Apr 30 11:01:28 2009
@@ -20,6 +20,11 @@
import java.io.Serializable;
import java.util.EventObject;
+/**
+ * The event sent to an {@code SSLSessionBindingListener} when the listener
+ * object is bound ({@link SSLSession#putValue(String, Object)}) or unbound
+ * ({@link SSLSession#removeValue(String)}) to an {@code SSLSession}.
+ */
public class SSLSessionBindingEvent extends EventObject implements Serializable {
/**
@@ -33,15 +38,36 @@
*/
private final String name;
+ /**
+ * Creates a new {@code SSLSessionBindingEvent} for the specified session
+ * indicating a binding event for the specified name.
+ *
+ * @param session
+ * the session for which the event occurs.
+ * @param name
+ * the name of the object being (un)bound.
+ */
public SSLSessionBindingEvent(SSLSession session, String name) {
super(session);
this.name = name;
}
+ /**
+ * Returns the name of the binding being added or removed.
+ *
+ * @return the name of the binding.
+ */
public String getName() {
return name;
}
+ /**
+ * Returns the session to which the binding is added or from which it is
+ * removed.
+ *
+ * @return the session to which the binding is added or from which it is
+ * removed.
+ */
public SSLSession getSession() {
return (SSLSession) this.source;
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java Thu Apr 30 11:01:28 2009
@@ -19,10 +19,26 @@
import java.util.EventListener;
+/**
+ * The interface to be implemented by any object that requires notification when
+ * data objects are bound to (or unbound from) an {@code SSLSession}.
+ */
public interface SSLSessionBindingListener extends EventListener {
+ /**
+ * Notifies this listener when a value is bound to an {@code SSLSession}.
+ *
+ * @param event
+ * the event data.
+ */
public void valueBound(SSLSessionBindingEvent event);
+ /**
+ * Notifies this listener when a value is unbound from an {@code SSLSession}.
+ *
+ * @param event
+ * the event data.
+ */
public void valueUnbound(SSLSessionBindingEvent event);
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java Thu Apr 30 11:01:28 2009
@@ -19,17 +19,64 @@
import java.util.Enumeration;
+/**
+ * A collection of {@code SSLSession}s.
+ */
public interface SSLSessionContext {
+ /**
+ * Returns an iterable of all session identifiers in this session context.
+ *
+ * @return an iterable of all session identifiers in this session context.
+ */
@SuppressWarnings("unchecked")
public Enumeration getIds();
+ /**
+ * Returns the session for the specified session identifier.
+ *
+ * @param sessionId
+ * the session identifier of the session to look up.
+ * @return the session for the specified session identifier, or {@code null}
+ * if the specified session identifier does not refer to a session
+ * in this context.
+ */
public SSLSession getSession(byte[] sessionId);
+ /**
+ * Returns the size of the session cache for this session context.
+ *
+ * @return the size of the session cache for this session context, or
+ * {@code zero} if unlimited.
+ */
public int getSessionCacheSize();
+ /**
+ * Returns the timeout for sessions in this session context. Sessions
+ * exceeding the timeout are invalidated.
+ *
+ * @return the timeout in seconds, or {@code zero} if unlimited.
+ */
public int getSessionTimeout();
+ /**
+ * Sets the size of the session cache for this session context.
+ *
+ * @param size
+ * the size of the session cache, or {@code zero} for unlimited
+ * cache size.
+ * @throws IllegalArgumentException
+ * if {@code size} is negative.
+ */
public void setSessionCacheSize(int size) throws IllegalArgumentException;
+ /**
+ * Sets the timeout for sessions in this context. Sessions exceeding the
+ * timeout are invalidated.
+ *
+ * @param seconds
+ * the timeout in seconds, or {@code zero} if unlimited.
+ * @throws IllegalArgumentException
+ * if {@code seconds} is negative.
+ */
public void setSessionTimeout(int seconds) throws IllegalArgumentException;
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java Thu Apr 30 11:01:28 2009
@@ -22,64 +22,278 @@
import java.net.Socket;
import java.net.UnknownHostException;
+/**
+ * The extension of {@code Socket} providing secure protocols like SSL (Secure
+ * Socket Layer") or TLS (Transport Layer Security).
+ */
public abstract class SSLSocket extends Socket {
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP socket.
+ */
protected SSLSocket() {
super();
}
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP socket connection to the specified host at the specified
+ * port.
+ *
+ * @param host
+ * the host name to connect to.
+ * @param port
+ * the port number to connect to.
+ * @throws IOException
+ * if creating the socket fails.
+ * @throws UnknownHostException
+ * if the specified host is not known.
+ */
protected SSLSocket(String host, int port) throws IOException, UnknownHostException {
super(host, port);
}
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP socket connection to the specified address at the specified
+ * port.
+ *
+ * @param address
+ * the address to connect to.
+ * @param port
+ * the port number to connect to.
+ * @throws IOException
+ * if creating the socket fails.
+ */
protected SSLSocket(InetAddress address, int port) throws IOException {
super(address, port);
}
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP socket connection to the specified host at the specified
+ * port with the client side bound to the specified address and port.
+ *
+ * @param host
+ * the host name to connect to.
+ * @param port
+ * the port number to connect to.
+ * @param clientAddress
+ * the client address to bind to
+ * @param clientPort
+ * the client port number to bind to.
+ * @throws IOException
+ * if creating the socket fails.
+ * @throws UnknownHostException
+ * if the specified host is not known.
+ */
protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)
throws IOException, UnknownHostException {
super(host, port, clientAddress, clientPort);
}
+ /**
+ * Only to be used by subclasses.
+ * <p>
+ * Creates a TCP socket connection to the specified address at the specified
+ * port with the client side bound to the specified address and port.
+ *
+ * @param address
+ * the address to connect to.
+ * @param port
+ * the port number to connect to.
+ * @param clientAddress
+ * the client address to bind to.
+ * @param clientPort
+ * the client port number to bind to.
+ * @throws IOException
+ * if creating the socket fails.
+ */
protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)
throws IOException {
super(address, port, clientAddress, clientPort);
}
+ /**
+ * Returns the names of the supported cipher suites.
+ *
+ * @return the names of the supported cipher suites.
+ */
public abstract String[] getSupportedCipherSuites();
+ /**
+ * Returns the names of the enabled cipher suites.
+ *
+ * @return the names of the enabled cipher suites.
+ */
public abstract String[] getEnabledCipherSuites();
+ /**
+ * Sets the names of the cipher suites to be enabled.
+ * Only cipher suites returned by {@link #getSupportedCipherSuites()} are
+ * allowed.
+ *
+ * @param suites
+ * the names of the to be enabled cipher suites.
+ * @throws IllegalArgumentException
+ * if one of the cipher suite names is not supported.
+ */
public abstract void setEnabledCipherSuites(String[] suites);
+ /**
+ * Returns the names of the supported protocols.
+ *
+ * @return the names of the supported protocols.
+ */
public abstract String[] getSupportedProtocols();
+ /**
+ * Returns the names of the enabled protocols.
+ *
+ * @return the names of the enabled protocols.
+ */
public abstract String[] getEnabledProtocols();
+ /**
+ * Sets the names of the protocols to be enabled. Only
+ * protocols returned by {@link #getSupportedProtocols()} are allowed.
+ *
+ * @param protocols
+ * the names of the to be enabled protocols.
+ * @throws IllegalArgumentException
+ * if one of the protocols is not supported.
+ */
public abstract void setEnabledProtocols(String[] protocols);
+ /**
+ * Returns the {@code SSLSession} for this connection. If necessary, a
+ * handshake will be initiated, in which case this method will block until the handshake
+ * has been established. If the handshake fails, an invalid session object
+ * will be returned.
+ *
+ * @return the session object.
+ */
public abstract SSLSession getSession();
+ /**
+ * Registers the specified listener to receive notification on completion of a
+ * handshake on this connection.
+ *
+ * @param listener
+ * the listener to register.
+ * @throws IllegalArgumentException
+ * if {@code listener} is {@code null}.
+ */
public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener);
+ /**
+ * Removes the specified handshake completion listener.
+ *
+ * @param listener
+ * the listener to remove.
+ * @throws IllegalArgumentException
+ * if the specified listener is not registered or {@code null}.
+ */
public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener);
+ /**
+ * Starts a new SSL handshake on this connection.
+ *
+ * @throws IOException
+ * if an error occurs.
+ */
public abstract void startHandshake() throws IOException;
+ /**
+ * Sets whether this connection should act in client mode when handshaking.
+ *
+ * @param mode
+ * {@code true} if this connection should act in client mode,
+ * {@code false} if not.
+ */
public abstract void setUseClientMode(boolean mode);
+ /**
+ * Returns whether this connection will act in client mode when handshaking.
+ *
+ * @return {@code true} if this connections will act in client mode when
+ * handshaking, {@code false} if not.
+ */
public abstract boolean getUseClientMode();
+ /**
+ * Sets whether this connection should require client authentication. This
+ * is only useful for sockets in server mode. The client authentication is
+ * one of the following:
+ * <ul>
+ * <li>authentication required</li>
+ * <li>authentication requested</li>
+ * <li>no authentication needed</li>
+ * </ul>
+ * This method overrides the setting of {@link #setWantClientAuth(boolean)}.
+ *
+ * @param need
+ * {@code true} if client authentication is required,
+ * {@code false} if no authentication is needed.
+ */
public abstract void setNeedClientAuth(boolean need);
+ /**
+ * Returns whether this connection requires client authentication.
+ * This is only useful for sockets in server mode.
+ *
+ * @return {@code true} if client authentication is required, {@code false}
+ * if no client authentication is needed.
+ */
public abstract boolean getNeedClientAuth();
+ /**
+ * Sets whether this connections should request client authentication. This
+ * is only useful for sockets in server mode. The client authentication is
+ * one of:
+ * <ul>
+ * <li>authentication required</li>
+ * <li>authentication requested</li>
+ * <li>no authentication needed</li>
+ * </ul>
+ * This method overrides the setting of {@link #setNeedClientAuth(boolean)}.
+ *
+ * @param want
+ * {@code true} if client authentication should be requested,
+ * {@code false} if not authentication is needed.
+ */
public abstract void setWantClientAuth(boolean want);
+ /**
+ * Returns whether this connections will request client authentication.
+ *
+ * @return {@code true} is client authentication will be requested,
+ * {@code false} if no client authentication is needed.
+ */
public abstract boolean getWantClientAuth();
+ /**
+ * Sets whether new SSL sessions may be created by this socket or if
+ * existing sessions must be reused.
+ *
+ * @param flag
+ * {@code true} if new sessions may be created, otherwise
+ * {@code false}.
+ */
public abstract void setEnableSessionCreation(boolean flag);
+ /**
+ * Returns whether new SSL sessions may be created by this socket or if
+ * existing sessions must be reused.
+ *
+ * @return {@code true} if new sessions may be created, otherwise
+ * {@code false}.
+ */
public abstract boolean getEnableSessionCreation();
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java Thu Apr 30 11:01:28 2009
@@ -25,6 +25,9 @@
import javax.net.SocketFactory;
+/**
+ * The abstract factory implementation to create {@code SSLSocket}s.
+ */
public abstract class SSLSocketFactory extends SocketFactory {
// FIXME EXPORT CONTROL
@@ -33,6 +36,12 @@
private static String defaultName;
+ /**
+ * Returns the default {@code SSLSocketFactory} instance. The default is
+ * defined by the security property {@code 'ssl.SocketFactory.provider'}.
+ *
+ * @return the default ssl socket factory instance.
+ */
public static synchronized SocketFactory getDefault() {
if (defaultSocketFactory != null) {
return defaultSocketFactory;
@@ -71,14 +80,48 @@
return defaultSocketFactory;
}
+ /**
+ * Creates a new {@code SSLSocketFactory}.
+ */
public SSLSocketFactory() {
super();
}
+ /**
+ * Returns the names of the cipher suites that are enabled by default.
+ *
+ * @return the names of the cipher suites that are enabled by default.
+ */
public abstract String[] getDefaultCipherSuites();
+ /**
+ * Returns the names of the cipher suites that are supported and could be
+ * enabled for an SSL connection.
+ *
+ * @return the names of the cipher suites that are supported.
+ */
public abstract String[] getSupportedCipherSuites();
+ /**
+ * Creates an {@code SSLSocket} over the specified socket that is connected
+ * to the specified host at the specified port.
+ *
+ * @param s
+ * the socket.
+ * @param host
+ * the host.
+ * @param port
+ * the port number.
+ * @param autoClose
+ * {@code true} if socket {@code s} should be closed when the
+ * created socket is closed, {@code false} if the socket
+ * {@code s} should be left open.
+ * @return the creates ssl socket.
+ * @throws IOException
+ * if creating the socket fails.
+ * @throws java.net.UnknownHostException
+ * if the host is unknown.
+ */
public abstract Socket createSocket(Socket s, String host, int port, boolean autoClose)
throws IOException;
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java Thu Apr 30 11:01:28 2009
@@ -17,5 +17,12 @@
package javax.net.ssl;
+/**
+ * The marker interface for JSSE trust managers. The purpose is to group trust
+ * managers. The responsibility a trust manager is to handle the trust data used to
+ * make trust decisions for deciding whether credentials of a peer should be
+ * accepted,
+ * @see TrustManagerFactory
+ */
public interface TrustManager {
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java Thu Apr 30 11:01:28 2009
@@ -29,6 +29,10 @@
import org.apache.harmony.security.fortress.Engine;
+/**
+ * The factory for {@code TrustManager}s based on {@code KeyStore} or provider
+ * specific implementation.
+ */
public class TrustManagerFactory {
// Store TrustManager service name
private static final String SERVICE = "TrustManagerFactory";
@@ -39,6 +43,13 @@
// Store default property name
private static final String PROPERTYNAME = "ssl.TrustManagerFactory.algorithm";
+ /**
+ * Returns the default algorithm name for the {@code TrustManagerFactory}. The
+ * default algorithm name is specified by the security property
+ * {@code 'ssl.TrustManagerFactory.algorithm'}.
+ *
+ * @return the default algorithm name.
+ */
public static final String getDefaultAlgorithm() {
return AccessController.doPrivileged(new PrivilegedAction<String>() {
public String run() {
@@ -48,8 +59,17 @@
}
/**
- * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
- * 1.4 release)
+ * Creates a new {@code TrustManagerFactory} instance for the specified
+ * trust management algorithm.
+ *
+ * @param algorithm
+ * the name of the requested trust management algorithm.
+ * @return a trust manager factory for the requested algorithm.
+ * @throws NoSuchAlgorithmException
+ * if no installed provider can provide the requested algorithm.
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null} (instead of
+ * NoSuchAlgorithmException as in 1.4 release)
*/
public static final TrustManagerFactory getInstance(String algorithm)
throws NoSuchAlgorithmException {
@@ -64,8 +84,23 @@
}
/**
- * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
- * 1.4 release)
+ * Creates a new {@code TrustManagerFactory} instance for the specified
+ * trust management algorithm from the specified provider.
+ *
+ * @param algorithm
+ * the name of the requested trust management algorithm name.
+ * @param provider
+ * the name of the provider that provides the requested
+ * algorithm.
+ * @return a trust manager factory for the requested algorithm.
+ * @throws NoSuchAlgorithmException
+ * if the specified provider cannot provide the requested
+ * algorithm.
+ * @throws NoSuchProviderException
+ * if the specified provider does not exist.
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null} (instead of
+ * NoSuchAlgorithmException as in 1.4 release)
*/
public static final TrustManagerFactory getInstance(String algorithm, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -80,8 +115,20 @@
}
/**
- * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
- * 1.4 release)
+ * Creates a new {@code TrustManagerFactory} instance for the specified
+ * trust management algorithm from the specified provider.
+ *
+ * @param algorithm
+ * the name of the requested key management algorithm name.
+ * @param provider
+ * the provider that provides the requested algorithm.
+ * @return a key manager factory for the requested algorithm.
+ * @throws NoSuchAlgorithmException
+ * if the specified provider cannot provide the requested
+ * algorithm.
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null} (instead of
+ * NoSuchAlgorithmException as in 1.4 release)
*/
public static final TrustManagerFactory getInstance(String algorithm, Provider provider)
throws NoSuchAlgorithmException {
@@ -106,6 +153,16 @@
// Store used algorithm
private final String algorithm;
+ /**
+ * Creates a new {@code TrustManagerFactory} instance.
+ *
+ * @param factorySpi
+ * the implementation delegate.
+ * @param provider
+ * the provider
+ * @param algorithm
+ * the algorithm name.
+ */
protected TrustManagerFactory(TrustManagerFactorySpi factorySpi, Provider provider,
String algorithm) {
this.provider = provider;
@@ -113,22 +170,58 @@
this.spiImpl = factorySpi;
}
+ /**
+ * Returns the name of this {@code TrustManagerFactory} algorithm
+ * implementation.
+ *
+ * @return the name of this {@code TrustManagerFactory} algorithm
+ * implementation.
+ */
public final String getAlgorithm() {
return algorithm;
}
+ /**
+ * Returns the provider for this {@code TrustManagerFactory} instance.
+ *
+ * @return the provider for this {@code TrustManagerFactory} instance.
+ */
public final Provider getProvider() {
return provider;
}
+ /**
+ * Initializes this factory instance with the specified keystore as source
+ * of certificate authorities and trust material.
+ *
+ * @param ks
+ * the keystore or {@code null}.
+ * @throws KeyStoreException
+ * if the initialization fails.
+ */
public final void init(KeyStore ks) throws KeyStoreException {
spiImpl.engineInit(ks);
}
+ /**
+ * Initializes this factory instance with the specified provider-specific
+ * parameters for a source of trust material.
+ *
+ * @param spec
+ * the provider-specific parameters.
+ * @throws InvalidAlgorithmParameterException
+ * if the initialization fails.
+ */
public final void init(ManagerFactoryParameters spec) throws InvalidAlgorithmParameterException {
spiImpl.engineInit(spec);
}
+ /**
+ * Returns the list of {@code TrustManager}s with one entry for each type
+ * of trust material.
+ *
+ * @return the list of {@code TrustManager}s
+ */
public final TrustManager[] getTrustManagers() {
return spiImpl.engineGetTrustManagers();
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java Thu Apr 30 11:01:28 2009
@@ -21,16 +21,47 @@
import java.security.KeyStore;
import java.security.KeyStoreException;
+/**
+ * The <i>Service Provider Interface</i> (SPI) for the
+ * {@code TrustManagerFactory} class.
+ */
public abstract class TrustManagerFactorySpi {
+ /**
+ * Creates a new {@code TrustManagerFactorySpi} instance.
+ */
public TrustManagerFactorySpi() {
super();
}
+ /**
+ * Initializes this factory instance with the specified keystore as source
+ * of certificate authorities and trust material.
+ *
+ * @param ks
+ * the keystore or {@code null}.
+ * @throws KeyStoreException
+ * if the initialization fails.
+ */
protected abstract void engineInit(KeyStore ks) throws KeyStoreException;
+ /**
+ * Initializes this factory instance with the specified provider-specific
+ * parameters for a source of trust material.
+ *
+ * @param spec
+ * the provider-specific parameters.
+ * @throws InvalidAlgorithmParameterException
+ * if the initialization fails.
+ */
protected abstract void engineInit(ManagerFactoryParameters spec)
throws InvalidAlgorithmParameterException;
+ /**
+ * Returns the list of {@code TrustManager}s with one entry for each type
+ * of trust material.
+ *
+ * @return the list of {@code TrustManager}s
+ */
protected abstract TrustManager[] engineGetTrustManagers();
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java Thu Apr 30 11:01:28 2009
@@ -19,17 +19,57 @@
import java.security.Principal;
+/**
+ * The abstract extension for the {@code X509KeyManager} interface.
+ */
public abstract class X509ExtendedKeyManager implements X509KeyManager {
+ /**
+ * To be used by subclasses only.
+ * <p>
+ * Creates a new {@code X509ExtendedKeyManager} instance.
+ */
protected X509ExtendedKeyManager() {
super();
}
- public String chooseEngineClientAlias(String[] keyType, Principal[] issuers, SSLEngine engine) {
+ /**
+ * Chooses a alias for the client side of an SSL connection to authenticate
+ * it with the specified public key type and certificate issuers.
+ *
+ * @param keyType
+ * the list of public key algorithm names.
+ * @param issuers
+ * the list of certificate issuers, or {@code null} if any issuer
+ * will do.
+ * @param engine
+ * the {@code SSLEngine} for the connection, or {@code null} if
+ * no engine is predefined.
+ * @return the alias name of a matching key or {@code null} if there are no
+ * matches.
+ */
+ public String chooseEngineClientAlias(String[] keyType,
+ Principal[] issuers, SSLEngine engine) {
return null;
}
- public String chooseEngineServerAlias(String keyType, Principal[] issuers, SSLEngine engine) {
+ /**
+ * Chooses a alias for the server side of an SSL connection to authenticate
+ * it with the specified public key type and certificate issuers.
+ *
+ * @param keyType
+ * the list of public key algorithm names.
+ * @param issuers
+ * the list of certificate issuers, or {@code null} if any issuer
+ * will do.
+ * @param engine
+ * the {@code SSLEngine} for the connection, or {@code null} if
+ * no engine is predefined.
+ * @return the alias name of a matching key or {@code null} if there are no
+ * matches.
+ */
+ public String chooseEngineServerAlias(String keyType, Principal[] issuers,
+ SSLEngine engine) {
return null;
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java Thu Apr 30 11:01:28 2009
@@ -22,17 +22,92 @@
import java.security.PrivateKey;
import java.security.cert.X509Certificate;
+/**
+ * A Key Manager for X509 certificate-based key pairs.
+ */
public interface X509KeyManager extends KeyManager {
- public String chooseClientAlias(String[] keyType, Principal[] issuers, Socket socket);
-
- public String chooseServerAlias(String keyType, Principal[] issuers, Socket socket);
-
+ /**
+ * Chooses an alias for the client side of an SSL connection to authenticate
+ * it with the specified public key type and certificate issuers.
+ *
+ * @param keyType
+ * the list of public key algorithm names.
+ * @param issuers
+ * the list of certificate issuers, or {@code null} if any issuer
+ * will do.
+ * @param socket
+ * the socket for the connection, or {@code null} if
+ * the alias selected does not depend on a specific socket.
+ * @return the alias name of a matching key or {@code null} if there are no
+ * matches.
+ */
+ public String chooseClientAlias(String[] keyType, Principal[] issuers,
+ Socket socket);
+
+ /**
+ * Chooses an alias for the server side of an SSL connection to authenticate
+ * it with the specified public key type and certificate issuers.
+ *
+ * @param keyType
+ * the list of public key algorithm type names.
+ * @param issuers
+ * the list of certificate issuers, or {@code null} if any issuer
+ * will do.
+ * @param socket
+ * the socket for the connection, or {@code null} if
+ * the alias selected does not depend on a specific socket.
+ * @return the alias name of a matching key or {@code null} if there are no
+ * matches.
+ */
+ public String chooseServerAlias(String keyType, Principal[] issuers,
+ Socket socket);
+
+ /**
+ * Returns the certificate chain for the specified alias.
+ *
+ * @param alias
+ * the alias to get the certificate chain for.
+ * @return the certificate chain for the specified alias, or {@code null} if
+ * the alias cannot be found.
+ */
public X509Certificate[] getCertificateChain(String alias);
+ /**
+ * Returns the client aliases for the specified public key type and list of
+ * certificate issuers.
+ *
+ * @param keyType
+ * the public key algorithm type name.
+ * @param issuers
+ * the list of certificate issuers, or {@code null} if any issuer
+ * will do.
+ * @return the client aliases for the specified public key type, or
+ * {@code null} if there are no matching aliases.
+ */
public String[] getClientAliases(String keyType, Principal[] issuers);
+ /**
+ * Returns the server aliases for the specified public key type and list of
+ * certificate issuers.
+ *
+ * @param keyType
+ * the public key algorithm type name.
+ * @param issuers
+ * the list of certificate issuers, or {@code null} if any issuer
+ * will do.
+ * @return the client aliases for the specified public key type, or
+ * {@code null} if there are no matching aliases.
+ */
public String[] getServerAliases(String keyType, Principal[] issuers);
+ /**
+ * Returns the private key for the specified alias.
+ *
+ * @param alias
+ * the alias to get the private key for.
+ * @return the private key for the specified alias, or {@code null} if the
+ * alias cannot be found.
+ */
public PrivateKey getPrivateKey(String alias);
}
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java Thu Apr 30 11:01:28 2009
@@ -20,13 +20,57 @@
import java.security.cert.CertificateException;
import java.security.cert.X509Certificate;
+/**
+ * The trust manager for X509 certificates to be used to perform authentication
+ * for secure sockets.
+ */
public interface X509TrustManager extends TrustManager {
+ /**
+ * Checks whether the specified certificate chain (partial or complete) can
+ * be validated and is trusted for client authentication for the specified
+ * authentication type.
+ *
+ * @param chain
+ * the certificate chain to validate.
+ * @param authType
+ * the authentication type used.
+ * @throws CertificateException
+ * if the certificate chain can't be validated or isn't trusted.
+ * @throws IllegalArgumentException
+ * if the specified certificate chain is empty or {@code null},
+ * or if the specified authentication type is {@code null} or an
+ * empty string.
+ */
public void checkClientTrusted(X509Certificate[] chain, String authType)
throws CertificateException;
+
+ /**
+ * Checks whether the specified certificate chain (partial or complete) can
+ * be validated and is trusted for server authentication for the specified
+ * key exchange algorithm.
+ *
+ * @param chain
+ * the certificate chain to validate.
+ * @param authType
+ * the key exchange algorithm name.
+ * @throws CertificateException
+ * if the certificate chain can't be validated or isn't trusted.
+ * @throws IllegalArgumentException
+ * if the specified certificate chain is empty or {@code null},
+ * or if the specified authentication type is {@code null} or an
+ * empty string.
+ */
public void checkServerTrusted(X509Certificate[] chain, String authType)
throws CertificateException;
+ /**
+ * Returns the list of certificate issuer authorities which are trusted for
+ * authentication of peers.
+ *
+ * @return the list of certificate issuer authorities which are trusted for
+ * authentication of peers.
+ */
public X509Certificate[] getAcceptedIssuers();
}