Subject: iSCSI: More draft-06 comments

From: Mark Bakke <[email-masked]>
Date: Fri, 25 May 2001 15:34:07 -0500

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
[email-masked]
763.398.1054

---

From: [email-masked]
Date: Sat, 26 May 2001 12:38:18 +0300

comments in text - Thanks, Julo

Mark Bakke <[email-masked]> on 25-05-2001 23:34:07

Please respond to Mark Bakke <[email-masked]>

To:   Julian Satran/Haifa/IBM@IBMIL, IPS <[email-masked]>
cc:
Subject:  iSCSI: More draft-06 comments

Julian-

--
Mark

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

   <key>=<valuex>

   <key>=none

       DataDigest=crc-32C,none

   <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

+++ in fact (after many debates) the current text reads:

1.1.1     1.1.1     Text Mode Negotiation

   In "list" negotiation, the offering party sends a list of values for a
   key in its order of preference.

   The value "none" MUST always be used to indicate a missing function.
   However, none is a valid selection only if it is explicitly offered and
   MAY be selected by omission (i.e., <key>=none MAY be omitted).

   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.  Any key not understood is answered with
   "NotUnderstood".

      Offer-> <key>=<value1>,<value2>,...,<valuen>
      Answer-> <key>=<valuex>|reject|NotUnderstood

   In "numerical" negotiations, the offering and responding party state a
   numerical value. The result of the negotiation is key dependent;
   frequently the lower or the higher of the two values is used.

   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.

++++ although this text has no ambiguity there is still a raging debate
between the proponents of an always explicit response (Matt and - in some
covoluted form Steph - and those like Steve Senum who whould like a hiatus
signaling a default.  The current text let you set none by default.  This
can be changed by removing the "  and MAY be selected by omission... "  +++
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:

+++ 2.1 reads now:

1.1  iSCSI PDU Length and Padding

   iSCSI PDUs are padded to an integer number of 4 byte words. The padding
   bytes should be 0.

   The length is handled separately is the length parts:

1.1.1.1   TotalAHSLength

   padding if any.

1.1.1.2   DataSegmentLength

   This is the data segment payload length in bytes (excluding padding).

   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.
+++  the PDU outline in 2.2 is clear enough.  The negative specification
(does not include like)
is unbounded. I will include some words in 2.2.1 +++

+++ will fix +++

  This would replace the sentence "No key SHOULD contain..."
+++ OK except that i'll make it bytes to account (limit) for I18N too. It
will read:

The data length of a text command or response SHOULD be less than 4096
bytes.  Key names MUST NOT exceed 64 bytes. Key values MUST NOT exceed 255
characters.

++++

+++ Numbers are often copied from various sources. Why should we limit
them?
There is no real gain and implementations will have anyhow to have both
conversions+++

++???+++

+++ go ahead +++
+++ will fix +++

+++ do we need an example? ++++

+++ I have a tool problem here ... and was unable to fix it up to now
(Word!) +++

+++ I don't know what reflection is.  If bit and byte ordering are
specified do we need something
more or is it a software specific issue +++

+++ Will consider - however it looks like a case of reject for which there
are examples +++

+++ I will try but I am not sure I'll manage an unfriendly tool +++

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.
+++ I think we took the names from the referred RFCs - but we will check
again +++
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.
+++ I'll replace it with "Who can send:" +++
E - The login and digest keys are missing from appendix E; I think
it would be worth describing all of the keys here.
+++ They are all in the security appendix +++
E - Each key should describe the exact format of its value, and
state whether it is a hex, decimal, UTF-8 string, etc.

+++ I really don't see a need to limit further freedom of expression :-)
+++

+++ you mean a data sequence (on R2T there can be several)?  I assume most
of implementation will do that for efficiency reasons but why should we
mandate it?  +++

--
Mark A. Bakke
Cisco Systems
[email-masked]
763.398.1054