iSCSI - an improved text for 4.1 & 4.2

["Julian Satran" <Julian_Satran@il.ibm.com>]

Here is another attempt.

Julo

Text Format

The initiator and target send a set of key=value 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 following character symbols are used in this document for text items:

(a-z, A-Z) - letters
(0-9) - digits
" " (0x20) - space
"." (0x2e) - dot
"-" (0x2d) - minus
"+" (0x2b) - plus
"@" (0x40) - commercial at
"_" (0x5f) - underscore
"=" (0x3d) - equal
":" (0x3a) - colon
"/" (0x2f) - solidus or slash
"[" (0x5b) - left bracket
"]" (0x5d) - right bracket
null(0x00) - null separator
"," (0x2c) - comma
"~" (0x7e) - tilde

A key-name is whatever precedes the first = in the key=value pair. The term key is used frequently in this document with the meaning of key-name.

A value is whatever follows the = that follows the key-name up to a null delimiter that marks the end of any key=value pair (including the last in a PDU).

The following definitions will be used in the rest of this document:

key-name:  a string of one or more characters consisting of letters, digits, point, minus, plus, commercial at, and underscore, A key-name MUST begin with a capital letter an must not exceed 63 characters.

text-value: a string of 0 or more characters consisting of let-ters, digits, dot, minus, plus, commercial at, underscore, slash, left bracket, right bracket and colon.

iSCSI-name-value: a string of one or more characters consist-ing of minus, dot, colon and any character allowed by the output of the iSCSI string-prep template as specified in [STPREP-iSCSI] (see also Section 2.2.6.2 iSCSI Name Encoding).

iSCSI-local-name-value: an UTF-8 string terminated by the null character that terminates the key=value pair; no null charac-ters are allowed in the string. This encoding is to be used for localized (internationalized) aliases.

boolean-value: the strings "Yes" or "No".

hex-constant: hexadecimal constant encoded as a string start-ing with "0x" or "0X" followed by 1 or more digits or the letters a, b, c, d, e, f, A, B, C, D, E and F.

decimal-constant: an unsigned decimal number - a string of 1 or more digits starting with a non-zero digit. This encoding is not used for numerical values equal or greater than 2**64.

base-64-constant: unsigned base-64 constant encoded as a string starting with "0b" or "0B" followed by 1 or more digits or letters or plus or slash or equal.

regular-numerical-value :  an unsigned integer less than 2**64 encoded as a decimal-constant, hex constant, or base-64 con-stant. For base-64 encoding the encoding is done according to [RFC2045].

large-numerical-value :  an unsigned integer larger than or equal to 2**64 encoded as a hex constant, or base-64 con-stant.

numerical-value: a regular-numerical-value or a large numeri-cal-value. Unsigned integer arithmetic applies to numeric-values.

numeric-range: two numerical-values separated by a tilde.

regular-binary-value :  a binary string less than 64 bits encoded as a decimal constant, hex constant or base-64 con-stant. For base-64 encoding the encoding is done according to [RFC2045]. The length of the string is either specified by the key definition or is implied by the encoding as the mini-mum number of bytes that can hold the encoded string.

large-binary-value :  a binary string encoded as a hex con-stant or base-64 constant. For base-64 encoding the encoding is done according to [RFC2045]. The length of the string is either specified by the key definition or is implied by the encoding as the minimum number of bytes that can hold the encoded string.

binary-value: a regular-binary-value or a large-binary-value. Operations on binary values are key specific.

simple-value: text-value, iSCSI-name-value, boolean-value, numeric-value, a numeric-range or a binary-value.

list-of-values: a sequence of text-values separated by comma


If not otherwise specified, the maximum length of a simple-value (not its encoded representation) is 255 bytes not including the delimiter (comma or null).

Any iSCSI target or initiator MUST support receiving at least 16384 bytes of key=value data in a negotiation sequence except when indi-cating support for very long authentication items by offering or selecting authentication methods such as public key certificates in which case they MUST support receiving at least 64 kilobytes of key=value data.

Text Mode Negotiation

During login, and thereafter, some session or connection parameters are either declared or negotiated through an exchange of textual information.

The initiator starts the negotiation and/or declaration through a Text/Login request and indicates when it is ready for completion (by setting to 1 and keeping to 1 the F bit in a Text Request or the T bit in the Login Request).

The format of a declaration is:

Declarer-> <key>=<valuex>

The general format of text negotiation is:

Originator-> <key>=<valuex>
Responder-> <key>=<valuey>|NotUnderstood|Irrelevant|Reject

The originator or declarer can either be the initiator or the target and the responder can either be the target or initiator, respec-tively. Target requests are not limited to respond to key=value pairs as offered by the initiator. The target may offer key=value pairs of its own.

All negotiations are explicit (i.e., the result MUST be based only on newly exchanged or declared values). There are no implicit offers. If an explicit offer is not made then a reply cannot be expected. Con-servative design requires also that default values should not be relied upon when use of some other value has serious consequences.

The value offered or declared can be an numerical-value, a numerical-range defined by lower and upper value - both integers separated by tilde, a binary value, a text-value, a iSCSI-name-value, an iSCSI-local-name-value, a boolean-value (Yes or No), or a list of comma separated text-values. A range MAY ONLY be offered if it is explic-itly allowed for a key.  An iSCSI-name-value and an iSCSI-local-name-value can be used only where explicitly allowed. A selected value can be an numerical-value, a text-value or a boolean-value.

If a specific key is not relevant for the current negotiation, the responder may answer with the constant "Irrelevant" for all types of negotiation.  However the negotiation is not considered as failed if the response is Irrelevant.

Any key not understood by the responder may be ignored by the responder without affecting the basic function. However, the Text Response for a key not understood MUST be key=NotUnderstood.

The constants "None", "Reject", "Irrelevant", and "NotUnderstood" are reserved and must only be used as described here.

None, Reject or Irrelevant are legitimate negotiation options where allowed but their excessive use is discouraged.
 
Some basic key=value pairs are described in Chapter 11. All keys in Chapter 11, except for the X- extension format, MUST be supported by iSCSI initiators and targets and MUST NOT be answered with NotUnder-stood.

Implementers may introduce new keys by prefixing them with X- fol-lowed by their (reversed) domain name. For example the entity owning the domain acme.com can issue:

X-com.acme.bar.foo.do_something=3

List negotiations

In list negotiation, the originator sends a list of values (which may include "None") in its order of preference.

The responding party MUST answer with the first value that it sup-ports (and is allowed to use for the specific originator) selected from the originator list.

The constant "None" MUST always be used to indicate a missing func-tion. However, None is a valid selection only if it is explicitly offered.

If a responder does not understand any particular value in a list it MUST ignore it. If a responder does not support, does not understand or is not allowed to use all of the offered options with a specific originator, it MAY use the constant "Reject".  The selection of a value not admissible under the selection rules is considered a nego-tiation failure and is handled as a protocol error. The selection rules are key-specific.

Simple-value negotiations

For simple-value negotiations, the responding party MUST respond with the same key. The value it selects, based on the selection rule spe-cific to the key, becomes the negotiation result. For a numerical range the value selected must be an integer within the offered range or "Reject" (if the range is unacceptable).  An offer of a value not admissible MAY be answered with the constant "Reject" or the responder MAY select an admissible value. The selection, by the responder, of a value not admissible under the selection rules is considered a negotiation failure and is handled accordingly. The selection rules are key-specific.

For boolean negotiations (keys taking the values Yes or No), the responding party MUST respond with the same key and the result of the negotiation when the received value does not determine that result by itself. The last value transmitted becomes the negotiation result. The rules for selecting the value with which to respond are expressed as Boolean functions of the value received and the value that the responding party would select in the absence of knowledge of the received value.
 
Specifically, the two cases in which responses are OPTIONAL are:

- The boolean function is "AND" and the value "No" is received. The outcome of the negotiation is "No".
- The boolean function is "OR" and the value "Yes" is received. The outcome of the negotiation is "Yes".

Responses are REQUIRED in all other cases, and the value chosen and sent by the responder becomes the outcome of the negotiation.