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}