Subject: [Netconf] list of 4742bis edits

From: Martin Bjorklund <[email-masked]>
Date: Fri, 10 Dec 2010 15:22:55 +0100 (CET)

Hi,

As requested by the chairs, attached is the updated list of proposed
edits to 4742bis.  Don't forget to send comments before 14 December
2010!

/martin

OLD (in 3.1):

   The following example shows a capability exchange.  Data sent by the
   NETCONF client are marked with "C:" and data sent by the NETCONF
   server are marked with "S:".

   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <capabilities>
   S:     <capability>
   S:       urn:ietf:params:xml:ns:netconf:base:1.0
   S:     </capability>
   S:     <capability>
   S:       urn:ietf:params:ns:netconf:capability:startup:1.0
   S:     </capability>
   S:   </capabilities>
   S:   <session-id>4<session-id>
   S: </hello>
   S: ]]>]]>

   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <capabilities>
   C:     <capability>
   C:       urn:ietf:params:xml:ns:netconf:base:1.0
   C:     </capability>
   C:   </capabilities>
   C: </hello>
   C: ]]>]]>

NEW:

   The following example shows a capability exchange.  Data sent by the
   NETCONF client are marked with "C: " and data sent by the NETCONF
   server are marked with "S: ".

   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <capabilities>
   S:     <capability>
   S:       urn:ietf:params:xml:ns:netconf:base:1.1
   S:     </capability>
   S:     <capability>
   S:       urn:ietf:params:ns:netconf:capability:startup:1.0
   S:     </capability>
   S:   </capabilities>
   S:   <session-id>4<session-id>
   S: </hello>
   S: ]]>]]>

   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <capabilities>
   C:     <capability>
   C:       urn:ietf:params:xml:ns:netconf:base:1.1
   C:     </capability>
   C:   </capabilities>
   C: </hello>
   C: ]]>]]>

Delete this from 3.1:

   As the previous example illustrates, a special character sequence,
   ]]>]]>, MUST be sent by both the NETCONF client and the NETCONF
   server after each XML document in the NETCONF exchange.  This
   character sequence MUST NOT appear in an XML document.

NEW (right after the first paragraph in Section 4.):

4.1.  Framing protocol

  The previous version of this document defined the character sequence
  "]]>]]>" as a message separator, under the assumption that it could
  not be found in well-formed XML documents.  However, this assumption
  is not correct.  It can legally appear in XML attributes, comments,
  and processing instructions.  In order to solve this problem, and at
  the same time be compatible with existing implementations, this
  document defines the following framing protocol.

  The <hello> message MUST be followed by the character sequence
  "]]>]]>".  Upon reception of the <hello> message, the receiving
  peer's SSH Transport layer conceptually passes the <hello>
  message to the Messages layer.  If the :base:1.1 capability is
  advertised by both peers, the chunked transfer mechanism (see
  Section 4.1.1) is used for the remainder of the NETCONF
  session.  Otherwise, the old end-of-message based mechanism
  (see Section 4.1.2) is used.

4.1.1.  Chunked Framing Mechanism

  This mechanism encodes all NETCONF messages with a chunked
  framing.  Specifically, the message follows the ABNF [RFC 5234]
  rule Chunked-Message:

      Chunked-Message = 1*chunk
                        end-of-chunks

      chunk           = LF HASH chunk-size LF
                        chunk-data
      chunk-size      = 1*DIGIT1 0*DIGIT
      chunk-data      = 1*OCTET

      end-of-chunks   = LF HASH HASH LF

      DIGIT1          = %x31-39
      DIGIT           = %x30-39
      HASH            = %x23
      LF              = %x0A
      OCTET           = %x00-FF

   The chunk-size field is a string of decimal digits indicating the
   number of octets in chunk-data.  Leading zeros are prohibited, and
   the maximum allowed chunk-size value is 4294967295.

   As an example, the message:

     <rpc message-id="102"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <close-session/>
     </rpc>

   could be encoded as:

     #4
     <rpc
     #18
      message-id="102"
     
     #79
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <close-session/>
     </rpc>
     ##

  Conceptually, the SSH Transport layer encodes messages sent by the
  Messages layer, and decodes messages received on the SSH channel
  before passing them to the Messages layer.

  If an error occurs during the decoding process, the peer MUST
  terminate the NETCONF session by closing the corresponding SSH
  channel.

4.1.2.  End-of-message Framing Mechanism

  This mechanism exists for backwards compatibility with
  implementations of previous versions of this document.  It is only
  used when the remote peer does not advertise the :base:1.1
  capability.

  When this mechanism is used, the special character sequence
  "]]>]]>", MUST be sent by both the NETCONF client and the NETCONF
  server after each message (XML document) in the NETCONF exchange.
  Conceptually, the SSH Transport layer passes any data found in
  between the "]]>]]>" characters to the Messages layer.

OLD (section 4):

   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <rpc message-id="105"
   C: xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <get-config>
   C:     <source><running/></source>
   C:     <config xmlns="http://example.com/schema/1.2/config">
   C:      <users/>
   C:     </config>
   C:   </get-config>
   C: </rpc>
   C: ]]>]]>

   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <rpc-reply message-id="105"
   S: xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <config xmlns="http://example.com/schema/1.2/config">
   S:     <users>
   S:       <user><name>root</name><type>superuser</type></user>
   S:       <user><name>fred</name><type>admin</type></user>
   S:       <user><name>barney</name><type>admin</type></user>
   S:     </users>
   S:   </config>
   S: </rpc-reply>
   S: ]]>]]>

NEW:

   C: 
   C: #271
   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <rpc message-id="105"
   C:      xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <get-config>
   C:     <source><running/></source>
   C:     <config xmlns="http://example.com/schema/1.2/config">
   C:      <users/>
   C:     </config>
   C:   </get-config>
   C: </rpc>
   C:
   C: ##

   S: 
   S: #404
   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <rpc-reply message-id="105"
   S:            xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <config xmlns="http://example.com/schema/1.2/config">
   S:     <users>
   S:       <user><name>root</name><type>superuser</type></user>
   S:       <user><name>fred</name><type>admin</type></user>
   S:       <user><name>barney</name><type>admin</type></user>
   S:     </users>
   S:   </config>
   S: </rpc-reply>
   S:
   S: ##

OLD (Section 5):

   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <rpc message-id="106"
   C: xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <close-session/>
   C: </rpc>
   C: ]]>]]>

   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <rpc-reply id="106"
   S: xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <ok/>
   S: </rpc-reply>
   S: ]]>]]

NEW:

   C: 
   C: #141
   C: <?xml version="1.0" encoding="UTF-8"?>
   C: <rpc message-id="106"
   C:      xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   C:   <close-session/>
   C: </rpc>
   C:
   C: ##

   S: 
   S: #140
   S: <?xml version="1.0" encoding="UTF-8"?>
   S: <rpc-reply id="106"
   S:            xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
   S:   <ok/>
   S: </rpc-reply>
   S:
   S: ##

OLD (Section 6):

   RFC 4742 assumes that the EOM sequence cannot appear in any XML
   document, which turned out to be mistaken.  The EOM sequence can
   cause operational problems and open space for attacks if sent
   deliberately in an XML document.  It is however believed that the
   associated threat is not very high.  This document keeps using the
   EOM sequence to avoid incompatibility with existing implementations.
   Implementations of SSH transport must exercise extra care and make
   sure the EOM sequence is not present in an XML document.

NEW:

   RFC 4742 assumes that the EOM sequence "]]>]]>" cannot appear in
   any well-formed XML document, which turned out to be mistaken.  The
   EOM sequence can cause operational problems and open space for
   attacks if sent deliberately in RPC messages.  It is however
   believed that the associated threat is not very high.  This
   document still uses the EOM sequence for the initial <hello>
   message to avoid incompatibility with existing implementations.
   When both peers implement this specification, a proper framing
   protocol is used for the rest of the NETCONF session, to avoid
   injection attacks.

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 10 Dec 2010 16:41:36 +0100

Hi,

I have reviewed the text with the proposed edits. I fully support the
inclusion of the chunked framing protocol because it significantly
increases robustness of the SSH transport. I also checked the chunk
sizes in all examples.

My suggestions for minor improvements of the proposed edits are below.

>   not be found in well-formed XML documents.  However, this assumption

s/could not be found/cannot appear/

>   terminate the NETCONF session by closing the corresponding SSH

I think the paragraph starting with "To continue the example given
above, ..." and the <get-config> example belongs here and not after
4.1.2.

>   implementations of previous versions of this document.  It is only

s/is only/MUST be/

>   used when the remote peer does not advertise the :base:1.1

... , and MUST NOT be used otherwise.

>   between the "]]>]]>" characters to the Messages layer.

According to the ABNF, all chunks - including the first one - begin with
LF, so I think all examples using the chunk framing should start with
the empty line, i.e. either

    C:

or

    S:

to indicate the presence of LF.

Lada
 
> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 10 Dec 2010 16:47:20 +0100 (CET)

Hi,

> to indicate the presence of LF.

I think they do, don't they?

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 10 Dec 2010 17:12:34 +0100

> I think they do, don't they?

Oh yes, sorry, I had the changes you sent on 30 November and didn't
notice you had corrected this in the new version.

Thanks, Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 10 Dec 2010 21:32:40 +0100

>    C: ##

[...]
 
>    S: ##

[...]

>    C: ##

[...]

>    S: ##

My understanding is that these empty lines are not necessarily needed.
If this is correct, then these examples might lead people to believe
these empty lines are needed and I would prefer that these empty lines
are removed.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1, 28759 Bremen, Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 10 Dec 2010 22:52:43 +0100

> these empty lines are needed and I would prefer that these empty lines

I agree. On the other hand, shouldn't the examples end with e.g.

    C: ##
    C:

to indicate the LF *after* the double hash?

Lada

--
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 10 Dec 2010 22:59:39 +0100

> to indicate the LF *after* the double hash?

We do not have a good way of visualizing line feeds that are distinct
from the word processing line feeds. This again might be read as two
line feeds - so its hardly better.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 10 Dec 2010 23:36:04 +0100 (CET)

> these empty lines are needed and I would prefer that these empty lines

Sure, that's an option.   If so, we must also decrement each chunk
size by 1.  If that makes the examples more clear, that's fine with me.

/martin

---

From: "Ersue, Mehmet (NSN - DE/Munich)" <[email-masked]>
Date: Thu, 16 Dec 2010 18:34:56 +0100

Hi All,

AFAICS we don't have any consensus to do a change and
can see the original proposal from Martin as the result 
of the discussion.

If there is anybody who sees the discussion differently
please state so at the latest by Friday EOB. 

If no, Margaret is going to submit 4742bis on Monday.

Mehmet

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of ext Martin Bjorklund
> Sent: Friday, December 10, 2010 11:36 PM
> To: [email-masked]
> Cc: [email-masked]
> Subject: Re: [Netconf] list of 4742bis edits
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 16 Dec 2010 21:28:55 +0100

> please state so at the latest by Friday EOB. 

I have not seen anybody speaking up against the suggested removable of
empty lines. Lada was in favour, Martin said the numbers need adjusted,
which is correct. Am I missing emails? I also checked the archive to
be sure...

/js

---

From: Andy Bierman <[email-masked]>
Date: Thu, 16 Dec 2010 13:05:10 -0800

> which is correct. Am I missing emails? I also checked the archive to

I just want the text to mention whether the example has an EOLN 0xa at the end.
It should be explained why 1 example is different than the other 2.
I don't care which way it is done (blank line or not).

> /js

Andy

---

From: "Ersue, Mehmet (NSN - DE/Munich)" <[email-masked]>
Date: Thu, 16 Dec 2010 22:33:52 +0100

Please provide concrete OLD/NEW text.
Thank you.

Mehmet

> From: ext Andy Bierman [mailto:[email-masked]]
> Sent: Thursday, December 16, 2010 10:05 PM
> To: Ersue, Mehmet (NSN - DE/Munich); [email-masked]; ext Margaret
> Wasserman
> Subject: Re: [Netconf] Submission of 4742bis WAS:RE: list of 4742bis
> edits
>

---

From: Andy Bierman <[email-masked]>
Date: Thu, 16 Dec 2010 13:43:19 -0800

OLD:

     #79

NEW:

     #79

  Note that there is no newline character after the 'rpc' end tag, so there
  is no blank line generated before the '##' line.

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Ersue, Mehmet (NSN - DE/Munich)
Sent: Thursday, December 16, 2010 1:34 PM
To: ext Andy Bierman; [email-masked]; ext Margaret Wasserman
Subject: Re: [Netconf] Submission of 4742bis WAS:RE: list of 4742bis edits

Mehmet

---

From: "Ersue, Mehmet (NSN - DE/Munich)" <[email-masked]>
Date: Thu, 16 Dec 2010 23:03:18 +0100

Sounds good to me.

Mehmet

> From: ext Andy Bierman [mailto:[email-masked]]
> Sent: Thursday, December 16, 2010 10:43 PM
> To: Ersue, Mehmet (NSN - DE/Munich); ext Andy Bierman;
> [email-masked]; ext Margaret Wasserman
> Subject: RE: [Netconf] Submission of 4742bis WAS:RE: list of 4742bis
> edits
> 
> 
> OLD:
> 
>      #79
> Behalf Of Ersue, Mehmet (NSN - DE/Munich)
> > > I have not seen anybody speaking up against the suggested
removable
> > of
> > I just want the text to mention whether the example has an EOLN 0xa
> at
> > the end.

---

From: Ladislav Lhotka <[email-masked]>
Date: Fri, 17 Dec 2010 09:52:23 +0100

>   before passing them to the Messages layer.

+1.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 17 Dec 2010 10:11:03 +0100 (CET)

> >   before passing them to the Messages layer.

+1

/martin

---

From: "t.petch" <[email-masked]>
Date: Wed, 22 Dec 2010 15:23:41 +0100

----- Original Message -----
From: "Martin Bjorklund" <[email-masked]>
To: <[email-masked]>
Cc: <[email-masked]>
Sent: Friday, December 10, 2010 11:36 PM
Subject: Re: [Netconf] list of 4742bis edit
> size by 1.  If that makes the examples more clear, that's fine with me.

Well  the empty lines were removed but the counts were not decremented so
I think the result unclear:-(

Second, the ABNF for the chunking says LF for the separating character
so I think the reference later to 'newline' confusing - replace 'newline' by
'Line Feed'
to match the ABNF. (Some would regard newline as CR LF not just LF)

Third, more subtle,
"Note that there is no newline character after the 'rpc' end tag"
well there is a Line Feed there just as there is after
        message-id="102"
             xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> 
         <close-session/>

The difference is that in these last three cases the Line Feed is
counted as part of the chunk-data whereas in the first case
it is counted as part of the end-of-chunks.  This needs stating.

Clearest would be a visible Line Feed character plus an explanation -
anything not used in the I-D would do -  or has that approach been rejected?

And yes, I comment as quickly as I am able to, but that is not as
quickly as yourselves:-(

Tom Petch