Subject: Re: [Netconf] Comments on draft-badra-netconf-rfc5539bis-02.txt

From: Alan Luchuk <[email-masked]>
Date: Wed, 19 Sep 2012 10:33:25 -0400 (EDT)

Hello,

Regarding Martin's comments about draft-badra-netconf-rfc5539bis-02.txt, 
available at:

   http://www.ietf.org/mail-archive/web/netconf/current/msg07683.html

I've gathered and replied to the comments starting with the ones that 
should require little or no discussion, then progressing to the ones 
that may require more discussion.

Thanks to Martin for the following proposed changes.  These clarify the
specification and should require very little or no disussion, so I 
agree these changes should be added:

>  o  3.2
>
>   OLD:
> 
>    The server MUST verify the identity of the client to ensure that the
>    incoming client request is legitimate before any configuration or
>    state data is sent to or received from the client.
> 
>   NEW:
> 
>    The server MUST verify the identity of the client to ensure that the
>    incoming client request is legitimate before the NETCONF session is
>    started.
> 
> 
> 
> o  3.2.1
> 
>   OLD:
> 
>    The NETCONF server MUST implement the algorithms for deriving NETCONF
>    usernames from presented certificates that are documented in the
>    ietf-netconf-tls YANG module.
>
>   Add a forward reference, like:
>
>   NEW:
> 
>    The NETCONF server MUST implement the algorithms for deriving NETCONF
>    usernames from presented certificates that are documented in the
>    ietf-netconf-tls YANG module, defined in Section 3.2.1.3.
>                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^ 
> 
> 
> o  3.2.1.2
> 
>   OLD:
> 
>     For details on how the PSK
>     identity MAY be encoded in UTF-8, see section 5.1. of RFC [RFC6241].
> 
>   NEW:
> 
>     For details on how the PSK
>     identity MAY be encoded in UTF-8, see section 5.1. of RFC [RFC4279].
> 
> 
> 
> o  YANG module
>
>    The YANG module is not valid:
>  
>    ietf-netconf-tls.yang:389: error: unexpected keyword "pattern"
>  
>    (pattern should be a substatement to string)
>
>    OLD:
>
>      leaf valid-not-after {
>        type yang:date-and-time;
>        description
>          "This PSK identity is not valid before the given data
>           and time.";
>      }
> 
>      leaf key {
>        type string;
>        pattern '([0-9a-fA-F]){2}(:([0-9a-fA-F]){2})*';
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>        nacm:default-deny-all;
>        description
>          "The key associated with the PSK identity";
>      }
>

Proposed new:

     leaf valid-not-after {
       type yang:date-and-time;
       description
         "This PSK identity is not valid before the given data
          and time.";
     }

     leaf key {
       type string {
         pattern '([0-9a-fA-F]){2}(:([0-9a-fA-F]){2})*';
       }
       nacm:default-deny-all;
       description
         "The key associated with the PSK identity";
     }

>     o  feature map-certificates
> 
>       OLD:
> 
>         "The :map-certificates capability implements mapping X.509
>          certificates to NETCONF user names.";
> 
>       This is not a capability, and the ":" notation is confusing.
> 
>       NEW:
> 
>         "The map-certificates feature indicates that the server implements
>          mapping X.509 certificates to NETCONF user names.";
> 
> 
>     
>     o  feature map-pre-shared-keys
> 
>       OLD:
> 
>         "The :map-pre-shared-keys capability implements mapping TLS
>          pre-shared keys to NETCONF user names.";
> 
>       This is not a capability, and the ":" notation is confusing.
> 
>       NEW:
> 
>         "The map-pre-shared-keys feature indicates that the server 
>          implements mapping TLS pre-shared keys to NETCONF user names.";
>                                                                   ^^^^ 
>

The following proposed changes affect the content and may require more 
discussion.

>  
> o  3.2.1
> 
>     The NETCONF server MAY
>     use any of the following algorithms to produce the NETCONF username
>     from the certificate presented by the NETCONF client:
> 
>   This sounds as the server also may use some other algorithm?  Is
>   this intentional?
>

Proposed new text:

    The NETCONF server uses one of the following algorithms to produce a
    NETCONF username from the certificate presented by the NETCONF client:

> 
> o  3.2.1.1
> 
>    A client certificate has an identity: the certificate.  The TLS and
>    corresponding protocols provide an identity.
> 
>   Did you mean "The TLS and corresponding protocols provides this
>   identity"?  If not, please clarify.
> 
> 
> o  3.2.1.1
> 
>     If a locally held copy of a trusted CA certificate is configured in
>     the transformation container,
> 
>   What is "the transformation container"?
> 
>     and that CA certificate was used to
>     validate the path to the presented certificate, then the NETCONF
>     server SHOULD use that list entry in the transformation container.
> 
>   What should the server use that list entry for?   And since this is
>   a SHOULD, it seems it doesn't have to use it?  During which
>   circumstances can it choose not to use it?
> 

The first two paragraphs of section 3.2.1.1 do not clarify the specification,
so I propose deleting them.  I propose merging the last paragraph of section 
3.2.1.1 as the last paragraph of section 3.2.1.  Thus, the current sectioon 
3.2.1.1 will disappear.  After these changes, the last two paragraphs of 
section 3.2.1 should be fixed.  

OLD:

   The NETCONF server MUST implement all of these algorithms, and allow
   the deployer to choose the algorithm used.  The certificate-to-
   username-transforms container in the ietf-netconf-tls YANG module
   specifies how a NETCONF server transforms a certificate into a
   NETCONF username.

   If a locally held copy of a trusted CA certificate is configured in
   the transformation container, and that CA certificate was used to
   validate the path to the presented certificate, then the NETCONF
   server SHOULD use that list entry in the transformation container.
   All presented certificates validated by the configured CA certificate
   will be transformed to NETCONF usernames using the same
   transformation algorithm.

Proposed last two paragraphs of section 3.2.1:

   The NETCONF server MUST implement all of these algorithms, and allow
   the deployer to choose the algorithm used.  The cert-map list in the
   ietf-netconf-tls YANG module specifies how a NETCONF server transforms 
   a certificate into a NETCONF username.

   If the fingerprint of locally held copy of a trusted CA certificate is 
   configured in the cert-map list in the ietf-netconf-tls YANG module, 
   and that CA certificate is used to validate the certificate presented
   by the client, then the NETCONF server uses that cert-map list entry 
   to produce the NETCONF username.  This allows multiple client certificates 
   (all signed by the same trusted CA certificate) to be mapped to a NETCONF 
   username by a single entry in the cert-map list.

> 
> o  3.2.1.2
> 
>   OLD:
> 
>    On the server side, this PSK identity is used to look up the key 
>    corresponding to the presented PSK identity.  
> 
>    If the selected pre-shared keys match and the key is
>    valid, then the client is authenticated and the NETCONF username
>    associated with the PSK identity.
> 
>   Bad sentence.
>

Proposed new text:

   On the server side, this PSK identity is used to look up the key 
   corresponding to the PSK identity presented by the client.
   The server iterates through the psk list in the psk-map container in
   the ietf-netconf-tls YANG module.  It searches for a psk list entry 
   with a psk-identity leaf that matches the PSK identity presented by 
   the client.  If the server finds a matching entry, and the pre-shared 
   keys match, then this authenticates the client.  The server uses the 
   value from the user-name leaf in the psk list as the NETCONF username.
   If the server cannot find a psk-identity leaf that matches the PSK 
   identity presented by the client, or if the pre-shared keys do not
   match, then the server terminates the connection.

> 
> o  YANG module
> 
>    o  container cert-mappings
> 
>    OLD:
> 
>      On an incoming TLS connection, the client's presented certificate
>      MUST either be validated based on an established trust anchor, or
>      it MUST directly match a fingerprint in this container.  This
>      container does not provide any mechanisms for configuring the
>      trust anchors;
> 
>   NEW:
> 
>      On an incoming TLS connection, the client's presented certificate
>      MUST either be validated based on an established trust anchor, or
>      it MUST directly match a fingerprint in the 'cert-map' list.  This
>      module does not provide any mechanisms for configuring the
>      trust anchors;
> 
>   The term "this container" is used several times in this text where
>   the list 'cert-map' is meant.  Please check the text and rephrase.
> 
>      However, this container is
>      flexible to allow for situations where existing deployed
>      certificate infrastructures do not provide adequate subjectAltName
>      values for use as NETCONF usernames."
> 
>   How is this flexibility done?  This needs to be clarified.

I believe the following replacement text for the description of the 
cert-mappings container addresses the comments above:

    OLD:

     description
       "This container is used by a NETCONF server to map the NETCONF
        client's presented X.509 certificate to a NETCONF username.

        On an incoming TLS connection, the client's presented certificate
        MUST either be validated based on an established trust anchor, or
        it MUST directly match a fingerprint in this container.  This
        container does not provide any mechanisms for configuring the
        trust anchors; the transfer of any needed trusted certificates
        for certificate chain validation is expected to occur through an
        out-of-band transfer.

        Once the certificate has been found acceptable (either by
        certificate chain validation or directly matching a fingerprint
        in this container), this container is consulted to determine the
        appropriate NETCONF username to associate with the remote
        connection.  This is done by considering each list entry from
        this container in prioritized order according to its index value.
        Each list entry's fingerprint value determines whether the list
        entry is a match for the incoming connection:

            1) If the list entry's fingerprint value matches that
               of the presented certificate, then consider the list entry
               as a successful match.

            2) If the list entry's fingerprint value matches that
               of a locally held copy of a trusted CA certificate, and
               that CA certificate was part of the CA certificate chain
               to the presented certificate, then consider the list entry
               as a successful match.

               This feature lets the NETCONF server derive NETCONF
               usernames from all certificates signed by the trusted
               CA certificate.  The NETCONF server will derive all
               NETCONF usernames using the same derivation algorithm.
               The NETCONF server requires only a single list entry
               to configure this behavior.

        Once a matching list entry has been found, the NETCONF server
        uses the map-type value to determine how the NETCONF username
        associated with the session should be determined.  See the map-
        type leaf's description for details on determining the NETCONF
        username value.  If it is impossible to determine a NETCONF
        username from the list entry's data combined with the data
        presented in the certificate, then additional list entries MUST
        be searched looking for another potential match.  If a resulting
        NETCONF username mapped from a given list entry is not compatible
        with the needed requirements of a NETCONF username, then it MUST
        be considered an invalid match and additional list entries MUST
        be searched looking for another potential match.

        If no matching and valid list entry can be found, then the
        NETCONF server MUST close the connection, and MUST NOT accept
        NETCONF messages over it.

        Non-consecutive values of index are acceptable and implementations
        should continue to the next highest numbered list entry.  It is
        recommended that administrators skip index values to leave room
        for the insertion of future list entries (for example, use values
        of 10 and 20 when creating initial list entries).

        Security administrators are encouraged to make use of certificates
        with subjectAltName fields that can be used as NETCONF usernames
        so that a single root CA certificate can allow all child
        certificate's subjectAltName to map directly to a NETCONF
        usernames via a 1:1 transformation.  However, this container is
        flexible to allow for situations where existing deployed
        certificate infrastructures do not provide adequate subjectAltName
        values for use as NETCONF usernames.";

    NEW:

     description
       "The cert-mappings container is used by a NETCONF server to map the 
        NETCONF client's presented X.509 certificate to a NETCONF username.

        On an incoming TLS connection, the client's presented certificate
        MUST either be validated based on an established trust anchor, or
        it MUST directly match a fingerprint in the 'cert-map' list.  This
        module does not provide any mechanisms for configuring the
        trust anchors; the transfer of any needed trusted certificates
        for certificate chain validation is expected to occur through an
        out-of-band transfer.

        Once the certificate has been found acceptable (either by
        certificate chain validation or directly matching a fingerprint
        in the cert-map list), the cert-map list is consulted to determine 
        the appropriate NETCONF username to associate with the remote
        connection.  This is done by considering each cert-map list entry 
        in prioritized order according to its index value.  The cert-map
        entry's fingerprint determines whether the list entry is a match 
        for the incoming connection:

            1) If the cert-map list entry's fingerprint value matches that
               of the presented certificate, then consider the list entry
               as a successful match.

            2) If the cert-map list entry's fingerprint value matches that
               of a locally held copy of a trusted CA certificate, and
               that CA certificate was part of the CA certificate chain
               to the presented certificate, then consider the list entry
               as a successful match.

        Once a matching cert-map list entry has been found, the NETCONF 
        server uses the map-type leaf to determine how the NETCONF username
        associated with the session should be determined.  See the map-
        type leaf's description for details on determining the NETCONF
        username value.  If it is impossible to determine a NETCONF
        username from the cert-map list entry's data combined with the data
        presented in the certificate, then additional cert-map list entries 
        MUST be searched looking for another potential match.  If a resulting
        NETCONF username mapped from a given cert-map list entry is not 
        compatible with the needed requirements of a NETCONF username, 
        then it MUST be considered an invalid match and additional cert-map
        list entries MUST be searched looking for another potential match.

        If no matching and valid cert-map list entry can be found, then the
        NETCONF server MUST close the connection, and MUST NOT accept
        NETCONF messages over it.

        Non-consecutive values of index are acceptable and implementations
        should continue to the next highest numbered cert-map list entry.  
        It is recommended that administrators skip index values to leave 
        room for the insertion of future list entries (for example, use 
        values of 10 and 20 when creating initial list entries).

        Security administrators are encouraged to make use of certificates
        with subjectAltName fields that can be used as NETCONF usernames
        so that a single root CA certificate can allow all child
        certificate's subjectAltName to map directly to a NETCONF
        usernames via a 1:1 transformation.";

> 
> o  YANG module
>
> o  list cert-map
> 
>   Instead of using an integer key, I suggest you use an ordered-by
>   user list with an arbitratry string as key.   This use case is why
>   ordered-by user lists exist.
> 
> 
> o leaf map-type {
> 
>   Instead of enumerating all different combinations, I suggest you use
>   an ordered-by user leaf-list.  Also, I think the following structure
>   would be more natural:
> 
>     choice map-type {
>       leaf specified {
>         type nacm:user-name-type;  // note the new type
>         // replaces your "data" leaf
>       }
>       leaf-list from-certificate {
>         type enumeration {
>           enum rfc822Name;
>           enum dNSName;
>           enum ipAddress;
>         }
>         ordered-by user;
>       }
>     }
> 
>   Then you can use for example:
> 
>     <specified>bob</specified>
> 
>   or
> 
>     <from-certificate>dnsName</from-certificate>
>     <from-certificate>rfc822Name</from-certificate>

I prefer to leave the YANG objects as proposed.

I believe Badra has already or, or is in process of addressing
the following comment:

>
> Your description of RFC822 names makes reference to a host part.
>
> This is incorrect - it should be a domain part, as per RFC822.
>

Regards,
--Alan

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 20 Sep 2012 10:23:43 +0200 (CEST)

Hi Alan,

>          "This PSK identity is not valid before the given data

s/data/date/

>     NETCONF username from the certificate presented by the NETCONF client:

Ok.

>    username by a single entry in the cert-map list.

Ok.

>    match, then the server terminates the connection.

Since the 'psk-identity' is the key in the 'psk', I think the text
about iterating and matching is confusing.  It makes it sound as if
there are potentially multiple matching entries.  I suggest:

    On the server side, this PSK identity is used to look up an
    entry in the psk list.  If such an entry is found, and the pre-shared 
    keys match, then the client is authenticated.  The server uses the 
    value from the user-name leaf in the psk list as the NETCONF username.
    If the server cannot find an entry in the psk list, or if the
    pre-shared keys do not match, then the server terminates the
    connection.

>         usernames via a 1:1 transformation.";

Ok, but see below.

I also beleive that anvert-map entry must have a fingerprint, right?
If so, the choice should be mandatory:

    container fingerprint {
      choice algorithm-and-hash {
        mandatory true;
        ...

> I prefer to leave the YANG objects as proposed.

Can you provide some motivation for this?  To me, this looks like a
rather direct translation from a MIB structure (which the document
also says it is).  I think it would be unfortunate to not use YANG's
more expressive constructs to make a nicer model.  Of course, what
makes a nice design is somewhat subjective, so I would like to hear
other people's opinion on this as well.

Note that there are three separate issues:

  1.  The use of a leaf-list instead of an
      enumeration-with-some-but-not-all-combinations.

  2.  Make the list 'ordered-by user' instead of using an integer
      value as a priority leaf.

  3.  Use a specific leaf for per-map-type data, instead of a generic
     'data' leaf that contains an opaque string.

I (pyang) also found a syntax error in the current version of the
module:

 revision "2012-09-13" {
   description
     "rename host-part to domain-part in the description of RFC822".

The '.' above should be ';'.

/martin