001/**
002 *
003 * Copyright 2003-2007 Jive Software.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.jivesoftware.smack;
019
020import java.net.InetAddress;
021import java.util.Arrays;
022import java.util.Collection;
023import java.util.Collections;
024import java.util.HashSet;
025import java.util.Set;
026
027import org.jivesoftware.smack.packet.Session;
028import org.jivesoftware.smack.proxy.ProxyInfo;
029import org.jivesoftware.smack.sasl.SASLMechanism;
030import org.jivesoftware.smack.sasl.core.SASLAnonymous;
031import org.jivesoftware.smack.util.CollectionUtil;
032import org.jivesoftware.smack.util.Objects;
033import org.jivesoftware.smack.util.StringUtils;
034import org.jxmpp.jid.DomainBareJid;
035import org.jxmpp.jid.EntityBareJid;
036import org.jxmpp.jid.impl.JidCreate;
037import org.jxmpp.jid.parts.Resourcepart;
038import org.jxmpp.stringprep.XmppStringprepException;
039
040import javax.net.SocketFactory;
041import javax.net.ssl.HostnameVerifier;
042import javax.net.ssl.SSLContext;
043import javax.net.ssl.X509TrustManager;
044import javax.security.auth.callback.CallbackHandler;
045
046/**
047 * Configuration to use while establishing the connection to the server.
048 *
049 * @author Gaston Dombiak
050 */
051public abstract class ConnectionConfiguration {
052
053    static {
054        // Ensure that Smack is initialized when ConnectionConfiguration is used, or otherwise e.g.
055        // SmackConfiguration.DEBUG may not be initialized yet.
056        SmackConfiguration.getVersion();
057    }
058
059    /**
060     * The XMPP domain of the XMPP Service. Usually servers use the same service name as the name
061     * of the server. However, there are some servers like google where host would be
062     * talk.google.com and the serviceName would be gmail.com.
063     */
064    protected final DomainBareJid xmppServiceDomain;
065
066    protected final InetAddress hostAddress;
067    protected final String host;
068    protected final int port;
069
070    private final String keystorePath;
071    private final String keystoreType;
072    private final String pkcs11Library;
073    private final SSLContext customSSLContext;
074
075    /**
076     * Used to get information from the user
077     */
078    private final CallbackHandler callbackHandler;
079
080    private final boolean debuggerEnabled;
081
082    // Holds the socket factory that is used to generate the socket in the connection
083    private final SocketFactory socketFactory;
084
085    private final CharSequence username;
086    private final String password;
087    private final Resourcepart resource;
088
089    /**
090     * The optional SASL authorization identity (see RFC 6120 § 6.3.8).
091     */
092    private final EntityBareJid authzid;
093
094    /**
095     * Initial presence as of RFC 6121 § 4.2
096     * @see <a href="http://xmpp.org/rfcs/rfc6121.html#presence-initial">RFC 6121 § 4.2 Initial Presence</a>
097     */
098    private final boolean sendPresence;
099
100    private final boolean legacySessionDisabled;
101    private final SecurityMode securityMode;
102
103    private final DnssecMode dnssecMode;
104
105    private final X509TrustManager customX509TrustManager;
106
107    /**
108     * 
109     */
110    private final String[] enabledSSLProtocols;
111
112    /**
113     * 
114     */
115    private final String[] enabledSSLCiphers;
116
117    private final HostnameVerifier hostnameVerifier;
118
119    // Holds the proxy information (such as proxyhost, proxyport, username, password etc)
120    protected final ProxyInfo proxy;
121
122    protected final boolean allowNullOrEmptyUsername;
123
124    private final Set<String> enabledSaslMechanisms;
125
126    protected ConnectionConfiguration(Builder<?,?> builder) {
127        authzid = builder.authzid;
128        username = builder.username;
129        password = builder.password;
130        callbackHandler = builder.callbackHandler;
131
132        // Resource can be null, this means that the server must provide one
133        resource = builder.resource;
134
135        xmppServiceDomain = builder.xmppServiceDomain;
136        if (xmppServiceDomain == null) {
137            throw new IllegalArgumentException("Must define the XMPP domain");
138        }
139        hostAddress = builder.hostAddress;
140        host = builder.host;
141        port = builder.port;
142
143        proxy = builder.proxy;
144        socketFactory = builder.socketFactory;
145
146        dnssecMode = builder.dnssecMode;
147
148        customX509TrustManager = builder.customX509TrustManager;
149
150        securityMode = builder.securityMode;
151        keystoreType = builder.keystoreType;
152        keystorePath = builder.keystorePath;
153        pkcs11Library = builder.pkcs11Library;
154        customSSLContext = builder.customSSLContext;
155        enabledSSLProtocols = builder.enabledSSLProtocols;
156        enabledSSLCiphers = builder.enabledSSLCiphers;
157        hostnameVerifier = builder.hostnameVerifier;
158        sendPresence = builder.sendPresence;
159        legacySessionDisabled = builder.legacySessionDisabled;
160        debuggerEnabled = builder.debuggerEnabled;
161        allowNullOrEmptyUsername = builder.allowEmptyOrNullUsername;
162        enabledSaslMechanisms = builder.enabledSaslMechanisms;
163
164        // If the enabledSaslmechanisms are set, then they must not be empty
165        assert(enabledSaslMechanisms != null ? !enabledSaslMechanisms.isEmpty() : true);
166
167        if (dnssecMode != DnssecMode.disabled && customSSLContext != null) {
168            throw new IllegalStateException("You can not use a custom SSL context with DNSSEC enabled");
169        }
170
171    }
172
173    /**
174     * Returns the server name of the target server.
175     *
176     * @return the server name of the target server.
177     * @deprecated use {@link #getXMPPServiceDomain()} instead.
178     */
179    @Deprecated
180    public DomainBareJid getServiceName() {
181        return xmppServiceDomain;
182    }
183
184    /**
185     * Returns the XMPP domain used by this configuration.
186     *
187     * @return the XMPP domain.
188     */
189    public DomainBareJid getXMPPServiceDomain() {
190        return xmppServiceDomain;
191    }
192
193    /**
194     * Returns the TLS security mode used when making the connection. By default,
195     * the mode is {@link SecurityMode#ifpossible}.
196     *
197     * @return the security mode.
198     */
199    public SecurityMode getSecurityMode() {
200        return securityMode;
201    }
202
203    public DnssecMode getDnssecMode() {
204        return dnssecMode;
205    }
206
207    public X509TrustManager getCustomX509TrustManager() {
208        return customX509TrustManager;
209    }
210
211    /**
212     * Retuns the path to the keystore file. The key store file contains the 
213     * certificates that may be used to authenticate the client to the server,
214     * in the event the server requests or requires it.
215     *
216     * @return the path to the keystore file.
217     */
218    public String getKeystorePath() {
219        return keystorePath;
220    }
221
222    /**
223     * Returns the keystore type, or <tt>null</tt> if it's not set.
224     *
225     * @return the keystore type.
226     */
227    public String getKeystoreType() {
228        return keystoreType;
229    }
230
231    /**
232     * Returns the PKCS11 library file location, needed when the
233     * Keystore type is PKCS11.
234     *
235     * @return the path to the PKCS11 library file
236     */
237    public String getPKCS11Library() {
238        return pkcs11Library;
239    }
240
241    /**
242     * Gets the custom SSLContext previously set with {@link ConnectionConfiguration.Builder#setCustomSSLContext(SSLContext)} for
243     * SSL sockets. This is null by default.
244     *
245     * @return the custom SSLContext or null.
246     */
247    public SSLContext getCustomSSLContext() {
248        return this.customSSLContext;
249    }
250
251    /**
252     * Return the enabled SSL/TLS protocols.
253     *
254     * @return the enabled SSL/TLS protocols
255     */
256    public String[] getEnabledSSLProtocols() {
257        return enabledSSLProtocols;
258    }
259
260    /**
261     * Return the enabled SSL/TLS ciphers.
262     *
263     * @return the enabled SSL/TLS ciphers
264     */
265    public String[] getEnabledSSLCiphers() {
266        return enabledSSLCiphers;
267    }
268
269    /**
270     * Returns the configured HostnameVerifier of this ConnectionConfiguration or the Smack default
271     * HostnameVerifier configured with
272     * {@link SmackConfiguration#setDefaultHostnameVerifier(HostnameVerifier)}.
273     * 
274     * @return a configured HostnameVerifier or <code>null</code>
275     */
276    public HostnameVerifier getHostnameVerifier() {
277        if (hostnameVerifier != null)
278            return hostnameVerifier;
279        return SmackConfiguration.getDefaultHostnameVerifier();
280    }
281
282    /**
283     * Returns true if the new connection about to be establish is going to be debugged. By
284     * default the value of {@link SmackConfiguration#DEBUG} is used.
285     *
286     * @return true if the new connection about to be establish is going to be debugged.
287     */
288    public boolean isDebuggerEnabled() {
289        return debuggerEnabled;
290    }
291
292    /**
293     * Returns true if a {@link Session} will be requested on login if the server
294     * supports it. Although this was mandatory on RFC 3921, RFC 6120/6121 don't
295     * even mention this part of the protocol.
296     *
297     * @return true if a session has to be requested when logging in.
298     * @deprecated Smack processes the 'optional' element of the session stream feature.
299     * @see Builder#setLegacySessionDisabled(boolean)
300     */
301    @Deprecated
302    public boolean isLegacySessionDisabled() {
303        return legacySessionDisabled;
304    }
305
306    /**
307     * Returns a CallbackHandler to obtain information, such as the password or
308     * principal information during the SASL authentication. A CallbackHandler
309     * will be used <b>ONLY</b> if no password was specified during the login while
310     * using SASL authentication.
311     *
312     * @return a CallbackHandler to obtain information, such as the password or
313     * principal information during the SASL authentication.
314     */
315    public CallbackHandler getCallbackHandler() {
316        return callbackHandler;
317    }
318
319    /**
320     * Returns the socket factory used to create new xmppConnection sockets.
321     * This is useful when connecting through SOCKS5 proxies.
322     * 
323     * @return socketFactory used to create new sockets.
324     */
325    public SocketFactory getSocketFactory() {
326        return this.socketFactory;
327    }
328
329    /**
330     * Get the configured proxy information (if any).
331     *
332     * @return the configured proxy information or <code>null</code>.
333     */
334    public ProxyInfo getProxyInfo() {
335        return proxy;
336    }
337
338    /**
339     * An enumeration for TLS security modes that are available when making a connection
340     * to the XMPP server.
341     */
342    public static enum SecurityMode {
343
344        /**
345         * Security via TLS encryption is required in order to connect. If the server
346         * does not offer TLS or if the TLS negotiation fails, the connection to the server
347         * will fail.
348         */
349        required,
350
351        /**
352         * Security via TLS encryption is used whenever it's available. This is the
353         * default setting.
354         * <p>
355         * <b>Do not use this setting</b> unless you can't use {@link #required}. An attacker could easily perform a
356         * Man-in-the-middle attack and prevent TLS from being used, leaving you with an unencrypted (and
357         * unauthenticated) connection.
358         * </p>
359         */
360        ifpossible,
361
362        /**
363         * Security via TLS encryption is disabled and only un-encrypted connections will
364         * be used. If only TLS encryption is available from the server, the connection
365         * will fail.
366         */
367        disabled
368    }
369
370    /**
371     * Determines the requested DNSSEC security mode.
372     * <b>Note that Smack's support for DNSSEC/DANE is experimental!</b>
373     * <p>
374     * The default '{@link #disabled}' means that neither DNSSEC nor DANE verification will be performed. When
375     * '{@link #needsDnssec}' is used, then the connection will not be established if the resource records used to connect
376     * to the XMPP service are not authenticated by DNSSEC. Additionally, if '{@link #needsDnssecAndDane}' is used, then
377     * the XMPP service's TLS certificate is verified using DANE.
378     *
379     */
380    public enum DnssecMode {
381
382        /**
383         * Do not perform any DNSSEC authentication or DANE verification.
384         */
385        disabled,
386
387        /**
388         * <b>Experimental!</b>
389         * Require all DNS information to be authenticated by DNSSEC.
390         */
391        needsDnssec,
392
393        /**
394         * <b>Experimental!</b>
395         * Require all DNS information to be authenticated by DNSSEC and require the XMPP service's TLS certificate to be verified using DANE.
396         */
397        needsDnssecAndDane,
398
399    }
400
401    /**
402     * Returns the username to use when trying to reconnect to the server.
403     *
404     * @return the username to use when trying to reconnect to the server.
405     */
406    public CharSequence getUsername() {
407        return this.username;
408    }
409
410    /**
411     * Returns the password to use when trying to reconnect to the server.
412     *
413     * @return the password to use when trying to reconnect to the server.
414     */
415    public String getPassword() {
416        return this.password;
417    }
418
419    /**
420     * Returns the resource to use when trying to reconnect to the server.
421     *
422     * @return the resource to use when trying to reconnect to the server.
423     */
424    public Resourcepart getResource() {
425        return resource;
426    }
427
428    /**
429     * Returns the optional XMPP address to be requested as the SASL authorization identity.
430     * 
431     * @return the authorization identifier.
432     * @see <a href="http://tools.ietf.org/html/rfc6120#section-6.3.8">RFC 6120 § 6.3.8. Authorization Identity</a>
433     * @since 4.2
434     */
435    public EntityBareJid getAuthzid() {
436        return authzid;
437    }
438
439    /**
440     * Returns true if an available presence should be sent when logging in while reconnecting.
441     *
442     * @return true if an available presence should be sent when logging in while reconnecting
443     */
444    public boolean isSendPresence() {
445        return sendPresence;
446    }
447
448    /**
449     * Returns true if the connection is going to use stream compression. Stream compression
450     * will be requested after TLS was established (if TLS was enabled) and only if the server
451     * offered stream compression. With stream compression network traffic can be reduced
452     * up to 90%. By default compression is disabled.
453     *
454     * @return true if the connection is going to use stream compression.
455     */
456    public boolean isCompressionEnabled() {
457        // Compression for non-TCP connections is always disabled
458        return false;
459    }
460
461    /**
462     * Check if the given SASL mechansism is enabled in this connection configuration.
463     *
464     * @param saslMechanism
465     * @return true if the given SASL mechanism is enabled, false otherwise.
466     */
467    public boolean isEnabledSaslMechanism(String saslMechanism) {
468        // If enabledSaslMechanisms is not set, then all mechanisms which are not blacklisted are enabled per default.
469        if (enabledSaslMechanisms == null) {
470            return !SASLAuthentication.getBlacklistedSASLMechanisms().contains(saslMechanism);
471        }
472        return enabledSaslMechanisms.contains(saslMechanism);
473    }
474
475    public Set<String> getEnabledSaslMechanisms() {
476        return Collections.unmodifiableSet(enabledSaslMechanisms);
477    }
478
479    /**
480     * A builder for XMPP connection configurations.
481     * <p>
482     * This is an abstract class that uses the builder design pattern and the "getThis() trick" to recover the type of
483     * the builder in a class hierarchies with a self-referential generic supertype. Otherwise chaining of build
484     * instructions from the superclasses followed by build instructions of a sublcass would not be possible, because
485     * the superclass build instructions would return the builder of the superclass and not the one of the subclass. You
486     * can read more about it a Angelika Langer's Generics FAQ, especially the entry <a
487     * href="http://www.angelikalanger.com/GenericsFAQ/FAQSections/ProgrammingIdioms.html#FAQ206">What is the
488     * "getThis()" trick?</a>.
489     * </p>
490     *
491     * @param <B> the builder type parameter.
492     * @param <C> the resulting connection configuration type parameter.
493     */
494    public static abstract class Builder<B extends Builder<B, C>, C extends ConnectionConfiguration> {
495        private SecurityMode securityMode = SecurityMode.ifpossible;
496        private DnssecMode dnssecMode = DnssecMode.disabled;
497        private String keystorePath = System.getProperty("javax.net.ssl.keyStore");
498        private String keystoreType = "jks";
499        private String pkcs11Library = "pkcs11.config";
500        private SSLContext customSSLContext;
501        private String[] enabledSSLProtocols;
502        private String[] enabledSSLCiphers;
503        private HostnameVerifier hostnameVerifier;
504        private EntityBareJid authzid;
505        private CharSequence username;
506        private String password;
507        private Resourcepart resource;
508        private boolean sendPresence = true;
509        private boolean legacySessionDisabled = false;
510        private ProxyInfo proxy;
511        private CallbackHandler callbackHandler;
512        private boolean debuggerEnabled = SmackConfiguration.DEBUG;
513        private SocketFactory socketFactory;
514        private DomainBareJid xmppServiceDomain;
515        private InetAddress hostAddress;
516        private String host;
517        private int port = 5222;
518        private boolean allowEmptyOrNullUsername = false;
519        private boolean saslMechanismsSealed;
520        private Set<String> enabledSaslMechanisms;
521        private X509TrustManager customX509TrustManager;
522
523        protected Builder() {
524        }
525
526        /**
527         * Set the XMPP entities username and password.
528         * <p>
529         * The username is usually the localpart of the clients JID. But some SASL mechanisms or services may require a different
530         * format (e.g. the full JID) as used authorization identity.
531         * </p>
532         *
533         * @param username the username or authorization identity
534         * @param password the password or token used to authenticate
535         * @return a reference to this builder.
536         */
537        public B setUsernameAndPassword(CharSequence username, String password) {
538            this.username = username;
539            this.password = password;
540            return getThis();
541        }
542
543        /**
544         * Set the XMPP domain. The XMPP domain is what follows after the '@' sign in XMPP addresses (JIDs).
545         *
546         * @param serviceName the service name
547         * @return a reference to this builder.
548         * @deprecated use {@link #setXmppDomain(DomainBareJid)} instead.
549         */
550        @Deprecated
551        public B setServiceName(DomainBareJid serviceName) {
552            return setXmppDomain(serviceName);
553        }
554
555        /**
556         * Set the XMPP domain. The XMPP domain is what follows after the '@' sign in XMPP addresses (JIDs).
557         *
558         * @param xmppDomain the XMPP domain.
559         * @return a reference to this builder.
560         */
561        public B setXmppDomain(DomainBareJid xmppDomain) {
562            this.xmppServiceDomain = xmppDomain;
563            return getThis();
564        }
565
566        /**
567         * Set the XMPP domain. The XMPP domain is what follows after the '@' sign in XMPP addresses (JIDs).
568         *
569         * @param xmppServiceDomain the XMPP domain.
570         * @return a reference to this builder.
571         * @throws XmppStringprepException if the given string is not a domain bare JID.
572         */
573        public B setXmppDomain(String xmppServiceDomain) throws XmppStringprepException {
574            this.xmppServiceDomain = JidCreate.domainBareFrom(xmppServiceDomain);
575            return getThis();
576        }
577
578        /**
579         * Set the resource we are requesting from the server.
580         * <p>
581         * If <code>resource</code> is <code>null</code>, the default, then the server will automatically create a
582         * resource for the client. Note that XMPP clients only suggest this resource to the server. XMPP servers are
583         * allowed to ignore the client suggested resource and instead assign a completely different
584         * resource (see RFC 6120 § 7.7.1).
585         * </p>
586         *
587         * @param resource the resource to use.
588         * @return a reference to this builder.
589         * @see <a href="https://tools.ietf.org/html/rfc6120#section-7.7.1">RFC 6120 § 7.7.1</a>
590         */
591        public B setResource(Resourcepart resource) {
592            this.resource = resource;
593            return getThis();
594        }
595
596        /**
597         * Set the resource we are requesting from the server.
598         *
599         * @param resource the non-null CharSequence to use a resource.
600         * @return a reference ot this builder.
601         * @throws XmppStringprepException if the CharSequence is not a valid resourcepart.
602         * @see #setResource(Resourcepart)
603         */
604        public B setResource(CharSequence resource) throws XmppStringprepException {
605            Objects.requireNonNull(resource, "resource must not be null");
606            return setResource(Resourcepart.from(resource.toString()));
607        }
608
609        /**
610         * Set the Internet address of the host providing the XMPP service. If set, then this will overwrite anything
611         * set via {@link #setHost(String)}.
612         *
613         * @param address the Internet address of the host providing the XMPP service.
614         * @return a reference to this builder.
615         * @since 4.2
616         */
617        public B setHostAddress(InetAddress address) {
618            this.hostAddress = address;
619            return getThis();
620        }
621
622        /**
623         * Set the name of the host providing the XMPP service. Note that this method does only allow DNS names and not
624         * IP addresses. Use {@link #setHostAddress(InetAddress)} if you want to explicitly set the Internet address of
625         * the host providing the XMPP service.
626         *
627         * @param host the DNS name of the host providing the XMPP service.
628         * @return a reference to this builder.
629         */
630        public B setHost(String host) {
631            this.host = host;
632            return getThis();
633        }
634
635        public B setPort(int port) {
636            if (port < 0 || port > 65535) {
637                throw new IllegalArgumentException(
638                        "Port must be a 16-bit unsiged integer (i.e. between 0-65535. Port was: " + port);
639            }
640            this.port = port;
641            return getThis();
642        }
643
644        /**
645         * Sets a CallbackHandler to obtain information, such as the password or
646         * principal information during the SASL authentication. A CallbackHandler
647         * will be used <b>ONLY</b> if no password was specified during the login while
648         * using SASL authentication.
649         *
650         * @param callbackHandler to obtain information, such as the password or
651         * principal information during the SASL authentication.
652         * @return a reference to this builder.
653         */
654        public B setCallbackHandler(CallbackHandler callbackHandler) {
655            this.callbackHandler = callbackHandler;
656            return getThis();
657        }
658
659        public B setDnssecMode(DnssecMode dnssecMode) {
660            this.dnssecMode = Objects.requireNonNull(dnssecMode, "DNSSEC mode must not be null");
661            return getThis();
662        }
663
664        public B setCustomX509TrustManager(X509TrustManager x509TrustManager) {
665            this.customX509TrustManager = x509TrustManager;
666            return getThis();
667        }
668
669        /**
670         * Sets the TLS security mode used when making the connection. By default,
671         * the mode is {@link SecurityMode#ifpossible}.
672         *
673         * @param securityMode the security mode.
674         * @return a reference to this builder.
675         */
676        public B setSecurityMode(SecurityMode securityMode) {
677            this.securityMode = securityMode;
678            return getThis();
679        }
680
681        /**
682         * Sets the path to the keystore file. The key store file contains the 
683         * certificates that may be used to authenticate the client to the server,
684         * in the event the server requests or requires it.
685         *
686         * @param keystorePath the path to the keystore file.
687         * @return a reference to this builder.
688         */
689        public B setKeystorePath(String keystorePath) {
690            this.keystorePath = keystorePath;
691            return getThis();
692        }
693
694        /**
695         * Sets the keystore type.
696         *
697         * @param keystoreType the keystore type.
698         * @return a reference to this builder.
699         */
700        public B setKeystoreType(String keystoreType) {
701            this.keystoreType = keystoreType;
702            return getThis();
703        }
704
705        /**
706         * Sets the PKCS11 library file location, needed when the
707         * Keystore type is PKCS11.
708         *
709         * @param pkcs11Library the path to the PKCS11 library file.
710         * @return a reference to this builder.
711         */
712        public B setPKCS11Library(String pkcs11Library) {
713            this.pkcs11Library = pkcs11Library;
714            return getThis();
715        }
716
717        /**
718         * Sets a custom SSLContext for creating SSL sockets.
719         * <p>
720         * For more information on how to create a SSLContext see <a href=
721         * "http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#X509TrustManager"
722         * >Java Secure Socket Extension (JSEE) Reference Guide: Creating Your Own X509TrustManager</a>
723         *
724         * @param context the custom SSLContext for new sockets.
725         * @return a reference to this builder.
726         */
727        public B setCustomSSLContext(SSLContext context) {
728            this.customSSLContext = Objects.requireNonNull(context, "The SSLContext must not be null");
729            return getThis();
730        }
731
732        /**
733         * Set the enabled SSL/TLS protocols.
734         *
735         * @param enabledSSLProtocols
736         * @return a reference to this builder.
737         */
738        public B setEnabledSSLProtocols(String[] enabledSSLProtocols) {
739            this.enabledSSLProtocols = enabledSSLProtocols;
740            return getThis();
741        }
742
743        /**
744         * Set the enabled SSL/TLS ciphers.
745         * 
746         * @param enabledSSLCiphers the enabled SSL/TLS ciphers 
747         * @return a reference to this builder.
748         */
749        public B setEnabledSSLCiphers(String[] enabledSSLCiphers) {
750            this.enabledSSLCiphers = enabledSSLCiphers;
751            return getThis();
752        }
753
754        /**
755         * Set the HostnameVerifier used to verify the hostname of SSLSockets used by XMPP connections
756         * created with this ConnectionConfiguration.
757         * 
758         * @param verifier
759         * @return a reference to this builder.
760         */
761        public B setHostnameVerifier(HostnameVerifier verifier) {
762            hostnameVerifier = verifier;
763            return getThis();
764        }
765
766        /**
767         * Sets if a {@link Session} will be requested on login if the server supports
768         * it. Although this was mandatory on RFC 3921, RFC 6120/6121 don't even
769         * mention this part of the protocol.
770         * <p>
771         * Deprecation notice: This setting is no longer required in most cases because Smack processes the 'optional'
772         * element eventually found in the session stream feature. See also <a
773         * href="https://tools.ietf.org/html/draft-cridland-xmpp-session-01">Here Lies Extensible Messaging and Presence
774         * Protocol (XMPP) Session Establishment</a>
775         * </p>
776         *
777         * @param legacySessionDisabled if a session has to be requested when logging in.
778         * @return a reference to this builder.
779         * @deprecated Smack processes the 'optional' element of the session stream feature.
780         */
781        @Deprecated
782        public B setLegacySessionDisabled(boolean legacySessionDisabled) {
783            this.legacySessionDisabled = legacySessionDisabled;
784            return getThis();
785        }
786
787        /**
788         * Sets if an initial available presence will be sent to the server. By default
789         * an available presence will be sent to the server indicating that this presence
790         * is not online and available to receive messages. If you want to log in without
791         * being 'noticed' then pass a <tt>false</tt> value.
792         *
793         * @param sendPresence true if an initial available presence will be sent while logging in.
794         * @return a reference to this builder.
795         */
796        public B setSendPresence(boolean sendPresence) {
797            this.sendPresence = sendPresence;
798            return getThis();
799        }
800
801        /**
802         * Sets if the new connection about to be establish is going to be debugged. By
803         * default the value of {@link SmackConfiguration#DEBUG} is used.
804         *
805         * @param debuggerEnabled if the new connection about to be establish is going to be debugged.
806         * @return a reference to this builder.
807         */
808        public B setDebuggerEnabled(boolean debuggerEnabled) {
809            this.debuggerEnabled = debuggerEnabled;
810            return getThis();
811        }
812
813        /**
814         * Sets the socket factory used to create new xmppConnection sockets.
815         * This is useful when connecting through SOCKS5 proxies.
816         *
817         * @param socketFactory used to create new sockets.
818         * @return a reference to this builder.
819         */
820        public B setSocketFactory(SocketFactory socketFactory) {
821            this.socketFactory = socketFactory;
822            return getThis();
823        }
824
825        /**
826         * Set the information about the Proxy used for the connection.
827         *
828         * @param proxyInfo the Proxy information.
829         * @return a reference to this builder.
830         */
831        public B setProxyInfo(ProxyInfo proxyInfo) {
832            this.proxy = proxyInfo;
833            return getThis();
834        }
835
836        /**
837         * Allow <code>null</code> or the empty String as username.
838         *
839         * Some SASL mechanisms (e.g. SASL External) may also signal the username (as "authorization identity"), in
840         * which case Smack should not throw an IllegalArgumentException when the username is not set.
841         * 
842         * @return a reference to this builder.
843         */
844        public B allowEmptyOrNullUsernames() {
845            allowEmptyOrNullUsername = true;
846            return getThis();
847        }
848
849        /**
850         * Perform anonymous authentication using SASL ANONYMOUS. Your XMPP service must support this authentication
851         * mechanism. This method also calls {@link #addEnabledSaslMechanism(String)} with "ANONYMOUS" as argument.
852         * 
853         * @return a reference to this builder.
854         */
855        public B performSaslAnonymousAuthentication() {
856            if (!SASLAuthentication.isSaslMechanismRegistered(SASLAnonymous.NAME)) {
857                throw new IllegalArgumentException("SASL " + SASLAnonymous.NAME + " is not registered");
858            }
859            throwIfEnabledSaslMechanismsSet();
860
861            allowEmptyOrNullUsernames();
862            addEnabledSaslMechanism(SASLAnonymous.NAME);
863            saslMechanismsSealed = true;
864            return getThis();
865        }
866
867        /**
868         * Perform authentication using SASL EXTERNAL. Your XMPP service must support this
869         * authentication mechanism. This method also calls {@link #addEnabledSaslMechanism(String)} with "EXTERNAL" as
870         * argument. It also calls {@link #allowEmptyOrNullUsernames()} and {@link #setSecurityMode(ConnectionConfiguration.SecurityMode)} to
871         * {@link SecurityMode#required}.
872         *
873         * @return a reference to this builder.
874         */
875        public B performSaslExternalAuthentication(SSLContext sslContext) {
876            if (!SASLAuthentication.isSaslMechanismRegistered(SASLMechanism.EXTERNAL)) {
877                throw new IllegalArgumentException("SASL " + SASLMechanism.EXTERNAL + " is not registered");
878            }
879            setCustomSSLContext(sslContext);
880            throwIfEnabledSaslMechanismsSet();
881
882            allowEmptyOrNullUsernames();
883            setSecurityMode(SecurityMode.required);
884            addEnabledSaslMechanism(SASLMechanism.EXTERNAL);
885            saslMechanismsSealed = true;
886            return getThis();
887        }
888
889        private void throwIfEnabledSaslMechanismsSet() {
890            if (enabledSaslMechanisms != null) {
891                throw new IllegalStateException("Enabled SASL mechanisms found");
892            }
893        }
894
895        /**
896         * Add the given mechanism to the enabled ones. See {@link #addEnabledSaslMechanism(Collection)} for a discussion about enabled SASL mechanisms.
897         *
898         * @param saslMechanism the name of the mechanism to enable.
899         * @return a reference to this builder.
900         */
901        public B addEnabledSaslMechanism(String saslMechanism) {
902            return addEnabledSaslMechanism(Arrays.asList(StringUtils.requireNotNullOrEmpty(saslMechanism,
903                            "saslMechanism must not be null or empty")));
904        }
905
906        /**
907         * Enable the given SASL mechanisms. If you never add a mechanism to the set of enabled ones, <b>all mechanisms
908         * known to Smack</b> will be enabled. Only explicitly enable particular SASL mechanisms if you want to limit
909         * the used mechanisms to the enabled ones.
910         * 
911         * @param saslMechanisms a collection of names of mechanisms to enable.
912         * @return a reference to this builder.
913         */
914        public B addEnabledSaslMechanism(Collection<String> saslMechanisms) {
915            if (saslMechanismsSealed) {
916                throw new IllegalStateException("The enabled SASL mechanisms are sealed, you can not add new ones");
917            }
918            CollectionUtil.requireNotEmpty(saslMechanisms, "saslMechanisms");
919            Set<String> blacklistedMechanisms = SASLAuthentication.getBlacklistedSASLMechanisms();
920            for (String mechanism : saslMechanisms) {
921                if (!SASLAuthentication.isSaslMechanismRegistered(mechanism)) {
922                    throw new IllegalArgumentException("SASL " + mechanism + " is not avaiable. Consider registering it with Smack");
923                }
924                if (blacklistedMechanisms.contains(mechanism)) {
925                    throw new IllegalArgumentException("SALS " + mechanism + " is blacklisted.");
926                }
927            }
928            if (enabledSaslMechanisms == null) {
929                enabledSaslMechanisms = new HashSet<>(saslMechanisms.size());
930            }
931            enabledSaslMechanisms.addAll(saslMechanisms);
932            return getThis();
933        }
934
935        /**
936         * Set the XMPP address to be used as authorization identity.
937         * <p>
938         * In XMPP, authorization identities are bare jids. In general, callers should allow the server to select the
939         * authorization identifier automatically, and not call this. Note that setting the authzid does not set the XMPP
940         * service domain, which should typically match.
941         * Calling this will also SASL CRAM, since this mechanism does not support authzid.
942         * </p>
943         * 
944         * @param authzid The BareJid to be requested as the authorization identifier.
945         * @return a reference to this builder.
946         * @see <a href="http://tools.ietf.org/html/rfc6120#section-6.3.8">RFC 6120 § 6.3.8. Authorization Identity</a>
947         * @since 4.2
948         */
949        public B setAuthzid(EntityBareJid authzid) {
950            this.authzid = authzid;
951            return getThis();
952        }
953
954        public abstract C build();
955
956        protected abstract B getThis();
957    }
958}