com.unboundid.util

Class SASLUtils

java.lang.Object

com.unboundid.util.SASLUtils

@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class SASLUtils
extends java.lang.Object

This class provides a utility that may be used to help process SASL bind operations using the LDAP SDK.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	SASL_OPTION_ACCESS_TOKEN The name of the SASL option that specifies the access token.
static java.lang.String	SASL_OPTION_AUTH_ID The name of the SASL option that specifies the authentication ID.
static java.lang.String	SASL_OPTION_AUTHZ_ID The name of the SASL option that specifies the authorization ID.
static java.lang.String	SASL_OPTION_CONFIG_FILE The name of the SASL option that specifies the path to the JAAS config file.
static java.lang.String	SASL_OPTION_DEBUG The name of the SASL option that indicates whether debugging should be enabled.
static java.lang.String	SASL_OPTION_KDC_ADDRESS The name of the SASL option that specifies the KDC address.
static java.lang.String	SASL_OPTION_MECHANISM The name of the SASL option that specifies the desired SASL mechanism to use to authenticate to the server.
static java.lang.String	SASL_OPTION_OTP The name of the SASL option that specifies a one-time password.
static java.lang.String	SASL_OPTION_PROMPT_FOR_STATIC_PW The name of the SASL option that may be used to indicate whether to prompt for a static password.
static java.lang.String	SASL_OPTION_PROTOCOL The name of the SASL option that specifies the GSSAPI service principal protocol.
static java.lang.String	SASL_OPTION_QOP The name of the SASL option that specifies the quality of protection that should be used for communication that occurs after the authentication has completed.
static java.lang.String	SASL_OPTION_REALM The name of the SASL option that specifies the realm name.
static java.lang.String	SASL_OPTION_RENEW_TGT The name of the SASL option that indicates whether to attempt to renew the Kerberos TGT for an existing session.
static java.lang.String	SASL_OPTION_REQUIRE_CACHE The name of the SASL option that indicates whether to require an existing Kerberos session from the ticket cache.
static java.lang.String	SASL_OPTION_TICKET_CACHE_PATH The name of the SASL option that specifies the path to the Kerberos ticket cache to use.
static java.lang.String	SASL_OPTION_TOTP_PASSWORD The name of the SASL option that specifies the TOTP authentication code.
static java.lang.String	SASL_OPTION_TRACE The name of the SASL option that specifies the trace string.
static java.lang.String	SASL_OPTION_USE_TICKET_CACHE The name of the SASL option that specifies whether to use a Kerberos ticket cache.
static java.lang.String	SASL_OPTION_USERNAME The name of the SASL option that specifies the username.

Method Summary

Modifier and Type	Method and Description
static SASLBindRequest	createBindRequest(java.lang.String bindDN, byte[] password, boolean promptForPassword, CommandLineTool tool, java.lang.String mechanism, java.util.List<java.lang.String> options, Control... controls) Creates a new SASL bind request using the provided information.
static SASLBindRequest	createBindRequest(java.lang.String bindDN, byte[] password, java.lang.String mechanism, java.util.List<java.lang.String> options, Control... controls) Creates a new SASL bind request using the provided information.
static SASLBindRequest	createBindRequest(java.lang.String bindDN, byte[] password, java.lang.String mechanism, java.lang.String... options) Creates a new SASL bind request using the provided information.
static SASLBindRequest	createBindRequest(java.lang.String bindDN, java.lang.String password, java.lang.String mechanism, java.util.List<java.lang.String> options, Control... controls) Creates a new SASL bind request using the provided information.
static SASLBindRequest	createBindRequest(java.lang.String bindDN, java.lang.String password, java.lang.String mechanism, java.lang.String... options) Creates a new SASL bind request using the provided information.
static void	ensureNoUnsupportedOptions(java.util.Map<java.lang.String,java.lang.String> options, java.lang.String mechanism) Ensures that the provided map is empty, and will throw an exception if it isn't.
static SASLMechanismInfo	getSASLMechanismInfo(java.lang.String mechanism) Retrieves information about the specified SASL mechanism.
static java.util.List<SASLMechanismInfo>	getSupportedSASLMechanisms() Retrieves information about the SASL mechanisms supported for use by this class.
static java.util.List<java.lang.String>	getUsage(int maxWidth) Retrieves lines that make up the SASL usage information, optionally wrapping long lines.
static java.util.List<java.lang.String>	getUsage(java.lang.String mechanism, int maxWidth) Retrieves lines that make up the SASL usage information, optionally wrapping long lines.
static java.lang.String	getUsageString(int maxWidth) Retrieves a string representation of the SASL usage information.
static java.lang.String	getUsageString(java.lang.String mechanism, int maxWidth) Retrieves a string representation of the SASL usage information.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SASL_OPTION_ACCESS_TOKEN

@NotNull
public static final java.lang.String SASL_OPTION_ACCESS_TOKEN

The name of the SASL option that specifies the access token. It may be used in conjunction with the OAUTHBEARER mechanism.

See Also:

Constant Field Values

SASL_OPTION_AUTH_ID

@NotNull
public static final java.lang.String SASL_OPTION_AUTH_ID

The name of the SASL option that specifies the authentication ID. It may be used in conjunction with the CRAM-MD5, DIGEST-MD5, GSSAPI, and PLAIN mechanisms.

See Also:

Constant Field Values

SASL_OPTION_AUTHZ_ID

@NotNull
public static final java.lang.String SASL_OPTION_AUTHZ_ID

The name of the SASL option that specifies the authorization ID. It may be used in conjunction with the DIGEST-MD5, GSSAPI, and PLAIN mechanisms.

See Also:

Constant Field Values

SASL_OPTION_CONFIG_FILE

@NotNull
public static final java.lang.String SASL_OPTION_CONFIG_FILE

The name of the SASL option that specifies the path to the JAAS config file. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

SASL_OPTION_DEBUG

@NotNull
public static final java.lang.String SASL_OPTION_DEBUG

The name of the SASL option that indicates whether debugging should be enabled. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

SASL_OPTION_KDC_ADDRESS

@NotNull
public static final java.lang.String SASL_OPTION_KDC_ADDRESS

The name of the SASL option that specifies the KDC address. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

SASL_OPTION_MECHANISM

@NotNull
public static final java.lang.String SASL_OPTION_MECHANISM

The name of the SASL option that specifies the desired SASL mechanism to use to authenticate to the server.

See Also:

Constant Field Values

SASL_OPTION_OTP

@NotNull
public static final java.lang.String SASL_OPTION_OTP

The name of the SASL option that specifies a one-time password. It may be used in conjunction with the UNBOUNDID-DELIVERED-OTP and UNBOUNDID-YUBIKEY-OTP mechanisms.

See Also:

Constant Field Values

SASL_OPTION_PROMPT_FOR_STATIC_PW

@NotNull
public static final java.lang.String SASL_OPTION_PROMPT_FOR_STATIC_PW

The name of the SASL option that may be used to indicate whether to prompt for a static password. It may be used in conjunction with the UNBOUNDID-TOTP and UNBOUNDID-YUBIKEY-OTP mechanisms.

See Also:

Constant Field Values

SASL_OPTION_PROTOCOL

@NotNull
public static final java.lang.String SASL_OPTION_PROTOCOL

The name of the SASL option that specifies the GSSAPI service principal protocol. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

SASL_OPTION_QOP

@NotNull
public static final java.lang.String SASL_OPTION_QOP

The name of the SASL option that specifies the quality of protection that should be used for communication that occurs after the authentication has completed.

See Also:

Constant Field Values

SASL_OPTION_REALM

@NotNull
public static final java.lang.String SASL_OPTION_REALM

The name of the SASL option that specifies the realm name. It may be used in conjunction with the DIGEST-MD5 and GSSAPI mechanisms.

See Also:

Constant Field Values

SASL_OPTION_REQUIRE_CACHE

@NotNull
public static final java.lang.String SASL_OPTION_REQUIRE_CACHE

The name of the SASL option that indicates whether to require an existing Kerberos session from the ticket cache. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

SASL_OPTION_RENEW_TGT

@NotNull
public static final java.lang.String SASL_OPTION_RENEW_TGT

The name of the SASL option that indicates whether to attempt to renew the Kerberos TGT for an existing session. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

SASL_OPTION_TICKET_CACHE_PATH

@NotNull
public static final java.lang.String SASL_OPTION_TICKET_CACHE_PATH

The name of the SASL option that specifies the path to the Kerberos ticket cache to use. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

SASL_OPTION_TOTP_PASSWORD

@NotNull
public static final java.lang.String SASL_OPTION_TOTP_PASSWORD

The name of the SASL option that specifies the TOTP authentication code. It may be used in conjunction with the UNBOUNDID-TOTP mechanism.

See Also:

Constant Field Values

SASL_OPTION_TRACE

@NotNull
public static final java.lang.String SASL_OPTION_TRACE

The name of the SASL option that specifies the trace string. It may be used in conjunction with the ANONYMOUS mechanism.

See Also:

Constant Field Values

SASL_OPTION_USERNAME

@NotNull
public static final java.lang.String SASL_OPTION_USERNAME

The name of the SASL option that specifies the username. It may be used in conjunction with the SCRAM-SHA-1, SCRAM-SHA-256, and SCRAM-SHA-512 mechanisms.

See Also:

Constant Field Values

SASL_OPTION_USE_TICKET_CACHE

@NotNull
public static final java.lang.String SASL_OPTION_USE_TICKET_CACHE

The name of the SASL option that specifies whether to use a Kerberos ticket cache. It may be used in conjunction with the GSSAPI mechanism.

See Also:

Constant Field Values

Method Detail

getSupportedSASLMechanisms

@NotNull
public static java.util.List<SASLMechanismInfo> getSupportedSASLMechanisms()

Retrieves information about the SASL mechanisms supported for use by this class.

Returns:

Information about the SASL mechanisms supported for use by this class.

getSASLMechanismInfo

@Nullable
public static SASLMechanismInfo getSASLMechanismInfo(@NotNull
                                                               java.lang.String mechanism)

Retrieves information about the specified SASL mechanism.

Parameters:

mechanism - The name of the SASL mechanism for which to retrieve information. It will be treated in a case-insensitive manner.

Returns:

Information about the requested SASL mechanism, or null if no information about the specified mechanism is available.

createBindRequest

@NotNull
public static SASLBindRequest createBindRequest(@Nullable
                                                         java.lang.String bindDN,
                                                         @Nullable
                                                         java.lang.String password,
                                                         @Nullable
                                                         java.lang.String mechanism,
                                                         @Nullable
                                                         java.lang.String... options)
                                                  throws LDAPException

Creates a new SASL bind request using the provided information.

Parameters:

bindDN - The bind DN to use for the SASL bind request. For most SASL mechanisms, this should be null, since the identity of the target user should be specified in some other way (e.g., via an "authID" SASL option).

password - The password to use for the SASL bind request. It may be null if no password is required for the desired SASL mechanism.

mechanism - The name of the SASL mechanism to use. It may be null if the provided set of options contains a "mech" option to specify the desired SASL option.

options - The set of SASL options to use when creating the bind request, in the form "name=value". It may be null or empty if no SASL options are needed and a value was provided for the mechanism argument. If the set of SASL options includes a "mech" option, then the mechanism argument must be null or have a value that matches the value of the "mech" SASL option.

Returns:

The SASL bind request created using the provided information.

Throws:

LDAPException - If a problem is encountered while trying to create the SASL bind request.

createBindRequest

@NotNull
public static SASLBindRequest createBindRequest(@Nullable
                                                         java.lang.String bindDN,
                                                         @Nullable
                                                         java.lang.String password,
                                                         @Nullable
                                                         java.lang.String mechanism,
                                                         @Nullable
                                                         java.util.List<java.lang.String> options,
                                                         @Nullable
                                                         Control... controls)
                                                  throws LDAPException

Creates a new SASL bind request using the provided information.

Parameters:

bindDN - The bind DN to use for the SASL bind request. For most SASL mechanisms, this should be null, since the identity of the target user should be specified in some other way (e.g., via an "authID" SASL option).

password - The password to use for the SASL bind request. It may be null if no password is required for the desired SASL mechanism.

mechanism - The name of the SASL mechanism to use. It may be null if the provided set of options contains a "mech" option to specify the desired SASL option.

options - The set of SASL options to use when creating the bind request, in the form "name=value". It may be null or empty if no SASL options are needed and a value was provided for the mechanism argument. If the set of SASL options includes a "mech" option, then the mechanism argument must be null or have a value that matches the value of the "mech" SASL option.

controls - The set of controls to include in the request.

Returns:

The SASL bind request created using the provided information.

Throws:

LDAPException - If a problem is encountered while trying to create the SASL bind request.

createBindRequest

@NotNull
public static SASLBindRequest createBindRequest(@Nullable
                                                         java.lang.String bindDN,
                                                         @Nullable
                                                         byte[] password,
                                                         @Nullable
                                                         java.lang.String mechanism,
                                                         @Nullable
                                                         java.lang.String... options)
                                                  throws LDAPException

Creates a new SASL bind request using the provided information.

Parameters:

bindDN - The bind DN to use for the SASL bind request. For most SASL mechanisms, this should be null, since the identity of the target user should be specified in some other way (e.g., via an "authID" SASL option).

password - The password to use for the SASL bind request. It may be null if no password is required for the desired SASL mechanism.

mechanism - The name of the SASL mechanism to use. It may be null if the provided set of options contains a "mech" option to specify the desired SASL option.

options - The set of SASL options to use when creating the bind request, in the form "name=value". It may be null or empty if no SASL options are needed and a value was provided for the mechanism argument. If the set of SASL options includes a "mech" option, then the mechanism argument must be null or have a value that matches the value of the "mech" SASL option.

Returns:

The SASL bind request created using the provided information.

Throws:

LDAPException - If a problem is encountered while trying to create the SASL bind request.

createBindRequest

@NotNull
public static SASLBindRequest createBindRequest(@Nullable
                                                         java.lang.String bindDN,
                                                         @Nullable
                                                         byte[] password,
                                                         @Nullable
                                                         java.lang.String mechanism,
                                                         @Nullable
                                                         java.util.List<java.lang.String> options,
                                                         @Nullable
                                                         Control... controls)
                                                  throws LDAPException

Creates a new SASL bind request using the provided information.

Parameters:

bindDN - The bind DN to use for the SASL bind request. For most SASL mechanisms, this should be null, since the identity of the target user should be specified in some other way (e.g., via an "authID" SASL option).

password - The password to use for the SASL bind request. It may be null if no password is required for the desired SASL mechanism.

mechanism - The name of the SASL mechanism to use. It may be null if the provided set of options contains a "mech" option to specify the desired SASL option.

options - The set of SASL options to use when creating the bind request, in the form "name=value". It may be null or empty if no SASL options are needed and a value was provided for the mechanism argument. If the set of SASL options includes a "mech" option, then the mechanism argument must be null or have a value that matches the value of the "mech" SASL option.

controls - The set of controls to include in the request.

Returns:

The SASL bind request created using the provided information.

Throws:

LDAPException - If a problem is encountered while trying to create the SASL bind request.

createBindRequest

@NotNull
public static SASLBindRequest createBindRequest(@Nullable
                                                         java.lang.String bindDN,
                                                         @Nullable
                                                         byte[] password,
                                                         boolean promptForPassword,
                                                         @Nullable
                                                         CommandLineTool tool,
                                                         @Nullable
                                                         java.lang.String mechanism,
                                                         @Nullable
                                                         java.util.List<java.lang.String> options,
                                                         @Nullable
                                                         Control... controls)
                                                  throws LDAPException

Creates a new SASL bind request using the provided information.

Parameters:

bindDN - The bind DN to use for the SASL bind request. For most SASL mechanisms, this should be null, since the identity of the target user should be specified in some other way (e.g., via an "authID" SASL option).

password - The password to use for the SASL bind request. It may be null if no password is required for the desired SASL mechanism.

promptForPassword - Indicates whether to interactively prompt for the password if one is needed but none was provided.

tool - The command-line tool whose input and output streams should be used when prompting for the bind password. It may be null if promptForPassword is false.

mechanism - The name of the SASL mechanism to use. It may be null if the provided set of options contains a "mech" option to specify the desired SASL option.

options - The set of SASL options to use when creating the bind request, in the form "name=value". It may be null or empty if no SASL options are needed and a value was provided for the mechanism argument. If the set of SASL options includes a "mech" option, then the mechanism argument must be null or have a value that matches the value of the "mech" SASL option.

controls - The set of controls to include in the request.

Returns:

The SASL bind request created using the provided information.

Throws:

LDAPException - If a problem is encountered while trying to create the SASL bind request.

ensureNoUnsupportedOptions

@InternalUseOnly
public static void ensureNoUnsupportedOptions(@NotNull
                                                               java.util.Map<java.lang.String,java.lang.String> options,
                                                               @NotNull
                                                               java.lang.String mechanism)
                                                        throws LDAPException

Ensures that the provided map is empty, and will throw an exception if it isn't. This method is intended for internal use only.

Parameters:

options - The map of options to ensure is empty.

mechanism - The associated SASL mechanism.

Throws:

LDAPException - If the map of SASL options is not empty.

getUsageString

@NotNull
public static java.lang.String getUsageString(int maxWidth)

Retrieves a string representation of the SASL usage information. This will include the supported SASL mechanisms and the properties that may be used with each.

Parameters:

maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.

Returns:

A string representation of the usage information.

getUsageString

@NotNull
public static java.lang.String getUsageString(@Nullable
                                                       java.lang.String mechanism,
                                                       int maxWidth)

Retrieves a string representation of the SASL usage information. This will include the supported SASL mechanisms and the properties that may be used with each.

Parameters:

mechanism - The name of the SASL mechanism for which to obtain usage information It may be null if usage should be displayed for all available mechamisms.

maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.

Returns:

A string representation of the usage information.

getUsage

@NotNull
public static java.util.List<java.lang.String> getUsage(int maxWidth)

Retrieves lines that make up the SASL usage information, optionally wrapping long lines.

Parameters:

maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.

Returns:

The lines that make up the SASL usage information.

getUsage

@NotNull
public static java.util.List<java.lang.String> getUsage(@Nullable
                                                                 java.lang.String mechanism,
                                                                 int maxWidth)

Retrieves lines that make up the SASL usage information, optionally wrapping long lines.

Parameters:

mechanism - The name of the SASL mechanism for which to obtain usage information It may be null if usage should be displayed for all available mechamisms.

maxWidth - The maximum line width to use for the output. If this is less than or equal to zero, then no wrapping will be performed.

Returns:

The lines that make up the SASL usage information.