[cifs-protocol] RE: erroneous references to little-endian

[Richard Guthrie]

Andrew,

We will continue to work to resolution on the broader issue of how to handle bit fields in the documentation.  Your feedback is much appreciated there.  For this specific issue, in general, for custom-marshaled fields you should see a bit field that follows the RFC convention where the high bit of the first byte to hit the wire is in column 0, and the low bit of the last byte to hit the wire is in column 31 (so that the bits are shown from left-to-right in the order they naturally appear over the network). We are going back through the documentation to ensure that custom marshaled fields have the appropriate specification for endianness.

Please let us know if you have any further questions/comments.

Richard Guthrie
Support Escalation Engineer
Open Protocols Support Team
http://blogs.msdn.com/OpenSpecification 
Tel: +1 (469) 775-7794
E-mail: rguthrie at microsoft.com 

-----Original Message-----
From: Andrew Bartlett [mailto:abartlet at samba.org] 
Sent: Sunday, June 28, 2009 11:56 PM
To: Richard Guthrie
Cc: Interoperability Documentation Help; 'pfif at tridgell.net'; 'cifs-protocol at samba.org'
Subject: RE: erroneous references to little-endian

On Fri, 2009-06-19 at 07:40 -0700, Richard Guthrie wrote:
> Andrew,
> 
> I wanted to confirm that the information below resolves your issue.  If I don't hear from you by Wednesday of next week I will go ahead and archive this issue.

No, it doesn't.  In short, this still feels like a complete mess, and is only made worse by the tables.  

> 
> Thank you for the feedback.  In Section 7.3.1.1, the 
> NETLOGON_NT_VERSION options bit table is indeed presented in 
> little-endian byte ordering with the lowest order byte being 
> represented by bits 0-7, the next higher byte represented by bits 8-15 
> and so on. Therefore the claim that the bit table is presented in 
> little-endian format is correct. We have verified this for other bit 
> fields in [MS-ADTS] as well. The explicit specification of whether the 
> bytes are ordered in little-endian or big endian format is intended to 
> clarify the relative position of the bytes in a multi-byte bit flag.

Ahh, so the table is self-contradictory and even more useless than normal.  I should have remembered, as this was one of the most annoying things I found when first going over this area.

It is *never* valid to present bits in a different order to the bytes.

> The NETLOGON_NT_VERSION options is not represented as an integer 
> string over LDAP. It may appear in the LDAP search filter of an LDAP 
> ping (Section 7.3.3) as a binary encoded value or it appears in an 
> LDAP response to an LDAP ping (Section 7.3.3.2) where it is packed as 
> part of one of the following (in little-endian format):
> NETLOGON_PRIMARY_RESPONSE (described in Section 7.3.1.5), 
> NETLOGON_SAM_LOGON_RESPONSE_NT40 (Section 7.3.1.7), 
> NETLOGON_SAM_LOGON_RESPONSE (Section 7.3.1.8), or 
> NETLOGON_SAM_LOGON_RESPONSE_EX (Section 7.3.1.9).  Please let us know 
> if you have any further questions/feedback.

I think this is an excellent example of why this documentation fails spectacularly to communicate these issues, and presents the least implementable formation for the bit-fields it attempts to describe.

Is is ever actually useful to list bits with a value such that the bit cannot be represented on the network with the calculation of 2^n = bit value?

Thanks,

Andrew Bartlett

--
Andrew Bartlett
http://samba.org/~abartlet/
Authentication Developer, Samba Team           http://samba.org
Samba Developer, Red Hat Inc.