com.unboundid.ldap.sdk.unboundidds.extensions

Class PasswordQualityRequirement

java.lang.Object

com.unboundid.ldap.sdk.unboundidds.extensions.PasswordQualityRequirement

All Implemented Interfaces:

java.io.Serializable

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class PasswordQualityRequirement
extends java.lang.Object
implements java.io.Serializable

This class provides a data structure that describes a requirement that passwords must satisfy in order to be accepted by the server.

NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

A password quality requirement will always include a description, which should be a string that provides a user-friendly description of the constraints that a proposed password must satisfy in order to meet this requirement and be accepted by the server. It may optionally include additional information that could allow an application to attempt some kind of pre-validation in order to determine whether a proposed password might fall outside the constraints associated with this requirement and would therefore be rejected by the server. This could allow a client to provide better performance (by not having to submit a password to the server and wait for the response in order to detect certain kinds of problems) and a better user experience (for example, by interactively indicating whether the value is acceptable as the user is entering it).

If a password quality requirement object does provide client-side validation data, then it will include at least a validation type (which indicates the nature of the validation that will be performed), and an optional set of properties that provide additional information about the specific nature of the validation. For example, if the server is configured with a length-based password validator that requires passwords to be between eight and 20 characters, then the requirement may have a validation type of "length" and two validation properties: "minimum-length" with a value of "8" and "maximum-length" with a value of "20". An application that supports this type of client-side validation could prevent a user from supplying a password that is too short or too long without the need to communicate with the server.

Note that not all types of password requirements will support client-side validation. For example, the server may be configured to use a dictionary with some of the most commonly-used passwords in an attempt to prevent users from selecting passwords that may be easily guessed, or the server may be configured with a password history to prevent users from selecting a password that they had already used. In these kinds of cases, the application will not have access to the information necessary to make the determination using client-side logic. The server is the ultimate authority as to whether a proposed password will be accepted, and even applications should be prepared to handle the case in which a password is rejected by the server even if client-side validation does not indicate that there are any problems with the password. There may also be cases in which the reason that an attempt to set a password fails for a reason that is not related to the quality of the provided password.

However, even in cases where an application may not be able to perform any client-side validation, the server may still offer a client-side validation type and validation properties. This is not intended to help the client determine whether a proposed password is acceptable, but could allow the client to convey information about the requirement to the user in a more flexible manner than simply providing the requirement description (e.g., it could allow the client to provide information about the requirement to the user in a different language than the server-provided description, or it could allow information about one requirement to be split into multiple elements, or multiple requirements combined into a single element.

If it appears in an LDAP protocol element (e.g., a get password quality requirements extended response, or a password validation details response control), it should have the following ASN.1 encoding:

   PasswordQualityRequirement ::= SEQUENCE {
        description                  OCTET STRING,
        clientSideValidationInfo     [0] SEQUENCE {
             validationType     OCTET STRING,
             properties         [0] SET OF SEQUENCE {
                  name      OCTET STRING,
                  value     OCTET STRING } OPTIONAL } OPTIONAL }
 

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
PasswordQualityRequirement(java.lang.String description) Creates a new password quality requirement object without any support for client-side validation.
PasswordQualityRequirement(java.lang.String description, java.lang.String clientSideValidationType, java.util.Map<java.lang.String,java.lang.String> clientSideValidationProperties) Creates a new password quality requirement object with optional support for client-side validation.

Method Summary

Modifier and Type	Method and Description
static PasswordQualityRequirement	decode(ASN1Element element) Decodes the provided ASN.1 element as a password quality requirement.
ASN1Element	encode() Encodes this password quality requirement to an ASN.1 element that may be included in LDAP protocol elements that may need to include it (e.g., a get password quality requirements extended response or a password validation details response control).
java.util.Map<java.lang.String,java.lang.String>	getClientSideValidationProperties() Retrieves a set of properties that may be used in the course of performing client-side validation for a proposed password.
java.lang.String	getClientSideValidationType() Retrieves a string that identifies the type of client-side validation that may be performed by applications in order to identify potential problems with a proposed password before sending it to the server.
java.lang.String	getDescription() Retrieves a user-friendly description of the constraints that a proposed password must satisfy in order to meet this requirement and be accepted by the server.
java.lang.String	toString() Retrieves a string representation of this password quality requirement.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this password quality requirement to the provided buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

PasswordQualityRequirement

public PasswordQualityRequirement(@NotNull
                                  java.lang.String description)

Creates a new password quality requirement object without any support for client-side validation.

Parameters:

description - A user-friendly description of the constraints that a proposed password must satisfy in order to meet this requirement and be accepted by the server. This must not be null.

PasswordQualityRequirement

public PasswordQualityRequirement(@NotNull
                                  java.lang.String description,
                                  @Nullable
                                  java.lang.String clientSideValidationType,
                                  @Nullable
                                  java.util.Map<java.lang.String,java.lang.String> clientSideValidationProperties)

Creates a new password quality requirement object with optional support for client-side validation.

Parameters:

description - A user-friendly description of the constraints that a proposed password must satisfy in order to meet this requirement and be accepted by the server. This must not be null.

clientSideValidationType - An optional string that identifies the type of validation associated with this requirement. Applications that support client-side validation and recognize this validation type can attempt to use their own logic in attempt to determine whether a proposed password may be rejected by the server because it does not satisfy this requirement. This may be null if no client-side validation is available for this requirement.

clientSideValidationProperties - An optional map of property names and values that may provide additional information that can be used for client-side validation. The properties that may be included depend on the validation type. This must be empty or null if the provided validation type is null. It may also be empty or null if no additional properties are required for the associated type of client-side validation.

Method Detail

getDescription

@NotNull
public java.lang.String getDescription()

Retrieves a user-friendly description of the constraints that a proposed password must satisfy in order to meet this requirement and be accepted by the server.

Returns:

A user-friendly description for this password quality requirement.

getClientSideValidationType

@Nullable
public java.lang.String getClientSideValidationType()

Retrieves a string that identifies the type of client-side validation that may be performed by applications in order to identify potential problems with a proposed password before sending it to the server. Client-side validation may not be available for all types of password quality requirements.

Returns:

The client side validation type for this password quality requirement, or null if client-side validation is not supported for this password quality requirement.

getClientSideValidationProperties

@NotNull
public java.util.Map<java.lang.String,java.lang.String> getClientSideValidationProperties()

Retrieves a set of properties that may be used in the course of performing client-side validation for a proposed password. The types of properties that may be included depend on the client-side validation type.

Returns:

A map of properties that may be used in the course of performing client-side validation, or an empty map if client-side validation is not available for this password quality requirement, or if no additional properties required for the associated type of client-side validation.

encode

@NotNull
public ASN1Element encode()

Encodes this password quality requirement to an ASN.1 element that may be included in LDAP protocol elements that may need to include it (e.g., a get password quality requirements extended response or a password validation details response control).

Returns:

An ASN.1-encoded representation of this password quality requirement.

decode

@NotNull
public static PasswordQualityRequirement decode(@NotNull
                                                         ASN1Element element)
                                                  throws LDAPException

Decodes the provided ASN.1 element as a password quality requirement.

Parameters:

element - The ASN.1 element to decode as a password quality requirement. It must not be null.

Returns:

The decoded password quality requirement.

Throws:

LDAPException - If a problem was encountered while attempting to decode the provided ASN.1 element as a password quality requirement.

toString

@NotNull
public java.lang.String toString()

Retrieves a string representation of this password quality requirement.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this password quality requirement.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer)

Appends a string representation of this password quality requirement to the provided buffer.

Parameters:

buffer - The buffer to which the information should be appended.