iSCSI: More draft-06 comments

[Mark Bakke <mbakke@cisco.com>]

Julian-

Here are a few more comments and proposed clarifications
on draft-06.  I apologize if some of them overlap with
comments made already.

--
Mark


1.2.4 - We'd like to add a clarification on the use of the keyword
"none" versus silently ignoring the key.

If a target does not explicitly send back <key>=none, the initiator will
not be sure whether the target selected none, or didn't understand the
option.  On each offered key, there are four choices a target can make:

   <key>=<some-value>
   <key>=none
   <key>=reject
   <key>=NotUnderstood

Given these options, the responding party MUST NOT silently ignore
a key.  The alternative is to remove the NotUnderstood value and have
silently ignoring a key to mean the same thing, although it's probably
best to be explicit.  BTW, are the reserved words case-sensitive?

The following is our understanding of what this section means:


1.2.4 Text Mode Negotiation 
    
   During login and thereafter some session or connection parameters are 
   negotiated through an exchange of textual information. 
    
   In "list" negotiation, the offering party sends a list of values for 
   a key in its order of preference. 
    
   The general format of text negotiation is: 
    
      Offer-> <key>=<value1>,<value2>,...,<valuen> 
      Answer-> <key>=<valuex> | "none" | "reject" | "NotUnderstood"

   There are four possible <valuex> answers:

   <key>=<valuex>

       The responding party answers with the first value from the list it 
       supports and is allowed to use for the specific initiator. 

   <key>=none

       The responding party supports none of the values in the list.
       "none" is also a valid keyword within the Offer, for example:

       DataDigest=crc-32C,none

       means that the offering party would prefer using crc-32c, but
       will accept "none" as well.

   <key>=reject

       If a target is not supporting, or not allowed to use with a specific 
       initiator, any of the offered options, it may use the value "reject". 
       The values "none" and "reject" are reserved and must be used only as 
       described here. 

   <key>=NotUnderstood

       If the responding party did not understand or recognize a key,
       it must indicate this with NotUnderstood.       
 
   The values "none", "reject", and "NotUnderstood" are reserved and
   must be used only as described here.  They are case-insensitive.

   The responding party MUST NOT silently ignore any keys sent by the
   offering party, and MUST respond with one of the four above options.
    
   In "numerical" negotiations, the offering and responding party state 
   a numerical value. The result of the negotiation is key dependent; 
   usually the lower or the higher of the two values is used.  

2.1 - Need to say that padding is not included in the
length field.  Should also specify a MUST for the pad byte value.

How about:

   iSCSI PDUs are padded to an integer number of 4 byte words. The 
   value of the pad bytes must be 0.  The pad bytes are not
   included in the DataSegmentLength field. 

2.2.1 - Also say here that the length fields do not include
the digests.  How about:

   Optional header and data digests protect the integrity and 
   authenticity of header and data, respectively. The digests, if 
   present, are located, respectively, after the header and PDU-specific 
   data and include the padding bytes.  The lengths of the digests
   are not included in the header or data length fields.  
 
2.2.2.5 - TotalAHSLength - How about:

   Total length of all AHS header segments in 4 byte words including 
   padding if any.  This length field does not include header
   digests.

2.2.2.6 - Need to specify whether DataSegmentLength includes
the data digest.  How about:

   This is the data segment payload length in bytes.  This length
   does not include either padding or data digests.

2.2.3.1 - Need clearer description of drop bit:

      B7 - Drop Bit - if set to one, the implementation may ignore
      this AHS if it is not understood; if set to zero, the
      implementation must reject this PDU if this AHS type is
      not understood.

2.8.3 - Need maximum size for a key name, and a harder maximum
  for the value; how about adding:

  Key names MUST NOT exceed 64 characters; key values MUST NOT
  exceed 255 characters.

  This would replace the sentence "No key SHOULD contain..."

2.8.3 - I don't think that we need or want a lot of flexibility
with regard to text value representation.  In particular, I think
that it's up to each key definition whether to use character,
decimal, or hexadecimal representations, and that each key
definition must pick just one of these for everyone to use.
There's just no reason for one implementation to be able to
send a key in one format, and another implementation to be able
to send the same key in another format; that will just make
interoperability harder.

We would like to see he statement about characters strings
and binary numbers tightened up to read:

   Character strings are represented as plain UTF-8 text.
   Numeric values with maximum values less than 32 bits
   should be represented as decimal numbers, but may be
   represented in hex if documented for the particular key.
   All binary values greater than 32 bits must be represented
   in hexadecimal.  Hexadecimal numbers are case-insensitive;
   either upper or lower case must be accepted.  The use of
   either decimal or hexadecimal (but not both) is specified
   separately for each key.  As this format is then implied,
   no prefixes such as "0x" are necessary.


2.8.3 - (not its string representation) - I think that the
limit should be on the string representation, not on the
converted value.

2.8.3 - We need to have the discussion on whether text commands
and responses are done all in software, and whether the size
of a text response really matters.  We'll bring this up on the
list separately.

2.10 - Login command - Need to put an X in the first bit of the
message header for the restart bit.

2.18.2 - If you want a useful example of a SCSI event, here's
one that could be added:

   One example using the SCSI Asynchronous Event would report
   that LUN data has changed if, for instance, a new LUN is
   added to the target.  Here is what the sense data would
   contain:

    senseData[0] = 0x71;        // Error code.
    senseData[2] = 0x06;        // Sense key: UNIT ATTENTION
    senseData[12]= 0x3F;        // ASC (REPORTED LUNS DATA HAS CHANGED)
    senseData[13]= 0x0E;        // ASCQ

   The DataSegmentLength in this example would be 14 (decimal).

Appendices - It would be nice to use a different numbering
scheme that starts over with each appendix; such as
A.1, A.2, B.1, etc.  Is this a limitation of the word doc?

B.01 - Need to specify bit reflection and byte ordering for the
CRC-32C.  Should add an example message and the expected CRC
for interoperability purposes.  I can put together a message
if you like.

B.03 - Should have an example for a target that doesn't support
authentication and an initiator that insists on authentication.

B.03 - This section should be broken into separate headings for
SRP, CHAP, etc. to make them easier to find.

B.03 - (p 108) A lot of fields are shown as numbers; this section
should specify which numbers are in hex and which (if any) are
in decimal.

B.03 - SRP uses "U=" for the name key; CHAP uses "N=" for its
name key.  They could be made the same for consistency, but it's
not really a problem.

E - Should explicitly define what "Who" means in the intro
to appendix E.  (e.g. who == which role can send the key).
Perhaps "role" would be a better word.

E - The login and digest keys are missing from appendix E; I think
it would be worth describing all of the keys here.

E - Each key should describe the exact format of its value, and
state whether it is a hex, decimal, UTF-8 string, etc.


E.23 - DataPDULength - we need to clarify that if a session has
negotiated a DataPDULength, that the initiator and target MUST NOT
send data PDUs of less than this length, except for the last PDU (or
only PDU) of a command.  This is what an implementation is likely
to do anyway, and will make it practical to keep the iSCSI data CRC
end-to-end, since the data CRC covers a PDU, and not a command's
worth of data.


-- 
Mark A. Bakke
Cisco Systems
mbakke@cisco.com
763.398.1054