|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] iSCSI - Change - Login/Text commands with the binary stage codeAs was agreed in London I did attempt a rewrite of part 4 (Login Phase) and added a binary current/next stage to the all the PDUs involved in the Login Phase (Login/Text command and response). Here are the changed parts (2.8, 2.9, 2.10, 2.11 and 4). The Login Appendix is also changed (attached). There are some more changes in the appendixes but those are minor. 1.1 Text Command The Text Command is provided to allow the exchange of information and for future extensions. It permits the initiator to inform a target of its capabilities or to request some special operations. Byte / 0 | 1 | 2 | 3 | / | | | | |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| +---------------+---------------+---------------+---------------+ 0|X|I| 0x04 |F|B|0 0| CNxSG | Reserved (0) | +---------------+---------------+---------------+---------------+ 4| Reserved (0) | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| Reserved (0) | + + 12| | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag | +---------------+---------------+---------------+---------------+ 20| Reserved (0) | +---------------+---------------+---------------+---------------+ 24| CmdSN | +---------------+---------------+---------------+---------------+ 28| ExpStatSN | +---------------+---------------+---------------+---------------+ 32| Reserved (0) | | | +---------------+---------------+---------------+---------------+ 40| Bookmark or Reserved (0) | | | +---------------+---------------+---------------+---------------+ 48| Digests if any... | +---------------+---------------+---------------+---------------+ / DataSegment (Text) / +/ / +---------------+---------------+---------------+---------------+ 1.1.1 F (Final) Bit When set to 1 it indicates that this is the last or only text command in a sequence of commands; otherwise it indicates that more commands will follow. 1.1.2 CNxSG Through this field, called Current-Next Stage (CNxSG), the textual negotiation commands and responses (Login and Text) are associated with a specific stage in the session (SecurityNegotiation, LoginOperationalNegotiation, FullPhaseOperationalNegotiations) and may indicate the next stage they want to move to (see 4). The current stage is coded in bits 0-1 and the next stage in bits 2-3. The next stage value is valid only when the F bit is 1 and can be ignored otherwise. The stage codes are: - 0 - SecurityNegotiation - 1 - LoginOperationalNegotiation - 3 - FullFeaturePhaseOperationalNegotiation 1.1.3 B (Bookmark-valid) Bit A value of 1 indicates that the Bookmark field is valid. 1.1.4 Initiator Task Tag The initiator assigned identifier for this Text Command. If the command is sent as part of a sequence of commands (e.g., the Login Phase or a sequence of Text commands) the Initiator Task Tag MUST be the same for all the commands within the sequence (similar to linked SCSI commands). 1.1.5 Bookmark An opaque handle copied from a previous text response. It is supposed to allow a target to transfer a large amount of textual data over a sequence of text-command/text-response exchanges. The target associates the bookmark it issues with the Initiator Task Tag and a received Bookmark is considered valid by the Target only if received with the same Initiator Task Tag and if the target did not receive on the same connection a text command with a different Initiator Text Tag since it issued the Bookmark. A target MAY reject an old Bookmark. The Bookmark field is valid only if the B bit is 1. Long text responses are handled as in the following example: I->T Text SendTargets=all (F=1,B=0) T->I Text <part 1> (F=0,B=1,Bookmark) I->T Text <empty> (F=1,B=1,Bookmark) T->I Text <part 2> (F=0,B=1,Bookmark) I->T Text <empty> (F=1,B=1,Bookmark) ... T->I Text <part n> (F=1,B=0) 1.1.6 Text The initiator sends the target a set of key=value or key=list pairs encoded in UTF-8 Unicode. All the text keys and text values specified in this document are to be presented and interpreted in the case they appear in this document (they are case sensitive). The key and value are separated by a '=' (0x3D) delimiter. Every key=value pair (including the last or only pair) MUST be followed by null (0x00) delimiter. A list is a set of values separated by comma (0x2C). Large binary items can be encoded using their hexadecimal representation (e.g., 8190 is 0x1FFE) or decimal representation. The maximum length of an individual value (not its string representation) is 255 bytes. The data lengths of a text command or response MUST NOT exceed 4096 bytes. Key names MUST NOT exceed 63 bytes. Key values MUST NOT exceed 255 characters. Character strings are represented as plain text. Numeric and binary values are represented using either decimal numbers or the hexadecimal 0xFFFF notation. Upper and lower case letters may be used interchangeably in hexadecimal notation (i.e., 0x1aBc, 0x1AbC and 0x1ABC are equivalent). The target responds by sending its response back to the initiator. The response text format is similar to the request text format. Some basic key=value pairs are described in Appendix A and Appendix D. All of these keys, except for the X- extension format, MUST be supported by iSCSI initiators and targets. Manufacturers may introduce new keys by prefixing them with X- followed by their (reversed) domain name, for example the company owning the domain acme.com can issue: X-com.acme.bar.foo.do_something=0000000000000003 Any other key not understood by the target may be ignored by the target without affecting basic function. However the Text Response for a key that was not understood MUST be key=NotUnderstood. Text operations are usually meant for parameter setting/negotiations but can be used also to perform some long lasting operations. It is recommended that Text operations that will take a long time should be placed in their own Text command. A connection may have only one outstanding text command at any given time. 1.2 Text Response The Text Response PDU contains the target's responses to the initiator's Text Command. The format of the Text field matches that of the Text Command. Byte / 0 | 1 | 2 | 3 | / | | | | |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| +---------------+---------------+---------------+---------------+ 0|1|1| 0x24 |F|B|0 0| CNxSG | Reserved (0) | +---------------+---------------+---------------+---------------+ 4| Reserved (0) | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| Reserved (0) | + + 12| | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag | +---------------+---------------+---------------+---------------+ 20| Reserved (0) | +---------------+---------------+---------------+---------------+ 24| StatSN | +---------------+---------------+---------------+---------------+ 28| ExpCmdSN | +---------------+---------------+---------------+---------------+ 32| MaxCmdSN | +---------------+---------------+---------------+---------------+ 36| Reserved (0) | +---------------+---------------+---------------+---------------+ 40| Bookmark or Reserved (0) | | | +---------------+---------------+---------------+---------------+ 48| Digests if any... | +---------------+---------------+---------------+---------------+ / DataSegment (Text) / +/ / +---------------+---------------+---------------+---------------+ 1.2.1 F (Final) Bit When set to 1 in response to a text command with the Final bit set to 1 the F bit indicates that the target has finished the current stage of the operation or the whole operation. Otherwise if set to 0 in response to a text command with the Final Bit set to 1 it indicates that the target has more work to do (invites a follow-on text command). A text response with the F bit set to 1 in response to a text command with the F bit set to 0 is a protocol error. A text response with a F bit set to 1 MUST NOT contain key=value pairs that may require additional answers from the initiator. 1.2.2 B (Bookmark-valid) Bit A value of 1 indicates that the Bookmark field is valid. F bit must be 0. 1.2.3 Initiator Task Tag The Initiator Task Tag matches the tag used in the initial Text Command or the Login Initiator Task Tag. 1.2.4 Bookmark An opaque handle to be copied to the next text command by the initiator. It is supposed to allow a target to transfer a large amount of textual data over a sequence of text-command/text-response exchanges. The target associates the bookmark it issues with the Initiator Task Tag and a received Bookmark is considered valid by the Target only if received with the same Initiator Task Tag and if the target did not receive on the same connection a text command with a different Initiator Text Tag since it issued the Bookmark. A target MAY reject an old Bookmark. The Bookmark is valid only if the F bit is 0 and the B bit is 1. 1.2.5 Text Response Data The Text Response Data Segment contains responses in the same key=value format as the Text Command and with the same length and coding constraints. Appendix C lists some basic Text Commands and their Responses. Although the initiator is the requesting party and controls the request-response initiation and termination the target can offer key=value pairs of its own as part of a sequence and not only in response to an identical key=value pair offered by the initiator. 1.3 Login Command After establishing a TCP connection between an initiator and a target, the initiator MUST issue a Login Command to gain further access to the target's resources. A Login Command MUST NOT be issued more than once on an iSCSI TCP connection. Byte / 0 | 1 | 2 | 3 | / | | | | |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| +---------------+---------------+---------------+---------------+ 0|X|I| 0x03 |F|0 0 0| CNxSG | Version-max | Version-min | +---------------+---------------+---------------+---------------+ 4| Reserved (0) | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| CID | Reserved (0) | +---------------+---------------+---------------+---------------+ 12| ISID |TSID | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag | +---------------+---------------+---------------+---------------+ 20| Reserved (0) | +---------------+---------------+---------------+---------------+ 24| CmdSN or Reserved (0) | +---------------+---------------+---------------+---------------+ 28| ExpStatSN or Reserved (0) | +---------------+---------------+---------------+---------------+ 32/ Reserved (0) / +/ / +---------------+---------------+---------------+---------------+ 48/ DataSegment - Login Parameters in Text Command Format / +/ / +---------------+---------------+---------------+---------------+ 1.3.1 X - Restart If this bit is set to 1 then this command is an attempt to reinstate a failed connection. CID does not change and this command performs first the logout function of the old connection if an explicit logout was not performed earlier. In sessions with a single connection, this may imply the opening of a second connection with the sole purpose of cleaning-up the first. Targets should support opening a second connection even when not supporting multiple connections in full feature phase. A restart login indicates to the target that commands may be missing and therefore it should be handled immediately. 1.3.2 F (Final) Bit If set to 1 indicates that the initiator has no more parameters to set. 1.3.3 Version-max Maximum Version number supported. 1.3.4 Version-min Minimum Version supported The version number of the current draft is 0x2. 1.3.5 CID This is a unique ID for this connection within the session. 1.3.6 ISID This is an initiator-defined session-identifier. It MUST be the same for all connections within a session. A SCSI initiator port is uniquely identified by the value pair (InitiatorName, ISID). When a target is detecting an attempt to open a new session by the same SCSI initiator port (same InitiatorName and ISID) to the same target portal group it MUST check if the old session is still active. If it is not active and the target has failed to realize that the old-session must be reset by the target and the new session established. Otherwise the Login MUST be terminated with a Login Response of "Session already open with this initiator". 1.3.7 CmdSN CmdSN is either the initial command sequence number of a session (for the first Login of a session - the "leading" login) or the command sequence number in the command stream (e.g., if the leading login carries the CmdSN 123 the next command carries the number 124 etc.). 1.3.8 ExpStatSN This is ExpStatSN for the old connection. This field is valid only if the X bit is set to 1. 1.3.9 Login Parameters The initiator MAY 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. The format of the parameters is as specified for the Text Command. Keys and their explanations are listed in the Appendixes. 1.4 Login Response The Login Response indicates the progress and/or end of the login phase. Note that after security is established, the login response is authenticated. Byte / 0 | 1 | 2 | 3 | / | | | | |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0| +---------------+---------------+---------------+---------------+ 0|1|1| 0x23 |F|0 0 0| CNxSG | Version-max | Version-active| +---------------+---------------+---------------+---------------+ 4| Reserved (0) | DataSegmentLength | +---------------+---------------+---------------+---------------+ 8| Reserved (0) | +---------------+---------------+---------------+---------------+ 12| ISID |TSID | +---------------+---------------+---------------+---------------+ 16| Initiator Task Tag | +---------------+---------------+---------------+---------------+ 20| Reserved (0) | +---------------+---------------+---------------+---------------+ 24| StatSN | +---------------+---------------+---------------+---------------+ 28| ExpCmdSN | +---------------+---------------+---------------+---------------+ 32| MaxCmdSN | +---------------+---------------+---------------+---------------+ 36| Status-Class | Status-Detail | Reserved (0) | +---------------+---------------+---------------+---------------+ 40/ Reserved (0) / +/ / +---------------+---------------+---------------+---------------+ 48| Digests if any... | +---------------+---------------+---------------+---------------+ / DataSegment - Login Parameters in Text Command Format / +/ / +---------------+---------------+---------------+---------------+ 1.4.1 F (Final) bit Final bit is set to one as an indicator of end of stage and if the next stage part in CNxSG is FullFeaturePhaseOperationalNegotiation the this is also the Final Login Response (see 4). A Final bit of 0 indicates a "partial" response, which means "more negotiation needed". A login response with a F bit set to 1 MUST NOT contain key=value pairs that may require additional answers from the initiator within the same stage. 1.4.2 Version-max This is the highest version number supported by the target. 1.4.3 Version-active/lowest Indicates the version supported (the highest version supported by the target and initiator). If the target is not supporting 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. 1.4.4 TSID The TSID is an initiator SCSI port identifying tag set by the target. It MUST be valid only in the final response. 1.4.5 StatSN For the first Login Response this is the starting status Sequence Number for the connection (the next response of any kind will carry this number + 1). This field is valid only if the Status Class is 0. 1.4.6 Status-Class and Status-Detail The Status returned in a Login Response indicates the status of the login request. The status includes: Status-Class Status-Detail The Status-Class is sufficient for a simple initiator to use when handling errors, without having to look at the Status-Detail. The Status-Detail allows finer-grained error recovery for more sophisticated initiators, as well as better information for error 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 valid only if Status-Class is 0). 1 - Redirection - indicates that further action must be taken by the initiator 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. 2 - Initiator Error - indicates that the initiator likely caused the error. This MAY be due to a request for a resource for which the initiator does not have permission. 3 - Target Error - indicates that the target is incapable of fulfilling the request. 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. The allowable state of the Final (F) bit in responses with each of the codes is also displayed. ----------------------------------------------------------------- Status | Code |Final| Description |(hex) | bit | ----------------------------------------------------------------- Accept Login | 0000 | 1/0 | Login is OK, moving to Full Feature | | | Phase or LoginOperationalNegotiation | | | stage (*1) ----------------------------------------------------------------- Authenticate | 0001 | 0 | The iSCSI TargetName (ITN) exists and | | | authentication proceeds. ----------------------------------------------------------------- iSCSI Target | 0002 | 0 | The ITN must be provided Name required | | | for authentication to proceed. ----------------------------------------------------------------- Target Moved | 0101 | 1 | The requested ITN has moved Temporarily | | | temporarily to the address provided. ----------------------------------------------------------------- Target Moved | 0102 | 1 | The requested ITN has moved Permanently | | | permanently to the address provided. ----------------------------------------------------------------- Proxy Required| 0103 | 1 | The initiator must use an iSCSI | | | proxy for this target. | | | The address is provided. ----------------------------------------------------------------- Initiator | 0200 | 1 | Miscellaneous iSCSI initiator Error | | | errors ----------------------------------------------------------------- Security Nego-| 0201 | 1 | The security negotiation failed tiation Failed| | | ----------------------------------------------------------------- Forbidden | 0202 | 1 | The initiator is not allowed access Target | | | to the given target. ----------------------------------------------------------------- Not Found | 0203 | 1 | The requested ITN does not | | | exist at this address. ----------------------------------------------------------------- Target Removed| 0204 | 1 | The requested ITN has been | | | removed. No forwarding address is | | | provided. ----------------------------------------------------------------- Target | 0205 | 1 | Target is currently in use by Conflict | | | another initiator and does | | | not support multiple initiators. ----------------------------------------------------------------- Initiator | 0206 | 1 | Invalid TSID - no more connections SID error | | | accepted | | | ----------------------------------------------------------------- Missing | 0207 | 1 | Missing parameters (e.g., iSCSI parameter | | | Initiator and/or Target Name) ----------------------------------------------------------------- Can't include | 0208 | 1 | Target does not support session in session | | | spanning to this connection (address) ----------------------------------------------------------------- Session open | 0209 | 1 | The iSCSI InitiatorName and ISID already with | | | identify an existing session this Initiator| | | with this initiator ----------------------------------------------------------------- Session type | 020a | 1 | Target does not support this type of Not supported | | | of session (not from this Initiator) ----------------------------------------------------------------- Target Error | 0300 | 1 | Miscellaneous iSCSI target | | | errors (out of resources, etc.). ----------------------------------------------------------------- Service | 0301 | 1 | The iSCSI service or target is not Unavailable | | | currently operational. ----------------------------------------------------------------- Unsupported | 0302 | 1 | The required version is not version | | | supported by the target. ----------------------------------------------------------------- (*1)If the Status is "accept login" (0x0000) the initiator has stated the current stage as LoginOperationalNegotiation (and if the F bit was 1 the next stage to FullFeaturePhaseOperationalNegotiation). If the response F bit is 1 (the next stage part is also FullFeaturePhaseOperationalNegotiation) the login phase is finished and the initiator may proceed to issue SCSI commands. If the Status is "accept login" (0x0000) and the F bit is 0, the initiator may proceed to negotiate operational parameters. 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. Part 4 (login) is now: 1. Login Phase In the rest of this chapter, whenever we mention security we mean security and/or data integrity. The login phase establishes an iSCSI session between initiator and target. It sets the iSCSI protocol parameters, security parameters, and authenticates the initiator and target to each other. The login phase is implemented via login and text commands and responses only. The whole login phase is considered as a single task and has a single Initiator Task Tag (similar to the linked SCSI commands). The login phase sequence of commands and responses proceeds as follows: - Login command (mandatory) - Login Partial-Response (optional) - Text Command(s) and Response(s) (optional) - Login Final-Response (mandatory) The Login Final-response accepts or rejects the Login Command. The Login Phase MAY include a SecurityNegotiation stage and a LoginOperationalNegotiation stage and MUST include at least one of them, but the included stage MAY be empty. The login and text commands and responses contain a field that indicates the negotiation stage (SecurityNegotiation or LoginOperationalNegotiation). If both stages are used the SecurityNegotiation MUST precede the LoginOperationalNegotiation. Some operational parameters can be negotiated outside login, through text command response - called for uniformity - FullFeaturePhaseOperationalNegotiation. Security MUST be completely negotiated within the Login Phase or provided by external means (e.g., IPSec). In some environments, a target or an initiator is not interested in authenticating its counterpart. It is possible to bypass authentication through the Login Command and Response. The initiator and target MAY want to negotiate authentication and data integrity parameters. Once this negotiation is completed, the channel is considered secure. Authentication and a Secure Channel setup MAY be performed independent of iSCSI (as when using tunneling IPSec or some implementations of transport IPSec) in which case the Login phase can be reduced to operational parameter negotiations. Most of the negotiation keys are allowed only in a specific stage - the SecurityNegotiation keys appear all in Appendix A while the LoginOperationalNegotiation keys appear in Appendix D. Only a limited set of keys (marked as Declarative in Appendix D) may be used in any of the 2 stages. Any given Login or Text command or response belongs to a specific stage and this determines the negotiation keys allowed with the command or response. Stage transition is performed through a command exchange (request/response) carrying the F bit and the same current stage code. During this exchange, the next stage selected is the lower of the two next stage codes. The initiator can request a transition whenever it is ready but a target can respond with a transition only after it is offered one by the initiator. In a negotiation sequence, the F bit settings in one pair of text/login request-responses have no bearing on the F bit settings of the next pair. An initiator having F bit set to 1 in one pair and being answered with an F bit setting of 0 may issue the next request with F bit set to 0. Stage transitions during login (including entering and exit) are possible only as outlined in the following table: +-----------------------------------------------------------+ |From To -> | Security | Operational | FullFeature | | | | | | | | V | | | | +-----------------------------------------------------------+ | (start) | yes | yes | no | +-----------------------------------------------------------+ | Security | no | yes | yes | +-----------------------------------------------------------+ | Operational | no | no | yes | +-----------------------------------------------------------+ The Login Final-Response that accepts a Login Command can come only as a response to a Login command with the F bit set to 1 or a Text Command with the F bit set to 1 and both the command and response MUST have FullFeaturePhaseOperationalNegotiation in the next stage part of the CNxSG field. 1.1 Login Phase Start The login phase starts with a login request via a login command from the initiator to the target. The login request includes: -Protocol version supported by the initiator (currently 0x'02') -Session and connection Ids -The negotiation stage that the initiator is ready to enter Optionally the login request may include: -Security/Integrity parameters OR -iSCSI operational parameters AND/OR -The next negotiation stage that the initiator is ready to enter The target can answer the login in the following ways: -Login Response with Login Reject. This is an immediate rejection from the target that causes the session to terminate. The F bit of the response MUST be set to 1 and the CNxSG is to be ignored -Login Response with Login Accept as a final response (F bit set to 1 and the next part of CNxSG in both command a response are set to FullFeaturePhaseOperationalNegotiation). The response includes the protocol version supported by the target and the session ID and may include iSCSI operational or security parameters (depending on the current stage). -Login Response with Login Accept as a partial response indicating the start of a negotiation sequence. The response includes the protocol version supported by the target and either security/integrity parameters or iSCSI parameters (when no security/integrity mechanism is chosen) supported by the target. If the initiator decides to forego the SecurityNegotiation stage it issues the Login with the CNxSG set to LoginOperationalNegotiation in the current stage and the target may replay with a Login Response indicating that it is unwilling to accept the connection without SecurityNegotiation and terminate the connection. If the initiator is willing no negotiate security but it is unwilling to make the initial parameter offer and may accept a connection without security it issues the Login with the F bit set to 1, the CNxSG set to SecurityNegotiation in the current stage and LoginOperationalNegotiation in the next stage. If the target is also ready to forego security the Login response is empty and has F bit is set to 1 and the CNxSG set to SecurityNegotiation in the current stage and LoginOperationalNegotiation in the next stage. An initiator that can operate without security and with all the operational parameters taking the default values issues the Login with the F bit set to 1, the CNxSG set to LoginOperationalNegotiation in the current stage and FullFeaturePhaseOperationalNegotiation in the next stage. If the target is also ready to forego security and LoginOperationalNegotiation the Login response is empty and has F bit is set to 1 and the CNxSG set to LoginOperationalNegotiation in the current stage and FullFeaturePhaseOperationalNegotiation in the next stage. A target MAY use the iSCSI Initiator Name as part of its access control mechanism; therefore, the iSCSI Initiator Name MUST be sent before the target is required to disclose its LUs. If the iSCSI Target Name and/or iSCSI Initiator Name is going to be used in determining the security mode or it is implicit part of authentication, then the iSCSI Target Name and/or iSCSI Initiator Name MUST be sent in the login command for the first connection of a session to identify the storage endpoint of the session. If sent on new connections within an existing session it MUST be the same as the one used for the leading connection. If the iSCSI Target Name and/or iSCSI Initiator Name is going to be used only for access control, it can be sent after the SecurityNegotiation stage. A target can be accessed without a Target Name only if the session type is a discovery session. The iSCSI Names MUST be in text command format. 1.2 iSCSI Security and Integrity Negotiation The security exchange sets the security mechanism and authenticates the user and the target to each other. The exchange proceeds according to the algorithms that were chosen in the negotiation phase and is conducted by the login and text commands key=value parameters. The negotiable security mechanisms include the following modes: -Initiator-target authentication - the host and the target authenticate themselves to each other. A negotiable algorithm such as Kerberos provides this feature. -PDU integrity - an integrity/authentication digest is attached to each packet. The algorithm is negotiable. Using IPsec for encryption or authentication may eliminate part of the security negotiation at the iSCSI level but not necessarily all. If security is established in the login phase then after the security negotiation is complete, each iSCSI PDU MUST include the appropriate digest field if any. The negotiation proceeds as follows: -The initiator sends a login or text command with an ordered list of the options it supports for each subject (authentication algorithm, iSCSI parameters and so on). The options are listed in the initiator's order of preference. -The target MUST reply with the first option in the list it supports and is allowed for the specific initiator. The parameters are encoded in UTF8 as key=value. The initiator MAY also send proprietary options. The "none" option, if allowed, MUST be included in the list, which indicates that no algorithm is supported by the target. For a list of security parameters see Appendix A. -The initiator must be aware of the imminent completion of the SecurityNegotiation stage and MUST set the F bit to 1 and the next stage part of CNxSG to what it would like the next stage to be. The target will answer with a Login or Text response with the F bit set to 1 and the next stage part of CNxSG to what it would like the next stage to be. The next stage selected will be the "lower" of the two. If the next stage is FullFeaturePhase, the target MUST respond with a Login Response with the Session ID and the protocol version. All PDUs sent after the security negotiation stage MUST be built using the agreed security. If the security negotiation fails at the target then the target MUST send the appropriate Login Response PDU. If the security negotiation fails at the initiator, the initiator shall drop the connection. 1.3 Operational Parameter Negotiation During the Login Phase Operational parameter negotiation during the login MAY be done: - starting with the Login command if the initiator does not offer any security/ integrity option - starting immediately after the security/integrity negotiation if the initiator and target perform such a negotiation An operational parameter negotiation on a connection MUST NOT start before the security negotiation if a security negotiation exists. Operational parameter negotiation MAY involve several request-response exchanges (login and/or text) started and terminated by the initiator. The initiator MUST indicate its intent to terminate the negotiation by setting the F bit to 1; the target sets the F bit to 1 on the last response. The last response MUST be the Login Response. If the target responds to a text or Login command with the F bit set to 1, with a text response with the F bit set to 0, or a login response with the F bit set to 0, the initiator must keep sending the text command (even empty) with the F bit set to 1 until it gets the Login Response with the F bit set to 1. Whenever parameter action or acceptance is dependent of other parameters the dependent parameters MUST be sent after the parameters they are depending on. If they are sent within the same command a response for a parameter might imply responses for others. A target MUST NOT send more than one Login Response with the F bit set to 0. An initiator MUST send a single Login command per connection, per session. For a list of operational parameters, see Appendix D. The Appendix A is now: Appendix A. iSCSI Security and Integrity 01 Security Keys and Values The parameters (keys) negotiated for security are: - Digests (HeaderDigest, DataDigest) - Authentication method (AuthMethod) Digests enable checking end-to-end data integrity beyond the integrity checks provided by the link layers and covering the whole communication path including all elements that may change the network level PDUs like routers, switches, proxies, etc. The following table lists cyclic integrity checksums that can be negotiated for the digests and MUST be implemented by every iSCSI initiator and target. Note that these digest options have only error detection significance. +---------------------------------------------+ | Name | Description | Generator | +---------------------------------------------+ | crc-32C | 32 bit CRC | 11EDC6F41 | +---------------------------------------------+ | none | no digest | +---------------------------------------------+ The generator polynomial for this digest is given in hex-notation, for example 3b stands for 0011 1011 - the polynomial x**5+X**4+x**3+x+1. Padding bytes, when present, in a segment covered by a CRC, should be set to 0 and are included in the CRC. The CRC should be calculated as follows: - data are assumed to be in the numbering order that appears in the draft - start with byte 0 bit 0 continue byte 1 bit 0 etc. (Big Endian on bytes / Little Endian on bits) - the CRC register is initialized with all 1s (equivalent to complementing the first 32 bits of the message) - the n PDU bits are considered coefficients of a polynomial M(x) of order n-1, with bit 0 of byte 0 being x^(n-1) - the polynomial is multiplied by x^32 and divided by G(x)- the generator polynomial - producing a remainder R(x) of degree <= 31 - the coefficients of R(x) are considered a 32 bit sequence - the bit sequence is complemented and the result is the CRC - after the last bit of the original segment the CRC bits are transmitted with x^31 first followed by x^30 etc. ( whenever examples are given the value to be specified in examples follows the same rules of representation as the rest of this document) - a receiver of a "good" segment (data or header) built using the generator 0x11EDC6F41 will end-up having in the CRC register the value 0x1c2d19ed (this a register value and not a word as outlined in this draft) Implementations MAY also negotiate digests with security significance for data authentication and integrity as detailed in the following table: +-------------------------------------------------------------+ | Name | Description | Definition | +-------------------------------------------------------------+ | KRB5_MD5 | the SGN_CKSUM field (8 bytes) | RFC1964 | | | of the GSS_GetMIC() token in | | | | GSS_KRB5_INTEG_C_QOP_MD5 QOP | | | | (partial MD5 ("MD2.5") ) | | +-------------------------------------------------------------+ | KRB5_DES_MD5 | the SGN_CKSUM field (8 bytes) | RFC1964 | | | of the GSS_GetMIC() token in | | | | GSS_KRB5_INTEG_C_QOP_DES_MD5 | | | | QOP (DES MAC of MD5) | | +-------------------------------------------------------------+ | KRB5_DES_MAC | the SGN_CKSUM field (8 bytes) | RFC1964 | | | of the GSS_GetMIC() token in | | | | GSS_KRB5_INTEG_C_QOP_ DES_MAC | | | | QOP (DES MAC) | | +-------------------------------------------------------------+ | SPKM | the int-cksum field of the | RFC2025 | | | SPKM-MIC token, calculated | | | | without the optional int-alg | | | | and snd-seq fields of the | | | | mic-header (i.e., the default | | | | I-ALG is used, and sequencing | | | | service is not used). | | +-------------------------------------------------------------+ Note: the KRB5_* digests are allowed only when combined with KRB5 authentication method (see below) (i.e., the initiator may offer one of these digests only if it also offers KRB5 as AuthMethod, and the target may respond with one of these digests only if it also responds with KRB5 as the AuthMethod). Similarly, the SPKM digest is allowed only when combined with SPKM-1 or SPKM-2 authentication methods (see below). Other and proprietary algorithms MAY also be negotiated. The none value is the only one that MUST be supported. The following table details authentication methods: +------------------------------------------------------------+ | Name | Description | +------------------------------------------------------------+ | KRB5 | Kerberos V5 | +------------------------------------------------------------+ | SPKM-1 | Simple Public-Key GSS-API Mechanism | +------------------------------------------------------------+ | SPKM-2 | Simple Public-Key GSS-API Mechanism | +------------------------------------------------------------+ | SRP | Secure Remote Password | +------------------------------------------------------------+ | CHAP | Challenge Handshake Authentication Protocol| +------------------------------------------------------------+ | none | No authentication | +------------------------------------------------------------+ KRB5 is defined in [RFC1510], SPKM-1, SPKM-2 are defined in [RFC2025], Secure Remote Password is defined in [RFC2945] and CHAP is defined in [RFC1994]. Initiator and target MUST implement SRP. 02 Authentication The authentication exchange authenticates the initiator to the target, and optionally the target to the initiator. Authentication is not mandatory and is distinct from the data integrity exchange. The authentication methods to be used are KRB5, SPKM-1, SPKM-2, SRP, CHAP, or proprietary. For KRB5 (Kerberos V5) [RFC1510], the initiator MUST use: KRB_AP_REQ=<KRB_AP_REQ> where KRB_AP_REQ is the client message as defined in [RFC1510]. If the initiator authentication fails, the target MUST return an error. 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 [RFC1510]. KRB_AP_REQ,KRB_AP_REP are large binaries encoded as hexadecimal strings. For SPKM-1,SPKM-2 [RFC2025], the initiator MUST use: SPKM-REQ=<SPKM-REQ> where SPKM-REQ is the first initiator token as defined in [RFC2025]. [RFC2025] defines situations where each side may send an error token which may cause the peer to re-generate and resend his last token. This scheme is followed in iSCSI, and the error token syntax is: SPKM-ERROR=<SPKM-ERROR> However, SPKM-DEL tokens that are defined by [RFC2025] for fatal errors will not be used by iSCSI. If the target needs (by [RFC2025]) to send SPKM-DEL token, it will, instead, send a Login "login reject" message and terminate the connection. If the initiator needs to send SPKM-DEL token, it will just abort the connection. In the sequel, we assume that no SPKM-ERROR tokens are required: If the initiator authentication fails, the target MUST return an error. Otherwise, if the AuthMethod is SPKM-1 or if the initiator has selected the mutual authentication option (by setting mutual-state bit in the options field of the REQ-TOKEN in the SPKM-REQ), the target MUST reply with: SPKM-REP-TI=<SPKM-REP-TI> where SPKM-REP-TI is the target token as defined in [RFC2025]. If mutual authentication was selected and target authentication fails, the initiator MUST abort the connection. Otherwise, if the AuthMethod is SPKM-1, the initiator MUST continue with: SPKM-REP-IT=<SPKM-REP-IT> where SPKM-REP-IT is the second initiator token as defined in [RFC2025]. All the SPKM-* tokens are large binaries encoded as hexadecimal strings. For SRP [RFC2945], the initiator MUST use: U=<user> TargetAuth=yes /* or TargetAuth=no */ The target MUST either return an error or reply with: N=<N> g=<g> s=<s> The initiator MUST continue with: A=<A> The target MUST either return an error or reply with: B=<B> The initiator MUST either abort or continue with: M=<M> If the initiator authentication fails, the target MUST return an error. Otherwise, If the initiator sent TargetAuth=yes in the first message (requiring target authentication) the target MUST reply with: HM=<H(A | M | K)> Where U, N, g, s, A, B, M and H(A | M | K) are defined in [RFC2945]. U is a text string, N,g,s,A,B,M and H(A | M | K) are numbers. For CHAP [RFC1994], the initiator MUST use: A=<A1,A2...> Where A1,A2... are proposed algorithms, in order of preference. The target MUST either return an error or reply with: A=<A> I=<I> C=<C> Where A is one of A1,A2... that were proposed by the initiator. The initiator MUST continue either with: N=<N> R=<R> or, if he requires target authentication, with: N=<N> R=<R> I=<I> C=<C> If the initiator authentication fails, the target MUST return an error. Otherwise, if the initiator required target authentication, the target MUST reply with N=<N> R=<R> Where N, (A,A1,A2), I, C, R are (correspondingly) the Name, Algorithm, Identifier, Challenge and Response as defined in [RFC1994]. N is a text string, A,A1,A2,I are numbers and C,R are large binaries encoded as hexadecimal strings. For the Algorithm, as stated in [RFC1994], one value is required to be implemented: 5 (CHAP with MD5) To guarantee interoperability, initiators SHOULD always offer it as one of the proposed algorithms. 03 Login Phase Examples In the first example, the initiator and target authenticate each other via Kerberos: I-> Login (CNxSG=0,1 F=1) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=KRB5_MD5,KRB5_DES_MAC,crc-32C,none DataDigest=crc-32C,none AuthMethod=SRP,KRB5,none T-> Login-PR (CNxSG=0,1 F=0) HeaderDigest=KRB5_MD5 DataDigest=crc-32C AuthMethod=KRB5 (Login-PR stands for Login-Partial-Response) I-> Text (CNxSG=0,1 F=1) KRB_AP_REQ=<krb_ap_req> (krb_ap_req contains the Kerberos V5 ticket and authenticator with MUTUAL-REQUIRED set in the ap-options field) If the authentication is successful, the target proceeds with: T-> Text (CNxSG=0,1 F=1) KRB_AP_REP=<krb_ap_rep> (krb_ap_rep is the Kerberos V5 mutual authentication reply) If the authentication is successful, the initiator proceeds. From this point on, any Text command and each PDU thereafter has a KRB5_MD5 digest for the header and a crc-32C for the data. The initiator may proceed: I-> Text (CNxSG=1,3 F=0) ... iSCSI Operational Parameters T-> Text (CNxSG=1,3 F=0) ... iSCSI Operational Parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters TargetName=iqn.1999-07.com.acme.diskarray.sn.88 T-> Login (CNxSG=1,3 F=1) "login accept" If the initiator authentication by the target is not successful, the target responds with: T-> Login "login reject" instead of the Text KRB_AP_REP message, and terminates the connection. If the target authentication by the initiator is not successful, the initiator terminates the connection (without responding to the Text KRB_AP_REP message). In the next example only the initiator is authenticated by the target via Kerberos: I-> Login (CNxSG=0,1 F=1) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=KRB5_MD5,KRB5_DES_MAC,crc-32C,none DataDigest=crc-32C,none AuthMethod=SRP,KRB5,none T-> Login-PR (CNxSG=0,1 F=0)HeaderDigest=KRB5_MD5 DataDigest=crc-32C AuthMethod=KRB5 I-> Text (CNxSG=0,1 F=1)KRB_AP_REQ=krb_ap_req (MUTUAL-REQUIRED not set in the ap-options field of krb_ap_req) If the authentication is successful, the target proceeds with: T-> Text (CNxSG=0,1 F=1) From this point on, any Text command and each PDU thereafter MUST have a KRB5_MD5 digest for the header and a crc-32C for the data. I-> Text (CNxSG=1,3 F=0) ... iSCSI parameters T-> Text (CNxSG=1,3 F=0)... iSCSI parameters . . . T-> Login (CNxSG=1,3 F=1)"login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 In the next example, the initiator and target authenticate each other via SPKM-1: I-> Login (CNxSG=0,1 F=1) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=KRB5_MD5,KRB5_DES_MAC,SPKM,crc-32C,none DataDigest=crc-32C,SPKM,none AuthMethod=SPKM-1,KRB5,none T-> Login-PR (CNxSG=0,1 F=0) HeaderDigest=SPKM DataDigest=SPKM AuthMethod=SPKM-1 I-> Text (CNxSG=0,1 F=0) SPKM-REQ=<spkm-req> (spkm-req is the SPKM-REQ token with the mutual-state bit in the options field of the REQ-TOKEN set) T-> Text (CNxSG=0,1 F=0) SPKM-REP-TI=<spkm-rep-ti> If the authentication is successful, the initiator proceeds: I-> Text (CNxSG=0,1 F=1) SPKM-REP-IT=<spkm-rep-it> If the authentication is successful, the target proceeds with: T-> Text (CNxSG=0,1 F=1) From this point on, any Text command and each PDU thereafter has SPKM digests for the header and data. The initiator may proceed: I-> Text (CNxSG=1,3 F=0) ... iSCSI parameters T-> Text (CNxSG=1,3 F=0) ... iSCSI parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 If the target authentication by the initiator is not successful, the initiator terminates the connection (without responding to the Text SPKM-REP-TI message). If the initiator authentication by the target is not successful, the target responds with: T-> Login "login reject" instead of the Text SecurityContextComplete=yes message, and terminates the connection. In the next example, the initiator and target authenticate each other via SPKM-2: I-> Login (CNxSG=0,1 F=0) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=SPKM,crc-32C,none DataDigest=crc-32C,SPKM,none AuthMethod=SPKM-1,SPKM-2 T-> Login-PR (CNxSG=0,1 F=0) HeaderDigest=SPKM DataDigest=SPKM AuthMethod=SPKM-2 I-> Text (CNxSG=0,1 F=1) SPKM-REQ=<spkm-req> (spkm-req is the SPKM-REQ token with the mutual-state bit in the options field of the REQ-TOKEN not set) If the authentication is successful, the target proceeds with: T-> Text (CNxSG=0,1 F=1) From this point on, any Text command and each PDU thereafter has SPKM digests for the header and data. The initiator may proceed: I-> Text (CNxSG=1,3 F=0) ... iSCSI parameters T-> Text (CNxSG=1,3 F=0) ... iSCSI parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 In the next example, the initiator and target authenticate each other via SRP: I-> Login (CNxSG=0,1 F=1) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=crc-32C,none DataDigest=crc-32C,none AuthMethod=KRB5,SRP,none T-> Login-PR (CNxSG=0,1 F=0) HeaderDigest=crc-32C DataDigest=crc-32C AuthMethod=SRP I-> Text (CNxSG=0,1 F=0) U=<user> TargetAuth=yes T-> Text (CNxSG=0,1 F=0) N=<N> g=<g> s=<s> I-> Text (CNxSG=0,1 F=0) A=<A> T-> Text (CNxSG=0,1 F=0) B=<B> I-> Text (CNxSG=0,1 F=1) M=<M> If the initiator authentication is successful, the target proceeds: T-> Text (CNxSG=0,1 F=1) HM=<H(A | M | K)> Where N, g, s, A, B, M, and H(A | M | K) are defined in [RFC2945]. If the target authentication is not successful, the initiator terminates the connection. Otherwise it proceeds. From this point on, any Text command and each PDU thereafter has a crc-32C digest for the header and the data. I-> Text(CNxSG=1,3 F=0) ... iSCSI parameters T-> Text(CNxSG=1,3 F=0) ... iSCSI parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 If the initiator authentication is not successful, the target responds with: T-> Login "login reject" Instead of the T-> Text HM=<H(A | M | K)> message and terminates the connection. In the next example only the initiator is authenticated by the target via SRP: I-> Login (CNxSG=0,1 F=1) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=crc-32C,none DataDigest=crc-32C,none AuthMethod=KRB5,SRP,none T-> Login-PR (CNxSG=0,1 F=0) HeaderDigest=crc-32C DataDigest=crc-32C AuthMethod=SRP I-> Text (CNxSG=0,1 F=0) U=<user> TargetAuth=no T-> Text (CNxSG=0,1 F=0) N=<N> g=<g> s=<s> I-> Text (CNxSG=0,1 F=0) A=<A> T-> Text (CNxSG=0,1 F=0) B=<B> I-> Text (CNxSG=0,1 F=1) M=<M> If the initiator authentication is successful, the target proceeds: T-> Text (CNxSG=0,1 F=1) From this point on, any Text command and each PDU thereafter has a crc-32C digest for the header and the data. I-> Text (CNxSG=1,3 F=0) ... iSCSI parameters T-> Text (CNxSG=1,3 F=0) ... iSCSI parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 In the next example the initiator and target authenticate each other via CHAP: I-> Login (CNxSG=0,1 F=0) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=crc-32C,none DataDigest=crc-32C,none AuthMethod=KRB5,CHAP,none T-> Login-PR (CNxSG=0,1 F=0) HeaderDigest=crc-32C DataDigest=crc-32C AuthMethod=CHAP I-> Text (CNxSG=0,1 F=0) A=<A1,A2> T-> Text (CNxSG=0,1 F=0) A=<A1> I=<I> C=<C> I-> Text (CNxSG=0,1 F=1) N=<N> R=<R> I=<I> C=<C> If the initiator authentication is successful, the target proceeds: T-> Text (CNxSG=0,1 F=1) N=<N> R=<R> If the target authentication is not successful, the initiator aborts the connection. Otherwise it proceeds. From this point on, any Text command and each PDU thereafter has a crc-32C digest for the header and the data. I-> Text (CNxSG=1,3 F=0) ... iSCSI parameters T-> Text (CNxSG=1,3 F=0) ... iSCSI parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 If the initiator authentication is not successful, the target responds with: T-> Login "login reject" Instead of the Text R=<response> SecurityContextComplete=yes message and terminates the connection. In the next example only the initiator is authenticated by the target via CHAP: I-> Login (CNxSG=0,1 F=0) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=crc-32C,none DataDigest=crc-32C,none AuthMethod=KRB5,CHAP,none T-> Login-PR (CNxSG=0,1 F=0) HeaderDigest=crc-32C DataDigest=crc-32C AuthMethod=CHAP I-> Text (CNxSG=0,1 F=0) A=<A1,A2> T-> Text (CNxSG=0,1 F=0) A=<A1> I=<I> C=<C> I-> Text (CNxSG=0,1 F=1) N=<N> R=<R> If the initiator authentication is successful, the target proceeds: T-> Text (CNxSG=0,1 F=1) I-> Text (CNxSG=1,3 F=0) ... iSCSI parameters T-> Text (CNxSG=1,3 F=0) ... iSCSI parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 In the next example, the initiator does not offer any security/integrity parameters, so it may offer iSCSI parameters on the Login PDU with the F bit set to 1, and the target may respond with a final Login Response PDU immediately: I-> Login (CNxSG=1,3 F=1) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 ... iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 ... ISCSI parameters In the next example, the initiator does offer security/integrity parameters on the Login PDU, but the target does not choose any (i.e., chooses the "none" values): I-> Login (CNxSG=0,1 F=1) InitiatorName=iqn.1999-07.com.os.hostid.77 TargetName=iqn.1999-07.com.acme.diskarray.sn.88 HeaderDigest=crc-32C,none DataDigest=crc-32C,none AuthMethod:KRB5,SRP,none T-> Login-PR (CNxSG=0,1 F=1) HeaderDigest=none, DataDigest=none, AuthMethod=none I-> Text (CNxSG=1,3 F=0) ... iSCSI parameters T-> Text (CNxSG=1,3 F=0) ... iSCSI parameters And at the end: I-> Text (CNxSG=1,3 F=1) optional iSCSI parameters T-> Login (CNxSG=1,3 F=1) "login accept" TargetName=iqn.1999-07.com.acme.diskarray.sn.88 Julo
Home Last updated: Tue Sep 04 01:03:57 2001 6315 messages in chronological order |