Subject: [Netconf] Updates to the ietf-netconf-tls.yang module

From: Alan Luchuk <[email-masked]>
Date: Wed, 11 Apr 2012 11:36:59 -0400 (EDT)

Hello,

Related to updates to draft-badra-netconf-rfc5539bis-01.txt, after reviewing
the NETCONF WG E-mail comments about the  ietf-netconf-tls YANG module, I've 
updated it and included it with this E-mail.  Almost all of the suggested 
changes have been incorporated, including:

  -  a number of editorial/textual changes;
  -  features for certficiates or psk;
  -  shorter names in the certificate container;
  -  removed a couple of scalars;
  -  added an import for ietf-netconf-acm;
  -  removed a number of enums from the map-type object - the ISMS WG 
     omitted the additional enumerations from the SNMP-TLS-TM-MIB because 
     the additional enumerations added complexity without much benefit;
  -  changed description references to "path" to "certificate chain";
  -  changed certificate-fingerprint so it's representation on the wire
     would be more YANG-like;

Regards,
--Alan

<CODE BEGINS> file "[email-masked]"

module ietf-netconf-tls {

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

 prefix "nctls";

 import ietf-yang-types {
   prefix yang;
 }

 import ietf-netconf-acm {
   prefix nacm;
 }

 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:   Mohamad 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 servers transform
    pre-shared TLS keys into NETCONF usernames.

    This YANG module is patterned after 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) 2012 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 "2012-04-11" {
   description
     "Incorporates comments on draft-badra-netconf-rfc5539bis-01.txt.";
   reference
     "RFC XXXX: NETCONF over Transport Layer Security (TLS)";
 }

 revision "2012-02-13" {
   description
     "Initial version";
   reference
     "RFC XXXX: NETCONF over Transport Layer Security (TLS)";
 }

 feature map-certificates {
   description 
     "The :map-certificates capability implements mapping X.509
      certificates to NETCONF user names.";
 }

 feature map-pre-shared-keys {
   description 
     "The :map-pre-shared-keys capability implements mapping TLS
      pre-shared keys to NETCONF user names.";
 }

 typedef tls-fingerprint-type {
   type binary {
     length "1..max";
   }
   description
     "A cryptographic signature (fingerprint) value that can be used to 
      uniquely reference other data of potentially arbitrary length.";
 }

 //
 //  Objects related to deriving NETCONF usernames from X.509 
 //  certificates.
 //

 container cert-mappings {
   if-feature map-certificates;
   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 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.";

   list cert-map {
     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.";
     }

     container fingerprint {
       choice algorithm-and-hash {
         leaf md5 {
           type tls-fingerprint-type;
         }
         leaf sha1 {
           type tls-fingerprint-type;
         }
         leaf sha224 {
           type tls-fingerprint-type;
         }
         leaf sha256 {
           type tls-fingerprint-type;
         }
         leaf sha384 {
           type tls-fingerprint-type;
         }
         leaf sha512 {
           type tls-fingerprint-type;
         }
         description
           "Specifies the signature algorithm and cryptographic 
            signature (fingerprint) used to identify an X.509 
            certificate.
  
            Implementations of this YANG module MAY, but are not 
            required to, implement all of these cryptographic signature
            algorithms.  Implementations of this YANG module MUST 
            implement at least one of these cryptographic signature 
            algorithms.  
  
            The available choices may be extended in the future as 
            stronger cryptographic signature algorithms become 
            available and are deemed necessary.";

         reference
           "RFC 5246: The Transport Layer Security (TLS) Protocol 
            Version 1.2; Section 7.4.1.4.1,  Signature Algorithms";
       }  // choice algorithm-and-hash
     }    // container fingerprint

     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;  }
       }

       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 subsequent 
         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

           The NETCONF server derives the NETCONF username from the 
           subjectAltName fields rfc822Name, dnsName, and ipAddress, 
           as described in sections above.  This enumeration specifies
           the NETCONF server first examines the rfc822Name, then 
           examines the dnsName, then finally examines the ipAddress.
           The first matching subjectAltName value found in the 
           certificate MUST be used when deriving the NETCONF username. 

           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 leaf.  Only some
         mapping systems will make use of this leaf.  When the NETCONF
         server derives the NETCONF username from the client's presented
         certificate, the value in this leaf MUST be ignored for any
         mapping type that does not require data present in this leaf.";
     }
   }  // list cert-map
 }    // container cert-mappings

 //
 //  Objects related to deriving NETCONF usernames from TLS pre-shared 
 //  keys.
 //

 container psk-map {
   if-feature map-pre-shared-keys;
   list psk {
     key psk-identity;

     leaf psk-identity {
       type string;
       description
         "The PSK identity encoded as a UTF-8 string.";
       reference
         "RFC 4279: Pre-Shared Key Ciphersuites for Transport Layer
                   Security (TLS)";
     }

     leaf user-name {
       type nacm:user-name-type;
       mandatory true;
       description
        "The NETCONF username associated with this PSK identity.";
     }

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

     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 binary;
       nacm:default-deny-all;
       description
         "The key associated with the PSK identity";
     }
   }
 }    // container psk-map
}

<CODE ENDS>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 11 Apr 2012 20:33:12 +0200

>       uniquely reference other data of potentially arbitrary length.";

The binary type means the data is encoded in base64. The tools I am
familiar with that produce hash values seem to generate hexadecimal
representations. 
 
>      }    // container fingerprint

I think we need to make this reusable, more generic and we need to put
the resulting grouping under IANA control. We need the same construct
for the SNMP configuration data model. So one way forward is that we
draft a reusable grouping and an associated fingerprint type (or hash
value type - whatever the correct term will be) to be placed into an
IANA maintained modules. We can do this here or we do it in NETMOD.  I
personally do not care much as long as we get a consistent and
reusable solution into place.

>  }    // container cert-mappings

This follows the MIB model but I am not sure this is the right way of
doing this in YANG. Martin uses a slightly different approach in
draft-bjorklund-netmod-snmp-cfg-02.txt.

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

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

s/data/date/

>          "The key associated with the PSK identity";

The same question raised above applies here. Is a base64
representation really what people feel comfortable with? Using base64
might be more OK here than above - I do not really know.

/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: Mohamad Badra <[email-masked]>
Date: Mon, 23 Apr 2012 22:08:27 +0200

Dear Juergen,

> familiar with that produce hash values seem to generate hexadecimal

Do you mean something like that?

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";
       }

> might be more OK here than above - I do not really know.

And:

  typedef tls-fingerprint-type {
type string {
pattern '([0-9a-fA-F]){2}(:([0-9a-fA-F]){2})*';
}
}

Best regards,
Badra