org.jscsi.parser.login

Class LoginRequestParser

java.lang.Object

org.jscsi.parser.AbstractMessageParser

org.jscsi.parser.InitiatorMessageParser

org.jscsi.parser.login.LoginRequestParser

public final class LoginRequestParser
extends InitiatorMessageParser

LoginRequestParser

This class parses a Login Request message defined in the iSCSI Standard (RFC3720).

After establishing a TCP connection between an initiator and a target, the initiator MUST start a Login Phase to gain further access to the target’s resources.

The Login Phase (see Chapter 5) consists of a sequence of Login Requests and Responses that carry the same Initiator Task Tag.

Login Requests are always considered as immediate.

The version number of the current draft is 0x00. As such, all devices MUST carry version 0x00 for both Version-min and Version-max.

Here the final flag has the following meaning: If set to 1, indicates that the initiator is ready to transit to the next stage.

If the T bit is set to 1 and NSG is FullFeaturePhase, then this also indicates that the initiator is ready for the Final Login Response (see Chapter 5).

T (Transit) Bit

If set to 1, indicates that the initiator is ready to transit to the next stage.

If the T bit is set to 1 and NSG is FullFeaturePhase, then this also indicates that the initiator is ready for the Final Login Response (see Chapter 5).

CmdSN

CmdSN is either the initial command sequence number of a session (for the first Login Request of a session - the "leading" login), or the command sequence number in the command stream if the login is for a new connection in an existing session.
Examples:

• Login on a leading connection - if the leading login carries the CmdSN 123, all other Login Requests in the same Login Phase carry the CmdSN 123 and the first non-immediate command in FullFeaturePhase also carries the CmdSN 123.
• Login on other than a leading connection - if the current CmdSN at the time the first login on the connection is issued is 500, then that PDU carries CmdSN=500. Subsequent Login Requests that are needed to complete this Login Phase may carry a CmdSN higher than 500 if non-immediate requests that were issued on other connections in the same session advance CmdSN.

If the Login Request is a leading Login Request, the target MUST use the value presented in CmdSN as the target value for ExpCmdSN.

ExpStatSN

For the first Login Request on a connection this is ExpStatSN for the old connection and this field is only valid if the Login Request restarts a connection (see Section 5.3.4 Connection Reinstatement). For subsequent Login Requests it is used to acknowledge the Login Responses with their increasing StatSN values.

Login Parameters (Data Segment)

The initiator MUST provide some basic parameters in order to enable the target to determine if the initiator may use the target’s resources and the initial text parameters for the security exchange. All the rules specified in Section 10.10.5 Text for text requests also hold for Login Requests. Keys and their explanations are listed in Chapter 11 (security negotiation keys) and Chapter 12 (operational parameter negotiation keys). All keys in Chapter 12, except for the X extension formats, MUST be supported by iSCSI initiators and targets. Keys in Chapter 11 only need to be supported when the function to which they refer is mandatory to implement.

Author:

Volker Wildi

Field Summary

Fields inherited from class org.jscsi.parser.InitiatorMessageParser

commandSequenceNumber, expectedStatusSequenceNumber

Fields inherited from class org.jscsi.parser.AbstractMessageParser

logicalUnitNumber, protocolDataUnit

Constructor Summary

Constructors

Constructor and Description
LoginRequestParser(ProtocolDataUnit initProtocolDataUnit) Default constructor, creates a new, empty LoginRequestParser object.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canHaveDigests() If this method returns true, then it indicates that this derived AbstractMessageParser instance can be protected by a digest.
protected void	checkIntegrity() This method checks, if all parsed fields are valid.
void	clear() This method sets all settings to their initial values.
protected void	deserializeBytes12to15(int line) Parse the bytes 12 till 15 in the Basic Header Segment.
protected void	deserializeBytes1to3(int line) Parse the bytes 1 till 3 in the Basic Header Segment.
protected void	deserializeBytes20to23(int line) Parse the bytes 20 till 23 in the Basic Header Segment.
int	getConnectionID() A unique ID for this connection within the session.
LoginStage	getCurrentStageNumber() Returns the Current Stage Number of this Login Request Message.
DataSegmentFactory.DataSegmentFormat	getDataSegmentFormat() If this method returns true, hen it indicates that the data segment data is interpreted as binary data.
ISID	getInitiatorSessionID() Returns the Initiator Session ID (ISID) of this LoginRequestParser object.
byte	getMaxVersion() Maximum Version number supported.
byte	getMinVersion() All Login Requests within the Login Phase MUST carry the same Version-min.
LoginStage	getNextStageNumber() Returns the Next Stage Number of this Login Request Message.
short	getTargetSessionIdentifyingHandle() Target Session Identifying Handle (TSIH) must be set in the first Login Request.
boolean	isContinueFlag() When set to 1, indicates that the text (set of key=value pairs) in this Login Request is not complete (it will be continued on subsequent Login Requests); otherwise, it indicates that this Login Request ends a set of key=value pairs.
protected int	serializeBytes12to15() Serializes the bytes 12 till 15 in the Basic Header Segment.
protected int	serializeBytes1to3() Serializes the bytes 1 till 3 in the Basic Header Segment.
protected int	serializeBytes20to23() Serializes the bytes 20 till 23 in the Basic Header Segment.
protected int	serializeBytes8to11() Serializes the bytes 8 till 11 in the Basic Header Segment.
void	setConnectionID(int initCID) Sets the new Connection ID of this LoginRequestParser object.
void	setContinueFlag(boolean initContinueFlag) Sets the new state of the Continue Flag of this LoginRequestParser obejct.
void	setCurrentStageNumber(LoginStage initCSG) Sets the new Current Stage Number of this LoginRequestParser object.
void	setInitiatorSessionID(ISID initISID) Sets the new Initiator Session ID (ISID) of this LoginRequestParser object.
void	setMaxVersion(byte initMaxVersion) Sets the new Maximum Version number of this LoginRequestParser object.
void	setMinVersion(byte initMinVersion) Sets the new Minimum Version number of this LoginRequestParser object.
void	setNextStageNumber(LoginStage initNSG) Sets the new Next Stage Number of this LoginRequestParser object.
void	setTargetSessionIdentifyingHandle(short initTSIH) Sets the new Target Session Identifying Handle of this LoginRequestParser object.
String	toString() This method concatenate all the fields of a derived parser to allow an easy generation of debug informations.

Methods inherited from class org.jscsi.parser.InitiatorMessageParser

deserializeBytes24to27, deserializeBytes28to31, deserializeBytes32to35, deserializeBytes36to39, deserializeBytes40to43, deserializeBytes44to47, getCommandSequenceNumber, getExpectedStatusSequenceNumber, getShortInfo, incrementSequenceNumber, serializeBytes24to27, serializeBytes28to31, serializeBytes32to35, serializeBytes36to39, serializeBytes40to43, serializeBytes44to47, setCommandSequenceNumber, setExpectedStatusSequenceNumber

Methods inherited from class org.jscsi.parser.AbstractMessageParser

canContainAdditionalHeaderSegments, deserializeBytes8to11, getLogicalUnitNumber, setLogicalUnitNumber

Methods inherited from class java.lang.Object

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

Constructor Detail

LoginRequestParser

public LoginRequestParser(ProtocolDataUnit initProtocolDataUnit)

Default constructor, creates a new, empty LoginRequestParser object.

Parameters:

initProtocolDataUnit - The reference ProtocolDataUnit instance, which contains this LoginRequestParser subclass object.

Method Detail

toString

public final String toString()

This method concatenate all the fields of a derived parser to allow an easy generation of debug informations.

Overrides:

toString in class InitiatorMessageParser

Returns:

The debug formatted string.

getDataSegmentFormat

public final DataSegmentFactory.DataSegmentFormat getDataSegmentFormat()

If this method returns true, hen it indicates that the data segment data is interpreted as binary data. Else the data segment data must be interpreted as Text Format.

Specified by:

getDataSegmentFormat in class AbstractMessageParser

Returns:

Returns a format defined by the DataSegmentFormat enumeration.

See Also:

DataSegmentFactory.DataSegmentFormat

canHaveDigests

public final boolean canHaveDigests()

If this method returns true, then it indicates that this derived AbstractMessageParser instance can be protected by a digest.

Overrides:

canHaveDigests in class AbstractMessageParser

Returns:

true, if the ProtocolDataUnit can be protected by a header and/or a data digest. Else false.

clear

public final void clear()

This method sets all settings to their initial values.

Overrides:

clear in class InitiatorMessageParser

getConnectionID

public final int getConnectionID()

A unique ID for this connection within the session.

All Login Requests within the Login Phase MUST carry the same CID.

The target MUST use the value presented with the first Login Request.

A Login Request with a non-zero TSIH and a CID equal to that of an existing connection implies a logout of the connection followed by a Login (see Section 5.3.4 Connection Reinstatement). For the details of the implicit Logout Request, see Section 10.14 Logout Request.

Returns:

The Connection ID of this LoginRequestParser object.

isContinueFlag

public final boolean isContinueFlag()

When set to 1, indicates that the text (set of key=value pairs) in this Login Request is not complete (it will be continued on subsequent Login Requests); otherwise, it indicates that this Login Request ends a set of key=value pairs. A Login Request with the C bit set to 1 MUST have the T bit set to 0.

Returns:

Returns true, if the Continue Bit is set. Else false.

getCurrentStageNumber

public final LoginStage getCurrentStageNumber()

Returns the Current Stage Number of this Login Request Message.

Through these fields, Current Stage (CSG) and Next Stage (NSG), the Login negotiation requests and responses are associated with a specific stage in the session (SecurityNegotiation, LoginOperationalNegotiation, FullFeaturePhase) and may indicate the next stage to which they want to move (see Chapter 5). The next stage value is only valid when the T bit is 1; otherwise, it is reserved.

The stage codes are:

• 0 - SecurityNegotiation
• 1 - LoginOperationalNegotiation
• 3 - FullFeaturePhase

All other codes are reserved.

Returns:

Number of the Current Stage.

See Also:

LoginStage

getInitiatorSessionID

public final ISID getInitiatorSessionID()

Returns the Initiator Session ID (ISID) of this LoginRequestParser object.

Returns:

Returns the Initiator Session ID (ISID) of this LoginRequestParser object.

See Also:

ISID

getMaxVersion

public final byte getMaxVersion()

Maximum Version number supported.

All Login Requests within the Login Phase MUST carry the same Version-max.

The target MUST use the value presented with the first Login Request.

Returns:

The maximum version of this login request message.

getMinVersion

public final byte getMinVersion()

All Login Requests within the Login Phase MUST carry the same Version-min. The target MUST use the value presented with the first Login Request.

Returns:

The minimum version of this login request message.

getNextStageNumber

public final LoginStage getNextStageNumber()

Returns the Next Stage Number of this Login Request Message.

Through these fields, Current Stage (CSG) and Next Stage (NSG), the Login negotiation requests and responses are associated with a specific stage in the session (SecurityNegotiation, LoginOperationalNegotiation, FullFeaturePhase) and may indicate the next stage to which they want to move (see Chapter 5). The next stage value is only valid when the T bit is 1; otherwise, it is reserved.

The stage codes are:

• 0 - SecurityNegotiation
• 1 - LoginOperationalNegotiation
• 3 - FullFeaturePhase

All other codes are reserved.

Returns:

The Number of the Next Stage.

See Also:

LoginStage

getTargetSessionIdentifyingHandle

public final short getTargetSessionIdentifyingHandle()

Target Session Identifying Handle (TSIH) must be set in the first Login Request. The reserved value 0 MUST be used on the first connection for a new session. Otherwise, the TSIH sent by the target at the conclusion of the successful login of the first connection for this session MUST be used. The TSIH identifies to the target the associated existing session for this new connection.

All Login Requests within a Login Phase MUST carry the same TSIH.

The target MUST check the value presented with the first Login Request and act as specified in Section 5.3.1 Login Phase Start.

Returns:

Returns the Target Session Identifying Handle of this LoginRequestParser object.

setConnectionID

public final void setConnectionID(int initCID)

Sets the new Connection ID of this LoginRequestParser object.

Parameters:

initCID - The new Connection ID.

See Also:

getConnectionID()

setContinueFlag

public final void setContinueFlag(boolean initContinueFlag)

Sets the new state of the Continue Flag of this LoginRequestParser obejct.

Parameters:

initContinueFlag - The new state of the Continue Flag.

See Also:

isContinueFlag()

setCurrentStageNumber

public final void setCurrentStageNumber(LoginStage initCSG)

Sets the new Current Stage Number of this LoginRequestParser object.

Parameters:

initCSG - The new Current Stage Number.

See Also:

getCurrentStageNumber()

setInitiatorSessionID

public final void setInitiatorSessionID(ISID initISID)

Sets the new Initiator Session ID (ISID) of this LoginRequestParser object.

Parameters:

initISID - The new Initiator Session ID (ISID).

setMaxVersion

public final void setMaxVersion(byte initMaxVersion)

Sets the new Maximum Version number of this LoginRequestParser object.

Parameters:

initMaxVersion - The new Maximum Version.

See Also:

getMaxVersion()

setMinVersion

public final void setMinVersion(byte initMinVersion)

Sets the new Minimum Version number of this LoginRequestParser object.

Parameters:

initMinVersion - The new Minimum Version.

See Also:

getMinVersion()

setNextStageNumber

public final void setNextStageNumber(LoginStage initNSG)

Sets the new Next Stage Number of this LoginRequestParser object.

Parameters:

initNSG - The new Next Stage Number.

See Also:

getNextStageNumber()

setTargetSessionIdentifyingHandle

public final void setTargetSessionIdentifyingHandle(short initTSIH)

Sets the new Target Session Identifying Handle of this LoginRequestParser object.

Parameters:

initTSIH - The new Target Session Identifying Handle.

deserializeBytes1to3

protected final void deserializeBytes1to3(int line)
                                   throws InternetSCSIException

Parse the bytes 1 till 3 in the Basic Header Segment.

Overrides:

deserializeBytes1to3 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

deserializeBytes12to15

protected final void deserializeBytes12to15(int line)
                                     throws InternetSCSIException

Parse the bytes 12 till 15 in the Basic Header Segment.

Overrides:

deserializeBytes12to15 in class AbstractMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

deserializeBytes20to23

protected void deserializeBytes20to23(int line)
                               throws InternetSCSIException

Parse the bytes 20 till 23 in the Basic Header Segment.

Overrides:

deserializeBytes20to23 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

checkIntegrity

protected final void checkIntegrity()
                             throws InternetSCSIException

This method checks, if all parsed fields are valid. Because there are several fields, which are reserved for future versions, and these must be zero. Is this the case an exception will be thrown.

Specified by:

checkIntegrity in class AbstractMessageParser

Throws:

InternetSCSIException - If the integrity is violated.

serializeBytes1to3

protected final int serializeBytes1to3()

Serializes the bytes 1 till 3 in the Basic Header Segment.

Overrides:

serializeBytes1to3 in class InitiatorMessageParser

Returns:

The serialized byte representation.

serializeBytes8to11

protected final int serializeBytes8to11()
                                 throws InternetSCSIException

Serializes the bytes 8 till 11 in the Basic Header Segment.

Overrides:

serializeBytes8to11 in class AbstractMessageParser

Returns:

The serialized byte representation.

Throws:

InternetSCSIException - if any violation of the iSCSI Standard (RFC3720) occurs.

serializeBytes12to15

protected final int serializeBytes12to15()

Serializes the bytes 12 till 15 in the Basic Header Segment.

Overrides:

serializeBytes12to15 in class AbstractMessageParser

Returns:

The serialized byte representation.

serializeBytes20to23

protected final int serializeBytes20to23()

Serializes the bytes 20 till 23 in the Basic Header Segment.

Overrides:

serializeBytes20to23 in class InitiatorMessageParser

Returns:

The serialized byte representation.