org.apache.commons.net.pop3

Class POP3SClient

java.lang.Object

org.apache.commons.net.SocketClient

org.apache.commons.net.pop3.POP3

org.apache.commons.net.pop3.POP3Client

org.apache.commons.net.pop3.POP3SClient

Direct Known Subclasses:

ExtendedPOP3Client

public class POP3SClient
extends POP3Client

POP3 over SSL processing. Copied from FTPSClient.java and modified to suit POP3. If implicit mode is selected (NOT the default), SSL/TLS negotiation starts right after the connection has been established. In explicit mode (the default), SSL/TLS negotiation starts when the user calls execTLS() and the server accepts the command. Implicit usage: POP3SClient c = new POP3SClient(true); c.connect("127.0.0.1", 995); Explicit usage: POP3SClient c = new POP3SClient(); c.connect("127.0.0.1", 110); if (c.execTLS()) { /rest of the commands here/ } Warning: the hostname is not verified against the certificate by default, use setHostnameVerifier(HostnameVerifier) or setEndpointCheckingEnabled(boolean) (on Java 1.7+) to enable verification.

Since:

3.0

Field Summary

Fields

Modifier and Type	Field and Description
private javax.net.ssl.SSLContext	context The context object.
private static int	DEFAULT_POP3S_PORT
private static java.lang.String	DEFAULT_PROTOCOL Default secure socket protocol name, like TLS
private javax.net.ssl.HostnameVerifier	hostnameVerifier The HostnameVerifier to use post-TLS, default null (i.e.
private boolean	isImplicit The security mode.
private javax.net.ssl.KeyManager	keyManager The KeyManager, default null.
private java.lang.String	protocol The secure socket protocol to be used, like SSL/TLS.
private java.lang.String[]	protocols The protocol versions.
private java.lang.String[]	suites The cipher suites.
private boolean	tlsEndpointChecking Use Java 1.7+ HTTPS Endpoint Identification Algorithim.
private javax.net.ssl.TrustManager	trustManager The FTPS TrustManager implementation, default null.

Fields inherited from class org.apache.commons.net.pop3.POP3

_commandSupport_, _DEFAULT_ENCODING, _ERROR, _lastReplyLine, _OK, _OK_INT, _reader, _replyCode, _replyLines, _writer, AUTHORIZATION_STATE, DEFAULT_PORT, DISCONNECTED_STATE, TRANSACTION_STATE, UPDATE_STATE

Fields inherited from class org.apache.commons.net.SocketClient

_defaultPort_, _hostname_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL

Constructor Summary

Constructors

Constructor and Description
POP3SClient() Constructor for POP3SClient, using DEFAULT_PROTOCOL i.e.
POP3SClient(boolean implicit) Constructor for POP3SClient, using DEFAULT_PROTOCOL i.e.
POP3SClient(boolean implicit, javax.net.ssl.SSLContext ctx) Constructor for POP3SClient, using DEFAULT_PROTOCOL i.e.
POP3SClient(javax.net.ssl.SSLContext context) Constructor for POP3SClient, using DEFAULT_PROTOCOL - TLS - and isImplicit = false
POP3SClient(java.lang.String proto) Constructor for POP3SClient.
POP3SClient(java.lang.String proto, boolean implicit) Constructor for POP3SClient.
POP3SClient(java.lang.String proto, boolean implicit, javax.net.ssl.SSLContext ctx) Constructor for POP3SClient.

Method Summary

Modifier and Type	Method and Description
protected void	_connectAction_() Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all of the connect() methods.
boolean	execTLS() The TLS command execution.
java.lang.String[]	getEnabledCipherSuites() Returns the names of the cipher suites which could be enabled for use on this connection.
java.lang.String[]	getEnabledProtocols() Returns the names of the protocol versions which are currently enabled for use on this connection.
javax.net.ssl.HostnameVerifier	getHostnameVerifier() Get the currently configured HostnameVerifier.
private javax.net.ssl.KeyManager	getKeyManager() Get the KeyManager instance.
javax.net.ssl.TrustManager	getTrustManager() Get the currently configured TrustManager.
private void	initSSLContext() Performs a lazy init of the SSL context.
boolean	isEndpointCheckingEnabled() Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled.
private void	performSSLNegotiation() SSL/TLS negotiation.
void	setEnabledCipherSuites(java.lang.String[] cipherSuites) Controls which particular cipher suites are enabled for use on this connection.
void	setEnabledProtocols(java.lang.String[] protocolVersions) Controls which particular protocol versions are enabled for use on this connection.
void	setEndpointCheckingEnabled(boolean enable) Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+.
void	setHostnameVerifier(javax.net.ssl.HostnameVerifier newHostnameVerifier) Override the default HostnameVerifier to use.
void	setKeyManager(javax.net.ssl.KeyManager newKeyManager) Set a KeyManager to use.
void	setTrustManager(javax.net.ssl.TrustManager newTrustManager) Override the default TrustManager to use.

Methods inherited from class org.apache.commons.net.pop3.POP3Client

capa, deleteMessage, listMessage, listMessages, listUniqueIdentifier, listUniqueIdentifiers, login, login, logout, noop, reset, retrieveMessage, retrieveMessageTop, status

Methods inherited from class org.apache.commons.net.pop3.POP3

disconnect, getAdditionalReply, getCommandSupport, getReplyString, getReplyStrings, getState, removeProtocolCommandistener, sendCommand, sendCommand, sendCommand, sendCommand, setState

Methods inherited from class org.apache.commons.net.SocketClient

addProtocolCommandListener, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getCharset, getCharsetName, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setCharset, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_POP3S_PORT

private static final int DEFAULT_POP3S_PORT

See Also:

Constant Field Values

DEFAULT_PROTOCOL

private static final java.lang.String DEFAULT_PROTOCOL

Default secure socket protocol name, like TLS

See Also:

Constant Field Values

isImplicit

private final boolean isImplicit

The security mode. True - Implicit Mode / False - Explicit Mode.

protocol

private final java.lang.String protocol

The secure socket protocol to be used, like SSL/TLS.

context

private javax.net.ssl.SSLContext context

The context object.

suites

private java.lang.String[] suites

The cipher suites. SSLSockets have a default set of these anyway, so no initialization required.

protocols

private java.lang.String[] protocols

The protocol versions.

trustManager

private javax.net.ssl.TrustManager trustManager

The FTPS TrustManager implementation, default null.

keyManager

private javax.net.ssl.KeyManager keyManager

The KeyManager, default null.

hostnameVerifier

private javax.net.ssl.HostnameVerifier hostnameVerifier

The HostnameVerifier to use post-TLS, default null (i.e. no verification).

tlsEndpointChecking

private boolean tlsEndpointChecking

Use Java 1.7+ HTTPS Endpoint Identification Algorithim.

Constructor Detail

POP3SClient

public POP3SClient()

Constructor for POP3SClient, using DEFAULT_PROTOCOL i.e. TLS Sets security mode to explicit.

POP3SClient

public POP3SClient(boolean implicit)

Constructor for POP3SClient, using DEFAULT_PROTOCOL i.e. TLS

Parameters:

implicit - The security mode, true for implicit, false for explicit

POP3SClient

public POP3SClient(java.lang.String proto)

Constructor for POP3SClient. Sets security mode to explicit.

Parameters:

proto - the protocol.

POP3SClient

public POP3SClient(java.lang.String proto,
                   boolean implicit)

Constructor for POP3SClient.

Parameters:

proto - the protocol.

implicit - The security mode, true for implicit, false for explicit

POP3SClient

public POP3SClient(java.lang.String proto,
                   boolean implicit,
                   javax.net.ssl.SSLContext ctx)

Constructor for POP3SClient. Sets the default port to DEFAULT_POP3S_PORT - 995 - if using implicit mode

Parameters:

proto - the protocol.

implicit - The security mode, true for implicit, false for explicit

ctx - the context to be used

POP3SClient

public POP3SClient(boolean implicit,
                   javax.net.ssl.SSLContext ctx)

Constructor for POP3SClient, using DEFAULT_PROTOCOL i.e. TLS

Parameters:

implicit - The security mode, true for implicit, false for explicit

ctx - A pre-configured SSL Context.

POP3SClient

public POP3SClient(javax.net.ssl.SSLContext context)

Constructor for POP3SClient, using DEFAULT_PROTOCOL - TLS - and isImplicit = false

Parameters:

context - A pre-configured SSL Context.

See Also:

POP3SClient(boolean, SSLContext)

Method Detail

_connectAction_

protected void _connectAction_()
                        throws java.io.IOException

Because there are so many connect() methods, the _connectAction_() method is provided as a means of performing some action immediately after establishing a connection, rather than reimplementing all of the connect() methods.

Overrides:

_connectAction_ in class POP3

Throws:

java.io.IOException - If it is thrown by _connectAction_().

See Also:

SocketClient._connectAction_()

initSSLContext

private void initSSLContext()
                     throws java.io.IOException

Performs a lazy init of the SSL context.

Throws:

java.io.IOException - When could not initialize the SSL context.

performSSLNegotiation

private void performSSLNegotiation()
                            throws java.io.IOException

SSL/TLS negotiation. Acquires an SSL socket of a connection and carries out handshake processing.

Throws:

java.io.IOException - If server negotiation fails.

getKeyManager

private javax.net.ssl.KeyManager getKeyManager()

Get the KeyManager instance.

Returns:

The current KeyManager instance.

setKeyManager

public void setKeyManager(javax.net.ssl.KeyManager newKeyManager)

Set a KeyManager to use.

Parameters:

newKeyManager - The KeyManager implementation to set.

See Also:

KeyManagerUtils

setEnabledCipherSuites

public void setEnabledCipherSuites(java.lang.String[] cipherSuites)

Controls which particular cipher suites are enabled for use on this connection. Called before server negotiation.

Parameters:

cipherSuites - The cipher suites.

getEnabledCipherSuites

public java.lang.String[] getEnabledCipherSuites()

Returns the names of the cipher suites which could be enabled for use on this connection. When the underlying Socket is not an SSLSocket instance, returns null.

Returns:

An array of cipher suite names, or null.

setEnabledProtocols

public void setEnabledProtocols(java.lang.String[] protocolVersions)

Controls which particular protocol versions are enabled for use on this connection. I perform setting before a server negotiation.

Parameters:

protocolVersions - The protocol versions.

getEnabledProtocols

public java.lang.String[] getEnabledProtocols()

Returns the names of the protocol versions which are currently enabled for use on this connection. When the underlying Socket is not an SSLSocket instance, returns null.

Returns:

An array of protocols, or null.

execTLS

public boolean execTLS()
                throws javax.net.ssl.SSLException,
                       java.io.IOException

The TLS command execution.

Returns:

TRUE if the command and negotiation succeeded.

Throws:

javax.net.ssl.SSLException - If the server reply code is not positive.

java.io.IOException - If an I/O error occurs while sending the command or performing the negotiation.

getTrustManager

public javax.net.ssl.TrustManager getTrustManager()

Get the currently configured TrustManager.

Returns:

A TrustManager instance.

setTrustManager

public void setTrustManager(javax.net.ssl.TrustManager newTrustManager)

Override the default TrustManager to use.

Parameters:

newTrustManager - The TrustManager implementation to set.

See Also:

TrustManagerUtils

getHostnameVerifier

public javax.net.ssl.HostnameVerifier getHostnameVerifier()

Get the currently configured HostnameVerifier.

Returns:

A HostnameVerifier instance.

Since:

3.4

setHostnameVerifier

public void setHostnameVerifier(javax.net.ssl.HostnameVerifier newHostnameVerifier)

Override the default HostnameVerifier to use.

Parameters:

newHostnameVerifier - The HostnameVerifier implementation to set or null to disable.

Since:

3.4

isEndpointCheckingEnabled

public boolean isEndpointCheckingEnabled()

Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled. The default behaviour is for this to be disabled.

Returns:

True if enabled, false if not.

Since:

3.4

setEndpointCheckingEnabled

public void setEndpointCheckingEnabled(boolean enable)

Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+. The default behaviour is for this to be disabled.

Parameters:

enable - Enable automatic endpoint identification checking using the HTTPS algorithm on Java 1.7+.

Since:

3.4