SMTPSClient
Date: 2016-06-23

org.apache.commons.net.smtp

## Class SMTPSClient

- java.lang.Object
- - org.apache.commons.net.SocketClient
  - - org.apache.commons.net.smtp.SMTP
    - - org.apache.commons.net.smtp.SMTPClient
      - - org.apache.commons.net.smtp.SMTPSClient

- Direct Known Subclasses:
    AuthenticatingSMTPClient

      public class SMTPSClient
      extends SMTPClient

  SMTP over SSL processing. Copied from FTPSClient.java and modified to suit SMTP. 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: SMTPSClient c = new SMTPSClient(true); c.connect("127.0.0.1", 465); Explicit usage: SMTPSClient c = new SMTPSClient(); c.connect("127.0.0.1", 25); 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 inherited from class org.apache.commons.net.smtp.SMTP

      `_commandSupport_, DEFAULT_PORT, encoding`

    - ### 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
    `SMTPSClient()` Constructor for SMTPSClient, using `DEFAULT_PROTOCOL` i.e.
    `SMTPSClient(boolean implicit)` Constructor for SMTPSClient, using `DEFAULT_PROTOCOL` i.e.
    `SMTPSClient(boolean implicit, javax.net.ssl.SSLContext ctx)` Constructor for SMTPSClient, using `DEFAULT_PROTOCOL` i.e.
    `SMTPSClient(javax.net.ssl.SSLContext context)` Constructor for SMTPSClient.
    `SMTPSClient(java.lang.String proto)` Constructor for SMTPSClient, using explicit security mode.
    `SMTPSClient(java.lang.String proto, boolean implicit)` Constructor for SMTPSClient.
    `SMTPSClient(java.lang.String proto, boolean implicit, java.lang.String encoding)` Constructor for SMTPSClient.

  - ### Method Summary

    Methods
    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`.
    `javax.net.ssl.KeyManager` | `getKeyManager()` Get the `KeyManager` instance.
    `javax.net.ssl.TrustManager` | `getTrustManager()` Get the currently configured `TrustManager`.
    `boolean` | `isEndpointCheckingEnabled()` Return whether or not endpoint identification using the HTTPS algorithm on Java 1.7+ is enabled.
    `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.smtp.SMTPClient

      `addRecipient, addRecipient, completePendingCommand, listHelp, listHelp, login, login, logout, reset, sendMessageData, sendNoOp, sendShortMessageData, sendSimpleMessage, sendSimpleMessage, setSender, setSender, verify`

    - ### Methods inherited from class org.apache.commons.net.smtp.SMTP

      `data, disconnect, expn, getCommandSupport, getReply, getReplyCode, getReplyString, getReplyStrings, helo, help, help, mail, noop, quit, rcpt, removeProtocolCommandistener, rset, saml, send, sendCommand, sendCommand, sendCommand, sendCommand, soml, turn, vrfy`

    - ### 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`

- - ### Constructor Detail

    - #### SMTPSClient

          public SMTPSClient()

      Constructor for SMTPSClient, using `DEFAULT_PROTOCOL` i.e. TLS Sets security mode to explicit (isImplicit = false).

    - #### SMTPSClient

          public SMTPSClient(boolean implicit)

      Constructor for SMTPSClient, using `DEFAULT_PROTOCOL` i.e. TLS
      Parameters:
        `implicit` - The security mode, `true` for implicit, `false` for explicit

    - #### SMTPSClient

          public SMTPSClient(java.lang.String proto)

      Constructor for SMTPSClient, using explicit security mode.
      Parameters:
        `proto` - the protocol.

    - #### SMTPSClient

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

      Constructor for SMTPSClient.
      Parameters:
        `proto` - the protocol.
        `implicit` - The security mode, `true` for implicit, `false` for explicit

    - #### SMTPSClient

          public SMTPSClient(java.lang.String proto,
                     boolean implicit,
                     java.lang.String encoding)

      Constructor for SMTPSClient.
      Parameters:
        `proto` - the protocol.
        `implicit` - The security mode, `true` for implicit, `false` for explicit
        `encoding` - the encoding
      Since:
        3.3

    - #### SMTPSClient

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

      Constructor for SMTPSClient, using `DEFAULT_PROTOCOL` i.e. TLS
      Parameters:
        `implicit` - The security mode, `true` for implicit, `false` for explicit
        `ctx` - A pre-configured SSL Context.

    - #### SMTPSClient

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

      Constructor for SMTPSClient.
      Parameters:
        `context` - A pre-configured SSL Context.
      See Also:
        `SMTPSClient(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 `SMTP`
      Throws:
        `java.io.IOException` - If it is thrown by _connectAction_().
      See Also:
        `SocketClient._connectAction_()`

    - #### getKeyManager

          public 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 java.io.IOException

      The TLS command execution.
      Returns:
        TRUE if the command and negotiation succeeded.
      Throws:
        `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