Subject: Re: [Netconf] RFC 5539 update for NETCONF usernames

From: Alan Luchuk <[email-masked]>
Date: Fri, 21 Oct 2011 10:47:12 -0400 (EDT)

Hello,

Here is the latest proposed text for an update to RFC 5539 for deriving
NETCONF usernames when using NETCONF over TLS.  Thanks to all who 
commented on earlier version(s) of this text.

Much of the text in the earlier draft has been replaced by a YANG module 
in this draft.  This YANG module heavily borrows ideas and text from the 
SNMP-TLS-TM-MIB from RFC 6353.  The description text in the YANG module 
should be more concise and clear than the deleted text.

Hopefully this lastest proposal will be a more useful starting point
for discussions about deriving NETCONF usernames when using TLS.

Regards,
--Alan

 ------------------------------------------------------------------------------
 Alan Luchuk               SNMP Research, Inc.          Voice:  +1 865 573 1434
 Senior Software Engineer  3001 Kimberlin Heights Road  FAX:    +1 865 573 9197
 [email-masked]           Knoxville, TN  37920-9716    http://www.snmp.com/
 ------------------------------------------------------------------------------

Deriving NETCONF Usernames From NETCONF Client Certificates
-----------------------------------------------------------

The NETCONF protocol [RFC6241] requires the transport protocol to
be responsible for authentication of the server to the client and
authentication of the client to the server.  TLS does this by
exchanging and verifying the certficates presented by the peer.

Additionally, the NETCONF protocol [RFC6241] requires that the 
transport protocol's authentication process MUST result in an 
authenticated client identity whose permissions are known to the 
server.  The authenticated identity of a client is commonly 
referred to as the NETCONF username.  Thus, an algorithm for 
transforming certificates to NETCONF usernames is needed.

The algorithm for deriving NETCONF usernames from TLS certificates
is patterned after the algorithm for deriving tmSecurityNames from
TLS certificates specified in Transport Layer Security (TLS) 
Transport Model for the Simple Network Management Protocol (SNMP)
[RFC6353].  RFC6353 specifies that an SNMP engine must implement
several algorithms for transforming a certificate to a tmSecurityName, 
and lets the SNMP engine deployer choose and configure the algorithm 
most suitable for the deployer's environment.

When a NETCONF server accepts a TLS connection from a NETCONF client, 
the NETCONF server must produce a NETCONF username from the certificate 
presented by the NETCONF client.  The NETCONF server may use any of 
the following algorithms to produce the NETCONF username from the 
certificate presented by the NETCONF client:

-  Map a certificate directly to a NETCONF username;

-  Extract the subjectAltName's rfc822Name from the certificate,
   then use the extracted rfc822Name as the NETCONF username;

-  Extract the subjectAltName's dnsName from the certificate,
   then use the extracted dnsName as the NETCONF username;

-  Extract the subjectAltName's iPAddress from the certificate,
   then use the extracted iPAddress as the NETCONF username;

-  Examine the subjectAltName's rfc822Name, dnsName, and iPAddress
   fields in a pre-defined order, then use the first matching
   subjectAltName value.  

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

   Identifying a Certificate
   -------------------------

A client certificate has an identity: the certificate.  The TLS and 
corresponding protocols provide an identity.  The identity 
shows that "this client certificate has shown that it, indeed, is on 
the other side of the connection".  With a complete certificate, 
the certificate receiver can be certain that for someone or something 
on the other side to use that certificate successfully, it has the
associated private key.

The problem with using the entire certificates as the identity is 
that they are difficult for people to use.  It is generally accepted 
that a fingerprint of a certificate is not likely to come up with a 
collision against a fingerprint of another (different) certificate.  
Thus, assuming a good hash algorithm, using fingerprints is a safe 
way to compare two certificates.

If 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.

Remote Configuration 
--------------------

The ietf-netconf-tls-username YANG module defines objects for remotely
configuring the mapping of TLS certficates to NETCONF usernames.

module ietf-netconf-tls-username {

  namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-tls-username";

  prefix "tls-username";

  import ietf-yang-types {
    prefix yang;
  }

  organization
    "IETF NETCONF (Network Configuration) Working Group";

  contact
    "WG Web:   <http://tools.ietf.org/wg/netconf/>
     WG List:  <mailto:[email-masked]>

     WG Chair: Mehmet Ersue
               <mailto:[email-masked]>

     WG Chair: Bert Wijnen
               <mailto:[email-masked]>

     Editor:   Badra
               <mailto:[email-masked]>";

  description
    "This module applies to NETCONF over TLS.  It specifies how
     NETCONF servers transform X.509 certificates presented by
     clients into NETCONF usernames.  It also specifies how NETCONF 
     clients transform NETCONF usernames into X.509 certificates
     for presentation to NETCONF servers.

     This YANG module is patterned after, and closely models, parts of
     the SNMP-TLS-TM-MIB defined in RFC 6353.  Much of the description 
     text has been copied directly from the SNMP-TLS-TM-MIB, and modified
     as necessary.

     Copyright (c) 2011 IETF Trust and the persons identified as
     authors of the code. All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the Simplified BSD
     License set forth in Section 4.c of the IETF Trust's
     Legal Provisions Relating to IETF Documents
     (http://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX; see
     the RFC itself for full legal notices.";
  // RFC Ed.: replace XXXX with actual RFC number and
  // remove this note

  // RFC Ed.: please update the date to the date of publication

  revision "2011-10-17" {
    description
      "Initial version";
    reference
      "RFC XXXX: NETCONF over Transport Layer Security (TLS)";
  }

  typedef tls-fingerprint-type {
    type binary {
      length "0..255";
    }
    description
      "A fingerprint value that can be used to uniquely reference
       other data of potentially arbitrary length.

       An tls-fingerprint-type value is composed of a 1-octet hashing
       algorithm identifier followed by the fingerprint value.  The
       octet value encoded is taken from the IANA TLS HashAlgorithm
       Registry (RFC 5246).  The remaining octets are filled using the
       results of the hashing algorithm.

       This typedef allows for a zero-length (blank) tls-fingerprint-type 
       value for use in containers where the fingerprint value may be 
       optional.  YANG definitions or implementations may refuse to 
       accept a zero-length value as appropriate.";
  }

  //
  //  Objects related to deriving NETCONF usernames from  X.509 certificates.
  //
  leaf certificate-to-username-transform-count {
    type yang:gauge32;
    description
      "A count of the number of certificate-to-username-transforms.";
    config false;
  }

  leaf certificate-to-username-transform-last-changed {
    type yang:date-and-time;
    description
      "The date and time when the certificate-to-username-transforms
       was last modified through any means.  The value 0 means the
       certificate-to-username-transforms has not been modified since
       the NETCONF server was started.";
    config false;
  }

  container certificate-to-username-transforms {
    config true;
    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 path validation is expected to occur
       through an out-of-band transfer.

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

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

           2) If the list entry's certificate-fingerprint value
              identifies a locally held copy of a trusted CA
              certificate and that CA certificate was used to
              validate the path to the presented certificate, then
              consider the list entry as a successful match.

       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 column'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, the connection MUST
       be closed and NETCONF messages MUST NOT be accepted over it.

       Missing 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).

       Users 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.";

//        Certificates may also be mapped to NETCONF usernames using the
//        CommonName portion of the Subject field.  However, the usage
//        of the CommonName field is deprecated and thus this usage is
//        NOT RECOMMENDED.  Direct mapping from each individual
//        certificate fingerprint to a NETCONF username is also possible
//        but requires one entry in the container per NETCONF username and
//        requires more management operations to completely configure a
//        device.";

    list certificate-to-username-transform {
      key "index";
      description
        "A single list entry that specifies a mapping for an incoming 
        TLS certificate to a NETCONF username.";

      leaf index {
        type uint32 {
          range "1..4294967295";
        }
        description
          "A unique, prioritized index for the given entry.  Lower
          numbers indicate a higher priority.";
      }

      leaf certificate-fingerprint {
        type tls-fingerprint-type {
          length "1..255";
        }
        description
          "A cryptographic hash of a X.509 certificate.  The results of
           a successful matching fingerprint to either the trusted CA in
           the certificate validation path or to the certificate itself
           is dictated by the map-type column.";
      }

      leaf map-type {
        type enumeration {
          enum specified                     { value 1;  }
          enum rfc822Name                    { value 2;  }
          enum dnsName                       { value 3;  }
          enum ipAddress                     { value 4;  }
          enum rfc822Name-dnsName-ipAddress  { value 5;  }
          enum rfc822Name-ipAddress-dnsName  { value 6;  }
          enum dnsName-ipAddress-rfc822Name  { value 7;  }
          enum dnsName-rfc822Name-ipAddress  { value 8;  }
          enum ipAddress-dnsName-rfc822Name  { value 9;  }
          enum ipAddress-rfc822Name-dnsName  { value 10; }
        }

        description
          "Specifies the algorithm for deriving a NETCONF username from
          a certificate.  If a mapping succeeds, then it will return a 
          NETCONF username.

          If the resulting mapped value is not compatible with the needed
          requirements of a NETCONF username, then future list entries MUST
          be searched for additional NETCONF username matches to look for a 
          mapping that succeeds.

          For each enumerated value listed above, the NETCONF server 
          derives the NETCONF from the presented client certificate 
          as described:

          specified

            Directly specifies the NETCONF username to be used for
            this certificate.  The value of the NETCONF username
            to use is specified in the data leaf of the list.  The
            data leaf must contain a non-zero length value or the
            mapping described in this list entry must be considered a 
            failure.

          rfc822Name

            Maps a subjectAltName's rfc822Name to a NETCONF username.
            The local part of the rfc822Name is passed unaltered but 
            the host-part of the name must be passed in lowercase.  
            This mapping results in a 1:1 correspondence between 
            equivalent subjectAltName rfc822Name values and NETCONF 
            username values except that the host-part of the name 
            MUST be passed in lowercase.

            Example rfc822Name Field:  [email-masked]
            is mapped to NETCONF username: [email-masked].

          dnsName

            Maps a subjectAltName's dNSName to a NETCONF username after
            first converting it to all lowercase (RFC 5280 does not 
            specify converting to lowercase so this involves an extra 
            step).  This mapping results in a 1:1 correspondence between 
            subjectAltName dNSName values and the NETCONF username values.
 
            reference:  RFC 5280 - Internet X.509 Public Key Infrastructure
                        Certificate and Certificate Revocation
                        List (CRL) Profile.

          ipAddress

            Maps a subjectAltName's iPAddress to a NETCONF username by 
            transforming the binary encoded address as follows:

            1) for IPv4, the value is converted into a
               decimal-dotted quad address (e.g., '192.0.2.1').

            2) for IPv6 addresses, the value is converted into a
               32-character all lowercase hexadecimal string
               without any colon separators.

               This mapping results in a 1:1 correspondence between
               subjectAltName iPAddress values and the NETCONF username
               values.

          rfc822Name-dnsName-ipAddress
          rfc822Name-ipAddress-dnsName
          dnsName-ipAddress-rfc822Name
          dnsName-rfc822Name-ipAddress
          ipAddress-dnsName-rfc822Name
          ipAddress-rfc822Name-dnsName

            For each of these enumerations, the NETCONF server derives the
            NETCONF username in a similar manner.  The NETCONF server
            derives the NETCONF username from the subjectAltName fields
            rfc822Name, dnsName, and ipAddress, as described in sections 
            above.  However, each of these subjectAltName fields is
            examined in the order specified by the enumeration name.
            The first matching subjectAltName value found in the certificate
            MUST be used when deriving the NETCONF username.
 
            For example, the rfc822Name-dnsName-ipAddress enumeration
            specifies the NETCONF server first examines the rfc822Name, 
            then examines the dnsName, then finally examines the ipAddress.
            In contrast, the ipAddress-rfc822Name-dnsName enumeration
            specifies the NETCONF server first examines the ipAddress 
            name, then examines the rfc822Name, then finally examines 
            the dnsName.
 
            These mappings result in a 1:1 correspondence between
            subjectAltName values and NETCONF username values.  The
            sub-mapping algorithms produced by these combined algorithms
            cannot produce conflicting results between themselves.";
      }  //  leaf map-type 

      leaf data {
        type string {
          length "1..max";
        }
        description
          "Auxiliary data used as optional configuration information for
          a given mapping specified by the map-type column.  Only some 
          mapping systems will make use of this column.  The value in this 
          column MUST be ignored for any mapping type that does not require 
          data present in this column.";
      }

    }  // list certificate-to-username-transform
  }    // container certificate-to-username-transform

}

Pre-shared Key Authentication
-----------------------------

Implementations may optionally support TLS Pre-Shared Key (PSK)
authentication.  RFC 4279 describes pre-shared key ciphersuites for
TLS. During the TLS Handshake, the client indicates which key to use
by including a PSK identity in the TLS ClientKeyExchange message
[RFC4279]. On the server side, this PSK identity is used to lookup the
key corresponding to the presented PSK identity. If the selected
pre-shared keys match, then the client is authenticated and the PSK
identity is used as the NETCONF username. For details how the PSK
identity may be encoded in UTF-8, see section 5.1. of RFC 4279.

---

From: "Randy Presuhn" <[email-masked]>
Date: Thu, 27 Oct 2011 10:50:22 -0700

Hi -

A few comments, in-line below.

> From: "Alan Luchuk" <[email-masked]>
> To: <[email-masked]>
> Sent: Friday, October 21, 2011 7:47 AM
> Subject: Re: [Netconf] RFC 5539 update for NETCONF usernames
...
> should be more concise and clear than the deleted text.
...
> transforming certificates to NETCONF usernames is needed.

I think someone else has already commented on how the "MUST"
here is a bit odd. 
<complex sentence alert>
Is it attempting to say that
it is impossible
for the permissions
of an authenticated client identity
to *not* be known
to the server?
</complex sentence alert>

> most suitable for the deployer's environment.

Recapping RFC6353 does be helpful, but it's more important to answer the
question of what *this* specification requires.  All this paragraph says is
"patterned after", which means "similar but likely different", and the
paragraph does not spell out what the differences are.
 
> certificate presented by the NETCONF client:

Is the use of "must" and "may deliberate?  I think what you mean is:
  When a NETCONF server accepts a TLS connection from a NETCONF client, 
   the NETCONF server attempts to derive a NETCONF username from the certificate 
  presented by the NETCONF client.  The NETCONF server MAY use any of 
   the following algorithms to produce the NETCONF username from the 

> -  Map a certificate directly to a NETCONF username;

What transforms are permitted in this mapping?
 
>    then use the extracted iPAddress as the NETCONF username;

Does anything need to be said about the representaiton of the IPAddress?

>    fields in a pre-defined order, then use the first matching

"matching" what?
 
> allow the deployer to choose and configure the algorithm used.

"and configure" - are there additional inputs to any of these algorithms?
If so, they need to be spelled out.

> server transforms an certificate into a NETCONF username.

If this paragraph applies to the first bullet above, I suggest turning it
into a note and attaching it directly to the bullet.

>    Identifying a Certificate

Only the last sentence of this paragraph makes any sense to me.
The first sentence (presumably the topic sentence of the paragraph)
is tautological nonsense.
 
> way to compare two certificates.

"Compare" is the wrong word.  I'd suggest replacing the last phrase
with "a fingerprint can be a safe short-hand for identifying a certificate."
I would recommend that someone actually do the math to figure out
what a "safe" fingerprint size would be.  Since this would be used for
configuration, interoperability is a concern, so the fingerprint algorithm
needs to be spelled out.

> will be transformed to NETCONF usernames using the same transformation 

This paragraph is just plain baffling in context.  It sounds like it presumes
a bunch of stuff spelled out in the Yang.

...
>   typedef tls-fingerprint-type {
...
>        algorithm identifier followed by the fingerprint value.

Wouldn't it make sense for this sub-structure to be explicit in the data
type's syntax?

>        accept a zero-length value as appropriate.";

If the data element is itself optional in such cases, why is the sentinel
value needed?

...
>       "A count of the number of certificate-to-username-transforms.";

Why is this needed?

>        the NETCONF server was started.";

Why is this needed?  If it's there for the reason I think it's there, limiting it
to "since the NETCONF server was started" defeats the purpose.

>        through an out-of-band transfer.

I can understand the bootstrap problem of getting an initial trust anchor.
However, I think this (or the security considerations section) also needs to
address why NETCONF can't be used to configure additional trust anchors
or to modify/delete the initial trust anchor.

...
>        NETCONF username to identify with the remote connection.  This

perhaps s/identify/associate/

>               identifies the presented certificate, then consider the

s/identifies/matches that of/

...
>               identifies a locally held copy of a trusted CA

s/identifies/matches that of/

>               consider the list entry as a successful match.

This seems just a bit odd.  Why should CAs be treated as NETCONF users?

>        with the session should be determined.  See the map-type column's

General note - is "column" the preferred terminology here and elsewhere?
It sounds rather MIB-ish.

...
>        be closed and NETCONF messages MUST NOT be accepted over it.

This seems quite reasonable, but contradicts the statement from above
"Additionally, the NETCONF protocol [RFC6241] requires that the 
transport protocol's authentication process MUST result in an 
authenticated client identity whose permissions are known to the 
server."

>        Missing values of index are acceptable and implementations 

How can the value of index be missing?  It's a key, with a simple integer range.

>        should continue to the next highest numbered list entry.  It is 

What is "next" after "missing"???

>        recommended that administrators skip index values to leave room 

Do you mean "RECOMMENDED"?

>        of 10 and 20 when creating initial list entries).

If so, what is the motivation for this operational practice?

>        Users are encouraged to make use of certificates with

By "users" do you mean "security administrators"?

...
>             the host-part of the name must be passed in lowercase.  

Does anything need to be said about IDNs here and in the other "lowercase"
conversion situations?

>           data present in this column.";

What does "MUST be ignored" mean?  During get-config?  During edit-config?

...
> [RFC4279]. On the server side, this PSK identity is used to lookup the

s/lookup/look up/

Randy