Package org.apache.commons.net.imap

Class IMAPSClient

java.lang.Object
org.apache.commons.net.SocketClient
org.apache.commons.net.imap.IMAP
org.apache.commons.net.imap.IMAPClient
org.apache.commons.net.imap.IMAPSClient
Direct Known Subclasses:
AuthenticatingIMAPClient
public class IMAPSClient extends IMAPClient
The IMAPSClient class provides SSL/TLS connection encryption to IMAPClient. Copied from FTPSClient and modified to suit IMAP. 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:

               IMAPSClient c = new IMAPSClient(true);
               c.connect("127.0.0.1", 993);

 //Explicit usage:

               IMAPSClient c = new IMAPSClient();
               c.connect("127.0.0.1", 143);
               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.

  • Field Details

    • DEFAULT_IMAPS_PORT

      public static final int DEFAULT_IMAPS_PORT
      The default IMAP over SSL port.
      See Also:

    • DEFAULT_PROTOCOL

      public static final String DEFAULT_PROTOCOL
      Default secure socket protocol name.
      See Also:

    • isImplicit

      private final boolean isImplicit
      The security mode. True - Implicit Mode / False - Explicit Mode.

    • protocol

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

    • context

      private SSLContext context
      The context object.

    • suites

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

    • protocols

      private String[] protocols
      The protocol versions.

    • trustManager

      private TrustManager trustManager
      The IMAPS TrustManager implementation, default null.

    • keyManager

      private KeyManager keyManager
      The KeyManager, default null.

    • hostnameVerifier

      private 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 Algorithm.

  • Constructor Details

    • IMAPSClient

      public IMAPSClient()
      Constructor for IMAPSClient. Sets security mode to explicit (isImplicit = false).

    • IMAPSClient

      public IMAPSClient(boolean implicit)
      Constructor for IMAPSClient.
      Parameters:
      implicit - The security mode (Implicit/Explicit).

    • IMAPSClient

      public IMAPSClient(boolean implicit, SSLContext ctx)
      Constructor for IMAPSClient.
      Parameters:
      implicit - The security mode(Implicit/Explicit).
      ctx - A pre-configured SSL Context.

    • IMAPSClient

      public IMAPSClient(SSLContext context)
      Constructor for IMAPSClient.
      Parameters:
      context - A pre-configured SSL Context.

    • IMAPSClient

      public IMAPSClient(String proto)
      Constructor for IMAPSClient.
      Parameters:
      proto - the protocol.

    • IMAPSClient

      public IMAPSClient(String proto, boolean implicit)
      Constructor for IMAPSClient.
      Parameters:
      proto - the protocol.
      implicit - The security mode(Implicit/Explicit).

    • IMAPSClient

      public IMAPSClient(String proto, boolean implicit, SSLContext ctx)
      Constructor for IMAPSClient.
      Parameters:
      proto - the protocol.
      implicit - The security mode(Implicit/Explicit).
      ctx - the SSL context

  • Method Details

    • _connectAction_

      protected void _connectAction_() throws 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 the connect() methods.
      Overrides:
      _connectAction_ in class IMAP
      Throws:
      IOException - If it is thrown by _connectAction_().
      See Also:

    • execTLS

      public boolean execTLS() throws SSLException, IOException
      The TLS command execution.
      Returns:
      TRUE if the command and negotiation succeeded.
      Throws:
      SSLException - If the server reply code is not positive.
      IOException - If an I/O error occurs while sending the command or performing the negotiation.

    • getEnabledCipherSuites

      public 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.

    • getEnabledProtocols

      public 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.

    • getHostnameVerifier

      public HostnameVerifier getHostnameVerifier()
      Gets the currently configured HostnameVerifier.
      Returns:
      A HostnameVerifier instance.
      Since:
      3.4

    • getKeyManager

      private KeyManager getKeyManager()
      Gets the KeyManager instance.
      Returns:
      The current KeyManager instance.

    • getTrustManager

      public TrustManager getTrustManager()
      Gets the currently configured TrustManager.
      Returns:
      A TrustManager instance.

    • initSSLContext

      private void initSSLContext() throws IOException
      Performs a lazy init of the SSL context.
      Throws:
      IOException - When could not initialize the SSL context.

    • isEndpointCheckingEnabled

      public boolean isEndpointCheckingEnabled()
      Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled. The default behavior is for this to be disabled.
      Returns:
      True if enabled, false if not.
      Since:
      3.4

    • performSSLNegotiation

      private void performSSLNegotiation() throws IOException
      SSL/TLS negotiation. Acquires an SSL socket of a connection and carries out handshake processing.
      Throws:
      IOException - If server negotiation fails.

    • setEnabledCipherSuites

      public void setEnabledCipherSuites(String[] cipherSuites)
      Controls which particular cipher suites are enabled for use on this connection. Called before server negotiation.
      Parameters:
      cipherSuites - The cipher suites.

    • setEnabledProtocols

      public void setEnabledProtocols(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.

    • setEndpointCheckingEnabled

      public void setEndpointCheckingEnabled(boolean enable)
      Automatic endpoint identification checking using the HTTPS algorithm is supported on Java 1.7+. The default behavior is for this to be disabled.
      Parameters:
      enable - Enable automatic endpoint identification checking using the HTTPS algorithm on Java 1.7+.
      Since:
      3.4

    • setHostnameVerifier

      public void setHostnameVerifier(HostnameVerifier newHostnameVerifier)
      Override the default HostnameVerifier to use.
      Parameters:
      newHostnameVerifier - The HostnameVerifier implementation to set or null to disable.
      Since:
      3.4

    • setKeyManager

      public void setKeyManager(KeyManager newKeyManager)
      Sets a KeyManager to use.
      Parameters:
      newKeyManager - The KeyManager implementation to set.
      See Also:

    • setTrustManager

      public void setTrustManager(TrustManager newTrustManager)
      Override the default TrustManager to use.
      Parameters:
      newTrustManager - The TrustManager implementation to set.
      See Also: