ConnectionConfiguration.java

  1. /**
  2.  *
  3.  * Copyright 2003-2007 Jive Software.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.jivesoftware.smack;

  20. import org.jivesoftware.smack.packet.Session;
  21. import org.jivesoftware.smack.proxy.ProxyInfo;
  22. import org.jxmpp.jid.DomainBareJid;

  24. import javax.net.SocketFactory;
  25. import javax.net.ssl.HostnameVerifier;
  26. import javax.net.ssl.SSLContext;
  27. import javax.security.auth.callback.CallbackHandler;

  29. /**
  30.  * Configuration to use while establishing the connection to the server.
  31.  *
  32.  * @author Gaston Dombiak
  33.  */
  34. public abstract class ConnectionConfiguration {

  36.     static {
  37.         // Ensure that Smack is initialized when ConnectionConfiguration is used, or otherwise e.g.
  38.         // SmackConfiguration.DEBUG may not be initialized yet.
  39.         SmackConfiguration.getVersion();
  40.     }

  42.     /**
  43.      * Hostname of the XMPP server. Usually servers use the same service name as the name
  44.      * of the server. However, there are some servers like google where host would be
  45.      * talk.google.com and the serviceName would be gmail.com.
  46.      */
  47.     protected final DomainBareJid serviceName;
  48.     protected final String host;
  49.     protected final int port;

  51.     private final String keystorePath;
  52.     private final String keystoreType;
  53.     private final String pkcs11Library;
  54.     private final SSLContext customSSLContext;

  56.     /**
  57.      * Used to get information from the user
  58.      */
  59.     private final CallbackHandler callbackHandler;

  61.     private final boolean debuggerEnabled;

  63.     // Holds the socket factory that is used to generate the socket in the connection
  64.     private final SocketFactory socketFactory;

  66.     private final CharSequence username;
  67.     private final String password;
  68.     private final String resource;

  70.     /**
  71.      * Initial presence as of RFC 6121 § 4.2
  72.      * @see <a href="http://xmpp.org/rfcs/rfc6121.html#presence-initial">RFC 6121 § 4.2 Initial Presence</a>
  73.      */
  74.     private final boolean sendPresence;

  76.     private final boolean legacySessionDisabled;
  77.     private final SecurityMode securityMode;

  79.     /**
  80.      * 
  81.      */
  82.     private final String[] enabledSSLProtocols;

  84.     /**
  85.      * 
  86.      */
  87.     private final String[] enabledSSLCiphers;

  89.     private final HostnameVerifier hostnameVerifier;

  91.     // Holds the proxy information (such as proxyhost, proxyport, username, password etc)
  92.     protected final ProxyInfo proxy;

  94.     protected final boolean allowNullOrEmptyUsername;

  96.     protected ConnectionConfiguration(Builder<?,?> builder) {
  97.         username = builder.username;
  98.         password = builder.password;
  99.         callbackHandler = builder.callbackHandler;

  101.         // Resource can be null, this means that the server must provide one
  102.         resource = builder.resource;

  104.         serviceName = builder.serviceName;
  105.         if (serviceName == null) {
  106.             throw new IllegalArgumentException("Must provide XMPP service name");
  107.         }
  108.         host = builder.host;
  109.         port = builder.port;

  111.         proxy = builder.proxy;
  112.         if (proxy != null) {
  113.             if (builder.socketFactory != null) {
  114.                 throw new IllegalArgumentException("Can not use proxy together with custom socket factory");
  115.             }
  116.             socketFactory = proxy.getSocketFactory();
  117.         } else {
  118.             socketFactory = builder.socketFactory;
  119.         }

  121.         securityMode = builder.securityMode;
  122.         keystoreType = builder.keystoreType;
  123.         keystorePath = builder.keystorePath;
  124.         pkcs11Library = builder.pkcs11Library;
  125.         customSSLContext = builder.customSSLContext;
  126.         enabledSSLProtocols = builder.enabledSSLProtocols;
  127.         enabledSSLCiphers = builder.enabledSSLCiphers;
  128.         hostnameVerifier = builder.hostnameVerifier;
  129.         sendPresence = builder.sendPresence;
  130.         legacySessionDisabled = builder.legacySessionDisabled;
  131.         debuggerEnabled = builder.debuggerEnabled;
  132.         allowNullOrEmptyUsername = builder.allowEmptyOrNullUsername;
  133.     }

  135.     /**
  136.      * Returns the server name of the target server.
  137.      *
  138.      * @return the server name of the target server.
  139.      */
  140.     public DomainBareJid getServiceName() {
  141.         return serviceName;
  142.     }

  144.     /**
  145.      * Returns the TLS security mode used when making the connection. By default,
  146.      * the mode is {@link SecurityMode#ifpossible}.
  147.      *
  148.      * @return the security mode.
  149.      */
  150.     public SecurityMode getSecurityMode() {
  151.         return securityMode;
  152.     }

  154.     /**
  155.      * Retuns the path to the keystore file. The key store file contains the 
  156.      * certificates that may be used to authenticate the client to the server,
  157.      * in the event the server requests or requires it.
  158.      *
  159.      * @return the path to the keystore file.
  160.      */
  161.     public String getKeystorePath() {
  162.         return keystorePath;
  163.     }

  165.     /**
  166.      * Returns the keystore type, or <tt>null</tt> if it's not set.
  167.      *
  168.      * @return the keystore type.
  169.      */
  170.     public String getKeystoreType() {
  171.         return keystoreType;
  172.     }

  174.     /**
  175.      * Returns the PKCS11 library file location, needed when the
  176.      * Keystore type is PKCS11.
  177.      *
  178.      * @return the path to the PKCS11 library file
  179.      */
  180.     public String getPKCS11Library() {
  181.         return pkcs11Library;
  182.     }

  184.     /**
  185.      * Gets the custom SSLContext previously set with {@link ConnectionConfiguration.Builder#setCustomSSLContext(SSLContext)} for
  186.      * SSL sockets. This is null by default.
  187.      *
  188.      * @return the custom SSLContext or null.
  189.      */
  190.     public SSLContext getCustomSSLContext() {
  191.         return this.customSSLContext;
  192.     }

  194.     /**
  195.      * Return the enabled SSL/TLS protocols.
  196.      *
  197.      * @return the enabled SSL/TLS protocols
  198.      */
  199.     public String[] getEnabledSSLProtocols() {
  200.         return enabledSSLProtocols;
  201.     }

  203.     /**
  204.      * Return the enabled SSL/TLS ciphers.
  205.      *
  206.      * @return the enabled SSL/TLS ciphers
  207.      */
  208.     public String[] getEnabledSSLCiphers() {
  209.         return enabledSSLCiphers;
  210.     }

  212.     /**
  213.      * Returns the configured HostnameVerifier of this ConnectionConfiguration or the Smack default
  214.      * HostnameVerifier configured with
  215.      * {@link SmackConfiguration#setDefaultHostnameVerifier(HostnameVerifier)}.
  216.      * 
  217.      * @return a configured HostnameVerifier or <code>null</code>
  218.      */
  219.     public HostnameVerifier getHostnameVerifier() {
  220.         if (hostnameVerifier != null)
  221.             return hostnameVerifier;
  222.         return SmackConfiguration.getDefaultHostnameVerifier();
  223.     }

  225.     /**
  226.      * Returns true if the new connection about to be establish is going to be debugged. By
  227.      * default the value of {@link SmackConfiguration#DEBUG} is used.
  228.      *
  229.      * @return true if the new connection about to be establish is going to be debugged.
  230.      */
  231.     public boolean isDebuggerEnabled() {
  232.         return debuggerEnabled;
  233.     }

  235.     /**
  236.      * Returns true if a {@link Session} will be requested on login if the server
  237.      * supports it. Although this was mandatory on RFC 3921, RFC 6120/6121 don't
  238.      * even mention this part of the protocol.
  239.      *
  240.      * @return true if a session has to be requested when logging in.
  241.      * @deprecated Smack processes the 'optional' element of the session stream feature.
  242.      * @see Builder#setLegacySessionDisabled(boolean)
  243.      */
  244.     @Deprecated
  245.     public boolean isLegacySessionDisabled() {
  246.         return legacySessionDisabled;
  247.     }

  249.     /**
  250.      * Returns a CallbackHandler to obtain information, such as the password or
  251.      * principal information during the SASL authentication. A CallbackHandler
  252.      * will be used <b>ONLY</b> if no password was specified during the login while
  253.      * using SASL authentication.
  254.      *
  255.      * @return a CallbackHandler to obtain information, such as the password or
  256.      * principal information during the SASL authentication.
  257.      */
  258.     public CallbackHandler getCallbackHandler() {
  259.         return callbackHandler;
  260.     }

  262.     /**
  263.      * Returns the socket factory used to create new xmppConnection sockets.
  264.      * This is useful when connecting through SOCKS5 proxies.
  265.      * 
  266.      * @return socketFactory used to create new sockets.
  267.      */
  268.     public SocketFactory getSocketFactory() {
  269.         return this.socketFactory;
  270.     }

  272.     /**
  273.      * An enumeration for TLS security modes that are available when making a connection
  274.      * to the XMPP server.
  275.      */
  276.     public static enum SecurityMode {

  278.         /**
  279.          * Securirty via TLS encryption is required in order to connect. If the server
  280.          * does not offer TLS or if the TLS negotiaton fails, the connection to the server
  281.          * will fail.
  282.          */
  283.         required,

  285.         /**
  286.          * Security via TLS encryption is used whenever it's available. This is the
  287.          * default setting.
  288.          * <p>
  289.          * <b>Do not use this setting</b> unless you can't use {@link #required}. An attacker could easily perform a
  290.          * Man-in-the-middle attack and prevent TLS from being used, leaving you with an unencrypted (and
  291.          * unauthenticated) connection.
  292.          * </p>
  293.          */
  294.         ifpossible,

  296.         /**
  297.          * Security via TLS encryption is disabled and only un-encrypted connections will
  298.          * be used. If only TLS encryption is available from the server, the connection
  299.          * will fail.
  300.          */
  301.         disabled
  302.     }

  304.     /**
  305.      * Returns the username to use when trying to reconnect to the server.
  306.      *
  307.      * @return the username to use when trying to reconnect to the server.
  308.      */
  309.     public CharSequence getUsername() {
  310.         return this.username;
  311.     }

  313.     /**
  314.      * Returns the password to use when trying to reconnect to the server.
  315.      *
  316.      * @return the password to use when trying to reconnect to the server.
  317.      */
  318.     public String getPassword() {
  319.         return this.password;
  320.     }

  322.     /**
  323.      * Returns the resource to use when trying to reconnect to the server.
  324.      *
  325.      * @return the resource to use when trying to reconnect to the server.
  326.      */
  327.     public String getResource() {
  328.         return resource;
  329.     }

  331.     /**
  332.      * Returns true if an available presence should be sent when logging in while reconnecting.
  333.      *
  334.      * @return true if an available presence should be sent when logging in while reconnecting
  335.      */
  336.     public boolean isSendPresence() {
  337.         return sendPresence;
  338.     }

  340.     /**
  341.      * Returns true if the connection is going to use stream compression. Stream compression
  342.      * will be requested after TLS was established (if TLS was enabled) and only if the server
  343.      * offered stream compression. With stream compression network traffic can be reduced
  344.      * up to 90%. By default compression is disabled.
  345.      *
  346.      * @return true if the connection is going to use stream compression.
  347.      */
  348.     public boolean isCompressionEnabled() {
  349.         // Compression for non-TCP connections is always disabled
  350.         return false;
  351.     }

  353.     /**
  354.      * A builder for XMPP connection configurations.
  355.      * <p>
  356.      * This is an abstract class that uses the builder design pattern and the "getThis() trick" to recover the type of
  357.      * the builder in a class hierarchies with a self-referential generic supertype. Otherwise chaining of build
  358.      * instructions from the superclasses followed by build instructions of a sublcass would not be possible, because
  359.      * the superclass build instructions would return the builder of the superclass and not the one of the subclass. You
  360.      * can read more about it a Angelika Langer's Generics FAQ, especially the entry <a
  361.      * href="http://www.angelikalanger.com/GenericsFAQ/FAQSections/ProgrammingIdioms.html#FAQ206">What is the
  362.      * "getThis()" trick?</a>.
  363.      * </p>
  364.      *
  365.      * @param <B> the builder type parameter.
  366.      * @param <C> the resulting connection configuration type parameter.
  367.      */
  368.     public static abstract class Builder<B extends Builder<B, C>, C extends ConnectionConfiguration> {
  369.         private SecurityMode securityMode = SecurityMode.ifpossible;
  370.         private String keystorePath = System.getProperty("javax.net.ssl.keyStore");
  371.         private String keystoreType = "jks";
  372.         private String pkcs11Library = "pkcs11.config";
  373.         private SSLContext customSSLContext;
  374.         private String[] enabledSSLProtocols;
  375.         private String[] enabledSSLCiphers;
  376.         private HostnameVerifier hostnameVerifier;
  377.         private CharSequence username;
  378.         private String password;
  379.         private String resource = "Smack";
  380.         private boolean sendPresence = true;
  381.         private boolean legacySessionDisabled = false;
  382.         private ProxyInfo proxy;
  383.         private CallbackHandler callbackHandler;
  384.         private boolean debuggerEnabled = SmackConfiguration.DEBUG;
  385.         private SocketFactory socketFactory;
  386.         private DomainBareJid serviceName;
  387.         private String host;
  388.         private int port = 5222;
  389.         private boolean allowEmptyOrNullUsername = false;

  391.         protected Builder() {
  392.         }

  394.         /**
  395.          * Set the XMPP entities username and password.
  396.          * <p>
  397.          * The username is usually the localpart of the clients JID. But some SASL mechanisms or services may require a different
  398.          * format (e.g. the full JID) as used authorization identity.
  399.          * </p>
  400.          *
  401.          * @param username the username or authorization identity
  402.          * @param password the password or token used to authenticate
  403.          * @return a reference to this builder.
  404.          */
  405.         public B setUsernameAndPassword(CharSequence username, String password) {
  406.             this.username = username;
  407.             this.password = password;
  408.             return getThis();
  409.         }

  411.         /**
  412.          * Set the service name of this XMPP service (i.e., the XMPP domain).
  413.          *
  414.          * @param serviceName the service name
  415.          * @return a reference to this builder.
  416.          */
  417.         public B setServiceName(DomainBareJid serviceName) {
  418.             this.serviceName = serviceName;
  419.             return getThis();
  420.         }

  422.         /**
  423.          * Set the resource to use.
  424.          * <p>
  425.          * If <code>resource</code> is <code>null</code>, then the server will automatically create a resource for the
  426.          * client. Default resource is "Smack".
  427.          * </p>
  428.          *
  429.          * @param resource the resource to use.
  430.          * @return a reference to this builder.
  431.          */
  432.         public B setResource(String resource) {
  433.             this.resource = resource;
  434.             return getThis();
  435.         }

  437.         public B setHost(String host) {
  438.             this.host = host;
  439.             return getThis();
  440.         }

  442.         public B setPort(int port) {
  443.             this.port = port;
  444.             return getThis();
  445.         }

  447.         /**
  448.          * Sets a CallbackHandler to obtain information, such as the password or
  449.          * principal information during the SASL authentication. A CallbackHandler
  450.          * will be used <b>ONLY</b> if no password was specified during the login while
  451.          * using SASL authentication.
  452.          *
  453.          * @param callbackHandler to obtain information, such as the password or
  454.          * principal information during the SASL authentication.
  455.          * @return a reference to this builder.
  456.          */
  457.         public B setCallbackHandler(CallbackHandler callbackHandler) {
  458.             this.callbackHandler = callbackHandler;
  459.             return getThis();
  460.         }

  462.         /**
  463.          * Sets the TLS security mode used when making the connection. By default,
  464.          * the mode is {@link SecurityMode#ifpossible}.
  465.          *
  466.          * @param securityMode the security mode.
  467.          * @return a reference to this builder.
  468.          */
  469.         public B setSecurityMode(SecurityMode securityMode) {
  470.             this.securityMode = securityMode;
  471.             return getThis();
  472.         }

  474.         /**
  475.          * Sets the path to the keystore file. The key store file contains the 
  476.          * certificates that may be used to authenticate the client to the server,
  477.          * in the event the server requests or requires it.
  478.          *
  479.          * @param keystorePath the path to the keystore file.
  480.          * @return a reference to this builder.
  481.          */
  482.         public B setKeystorePath(String keystorePath) {
  483.             this.keystorePath = keystorePath;
  484.             return getThis();
  485.         }

  487.         /**
  488.          * Sets the keystore type.
  489.          *
  490.          * @param keystoreType the keystore type.
  491.          * @return a reference to this builder.
  492.          */
  493.         public B setKeystoreType(String keystoreType) {
  494.             this.keystoreType = keystoreType;
  495.             return getThis();
  496.         }

  498.         /**
  499.          * Sets the PKCS11 library file location, needed when the
  500.          * Keystore type is PKCS11
  501.          *
  502.          * @param pkcs11Library the path to the PKCS11 library file.
  503.          * @return a reference to this builder.
  504.          */
  505.         public B setPKCS11Library(String pkcs11Library) {
  506.             this.pkcs11Library = pkcs11Library;
  507.             return getThis();
  508.         }

  510.         /**
  511.          * Sets a custom SSLContext for creating SSL sockets.
  512.          * <p>
  513.          * For more information on how to create a SSLContext see <a href=
  514.          * "http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#X509TrustManager"
  515.          * >Java Secure Socket Extension (JSEE) Reference Guide: Creating Your Own X509TrustManager</a>
  516.          *
  517.          * @param context the custom SSLContext for new sockets.
  518.          * @return a reference to this builder.
  519.          */
  520.         public B setCustomSSLContext(SSLContext context) {
  521.             this.customSSLContext = context;
  522.             return getThis();
  523.         }

  525.         /**
  526.          * Set the enabled SSL/TLS protocols.
  527.          *
  528.          * @param enabledSSLProtocols
  529.          * @return a reference to this builder.
  530.          */
  531.         public B setEnabledSSLProtocols(String[] enabledSSLProtocols) {
  532.             this.enabledSSLProtocols = enabledSSLProtocols;
  533.             return getThis();
  534.         }

  536.         /**
  537.          * Set the enabled SSL/TLS ciphers.
  538.          * 
  539.          * @param enabledSSLCiphers the enabled SSL/TLS ciphers 
  540.          * @return a reference to this builder.
  541.          */
  542.         public B setEnabledSSLCiphers(String[] enabledSSLCiphers) {
  543.             this.enabledSSLCiphers = enabledSSLCiphers;
  544.             return getThis();
  545.         }

  547.         /**
  548.          * Set the HostnameVerifier used to verify the hostname of SSLSockets used by XMPP connections
  549.          * created with this ConnectionConfiguration.
  550.          * 
  551.          * @param verifier
  552.          * @return a reference to this builder.
  553.          */
  554.         public B setHostnameVerifier(HostnameVerifier verifier) {
  555.             hostnameVerifier = verifier;
  556.             return getThis();
  557.         }

  559.         /**
  560.          * Sets if a {@link Session} will be requested on login if the server supports
  561.          * it. Although this was mandatory on RFC 3921, RFC 6120/6121 don't even
  562.          * mention this part of the protocol.
  563.          * <p>
  564.          * Deprecation notice: This setting is no longer required in most cases because Smack processes the 'optional'
  565.          * element eventually found in the session stream feature. See also <a
  566.          * href="https://tools.ietf.org/html/draft-cridland-xmpp-session-01">Here Lies Extensible Messaging and Presence
  567.          * Protocol (XMPP) Session Establishment</a>
  568.          * </p>
  569.          *
  570.          * @param legacySessionDisabled if a session has to be requested when logging in.
  571.          * @return a reference to this builder.
  572.          * @deprecated Smack processes the 'optional' element of the session stream feature.
  573.          */
  574.         @Deprecated
  575.         public B setLegacySessionDisabled(boolean legacySessionDisabled) {
  576.             this.legacySessionDisabled = legacySessionDisabled;
  577.             return getThis();
  578.         }

  580.         /**
  581.          * Sets if an initial available presence will be sent to the server. By default
  582.          * an available presence will be sent to the server indicating that this presence
  583.          * is not online and available to receive messages. If you want to log in without
  584.          * being 'noticed' then pass a <tt>false</tt> value.
  585.          *
  586.          * @param sendPresence true if an initial available presence will be sent while logging in.
  587.          * @return a reference to this builder.
  588.          */
  589.         public B setSendPresence(boolean sendPresence) {
  590.             this.sendPresence = sendPresence;
  591.             return getThis();
  592.         }

  594.         /**
  595.          * Sets if the new connection about to be establish is going to be debugged. By
  596.          * default the value of {@link SmackConfiguration#DEBUG} is used.
  597.          *
  598.          * @param debuggerEnabled if the new connection about to be establish is going to be debugged.
  599.          * @return a reference to this builder.
  600.          */
  601.         public B setDebuggerEnabled(boolean debuggerEnabled) {
  602.             this.debuggerEnabled = debuggerEnabled;
  603.             return getThis();
  604.         }

  606.         /**
  607.          * Sets the socket factory used to create new xmppConnection sockets.
  608.          * This is useful when connecting through SOCKS5 proxies.
  609.          *
  610.          * @param socketFactory used to create new sockets.
  611.          * @return a reference to this builder.
  612.          */
  613.         public B setSocketFactory(SocketFactory socketFactory) {
  614.             this.socketFactory = socketFactory;
  615.             return getThis();
  616.         }

  618.         /**
  619.          * Allow <code>null</code> or the empty String as username.
  620.          *
  621.          * Some SASL mechanisms (e.g. SASL External) may also signal the username (as "authorization identity"), in
  622.          * which case Smack should not throw an IllegalArgumentException when the username is not set.
  623.          * 
  624.          * @return a reference to this builder.
  625.          */
  626.         public B allowEmptyOrNullUsernames() {
  627.             allowEmptyOrNullUsername = true;
  628.             return getThis();
  629.         }

  631.         public abstract C build();

  633.         protected abstract B getThis();
  634.     }
  635. }
Created with JaCoCo 0.7.4.201502262128