Package org.apache.commons.net.imap

Class 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 Detail

      • DEFAULT_IMAPS_PORT

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

      • DEFAULT_PROTOCOL

        public static final java.lang.String DEFAULT_PROTOCOL
        Default secure socket protocol name.
        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 IMAPS 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 Algorithm.

    • Constructor Detail

      • 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,
                   javax.net.ssl.SSLContext ctx)
        Constructor for IMAPSClient.
        Parameters:
        implicit - The security mode(Implicit/Explicit).
        ctx - A pre-configured SSL Context.

      • IMAPSClient

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

      • IMAPSClient

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

      • IMAPSClient

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

      • IMAPSClient

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

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

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

      • getEnabledCipherSuites

        public java.lang.String[] getEnabledCipherSuites()
        Gets 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 java.lang.String[] getEnabledProtocols()
        Gets 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 javax.net.ssl.HostnameVerifier getHostnameVerifier()
        Gets the currently configured HostnameVerifier.
        Returns:
        A HostnameVerifier instance.
        Since:
        3.4

      • getKeyManager

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

      • getTrustManager

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

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

      • isEndpointCheckingEnabled

        public boolean isEndpointCheckingEnabled()
        Tests 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 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.

      • setEnabledCipherSuites

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

      • setEnabledProtocols

        public void setEnabledProtocols​(java.lang.String[] protocolVersions)
        Sets 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)
        Sets 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​(javax.net.ssl.HostnameVerifier newHostnameVerifier)
        Sets to override the default HostnameVerifier to use.
        Parameters:
        newHostnameVerifier - The HostnameVerifier implementation to set or null to disable.
        Since:
        3.4

      • setKeyManager

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

      • setTrustManager

        public void setTrustManager​(javax.net.ssl.TrustManager newTrustManager)
        Sets to override the default TrustManager to use.
        Parameters:
        newTrustManager - The TrustManager implementation to set.
        See Also:
        TrustManagerUtils