Package org.forgerock.opendj.ldap.messages

Interface BindRequest

  • All Superinterfaces:
    ProtocolOp, Request
    public interface BindRequest
extends Request
    The Bind operation allows authentication information to be exchanged between the client and server. The Bind operation should be thought of as the "authenticate" operation.

    • Field Detail

      • AUTHENTICATION_TYPE_SIMPLE

        static final byte AUTHENTICATION_TYPE_SIMPLE
        The authentication type value (0x80) reserved for simple authentication.
        See Also:
        Constant Field Values

      • AUTHENTICATION_TYPE_SASL

        static final byte AUTHENTICATION_TYPE_SASL
        The authentication type value (0xA3) reserved for SASL authentication.
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_ANONYMOUS

        static final String SASL_MECHANISM_NAME_ANONYMOUS
        The name of the SASL mechanism that uses anonymous access and having the name "ANONYMOUS".
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_CRAM_MD5

        static final String SASL_MECHANISM_NAME_CRAM_MD5
        The name of the SASL mechanism that uses CRAM-MD5 authentication and having the name "CRAM-MD5".
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_DIGEST_MD5

        static final String SASL_MECHANISM_NAME_DIGEST_MD5
        The name of the SASL mechanism that uses DIGEST-MD5 authentication and having the name "DIGEST-MD5".
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_PLAIN

        static final String SASL_MECHANISM_NAME_PLAIN
        The name of the SASL mechanism that uses PLAIN authentication and having the name "PLAIN".
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_EXTERNAL

        static final String SASL_MECHANISM_NAME_EXTERNAL
        The name of the SASL mechanism that uses external authentication and having the name "EXTERNAL".
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_GSSAPI

        static final String SASL_MECHANISM_NAME_GSSAPI
        The name of the SASL mechanism that uses GSS-API authentication and having the name "GSSAPI".
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_SCRAM_SHA_256

        static final String SASL_MECHANISM_NAME_SCRAM_SHA_256
        The name of the SASL mechanism that uses SCRAM-SHA-256 authentication and having the name "SCRAM-SHA-256".
        See Also:
        Constant Field Values

      • SASL_MECHANISM_NAME_SCRAM_SHA_512

        static final String SASL_MECHANISM_NAME_SCRAM_SHA_512
        The name of the SASL mechanism that uses SCRAM-SHA-512 authentication and having the name "SCRAM-SHA-512".
        See Also:
        Constant Field Values

    • Method Detail

      • getVersion

        int getVersion()
        Returns the version of the protocol to be used at the LDAP message layer. There is no version negotiation. The client sets this field to the version it desires. If the server does not support the specified version then it will respond with a result whose error code is ResultCode.PROTOCOL_ERROR.

        By default LDAP version 3 will be used which is the most recent LDAP version and the one recommended for all client applications. Furthermore, OpenDJ only has partial support for LDAPv2.

        Returns:
        The version of the protocol to be used at the LDAP message layer.

      • setVersion

        BindRequest setVersion​(int version)
        Sets the version of the protocol to be used at the LDAP message layer. There is no version negotiation. The client sets this field to the version it desires. If the server does not support the specified version then it will respond with a result whose error code is ResultCode.PROTOCOL_ERROR.

        By default LDAP version 3 will be used which is the most recent LDAP version and the one recommended for all client applications. Furthermore, OpenDJ only has partial support for LDAPv2.

        Parameters:
        version - The version of the protocol to be used at the LDAP message layer.
        Returns:
        This bind request.
        Throws:
        IllegalArgumentException - If version is less than 1 or greater than 127.
        UnsupportedOperationException - If this bind request does not permit the version to be set.

      • getName

        Dn getName()
        Returns the name of the Directory object that the client wishes to bind as. The name may be empty (but never null) when used for anonymous binds, or when using SASL authentication. The server shall not dereference any aliases in locating the named object.

        The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

        Returns:
        The name of the Directory object that the client wishes to bind as. May be empty, but cannot be null.

      • setName

        BindRequest setName​(Dn name)
        Sets the name of the Directory object that the client wishes to bind as. The name may be empty (but never null when used for of anonymous binds, or when using SASL authentication. The server shall not dereference any aliases in locating the named object.

        The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

        Parameters:
        name - The name of the Directory object that the client wishes to bind as. May be empty, but cannot be null.
        Returns:
        This bind request.
        Throws:
        UnsupportedOperationException - If this bind request does not permit the distinguished name to be set.
        NullPointerException - If name was null.

      • getAuthenticationType

        byte getAuthenticationType()
        Returns the authentication mechanism identifier for this bind request as defined by the LDAP protocol. Note that the value AUTHENTICATION_TYPE_SIMPLE (0x80) is reserved for simple authentication and the value AUTHENTICATION_TYPE_SASL ( 0xA3) is reserved for SASL authentication.
        Returns:
        The authentication mechanism identifier.

      • getAuthenticationValue

        byte[] getAuthenticationValue()
        Returns a defensive copy of the encoded authentication value for this bind request as defined by the LDAP protocol. For simple authentication the authentication value is the byte representation of the password. For SASL authentication the authentication value is an ASN.1 encoded sequence comprising of the SASL mechanism name and the optional SASL mechanism specific credentials.
        Returns:
        A defensive copy of the encoded authentication value for this bind request as defined by the LDAP protocol.

      • setAuthenticationTypeAndValue

        BindRequest setAuthenticationTypeAndValue​(byte type,
                                          byte[] value)
                                   throws IOException
        Sets the authentication type and value. If type is equal to AUTHENTICATION_TYPE_SIMPLE then the value will be interpreted as the password. If type is equal to AUTHENTICATION_TYPE_SASL then the value will be interpreted as the encoded SASL mechanism and credentials. Otherwise, the value will be interpreted as an unrecognized extended authentication value.
        Parameters:
        type - The authentication mechanism identifier.
        value - The encoded authentication value for this bind request as defined by the LDAP protocol, which may be an empty array but must not be null. The value will be defensively copied.
        Returns:
        This bind request.
        Throws:
        IOException - If the authentication type is AUTHENTICATION_TYPE_SASL and the value could not be decoded as an encoded SASL mechanism and credentials.
        UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.
        NullPointerException - If value was null.

      • getSimplePassword

        byte[] getSimplePassword()
        Returns a defensive copy of the simple bind password, or null if the authentication type is not AUTHENTICATION_TYPE_SIMPLE.
        Returns:
        A defensive copy of the simple bind password, or null if the authentication type is not AUTHENTICATION_TYPE_SIMPLE.

      • setSimplePassword

        BindRequest setSimplePassword​(byte[] password)
        Sets the authentication type to AUTHENTICATION_TYPE_SIMPLE and the authentication value to a copy of the provided password.
        Parameters:
        password - The non-null simple bind password, which will be defensively copied.
        Returns:
        This bind request.
        Throws:
        UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.
        NullPointerException - If password was null.

      • getSaslCredentials

        byte[] getSaslCredentials()
        Returns a defensive copy of the optional SASL credentials, or null if the authentication type is not AUTHENTICATION_TYPE_SASL or if the SASL credentials are not present.
        Returns:
        A defensive copy of the optional SASL credentials, or null if the authentication type is not AUTHENTICATION_TYPE_SASL or if the SASL credentials are not present.

      • getSaslClient

        SaslClient getSaslClient()
        Returns the SaslClient that will be responsible for continuing the SASL challenge-response sequence as well as potentially installing a SASL security layer once the bind sequence completes, or null if a no SaslClient has been provided.

        A SaslClient is only required if the application is performing SASL authentication and wishes the network layer to drive the complete challenge-response sequence. An application may choose to drive the SASL bind sequence itself, but the application:

        1. will not be able to control where bind requests are sent if load-balancing is active,
        2. nor will it be able to install a security layer upon completion of the bind sequence.
        Returns:
        The SaslClient that will be responsible for continuing the SASL challenge-response sequence, as well as potentially installing a SASL security layer once the bind sequence completes, or null if none has been provided.
        See Also:
        setSaslMechanismAndCredentials(SaslClient)

      • setSaslMechanismAndCredentials

        BindRequest setSaslMechanismAndCredentials​(String mechanism,
                                           byte[] credentials)
        Sets the authentication type to AUTHENTICATION_TYPE_SASL, the SASL mechanism name, and the optional SASL credentials.
        Parameters:
        mechanism - The SASL mechanism name, such as SASL_MECHANISM_NAME_PLAIN.
        credentials - The optional SASL credentials which will be defensively copied if provided.
        Returns:
        This bind request.
        Throws:
        UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.
        NullPointerException - If mechanism was null.

      • setSaslMechanismAndCredentials

        BindRequest setSaslMechanismAndCredentials​(SaslClient saslClient)
        Configures this bind request for SASL authentication using the provided SaslClient. The authentication type will be set to AUTHENTICATION_TYPE_SASL, the SASL mechanism name will be obtained from the SaslClient, and the SASL credentials will be derived from the SaslClient if it has an initial response, otherwise they will be left undefined.

        This method should be used if the application is performing SASL authentication and wishes the network layer to drive the complete challenge-response sequence. An application may choose to drive the SASL bind sequence itself, but the application a) will not be able to control where bind requests are sent if load-balancing is active, b) nor will it be able to install a security layer upon completion of the bind sequence if one is negotiated.

        Parameters:
        saslClient - The SaslClient that will be responsible for continuing the SASL challenge-response sequence, as well as potentially installing a SASL security layer once the bind sequence completes.
        Returns:
        This bind request.
        Throws:
        IllegalArgumentException - If the provided SASL client has not been configured correctly.
        UnsupportedOperationException - If this bind request does not permit the SaslClient to be set.
        NullPointerException - If saslClient was null.

      • evaluateSaslChallenge

        BindRequest evaluateSaslChallenge​(byte[] serverSaslCredentials)
                           throws SaslException
        Evaluates the provided SASL credentials (challenge) returned by the server and creates the next SASL bind request that should be sent to the server in order to continue or complete the SASL authentication sequence. This method may only be called if this request has been configured to use a SaslClient.
        Parameters:
        serverSaslCredentials - The non-null SASL challenge sent from the server, which may be empty.
        Returns:
        The next SASL bind request to be sent to the server, or null if the SASL bind sequence has completed.
        Throws:
        SaslException - If an error occurred while evaluating the challenge or generating a response.
        IllegalStateException - If this bind request has not been configured to use a SaslClient.
        NullPointerException - If serverSaslCredentials was null.
        See Also:
        setSaslMechanismAndCredentials(SaslClient)

      • hasNegotiatedSaslQop

        boolean hasNegotiatedSaslQop()
        Returns true if the SASL bind sequence has negotiated a SASL security layer using Quality of Protection (QOP). This method may only be called if this request has been configured to use a SaslClient and the SASL bind sequence has completed (the previous call to evaluateSaslChallenge(byte[]) returned null).
        Returns:
        true if the SASL bind sequence has negotiated a SASL security layer (QOP).
        Throws:
        IllegalStateException - If this bind request has not been configured to use a SaslClient or the SASL bind sequence has not completed.
        See Also:
        setSaslMechanismAndCredentials(SaslClient)

      • addControl

        BindRequest addControl​(Control control)
        Description copied from interface: ProtocolOp
        Adds the provided control to this protocol-op.
        Specified by:
        addControl in interface ProtocolOp
        Specified by:
        addControl in interface Request
        Parameters:
        control - The control to be added to this protocol-op.
        Returns:
        This protocol-op.

      • getControl

        <C extends Control> C getControl​(ControlDecoder<C> decoder,
                                 DecodeOptions options)
                          throws DecodeException
        Description copied from interface: ProtocolOp
        Decodes and returns the first control in this protocol-op having an OID corresponding to the provided control decoder.
        Specified by:
        getControl in interface ProtocolOp
        Type Parameters:
        C - The type of control to be decoded and returned.
        Parameters:
        decoder - The control decoder.
        options - The set of decode options which should be used when decoding the control.
        Returns:
        The decoded control, or null if the control is not included with this protocol-op.
        Throws:
        DecodeException - If the control could not be decoded because it was malformed in some way (e.g. the control value was missing, or its content could not be decoded).

      • getControls

        List<Control> getControls()
        Description copied from interface: ProtocolOp
        Returns a List containing the controls included with this protocol-op. The returned List may be modified if permitted by this protocol-op.
        Specified by:
        getControls in interface ProtocolOp
        Returns:
        A List containing the controls.

      • destroy

        void destroy()
        Destroys the credentials contained within this bind request. This method does not dispose the SaslClient. Instead the underlying network layer will dispose of the SaslClient when it is no longer in use. This bind request can no longer be used once this method returns.