|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: iSCSI - an improved text for 4.1 & 4.2
We are getting close - more comments in text. Julo
Martins Krikis
<mkrikis@yahoo.co To: Julian Satran/Haifa/IBM@IBMIL
m> cc:
Subject: Re: iSCSI - an improved text for 4.1 & 4.2
05/06/2002 11:26
PM
Please respond to
Martins Krikis
--- Julian Satran <Julian_Satran@il.ibm.com> wrote:
>
> comments in text - julo
Thanks for your attention to these issues.
I've deleted everything that I don't have any
more immediate comments on.
> How the encoding is done would be better put higher
> up with the base-64-constant definition, then it
> would
> not need to be repeated again and again.
> +++ that is what regular and large attempt +++
My point was this. The draft mentions 3 times how
the base-64 encoding should be done (i.e., according
to RFC2045). It does this for regular-numerical,
regular-binary and large-binary values. It forgets
to say this for large-numerical. Instead of these
3 (should have been 4?) times, it would have sufficed
to say so once and say it where the base-64-constant
is defined. And it would have been better to say it
there because then one would know how to encode this
constant immediately, before reading about its
applicability to regular/large-numerical/binary
values...
+++ OK - now that I understand you +++
> > 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.
>
> The last sentence is ambiguous, IMHO, and incorrect
> no matter how understood. If, encoded as
> as a hex constant, the value is 0x000f, what is its
> length when decoded? 6 bytes ("0x000f" w/o '\0')
> or 1 byte (containing bits 00001111)? The answer
> that I think we want is 2 bytes... The problem is
> that
> not knowing what the string is, we can't tell
> how many bytes are required to hold it. Some other
> description will be necessary, I'm afraid.
>
> +++ that is incorrect. the text says the minimum
> number of BYTES:
> 0xf or 0x0f fit in ONE byte, 0x000f fit in 2 bytes.
It all depends on how "fit" is defined. Since it
isn't, I can quite reasonably assume that 0x000f
does fit in 1 byte. Therefore, the draft should
say that for hex-encoded binary strings, the
leading zeroes in hex encoding do count. Each
hex digit results in 4 bits. Then we can say that
the string consists of the minimum number of bytes
that can hold all those bits.
+++ well we must be a funny sort of computer geeks if we assume that the
rest of the text is understandable but here we have an issue. How about the
following text:
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
nul (0x00) - nul 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
zero-byte delimiter that marks the end of any key=value pair
(includ-ing 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, dot, minus, plus, commercial at, and
under-score, 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; no nul characters are
allowed in the string. This encoding is to be used for
local-ized (internationalized) aliases.
boolean-value: the string "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. Hex-constants are used
to encode numerical values or binary strings. When used to
encode numerical values the excesive use of leading 0 digits is
discouraged. When used to encode binary strings hexadecimal
constants have an implicit byte-length that includes 4 bits for
every hexadecimal digit of the constant, including eading
zeroes (i.e., a hex-constant of n hexadeci-mal digits has a
byte-length of (the integer part of) (n+1)/ 2).
decimal-constant: an unsigned decimal number - the digit 0 or 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. Decimal-constants are used to encode numerical values or
binary strings. When used to encode binary strings decimal
constants have an implicit byte-length that is the minimum
number of bytes needed to represent the base2 encoding of the
decimal number.
base64-constant: base64 constant encoded as a string starting
with "0b" or "0B" followed by 1 or more digits or letters or
plus or slash or equal. The encoding is done according to
[RFC2045]. base64-constants are used to encode numerical
val-ues or binary strings. When used to encode numerical values
the excesive use of leading 0s prior to encoding - encoded as
"A" - is discouraged. When used to encode binary strings
base64-constants have an implicit byte-length that includes 6
bits for every character of the constant excluding trailing
equals (i.e., a base64-constant of n base64 characters with m
trailing equals has a byte-length of ((the integer part of)
((n+3)*3/4) - m).
regular-numerical-value : an unsigned integer less than 2**64
encoded as a decimal-constant, hex constant, or
base64-con-stant.
large-numerical-value : an unsigned integer larger than or equal
to 2**64 encoded as a hex constant, or base64-constant.
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 where
the value to the right of tilde must not be lower that the
value to the left.
regular-binary-value : a binary string less than 64 bits encoded
as a decimal constant, hex constant or base64-con-stant. The
length of the string is either specified by the key definition
or is implicit byte-length of the encoded string.
large-binary-value : a binary string encoded as a hex-con-stant
or base64-constant. The length of the string is either
specified by the key definition or is implicit byte-length of
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 zero byte).
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.
++++
> Hex constant encode binary strings and not numbers.
> to avoid any ambiguity I've rephrased it:
>
> 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 all
> hexadecimal digits of the encoded string. ++++
This, IMO, didn't clear the problem that I was
referring to. Furthermore it made me notice that
the length-of-string question is not applicable
to base-64-constants, and therefore the explanation
of how to determine the string length should say
that this is only for hex encoding. (Currently it
looks like this refers to all kinds of encodings,
then refers to hexadecimal digits.) How about this:
The length of the string is either specified
by the key definition or by its encoding.
For strings encoded as hex-constants, every
hexadecimal digit of the encoding, including
leading zeroes, represents 4 bits of the original
string. Therefore, if the hex-constant has n
hexadecimal digits, the length of the string that
it encodes is (the integer part of) (n+1)/2.
> > simple-value: text-value, iSCSI-name-value,
> > boolean-value,
> > numeric-value, a
> > numeric-range or a binary-value.
>
> iSCSI-local-name-value seems to be missing.
>
> +++ they appear later not as simple-values ... +++
Only in the subsection Text Mode Negotiation, where
all kinds of simple-values are listed again (begging
the question, why was the simple-value defined if
all this is listed again explicitly). OK, I take it
that the main reason for defining simple-value
was the 255 byte length restriction and that
iSCSI-local-name-value doesn't have it and therefore
isn't simple. If so, then please disregard my previous
comment. Please note however, that should such values
ever become negotiated, the draft hasn't described
yet how to do that (only simple-values and
lists-of-values are covered).
> > ... 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".
>
> If I don't support "all", but support at
> least one of the offered values,
> I should answer with something I support
> and not with Reject. "Options" have not been
> defined or used before. Alright, I'm not a
> native English speaker myself, but I'll volunteer:
>
> If each of the offered values is not understood
> or not supported, or the responder is not
> allowed to use it with the specific
> originator,it MAY use the constant "Reject".
> +++ I have made it Anyone - I am sick about this
> statement that everybody understands and
> everybody tries to rephrase +++
Sorry, I wasn't aware of this statement even being
noticed by anybody. I can't see how "Anyone" could
make it better, but I'll wait for the text.
> > 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.
>
> It was just said above (I didn't quote it)
> that the selection rule is to pick the first
> value supported. Thus, I'm not sure why here the
> rule is key-specific.
>
> +++ If you are offered a range and select ouside the
> range or if you are
> offered a key=no and you respond key=yes when the
> specific rule is AND or
> if you are given a buffer-size and you select a
> larger value - those are
> each errors but each according to a separate and key
> specific rule +++
Yes, those are the generic rules, but the point
was that this text is in the context of list
negotiations, where the only rule is "pick-the-first".
And it was just said that that's the rule. Therefore
telling afterwards that the rule is key-specific
can be confusing.
+++ I'll fix the text for list +++
> > 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.
>
> What was meant here by "value not admissible"?
> Outside the legal range
> of values or simply outside the range that the
> responder supports?
+++ See above +++
No, sorry, the above was about selection. This is
about offers. Concrete example: IFMarkInt. The
allowed range is 1 to 65535. The range I support
is 1 to 16. If the other side sends 17 is this
"value not admissible"? If the other side sends
65536, is that "value inadmissible"? The draft
is not clear here, that's all I'm pointing out.
> Am I right or wrong?
+++ You are wrong! +++
I think I was right :-) But I am happy with how
it was rephrased so I'll move on.
Thanks,
Martins Krikis, Intel Corp.
P.S. I hope the next version will clearly address
the repetition issues regarding Reject and Irrelevant.
Previous confusion about this has severely impacted
my own implementation.
+++ 4.2 text is
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.
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 respond with the same key and select first
value that it supports (and is allowed to use for the specific
origi-nator) 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 anyone of the offered options with a
spe-cific originator, it MAY use the constant "Reject" or it respond
with an admissible value. The selection of a value not offered is
consid-ered a negotiation failure and is handled as a protocol
error.
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 (e.g., not within the specified bounds)
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 have selected if given a choice.
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.
__________________________________________________
Do You Yahoo!?
Yahoo! Health - your guide to health and wellness
http://health.yahoo.com
Home Last updated: Fri May 10 17:18:27 2002 10065 messages in chronological order |