* Technically there are typically at least two parameters required: Some kind of credentials for authentication. And * the XMPP service domain. The credentials often consists of a username and password use for the SASL authentication. * But there are also other authentication mechanisms, like client side certificates, which do not require a particular * username and password. *
** There are some misconceptions about XMPP client-to-server parameters: The first is that the username used for * authentication will be equal to the localpart of the bound XMPP address after authentication. While this is usually * true, it is not required. Technically the username used for authentication and the resulting XMPP address are * completely independent from each other. The second common misconception steers from the terms "XMPP host" and "XMPP * service domain": An XMPP service host is a system which hosts one or multiple XMPP domains. The "XMPP service domain" * will be usually the domainpart of the bound JID. This domain is used to verify the remote endpoint, typically using * TLS. This third misconception is that the XMPP service domain is required to become the domainpart of the bound JID. * Again, while this is very common to be true, it is not strictly required. *
* * @author Gaston Dombiak * @author Florian Schmaus */ public abstract class ConnectionConfiguration { static { Smack.ensureInitialized(); } private static final Logger LOGGER = Logger.getLogger(ConnectionConfiguration.class.getName()); /** * The XMPP domain of the XMPP Service. Usually servers use the same service name as the name * of the server. However, there are some servers like google where host would be * talk.google.com and the serviceName would be gmail.com. */ protected final DomainBareJid xmppServiceDomain; protected final DnsName xmppServiceDomainDnsName; protected final InetAddress hostAddress; protected final DnsName host; protected final UInt16 port; /** * Used to get information from the user */ private final CallbackHandler callbackHandler; private final SmackDebuggerFactory debuggerFactory; // Holds the socket factory that is used to generate the socket in the connection private final SocketFactory socketFactory; private final CharSequence username; private final String password; private final Resourcepart resource; private final Locale language; /** * The optional SASL authorization identity (see RFC 6120 § 6.3.8). */ private final EntityBareJid authzid; /** * Initial presence as of RFC 6121 § 4.2 * @see RFC 6121 § 4.2 Initial Presence */ private final boolean sendPresence; private final SecurityMode securityMode; final SmackTlsContext smackTlsContext; private final DnssecMode dnssecMode; /** * */ private final String[] enabledSSLProtocols; /** * */ private final String[] enabledSSLCiphers; private final HostnameVerifier hostnameVerifier; // Holds the proxy information (such as proxyhost, proxyport, username, password etc) protected final ProxyInfo proxy; protected final boolean allowNullOrEmptyUsername; private final Setnull.
*
* @return the XMPP service domain as DNS name or null.
* @since 4.3.4
*/
public DnsName getXmppServiceDomainAsDnsNameIfPossible() {
return xmppServiceDomainDnsName;
}
/**
* Returns the TLS security mode used when making the connection. By default,
* the mode is {@link SecurityMode#required}.
*
* @return the security mode.
*/
public SecurityMode getSecurityMode() {
return securityMode;
}
public DnssecMode getDnssecMode() {
return dnssecMode;
}
/**
* Return the enabled SSL/TLS protocols.
*
* @return the enabled SSL/TLS protocols
*/
public String[] getEnabledSSLProtocols() {
return enabledSSLProtocols;
}
/**
* Return the enabled SSL/TLS ciphers.
*
* @return the enabled SSL/TLS ciphers
*/
public String[] getEnabledSSLCiphers() {
return enabledSSLCiphers;
}
/**
* Returns the configured HostnameVerifier of this ConnectionConfiguration or the Smack default
* HostnameVerifier configured with
* {@link SmackConfiguration#setDefaultHostnameVerifier(HostnameVerifier)}.
*
* @return a configured HostnameVerifier or null
*/
public HostnameVerifier getHostnameVerifier() {
if (hostnameVerifier != null)
return hostnameVerifier;
return SmackConfiguration.getDefaultHostnameVerifier();
}
/**
* Returns the Smack debugger factory.
*
* @return the Smack debugger factory or null
*/
public SmackDebuggerFactory getDebuggerFactory() {
return debuggerFactory;
}
/**
* Returns a CallbackHandler to obtain information, such as the password or
* principal information during the SASL authentication. A CallbackHandler
* will be used ONLY if no password was specified during the login while
* using SASL authentication.
*
* @return a CallbackHandler to obtain information, such as the password or
* principal information during the SASL authentication.
*/
public CallbackHandler getCallbackHandler() {
return callbackHandler;
}
/**
* Returns the socket factory used to create new xmppConnection sockets.
* This is useful when connecting through SOCKS5 proxies.
*
* @return socketFactory used to create new sockets.
*/
public SocketFactory getSocketFactory() {
return this.socketFactory;
}
/**
* Get the configured proxy information (if any).
*
* @return the configured proxy information or null.
*/
public ProxyInfo getProxyInfo() {
return proxy;
}
/**
* An enumeration for TLS security modes that are available when making a connection
* to the XMPP server.
*/
public enum SecurityMode {
/**
* Security via TLS encryption is required in order to connect. If the server
* does not offer TLS or if the TLS negotiation fails, the connection to the server
* will fail.
*/
required,
/**
* Security via TLS encryption is used whenever it's available. This is the
* default setting.
* * Do not use this setting unless you can't use {@link #required}. An attacker could easily perform a * Man-in-the-middle attack and prevent TLS from being used, leaving you with an unencrypted (and * unauthenticated) connection. *
*/ ifpossible, /** * Security via TLS encryption is disabled and only un-encrypted connections will * be used. If only TLS encryption is available from the server, the connection * will fail. */ disabled } /** * Determines the requested DNSSEC security mode. * Note that Smack's support for DNSSEC/DANE is experimental! ** The default '{@link #disabled}' means that neither DNSSEC nor DANE verification will be performed. When * '{@link #needsDnssec}' is used, then the connection will not be established if the resource records used to connect * to the XMPP service are not authenticated by DNSSEC. Additionally, if '{@link #needsDnssecAndDane}' is used, then * the XMPP service's TLS certificate is verified using DANE. * */ public enum DnssecMode { /** * Do not perform any DNSSEC authentication or DANE verification. */ disabled, /** * Experimental! * Require all DNS information to be authenticated by DNSSEC. */ needsDnssec, /** * Experimental! * Require all DNS information to be authenticated by DNSSEC and require the XMPP service's TLS certificate to be verified using DANE. */ needsDnssecAndDane, } /** * Returns the username to use when trying to reconnect to the server. * * @return the username to use when trying to reconnect to the server. */ public CharSequence getUsername() { return this.username; } /** * Returns the password to use when trying to reconnect to the server. * * @return the password to use when trying to reconnect to the server. */ public String getPassword() { return this.password; } /** * Returns the resource to use when trying to reconnect to the server. * * @return the resource to use when trying to reconnect to the server. */ public Resourcepart getResource() { return resource; } /** * Returns the stream language to use when connecting to the server. * * @return the stream language to use when connecting to the server. */ public Locale getLanguage() { return language; } /** * Returns the xml:lang string of the stream language to use when connecting to the server. * *
If the developer sets the language to null, this will also return null, leading to * the removal of the xml:lang tag from the stream. If a Locale("") is configured, this will * return "", which can be used as an override.
* * @return the stream language to use when connecting to the server. */ public String getXmlLang() { // TODO: Change to Locale.toLanguageTag() once Smack's minimum Android API level is 21 or higher. // This will need a workaround for new Locale("").getLanguageTag() returning "und". Expected // behavior of this function: // - returns null if language is null // - returns "" if language.getLanguage() returns the empty string // - returns language.toLanguageTag() otherwise return language != null ? language.toString().replace("_", "-") : null; } /** * Returns the optional XMPP address to be requested as the SASL authorization identity. * * @return the authorization identifier. * @see RFC 6120 § 6.3.8. Authorization Identity * @since 4.2 */ public EntityBareJid getAuthzid() { return authzid; } /** * Returns true if an available presence should be sent when logging in while reconnecting. * * @return true if an available presence should be sent when logging in while reconnecting */ public boolean isSendPresence() { return sendPresence; } /** * Returns true if the connection is going to use stream compression. Stream compression * will be requested after TLS was established (if TLS was enabled) and only if the server * offered stream compression. With stream compression network traffic can be reduced * up to 90%. By default compression is disabled. * * @return true if the connection is going to use stream compression. */ public boolean isCompressionEnabled() { return compressionEnabled; } /** * Check if the given SASL mechansism is enabled in this connection configuration. * * @param saslMechanism TODO javadoc me please * @return true if the given SASL mechanism is enabled, false otherwise. */ public boolean isEnabledSaslMechanism(String saslMechanism) { // If enabledSaslMechanisms is not set, then all mechanisms which are not blacklisted are enabled per default. if (enabledSaslMechanisms == null) { return !SASLAuthentication.getBlacklistedSASLMechanisms().contains(saslMechanism); } return enabledSaslMechanisms.contains(saslMechanism); } /** * Return the explicitly enabled SASL mechanisms. May returnnull if no SASL mechanisms where
* explicitly enabled, i.e. all SALS mechanisms supported and announced by the service will be considered.
*
* @return the enabled SASL mechanisms or null.
*/
public Set* This is an abstract class that uses the builder design pattern and the "getThis() trick" to recover the type of * the builder in a class hierarchies with a self-referential generic supertype. Otherwise chaining of build * instructions from the superclasses followed by build instructions of a subclass would not be possible, because * the superclass build instructions would return the builder of the superclass and not the one of the subclass. You * can read more about it a Angelika Langer's Generics FAQ, especially the entry What is the * "getThis()" trick?. *
* * @param the builder type parameter. * @param* Please note that this does and can not configure the client XMPP address. XMPP services are not required to * assign bound JIDs where the localpart matches the username and the domainpart matches the verified domainpart. * Although most services will follow that pattern. *
* * @param jid TODO javadoc me please * @param password TODO javadoc me please * @return a reference to this builder. * @since 4.4.0 */ public B setXmppAddressAndPassword(EntityBareJid jid, String password) { setUsernameAndPassword(jid.getLocalpart(), password); return setXmppDomain(jid.asDomainBareJid()); } /** * Set the XMPP entities username and password. ** The username is usually the localpart of the clients JID. But some SASL mechanisms or services may require a different * format (e.g. the full JID) as used authorization identity. *
* * @param username the username or authorization identity * @param password the password or token used to authenticate * @return a reference to this builder. */ public B setUsernameAndPassword(CharSequence username, String password) { this.username = username; this.password = password; return getThis(); } /** * Set the XMPP domain. The XMPP domain is what follows after the '@' sign in XMPP addresses (JIDs). * * @param serviceName the service name * @return a reference to this builder. * @deprecated use {@link #setXmppDomain(DomainBareJid)} instead. */ @Deprecated public B setServiceName(DomainBareJid serviceName) { return setXmppDomain(serviceName); } /** * Set the XMPP domain. The XMPP domain is what follows after the '@' sign in XMPP addresses (JIDs). * * @param xmppDomain the XMPP domain. * @return a reference to this builder. */ public B setXmppDomain(DomainBareJid xmppDomain) { this.xmppServiceDomain = xmppDomain; return getThis(); } /** * Set the XMPP domain. The XMPP domain is what follows after the '@' sign in XMPP addresses (JIDs). * * @param xmppServiceDomain the XMPP domain. * @return a reference to this builder. * @throws XmppStringprepException if the given string is not a domain bare JID. */ public B setXmppDomain(String xmppServiceDomain) throws XmppStringprepException { this.xmppServiceDomain = JidCreate.domainBareFrom(xmppServiceDomain); return getThis(); } /** * Set the resource we are requesting from the server. *
* If resource is null, the default, then the server will automatically create a
* resource for the client. Note that XMPP clients only suggest this resource to the server. XMPP servers are
* allowed to ignore the client suggested resource and instead assign a completely different
* resource (see RFC 6120 § 7.7.1).
*
null as
* {@link SecureRandom} argument. And all sane {@link SSLContext} implementations will then select a safe secure
* random source by default.
*
* @param secureRandom the {@link SecureRandom} to initialize the {@link SSLContext} with.
* @return a reference to this builder.
* @since 4.4.5
*/
public B setSslContextSecureRandom(SecureRandom secureRandom) {
this.sslContextSecureRandom = secureRandom;
return getThis();
}
/**
* Sets the path to the keystore file. The key store file contains the
* certificates that may be used to authenticate the client to the server,
* in the event the server requests or requires it.
*
* @param keystorePath the path to the keystore file.
* @return a reference to this builder.
* @deprecated set a keystore-path aware {@link KeyManager} via {@link #setKeyManager(KeyManager)} or
* {@link #setKeyManagers(KeyManager[])}, created by
* {@link #getKeyManagersFrom(String, String, CallbackHandler, String)}, instead.
*/
// TODO: Remove in Smack 4.6.
@Deprecated
public B setKeystorePath(String keystorePath) {
this.keystorePath = keystorePath;
return getThis();
}
/**
* Sets the keystore type.
*
* @param keystoreType the keystore type.
* @return a reference to this builder.
* @deprecated set a key-type aware {@link KeyManager} via {@link #setKeyManager(KeyManager)} or
* {@link #setKeyManagers(KeyManager[])}, created by
* {@link #getKeyManagersFrom(String, String, CallbackHandler, String)}, instead.
*/
// TODO: Remove in Smack 4.6.
@Deprecated
public B setKeystoreType(String keystoreType) {
this.keystoreType = keystoreType;
return getThis();
}
/**
* Sets the PKCS11 library file location, needed when the
* Keystore type is PKCS11.
*
* @param pkcs11Library the path to the PKCS11 library file.
* @return a reference to this builder.
* @deprecated set a PKCS11-library aware {@link KeyManager} via {@link #setKeyManager(KeyManager)} or
* {@link #setKeyManagers(KeyManager[])}, created by
* {@link #getKeyManagersFrom(String, String, CallbackHandler, String)}, instead.
*/
// TODO: Remove in Smack 4.6.
@Deprecated
public B setPKCS11Library(String pkcs11Library) {
this.pkcs11Library = pkcs11Library;
return getThis();
}
/**
* Sets a custom SSLContext for creating SSL sockets.
* * For more information on how to create a SSLContext see Java Secure Socket Extension (JSEE) Reference Guide: Creating Your Own X509TrustManager * * @param context the custom SSLContext for new sockets. * @return a reference to this builder. * @deprecated use {@link #setSslContextFactory(SslContextFactory)} instead}. */ // TODO: Remove in Smack 4.5. @Deprecated public B setCustomSSLContext(SSLContext context) { return setSslContextFactory(() -> { return context; }); } /** * Sets a custom SSLContext for creating SSL sockets. *
* For more information on how to create a SSLContext see Java Secure Socket Extension (JSEE) Reference Guide: Creating Your Own X509TrustManager
*
* @param sslContextFactory the custom SSLContext for new sockets.
* @return a reference to this builder.
*/
public B setSslContextFactory(SslContextFactory sslContextFactory) {
this.sslContextFactory = Objects.requireNonNull(sslContextFactory, "The provided SslContextFactory must not be null");
return getThis();
}
/**
* Set the enabled SSL/TLS protocols.
*
* @param enabledSSLProtocols TODO javadoc me please
* @return a reference to this builder.
*/
public B setEnabledSSLProtocols(String[] enabledSSLProtocols) {
this.enabledSSLProtocols = enabledSSLProtocols;
return getThis();
}
/**
* Set the enabled SSL/TLS ciphers.
*
* @param enabledSSLCiphers the enabled SSL/TLS ciphers
* @return a reference to this builder.
*/
public B setEnabledSSLCiphers(String[] enabledSSLCiphers) {
this.enabledSSLCiphers = enabledSSLCiphers;
return getThis();
}
/**
* Set the HostnameVerifier used to verify the hostname of SSLSockets used by XMPP connections
* created with this ConnectionConfiguration.
*
* @param verifier TODO javadoc me please
* @return a reference to this builder.
*/
public B setHostnameVerifier(HostnameVerifier verifier) {
hostnameVerifier = verifier;
return getThis();
}
/**
* Sets if an initial available presence will be sent to the server. By default
* an available presence will be sent to the server indicating that this presence
* is not online and available to receive messages. If you want to log in without
* being 'noticed' then pass a
* In XMPP, authorization identities are bare jids. In general, callers should allow the server to select the
* authorization identifier automatically, and not call this. Note that setting the authzid does not set the XMPP
* service domain, which should typically match.
* Calling this will also SASL CRAM, since this mechanism does not support authzid.
* false value.
*
* @param sendPresence true if an initial available presence will be sent while logging in.
* @return a reference to this builder.
*/
public B setSendPresence(boolean sendPresence) {
this.sendPresence = sendPresence;
return getThis();
}
public B enableDefaultDebugger() {
this.debuggerFactory = SmackConfiguration.getDefaultSmackDebuggerFactory();
assert this.debuggerFactory != null;
return getThis();
}
/**
* Set the Smack debugger factory used to construct Smack debuggers.
*
* @param debuggerFactory the Smack debugger factory.
* @return a reference to this builder.
*/
public B setDebuggerFactory(SmackDebuggerFactory debuggerFactory) {
this.debuggerFactory = debuggerFactory;
return getThis();
}
/**
* Sets the socket factory used to create new xmppConnection sockets.
* This is useful when connecting through SOCKS5 proxies.
*
* @param socketFactory used to create new sockets.
* @return a reference to this builder.
*/
public B setSocketFactory(SocketFactory socketFactory) {
this.socketFactory = socketFactory;
return getThis();
}
/**
* Set the information about the Proxy used for the connection.
*
* @param proxyInfo the Proxy information.
* @return a reference to this builder.
*/
public B setProxyInfo(ProxyInfo proxyInfo) {
this.proxy = proxyInfo;
return getThis();
}
/**
* Allow null or the empty String as username.
*
* Some SASL mechanisms (e.g. SASL External) may also signal the username (as "authorization identity"), in
* which case Smack should not throw an IllegalArgumentException when the username is not set.
*
* @return a reference to this builder.
*/
public B allowEmptyOrNullUsernames() {
allowEmptyOrNullUsername = true;
return getThis();
}
/**
* Perform anonymous authentication using SASL ANONYMOUS. Your XMPP service must support this authentication
* mechanism. This method also calls {@link #addEnabledSaslMechanism(String)} with "ANONYMOUS" as argument.
*
* @return a reference to this builder.
*/
public B performSaslAnonymousAuthentication() {
if (!SASLAuthentication.isSaslMechanismRegistered(SASLAnonymous.NAME)) {
throw new IllegalArgumentException("SASL " + SASLAnonymous.NAME + " is not registered");
}
throwIfEnabledSaslMechanismsSet();
allowEmptyOrNullUsernames();
addEnabledSaslMechanism(SASLAnonymous.NAME);
saslMechanismsSealed = true;
return getThis();
}
/**
* Perform authentication using SASL EXTERNAL. Your XMPP service must support this
* authentication mechanism. This method also calls {@link #addEnabledSaslMechanism(String)} with "EXTERNAL" as
* argument. It also calls {@link #allowEmptyOrNullUsernames()} and {@link #setSecurityMode(ConnectionConfiguration.SecurityMode)} to
* {@link SecurityMode#required}.
*
* @param sslContext custom SSLContext to be used.
* @return a reference to this builder.
*/
public B performSaslExternalAuthentication(SSLContext sslContext) {
if (!SASLAuthentication.isSaslMechanismRegistered(SASLMechanism.EXTERNAL)) {
throw new IllegalArgumentException("SASL " + SASLMechanism.EXTERNAL + " is not registered");
}
setCustomSSLContext(sslContext);
throwIfEnabledSaslMechanismsSet();
allowEmptyOrNullUsernames();
setSecurityMode(SecurityMode.required);
addEnabledSaslMechanism(SASLMechanism.EXTERNAL);
saslMechanismsSealed = true;
return getThis();
}
private void throwIfEnabledSaslMechanismsSet() {
if (enabledSaslMechanisms != null) {
throw new IllegalStateException("Enabled SASL mechanisms found");
}
}
/**
* Add the given mechanism to the enabled ones. See {@link #addEnabledSaslMechanism(Collection)} for a discussion about enabled SASL mechanisms.
*
* @param saslMechanism the name of the mechanism to enable.
* @return a reference to this builder.
*/
public B addEnabledSaslMechanism(String saslMechanism) {
return addEnabledSaslMechanism(Arrays.asList(StringUtils.requireNotNullNorEmpty(saslMechanism,
"saslMechanism must not be null nor empty")));
}
/**
* Enable the given SASL mechanisms. If you never add a mechanism to the set of enabled ones, all mechanisms
* known to Smack will be enabled. Only explicitly enable particular SASL mechanisms if you want to limit
* the used mechanisms to the enabled ones.
*
* @param saslMechanisms a collection of names of mechanisms to enable.
* @return a reference to this builder.
*/
public B addEnabledSaslMechanism(Collection