RFC 7143
Internet Small Computer System Interface (iSCSI) Protocol (Consolidated)
Pages: 295
Proposed Standard
Obsoletes: 3720 3980 4850 5048
Updates: 3721
Proposed Standard
Obsoletes: 3720 3980 4850 5048
Updates: 3721
Part 8 of 10 – Pages 199 to 229
11.12.5. ISID
This is an initiator-defined component of the session identifier and is structured as follows (see Section 10.1.1 for details): Byte/ 0 | 1 | 2 | 3 | / | | | | |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| +---------------+---------------+---------------+---------------+ 8| T | A | B | C | +---------------+---------------+---------------+---------------+ 12| D | +---------------+---------------+ The T field identifies the format and usage of A, B, C, and D as indicated below: T 00b OUI-Format A and B: 22-bit OUI (the I/G and U/L bits are omitted) C and D: 24-bit Qualifier 01b EN: Format (IANA Enterprise Number) A: Reserved B and C: EN (IANA Enterprise Number) D: Qualifier 10b "Random" A: Reserved B and C: Random D: Qualifier 11b A, B, C, and D: Reserved For the T field values 00b and 01b, a combination of A and B (for 00b) or B and C (for 01b) identifies the vendor or organization whose component (software or hardware) generates this ISID. A vendor or
organization with one or more OUIs, or one or more Enterprise Numbers, MUST use at least one of these numbers and select the appropriate value for the T field when its components generate ISIDs. An OUI or EN MUST be set in the corresponding fields in network byte order (byte big-endian). If the T field is 10b, B and C are set to a random 24-bit unsigned integer value in network byte order (byte big-endian). See [RFC3721] for how this affects the principle of "conservative reuse". The Qualifier field is a 16-bit or 24-bit unsigned integer value that provides a range of possible values for the ISID within the selected namespace. It may be set to any value within the constraints specified in the iSCSI protocol (see Sections 4.4.3 and 10.1.1). The T field value of 11b is reserved. If the ISID is derived from something assigned to a hardware adapter or interface by a vendor as a preset default value, it MUST be configurable to a value assigned according to the SCSI port behavior desired by the system in which it is installed (see Sections 10.1.1 and 10.1.2). The resultant ISID MUST also be persistent over power cycles, reboot, card swap, etc.11.12.6. TSIH
The 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 6.3.1.11.12.7. Connection ID (CID)
The CID provides 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 6.3.4). For details regarding the implicit Logout Request, see Section 11.14.11.12.8. CmdSN
The 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 the Full Feature Phase 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 the CmdSN. If the Login Request is a leading Login Request, the target MUST use the value presented in the CmdSN as the target value for the ExpCmdSN.11.12.9. ExpStatSN
For the first Login Request on a connection, this is the ExpStatSN for the old connection, and this field is only valid if the Login Request restarts a connection (see Section 6.3.4). For subsequent Login Requests, it is used to acknowledge the Login Responses with their increasing StatSN values.11.12.10. Login Parameters
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 11.10.5 for Text Requests also hold for Login Requests. Keys and their explanations are listed in Section 12 (security negotiation keys) and in Section 13 (operational
parameter negotiation keys). All keys listed in Section 13, except for the X extension formats, MUST be supported by iSCSI initiators and targets. Keys listed in Section 12 only need to be supported when the function to which they refer is mandatory to implement.11.13. Login Response
The Login Response indicates the progress and/or end of the Login Phase. Byte/ 0 | 1 | 2 | 3 | / | | | | |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| +---------------+---------------+---------------+---------------+ 0|.|.| 0x23 |T|C|.|.|CSG|NSG| Version-max |Version-active | +---------------+---------------+---------------+---------------+ 4|TotalAHSLength | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| ISID | + +---------------+---------------+ 12| | TSIH | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag | +---------------+---------------+---------------+---------------+ 20| Reserved | +---------------+---------------+---------------+---------------+ 24| StatSN | +---------------+---------------+---------------+---------------+ 28| ExpCmdSN | +---------------+---------------+---------------+---------------+ 32| MaxCmdSN | +---------------+---------------+---------------+---------------+ 36| Status-Class | Status-Detail | Reserved | +---------------+---------------+---------------+---------------+ 40/ Reserved / +/ / +---------------+---------------+---------------+---------------+ 48/ DataSegment - Login Parameters in Text Request Format / +/ / +---------------+---------------+---------------+---------------+11.13.1. Version-max
This is the highest version number supported by the target. All Login Responses within the Login Phase MUST carry the same Version-max.
The initiator MUST use the value presented as a response to the first Login Request.11.13.2. Version-active
Version-active indicates the highest version supported by the target and initiator. If the target does not support a version within the range specified by the initiator, the target rejects the login and this field indicates the lowest version supported by the target. All Login Responses within the Login Phase MUST carry the same Version-active. The initiator MUST use the value presented as a response to the first Login Request.11.13.3. TSIH
The TSIH is the target-assigned session-identifying handle. Its internal format and content are not defined by this protocol, except for the value 0, which is reserved. With the exception of the Login Final-Response in a new session, this field should be set to the TSIH provided by the initiator in the Login Request. For a new session, the target MUST generate a non-zero TSIH and ONLY return it in the Login Final-Response (see Section 6.3).11.13.4. StatSN
For the first Login Response (the response to the first Login Request), this is the starting status sequence number for the connection. The next response of any kind -- including the next Login Response, if any, in the same Login Phase -- will carry this number + 1. This field is only valid if the Status-Class is 0.11.13.5. Status-Class and Status-Detail
The Status returned in a Login Response indicates the execution status of the Login Phase. The status includes: Status-Class Status-Detail A Status-Class of 0 indicates success. A non-zero Status-Class indicates an exception. In this case, Status-Class is sufficient for a simple initiator to use when handling exceptions, without having to look at the Status-Detail.
The Status-Detail allows finer-grained exception handling for more
sophisticated initiators and for better information for logging.
The Status-Classes are as follows:
0 Success - indicates that the iSCSI target successfully
received, understood, and accepted the request. The numbering
fields (StatSN, ExpCmdSN, MaxCmdSN) are only valid if Status-
Class is 0.
1 Redirection - indicates that the initiator must take further
action to complete the request. This is usually due to the
target moving to a different address. All of the redirection
Status-Class responses MUST return one or more text key
parameters of the type "TargetAddress", which indicates the
target's new address. A redirection response MAY be issued by
a target prior to or after completing a security negotiation if
a security negotiation is required. A redirection SHOULD be
accepted by an initiator, even without having the target
complete a security negotiation if any security negotiation is
required, and MUST be accepted by the initiator after the
completion of the security negotiation if any security
negotiation is required.
2 Initiator Error (not a format error) - indicates that the
initiator most likely caused the error. This MAY be due to a
request for a resource for which the initiator does not have
permission. The request should not be tried again.
3 Target Error - indicates that the target sees no errors in the
initiator's Login Request but is currently incapable of
fulfilling the request. The initiator may retry the same Login
Request later.
The table below shows all of the currently allocated status codes.
The codes are in hexadecimal; the first byte is the Status-Class, and
the second byte is the status detail.
-----------------------------------------------------------------
Status | Code | Description
|(hex) |
-----------------------------------------------------------------
Success | 0000 | Login is proceeding OK (*1).
-----------------------------------------------------------------
Target moved | 0101 | The requested iSCSI Target Name (ITN)
temporarily | | has temporarily moved
| | to the address provided.
-----------------------------------------------------------------
Target moved | 0102 | The requested ITN has permanently moved
permanently | | to the address provided.
-----------------------------------------------------------------
Initiator | 0200 | Miscellaneous iSCSI initiator
error | | errors.
-----------------------------------------------------------------
Authentication| 0201 | The initiator could not be
failure | | successfully authenticated or target
| | authentication is not supported.
-----------------------------------------------------------------
Authorization | 0202 | The initiator is not allowed access
failure | | to the given target.
-----------------------------------------------------------------
Not found | 0203 | The requested ITN does not
| | exist at this address.
-----------------------------------------------------------------
Target removed| 0204 | The requested ITN has been removed, and
| | no forwarding address is provided.
-----------------------------------------------------------------
Unsupported | 0205 | The requested iSCSI version range is
version | | not supported by the target.
-----------------------------------------------------------------
Too many | 0206 | Too many connections on this SSID.
connections | |
-----------------------------------------------------------------
Missing | 0207 | Missing parameters (e.g., iSCSI
parameter | | Initiator Name and/or Target Name).
-----------------------------------------------------------------
Can't include | 0208 | Target does not support session
in session | | spanning to this connection (address).
-----------------------------------------------------------------
Session type | 0209 | Target does not support this type of
not supported | | session or not from this initiator.
-----------------------------------------------------------------
Session does | 020a | Attempt to add a connection
not exist | | to a non-existent session.
-----------------------------------------------------------------
Invalid during| 020b | Invalid request type during login.
login | |
-----------------------------------------------------------------
Target error | 0300 | Target hardware or software error.
-----------------------------------------------------------------
Service | 0301 | The iSCSI service or target is not
unavailable | | currently operational.
-----------------------------------------------------------------
Out of | 0302 | The target has insufficient session,
resources | | connection, or other resources.
-----------------------------------------------------------------
(*1) If the response T bit is set to 1 in both the request and the
matching response, and the NSG is set to FullFeaturePhase in
both the request and the matching response, the Login Phase is
finished, and the initiator may proceed to issue SCSI commands.
If the Status-Class is not 0, the initiator and target MUST close the
TCP connection.
If the target wishes to reject the Login Request for more than one
reason, it should return the primary reason for the rejection.
11.13.6. T (Transit) Bit
The T bit is set to 1 as an indicator of the end of the stage. If
the T bit is set to 1 and the NSG is set to FullFeaturePhase, then
this is also the Login Final-Response (see Section 6.3). A T bit of
0 indicates a "partial" response, which means "more negotiation
needed".
A Login Response with the T bit set to 1 MUST NOT contain key=value
pairs that may require additional answers from the initiator within
the same stage.
If the Status-Class is 0, the T bit MUST NOT be set to 1 if the T bit
in the request was set to 0.
11.13.7. C (Continue) Bit
When set to 1, this bit indicates that the text (set of key=value
pairs) in this Login Response is not complete (it will be continued
on subsequent Login Responses); otherwise, it indicates that this
Login Response ends a set of key=value pairs. A Login Response with
the C bit set to 1 MUST have the T bit set to 0.
11.13.8. Login Parameters
The target MUST provide some basic parameters in order to enable the initiator to determine if it is connected to the correct port and the initial text parameters for the security exchange. All the rules specified in Section 11.11.6 for Text Responses also hold for Login Responses. Keys and their explanations are listed in Section 12 (security negotiation keys) and in Section 13 (operational parameter negotiation keys). All keys listed in Section 13, except for the X extension formats, MUST be supported by iSCSI initiators and targets. Keys listed in Section 12 only need to be supported when the function to which they refer is mandatory to implement.11.14. Logout Request
The Logout Request is used to perform a controlled closing of a connection. An initiator MAY use a Logout Request to remove a connection from a session or to close an entire session. After sending the Logout Request PDU, an initiator MUST NOT send any new iSCSI requests on the closing connection. If the Logout Request is intended to close the session, new iSCSI requests MUST NOT be sent on any of the connections participating in the session. When receiving a Logout Request with the reason code "close the connection" or "close the session", the target MUST terminate all pending commands, whether acknowledged via the ExpCmdSN or not, on that connection or session, respectively. When receiving a Logout Request with the reason code "remove the connection for recovery", the target MUST discard all requests not yet acknowledged via the ExpCmdSN that were issued on the specified connection and suspend all data/status/R2T transfers on behalf of pending commands on the specified connection. The target then issues the Logout Response and half-closes the TCP connection (sends FIN). After receiving the Logout Response and attempting to receive the FIN (if still possible), the initiator MUST completely close the logging-out connection. For the terminated commands, no additional responses should be expected. A Logout for a CID may be performed on a different transport connection when the TCP connection for the CID has already been terminated. In such a case, only a logical "closing" of the iSCSI connection for the CID is implied with a Logout.
All commands that were not terminated or not completed (with status) and acknowledged when the connection is closed completely can be reassigned to a new connection if the target supports connection recovery. If an initiator intends to start recovery for a failing connection, it MUST use the Logout Request to "clean up" the target end of a failing connection and enable recovery to start, or use the Login Request with a non-zero TSIH and the same CID on a new connection for the same effect. In sessions with a single connection, the connection can be closed and then a new connection reopened. A connection reinstatement login can be used for recovery (see Section 6.3.4). A successful completion of a Logout Request with the reason code "close the connection" or "remove the connection for recovery" results at the target in the discarding of unacknowledged commands received on the connection being logged out. These are commands that have arrived on the connection being logged out but that have not been delivered to SCSI because one or more commands with a smaller CmdSN have not been received by iSCSI. See Section 4.2.2.1. The resulting holes in the command sequence numbers will have to be handled by appropriate recovery (see Section 7), unless the session is also closed. The entire logout discussion in this section is also applicable for an implicit Logout realized by way of a connection reinstatement or session reinstatement. When a Login Request performs an implicit Logout, the implicit Logout is performed as if having the reason codes specified below: Reason Code Type of Implicit Logout ------------------------------------------------------------- 0 session reinstatement 1 connection reinstatement when the operational ErrorRecoveryLevel < 2 2 connection reinstatement when the operational ErrorRecoveryLevel = 2
Byte/ 0 | 1 | 2 | 3 |
/ | | | |
|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
+---------------+---------------+---------------+---------------+
0|.|I| 0x06 |1| Reason Code | Reserved |
+---------------+---------------+---------------+---------------+
4|TotalAHSLength | DataSegmentLength |
+---------------------------------------------------------------+
8/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
16| Initiator Task Tag |
+---------------+---------------+---------------+---------------+
20| CID or Reserved | Reserved |
+---------------+---------------+---------------+---------------+
24| CmdSN |
+---------------+---------------+---------------+---------------+
28| ExpStatSN |
+---------------+---------------+---------------+---------------+
32/ Reserved /
+/ /
+---------------+---------------+---------------+---------------+
48| Header-Digest (optional) |
+---------------+---------------+---------------+---------------+
11.14.1. Reason Code
The Reason Code field indicates the reason for Logout as follows:
0 - close the session. All commands associated with the
session (if any) are terminated.
1 - close the connection. All commands associated with the
connection (if any) are terminated.
2 - remove the connection for recovery. The connection is
closed, and all commands associated with it, if any, are
to be prepared for a new allegiance.
All other values are reserved.
11.14.2. TotalAHSLength and DataSegmentLength
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0.
11.14.3. CID
This is the connection ID of the connection to be closed (including closing the TCP stream). This field is only valid if the reason code is not "close the session".11.14.4. ExpStatSN
This is the last ExpStatSN value for the connection to be closed.11.14.5. Implicit Termination of Tasks
A target implicitly terminates the active tasks due to the iSCSI protocol in the following cases: a) When a connection is implicitly or explicitly logged out with the reason code "close the connection" and there are active tasks allegiant to that connection. b) When a connection fails and eventually the connection state times out (state transition M1 in Section 8.2.2) and there are active tasks allegiant to that connection. c) When a successful recovery Logout is performed while there are active tasks allegiant to that connection and those tasks eventually time out after the Time2Wait and Time2Retain periods without allegiance reassignment. d) When a connection is implicitly or explicitly logged out with the reason code "close the session" and there are active tasks in that session. If the tasks terminated in any of the above cases are SCSI tasks, they must be internally terminated as if with CHECK CONDITION status. This status is only meaningful for appropriately handling the internal SCSI state and SCSI side effects with respect to ordering, because this status is never communicated back as a terminating status to the initiator. However, additional actions may have to be taken at the SCSI level, depending on the SCSI context as defined by the SCSI standards (e.g., queued commands and ACA; UA for the next command on the I_T nexus in cases a), b), and c) above). After the tasks are terminated, the target MUST report a Unit Attention condition on the next command processed on any connection for each affected I_T_L nexus with the status of CHECK CONDITION, the ASC/ASCQ value of 47h/7Fh ("SOME COMMANDS CLEARED BY ISCSI PROTOCOL EVENT"), etc.; see [SPC3].
11.15. Logout Response
The Logout Response is used by the target to indicate if the cleanup operation for the connection(s) has completed. After Logout, the TCP connection referred by the CID MUST be closed at both ends (or all connections must be closed if the logout reason was session close). Byte/ 0 | 1 | 2 | 3 | / | | | | |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| +---------------+---------------+---------------+---------------+ 0|.|.| 0x26 |1| Reserved | Response | Reserved | +---------------+---------------+---------------+---------------+ 4|TotalAHSLength | DataSegmentLength | +---------------------------------------------------------------+ 8/ Reserved / +/ / +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag | +---------------+---------------+---------------+---------------+ 20| Reserved | +---------------+---------------+---------------+---------------+ 24| StatSN | +---------------+---------------+---------------+---------------+ 28| ExpCmdSN | +---------------+---------------+---------------+---------------+ 32| MaxCmdSN | +---------------+---------------+---------------+---------------+ 36| Reserved | +---------------------------------------------------------------+ 40| Time2Wait | Time2Retain | +---------------+---------------+---------------+---------------+ 44| Reserved | +---------------+---------------+---------------+---------------+ 48| Header-Digest (optional) | +---------------+---------------+---------------+---------------+
11.15.1. Response
Response field settings are as follows: 0 - connection or session closed successfully. 1 - CID not found. 2 - connection recovery is not supported (i.e., the Logout reason code was "remove the connection for recovery" and the target does not support it as indicated by the operational ErrorRecoveryLevel). 3 - cleanup failed for various reasons.11.15.2. TotalAHSLength and DataSegmentLength
For this PDU, TotalAHSLength and DataSegmentLength MUST be 0.11.15.3. Time2Wait
If the Logout response code is 0 and the operational ErrorRecoveryLevel is 2, this is the minimum amount of time, in seconds, to wait before attempting task reassignment. If the Logout response code is 0 and the operational ErrorRecoveryLevel is less than 2, this field is to be ignored. This field is invalid if the Logout response code is 1. If the Logout response code is 2 or 3, this field specifies the minimum time to wait before attempting a new implicit or explicit logout. If Time2Wait is 0, the reassignment or a new Logout may be attempted immediately.11.15.4. Time2Retain
If the Logout response code is 0 and the operational ErrorRecoveryLevel is 2, this is the maximum amount of time, in seconds, after the initial wait (Time2Wait) that the target waits for the allegiance reassignment for any active task, after which the task state is discarded. If the Logout response code is 0 and the operational ErrorRecoveryLevel is less than 2, this field is to be ignored. This field is invalid if the Logout response code is 1.
If the Logout response code is 2 or 3, this field specifies the maximum amount of time, in seconds, after the initial wait (Time2Wait) that the target waits for a new implicit or explicit logout. If it is the last connection of a session, the whole session state is discarded after Time2Retain. If Time2Retain is 0, the target has already discarded the connection (and possibly the session) state along with the task states. No reassignment or Logout is required in this case.11.16. SNACK Request
Byte/ 0 | 1 | 2 | 3 | / | | | | |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| +---------------+---------------+---------------+---------------+ 0|.|.| 0x10 |1|.|.|.| Type | Reserved | +---------------+---------------+---------------+---------------+ 4|TotalAHSLength | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| LUN or Reserved | + + 12| | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag or 0xffffffff | +---------------+---------------+---------------+---------------+ 20| Target Transfer Tag or SNACK Tag or 0xffffffff | +---------------+---------------+---------------+---------------+ 24| Reserved | +---------------+---------------+---------------+---------------+ 28| ExpStatSN | +---------------+---------------+---------------+---------------+ 32/ Reserved / +/ / +---------------+---------------+---------------+---------------+ 40| BegRun | +---------------------------------------------------------------+ 44| RunLength | +---------------------------------------------------------------+ 48| Header-Digest (optional) | +---------------+---------------+---------------+---------------+ If the implementation supports ErrorRecoveryLevel greater than zero, it MUST support all SNACK types.
The SNACK is used by the initiator to request the retransmission of
numbered responses, data, or R2T PDUs from the target. The SNACK
Request indicates the numbered responses or data "runs" whose
retransmission is requested, where the run starts with the first
StatSN, DataSN, or R2TSN whose retransmission is requested and
indicates the number of Status, Data, or R2T PDUs requested,
including the first. 0 has special meaning when used as a starting
number and length:
- When used in RunLength, it means all PDUs starting with the
initial.
- When used in both BegRun and RunLength, it means all
unacknowledged PDUs.
The numbered response(s) or R2T(s) requested by a SNACK MUST be
delivered as exact replicas of the ones that the target transmitted
originally, except for the fields ExpCmdSN, MaxCmdSN, and ExpDataSN,
which MUST carry the current values. R2T(s)requested by SNACK MUST
also carry the current value of the StatSN.
The numbered Data-In PDUs requested by a Data SNACK MUST be delivered
as exact replicas of the ones that the target transmitted originally,
except for the fields ExpCmdSN and MaxCmdSN, which MUST carry the
current values; and except for resegmentation (see Section 11.16.3).
Any SNACK that requests a numbered response, data, or R2T that was
not sent by the target or was already acknowledged by the initiator
MUST be rejected with a reason code of "Protocol Error".
11.16.1. Type
This field encodes the SNACK function as follows:
0 - Data/R2T SNACK: requesting retransmission of one or more
Data-In or R2T PDUs.
1 - Status SNACK: requesting retransmission of one or more
numbered responses.
2 - DataACK: positively acknowledges Data-In PDUs.
3 - R-Data SNACK: requesting retransmission of Data-In PDUs with
possible resegmentation and status tagging.
All other values are reserved.
Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST precede status acknowledgment for the given command.11.16.2. Data Acknowledgment
If an initiator operates at ErrorRecoveryLevel 1 or higher, it MUST issue a SNACK of type DataACK after receiving a Data-In PDU with the A bit set to 1. However, if the initiator has detected holes in the input sequence, it MUST postpone issuing the SNACK of type DataACK until the holes are filled. An initiator MAY ignore the A bit if it deems that the bit is being set aggressively by the target (i.e., before the MaxBurstLength limit is reached). The DataACK is used to free resources at the target and not to request or imply data retransmission. An initiator MUST NOT request retransmission for any data it had already acknowledged.11.16.3. Resegmentation
If the initiator MaxRecvDataSegmentLength changed between the original transmission and the time the initiator requests retransmission, the initiator MUST issue a R-Data SNACK (see Section 11.16.1). With R-Data SNACK, the initiator indicates that it discards all the unacknowledged data and expects the target to resend it. It also expects resegmentation. In this case, the retransmitted Data-In PDUs MAY be different from the ones originally sent in order to reflect changes in MaxRecvDataSegmentLength. Their DataSN starts with the BegRun of the last DataACK received by the target if any was received; otherwise, it starts with 0 and is increased by 1 for each resent Data-In PDU. A target that has received a R-Data SNACK MUST return a SCSI Response that contains a copy of the SNACK Tag field from the R-Data SNACK in the SCSI Response SNACK Tag field as its last or only Response. For example, if it has already sent a response containing another value in the SNACK Tag field or had the status included in the last Data-In PDU, it must send a new SCSI Response PDU. If a target sends more than one SCSI Response PDU due to this rule, all SCSI Response PDUs must carry the same StatSN (see Section 11.4.4). If an initiator attempts to recover a lost SCSI Response (with a Status-SNACK; see Section 11.16.1) when more than one response has been sent, the target will send the SCSI Response with the latest content known to the target, including the last SNACK Tag for the command.
For considerations in allegiance reassignment of a task to a connection with a different MaxRecvDataSegmentLength, refer to Section 7.2.2.11.16.4. Initiator Task Tag
For a Status SNACK and DataACK, the Initiator Task Tag MUST be set to the reserved value 0xffffffff. In all other cases, the Initiator Task Tag field MUST be set to the Initiator Task Tag of the referenced command.11.16.5. Target Transfer Tag or SNACK Tag
For a R-Data SNACK, this field MUST contain a value that is different from 0 or 0xffffffff and is unique for the task (identified by the Initiator Task Tag). This value MUST be copied by the iSCSI target in the last or only SCSI Response PDU it issues for the command. For DataACK, the Target Transfer Tag MUST contain a copy of the Target Transfer Tag and LUN provided with the SCSI Data-In PDU with the A bit set to 1. In all other cases, the Target Transfer Tag field MUST be set to the reserved value 0xffffffff.11.16.6. BegRun
This field indicates the DataSN, R2TSN, or StatSN of the first PDU whose retransmission is requested (Data/R2T and Status SNACK), or the next expected DataSN (DataACK SNACK). A BegRun of 0, when used in conjunction with a RunLength of 0, means "resend all unacknowledged Data-In, R2T or Response PDUs". BegRun MUST be 0 for a R-Data SNACK.11.16.7. RunLength
This field indicates the number of PDUs whose retransmission is requested. A RunLength of 0 signals that all Data-In, R2T, or Response PDUs carrying the numbers equal to or greater than BegRun have to be resent. The RunLength MUST also be 0 for a DataACK SNACK in addition to a R-Data SNACK.
11.17. Reject
Byte/ 0 | 1 | 2 | 3 | / | | | | |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| +---------------+---------------+---------------+---------------+ 0|.|.| 0x3f |1| Reserved | Reason | Reserved | +---------------+---------------+---------------+---------------+ 4|TotalAHSLength | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8/ Reserved / +/ / +---------------+---------------+---------------+---------------+ 16| 0xffffffff | +---------------+---------------+---------------+---------------+ 20| Reserved | +---------------+---------------+---------------+---------------+ 24| StatSN | +---------------+---------------+---------------+---------------+ 28| ExpCmdSN | +---------------+---------------+---------------+---------------+ 32| MaxCmdSN | +---------------+---------------+---------------+---------------+ 36| DataSN/R2TSN or Reserved | +---------------+---------------+---------------+---------------+ 40| Reserved | +---------------+---------------+---------------+---------------+ 44| Reserved | +---------------+---------------+---------------+---------------+ 48| Header-Digest (optional) | +---------------+---------------+---------------+---------------+ xx/ Complete Header of Bad PDU / +/ / +---------------+---------------+---------------+---------------+ yy/Vendor-specific data (if any) / / / +---------------+---------------+---------------+---------------+ zz| Data-Digest (optional) | +---------------+---------------+---------------+---------------+ Reject is used to indicate an iSCSI error condition (protocol, unsupported option, etc.).
11.17.1. Reason
The reject Reason is coded as follows: +------+----------------------------------------+----------------+ | Code | Explanation |Can the original| | (hex)| |PDU be resent? | +------+----------------------------------------+----------------+ | 0x01 | Reserved | no | | | | | | 0x02 | Data (payload) digest error | yes (Note 1) | | | | | | 0x03 | SNACK Reject | yes | | | | | | 0x04 | Protocol Error (e.g., SNACK Request for| no | | | a status that was already acknowledged)| | | | | | | 0x05 | Command not supported | no | | | | | | 0x06 | Immediate command reject - too many | yes | | | immediate commands | | | | | | | 0x07 | Task in progress | no | | | | | | 0x08 | Invalid data ack | no | | | | | | 0x09 | Invalid PDU field | no (Note 2) | | | | | | 0x0a | Long op reject - Can't generate Target | yes | | | Transfer Tag - out of resources | | | | | | | 0x0b | Deprecated; MUST NOT be used | N/A (Note 3) | | | | | | 0x0c | Waiting for Logout | no | +------+----------------------------------------+----------------+ Note 1: For iSCSI, Data-Out PDU retransmission is only done if the target requests retransmission with a recovery R2T. However, if this is the data digest error on immediate data, the initiator may choose to retransmit the whole PDU, including the immediate data. Note 2: A target should use this reason code for all invalid values of PDU fields that are meant to describe a task, a response, or a data transfer. Some examples are invalid TTT/ITT, buffer offset, LUN qualifying a TTT, and an invalid sequence number in a SNACK.
Note 3: Reason code 0x0b ("Negotiation Reset") as defined in
Section 10.17.1 of [RFC3720] is deprecated and MUST NOT be
used by implementations. An implementation receiving reason
code 0x0b MUST treat it as a negotiation failure that
terminates the Login Phase and the TCP connection, as
specified in Section 7.12.
All other values for Reason are unassigned.
In all the cases in which a pre-instantiated SCSI task is terminated
because of the reject, the target MUST issue a proper SCSI command
response with CHECK CONDITION as described in Section 11.4.3. In
these cases in which a status for the SCSI task was already sent
before the reject, no additional status is required. If the error is
detected while data from the initiator is still expected (i.e., the
command PDU did not contain all the data and the target has not
received a Data-Out PDU with the Final bit set to 1 for the
unsolicited data, if any, and all outstanding R2Ts, if any), the
target MUST wait until it receives the last expected Data-Out PDUs
with the F bit set to 1 before sending the Response PDU.
For additional usage semantics of the Reject PDU, see Section 7.3.
11.17.2. DataSN/R2TSN
This field is only valid if the rejected PDU is a Data/R2T SNACK and
the Reject reason code is "Protocol Error" (see Section 11.16). The
DataSN/R2TSN is the next Data/R2T sequence number that the target
would send for the task, if any.
11.17.3. StatSN, ExpCmdSN, and MaxCmdSN
These fields carry their usual values and are not related to the
rejected command. The StatSN is advanced after a Reject.
11.17.4. Complete Header of Bad PDU
The target returns the header (not including the digest) of the PDU
in error as the data of the response.
11.18. NOP-Out
Byte/ 0 | 1 | 2 | 3 | / | | | | |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| +---------------+---------------+---------------+---------------+ 0|.|I| 0x00 |1| Reserved | +---------------+---------------+---------------+---------------+ 4|TotalAHSLength | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| LUN or Reserved | + + 12| | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag or 0xffffffff | +---------------+---------------+---------------+---------------+ 20| Target Transfer Tag or 0xffffffff | +---------------+---------------+---------------+---------------+ 24| CmdSN | +---------------+---------------+---------------+---------------+ 28| ExpStatSN | +---------------+---------------+---------------+---------------+ 32/ Reserved / +/ / +---------------+---------------+---------------+---------------+ 48| Header-Digest (optional) | +---------------+---------------+---------------+---------------+ / DataSegment - Ping Data (optional) / +/ / +---------------+---------------+---------------+---------------+ | Data-Digest (optional) | +---------------+---------------+---------------+---------------+ NOP-Out may be used by an initiator as a "ping request" to verify that a connection/session is still active and all its components are operational. The NOP-In response is the "ping echo". A NOP-Out is also sent by an initiator in response to a NOP-In. A NOP-Out may also be used to confirm a changed ExpStatSN if another PDU will not be available for a long time. Upon receipt of a NOP-In with the Target Transfer Tag set to a valid value (not the reserved value 0xffffffff), the initiator MUST respond with a NOP-Out. In this case, the NOP-Out Target Transfer Tag MUST contain a copy of the NOP-In Target Transfer Tag. The initiator
SHOULD NOT send a NOP-Out in response to any other received NOP-In, in order to avoid lengthy sequences of NOP-In and NOP-Out PDUs sent in response to each other.11.18.1. Initiator Task Tag
The NOP-Out MUST have the Initiator Task Tag set to a valid value only if a response in the form of a NOP-In is requested (i.e., the NOP-Out is used as a ping request). Otherwise, the Initiator Task Tag MUST be set to 0xffffffff. When a target receives the NOP-Out with a valid Initiator Task Tag, it MUST respond with a NOP-In Response (see Section 4.6.3.6). If the Initiator Task Tag contains 0xffffffff, the I bit MUST be set to 1, and the CmdSN is not advanced after this PDU is sent.11.18.2. Target Transfer Tag
The Target Transfer Tag is a target-assigned identifier for the operation. The NOP-Out MUST only have the Target Transfer Tag set if it is issued in response to a NOP-In with a valid Target Transfer Tag. In this case, it copies the Target Transfer Tag from the NOP-In PDU. Otherwise, the Target Transfer Tag MUST be set to 0xffffffff. When the Target Transfer Tag is set to a value other than 0xffffffff, the LUN field MUST also be copied from the NOP-In.11.18.3. Ping Data
Ping data is reflected in the NOP-In Response. The length of the reflected data is limited to MaxRecvDataSegmentLength. The length of ping data is indicated by the DataSegmentLength. 0 is a valid value for the DataSegmentLength and indicates the absence of ping data.
11.19. NOP-In
Byte/ 0 | 1 | 2 | 3 | / | | | | |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| +---------------+---------------+---------------+---------------+ 0|.|.| 0x20 |1| Reserved | +---------------+---------------+---------------+---------------+ 4|TotalAHSLength | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| LUN or Reserved | + + 12| | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag or 0xffffffff | +---------------+---------------+---------------+---------------+ 20| Target Transfer Tag or 0xffffffff | +---------------+---------------+---------------+---------------+ 24| StatSN | +---------------+---------------+---------------+---------------+ 28| ExpCmdSN | +---------------+---------------+---------------+---------------+ 32| MaxCmdSN | +---------------+---------------+---------------+---------------+ 36/ Reserved / +/ / +---------------+---------------+---------------+---------------+ 48| Header-Digest (optional) | +---------------+---------------+---------------+---------------+ / DataSegment - Return Ping Data / +/ / +---------------+---------------+---------------+---------------+ | Data-Digest (optional) | +---------------+---------------+---------------+---------------+ NOP-In is sent by a target as either a response to a NOP-Out, a "ping" to an initiator, or a means to carry a changed ExpCmdSN and/or MaxCmdSN if another PDU will not be available for a long time (as determined by the target). When a target receives the NOP-Out with a valid Initiator Task Tag (not the reserved value 0xffffffff), it MUST respond with a NOP-In with the same Initiator Task Tag that was provided in the NOP-Out request. It MUST also duplicate up to the first MaxRecvDataSegmentLength bytes of the initiator-provided Ping Data. For such a response, the Target Transfer Tag MUST be 0xffffffff. The
target SHOULD NOT send a NOP-In in response to any other received NOP-Out in order to avoid lengthy sequences of NOP-In and NOP-Out PDUs sent in response to each other. Otherwise, when a target sends a NOP-In that is not a response to a NOP-Out received from the initiator, the Initiator Task Tag MUST be set to 0xffffffff, and the data segment MUST NOT contain any data (DataSegmentLength MUST be 0).11.19.1. Target Transfer Tag
If the target is responding to a NOP-Out, this field is set to the reserved value 0xffffffff. If the target is sending a NOP-In as a ping (intending to receive a corresponding NOP-Out), this field is set to a valid value (not the reserved value 0xffffffff). If the target is initiating a NOP-In without wanting to receive a corresponding NOP-Out, this field MUST hold the reserved value 0xffffffff.11.19.2. StatSN
The StatSN field will always contain the next StatSN. However, when the Initiator Task Tag is set to 0xffffffff, the StatSN for the connection is not advanced after this PDU is sent.11.19.3. LUN
A LUN MUST be set to a correct value when the Target Transfer Tag is valid (not the reserved value 0xffffffff).12. iSCSI Security Text Keys and Authentication Methods
Only the following keys are used during the SecurityNegotiation stage of the Login Phase: SessionType InitiatorName TargetName TargetAddress InitiatorAlias
TargetAlias
TargetPortalGroupTag
AuthMethod and the keys used by the authentication methods
specified in Section 12.1, along with all of their associated
keys, as well as Vendor-Specific Authentication Methods.
Other keys MUST NOT be used.
SessionType, InitiatorName, TargetName, InitiatorAlias, TargetAlias,
and TargetPortalGroupTag are described in Section 13 as they can be
used in the OperationalNegotiation stage as well.
All security keys have connection-wide applicability.
12.1. AuthMethod
Use: During Login - Security Negotiation
Senders: Initiator and target
Scope: connection
AuthMethod = <list-of-values>
The main item of security negotiation is the authentication method
(AuthMethod).
The authentication methods that can be used (appear in the list-of-
values) are either vendor-unique methods or those listed in the
following table:
+--------------------------------------------------------------+
| Name | Description |
+--------------------------------------------------------------+
| KRB5 | Kerberos V5 - defined in [RFC4120] |
+--------------------------------------------------------------+
| SRP | Secure Remote Password - |
| | defined in [RFC2945] |
+--------------------------------------------------------------+
| CHAP | Challenge Handshake Authentication Protocol - |
| | defined in [RFC1994] |
+--------------------------------------------------------------+
| None | No authentication |
+--------------------------------------------------------------+
The AuthMethod selection is followed by an "authentication exchange"
specific to the authentication method selected.
The authentication method proposal may be made by either the
initiator or the target. However, the initiator MUST make the first
step specific to the selected authentication method as soon as it is
selected. It follows that if the target makes the authentication
method proposal, the initiator sends the first key(s) of the exchange
together with its authentication method selection.
The authentication exchange authenticates the initiator to the target
and, optionally, the target to the initiator. Authentication is
OPTIONAL to use but MUST be supported by the target and initiator.
The initiator and target MUST implement CHAP. All other
authentication methods are OPTIONAL.
Private or public extension algorithms MAY also be negotiated for
authentication methods. Whenever a private or public extension
algorithm is part of the default offer (the offer made in the absence
of explicit administrative action), the implementer MUST ensure that
CHAP is listed as an alternative in the default offer and "None" is
not part of the default offer.
Extension authentication methods MUST be named using one of the
following two formats:
1) Z-reversed.vendor.dns_name.do_something=
2) New public key with no name prefix constraints
Authentication methods named using the Z- format are used as private
extensions. New public keys must be registered with IANA using the
IETF Review process ([RFC5226]). New public extensions for
authentication methods MUST NOT use the Z# name prefix.
For all of the public or private extension authentication methods,
the method-specific keys MUST conform to the format specified in
Section 6.1 for standard-label.
To identify the vendor for private extension authentication methods,
we suggest using the reversed DNS-name as a prefix to the proper
digest names.
The part of digest-name following Z- MUST conform to the format for
standard-label specified in Section 6.1.
Support for public or private extension authentication methods is
OPTIONAL.
The following subsections define the specific exchanges for each of the standardized authentication methods. As mentioned earlier, the first step is always done by the initiator.12.1.1. Kerberos
For KRB5 (Kerberos V5) [RFC4120] [RFC1964], the initiator MUST use: KRB_AP_REQ=<KRB_AP_REQ> where KRB_AP_REQ is the client message as defined in [RFC4120]. The default principal name assumed by an iSCSI initiator or target (prior to any administrative configuration action) MUST be the iSCSI Initiator Name or iSCSI Target Name, respectively, prefixed by the string "iscsi/". If the initiator authentication fails, the target MUST respond with a Login reject with "Authentication Failure" status. Otherwise, if the initiator has selected the mutual authentication option (by setting MUTUAL-REQUIRED in the ap-options field of the KRB_AP_REQ), the target MUST reply with: KRB_AP_REP=<KRB_AP_REP> where KRB_AP_REP is the server's response message as defined in [RFC4120]. If mutual authentication was selected and target authentication fails, the initiator MUST close the connection. KRB_AP_REQ and KRB_AP_REP are binary-values, and their binary length (not the length of the character string that represents them in encoded form) MUST NOT exceed 65536 bytes. Hex or Base64 encoding may be used for KRB_AP_REQ and KRB_AP_REP; see Section 6.1.12.1.2. Secure Remote Password (SRP)
For SRP [RFC2945], the initiator MUST use: SRP_U=<U> TargetAuth=Yes /* or TargetAuth=No */ The target MUST answer with a Login reject with the "Authorization Failure" status or reply with: SRP_GROUP=<G1,G2...> SRP_s=<s> where G1,G2... are proposed groups, in order of preference.
The initiator MUST either close the connection or continue with:
SRP_A=<A> SRP_GROUP=<G>
where G is one of G1,G2... that were proposed by the target.
The target MUST answer with a Login reject with the "Authentication
Failure" status or reply with:
SRP_B=<B>
The initiator MUST close the connection or continue with:
SRP_M=<M>
If the initiator authentication fails, the target MUST answer with a
Login reject with "Authentication Failure" status. Otherwise, if the
initiator sent TargetAuth=Yes in the first message (requiring target
authentication), the target MUST reply with:
SRP_HM=<H(A | M | K)>
If the target authentication fails, the initiator MUST close the
connection:
where U, s, A, B, M, and H(A | M | K) are defined in [RFC2945] (using
the SHA1 hash function, such as SRP-SHA1)
and
G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups
specified in [RFC3723].
G, Gn, and U are text strings; s,A,B,M, and H(A | M | K) are
binary-values. The length of s,A,B,M and H(A | M | K) in binary form
(not the length of the character string that represents them in
encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may
be used for s,A,B,M and H(A | M | K); see Section 6.1.
See Appendix B for the related login example.
For the SRP_GROUP, all the groups specified in [RFC3723] up to
1536 bits (i.e., SRP-768, SRP-1024, SRP-1280, SRP-1536) must be
supported by initiators and targets. To guarantee interoperability,
targets MUST always offer "SRP-1536" as one of the proposed groups.
12.1.3. Challenge Handshake Authentication Protocol (CHAP)
For CHAP [RFC1994], the initiator MUST use: CHAP_A=<A1,A2...> where A1,A2... are proposed algorithms, in order of preference. The target MUST answer with a Login reject with the "Authentication Failure" status or reply with: CHAP_A=<A> CHAP_I=<I> CHAP_C=<C> where A is one of A1,A2... that were proposed by the initiator. The initiator MUST continue with: CHAP_N=<N> CHAP_R=<R> or, if it requires target authentication, with: CHAP_N=<N> CHAP_R=<R> CHAP_I=<I> CHAP_C=<C> If the initiator authentication fails, the target MUST answer with a Login reject with "Authentication Failure" status. Otherwise, if the initiator required target authentication, the target MUST either answer with a Login reject with "Authentication Failure" or reply with: CHAP_N=<N> CHAP_R=<R> If the target authentication fails, the initiator MUST close the connection: where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, Algorithm, Identifier, Challenge, and Response as defined in [RFC1994]. N is a text string; A,A1,A2, and I are numbers; C and R are binary-values. Their binary length (not the length of the character string that represents them in encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may be used for C and R; see Section 6.1. See Appendix B for the related login example.
For the Algorithm, as stated in [RFC1994], one value is required to be implemented: 5 (CHAP with MD5) To guarantee interoperability, initiators MUST always offer it as one of the proposed algorithms.13. Login/Text Operational Text Keys
Some session-specific parameters MUST only be carried on the leading connection and cannot be changed after the leading connection login (e.g., MaxConnections -- the maximum number of connections). This holds for a single connection session with regard to connection restart. The keys that fall into this category have the "use: LO" (Leading Only). Keys that can only be used during login have the "use: IO" (Initialize Only), while those that can be used in both the Login Phase and Full Feature Phase have the "use: ALL". Keys that can only be used during the Full Feature Phase use FFPO (Full Feature Phase Only). Keys marked as Any-Stage may also appear in the SecurityNegotiation stage, while all other keys described in this section are operational keys. Keys that do not require an answer are marked as Declarative. Key scope is indicated as session-wide (SW) or connection-only (CO). "Result function", wherever mentioned, states the function that can be applied to check the validity of the responder selection. "Minimum" means that the selected value cannot exceed the offered value. "Maximum" means that the selected value cannot be lower than the offered value. "AND" means that the selected value must be a possible result of a Boolean "and" function with an arbitrary Boolean value (e.g., if the offered value is No the selected value must be No). "OR" means that the selected value must be a possible result of a Boolean "or" function with an arbitrary Boolean value (e.g., if the offered value is Yes the selected value must be Yes).
(next page on part 9)