Internet Draft I. Chen Ericsson Intended Status: Standards Track Expires in 6 months November 2, 2015 YANG Data Model for RFC 7210 Key Table Status of this Memo Distribution of this memo is unlimited. This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire in 6 months. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Chen Expires in 6 months [Page 1] Internet Draft Key Table YANG November 2, 2015 Abstract RFC 7210 defines a key table that consists of cryptographic keys that stores information for many different types of routing protocols to ensure message security. This document defines a YANG data model that represents the key table defined in RFC 7210, with the information necessary for YANG and NETCONF to provide routing protocol authentication. Chen Expires in 6 months [Page 2] Internet Draft Key Table YANG November 2, 2015 Table of Contents 1. Introduction ....................................................3 1.1 Terminology .................................................3 1.2 Tree Diagram ................................................3 2. Design of the Data Model ........................................4 2.1 Base Model ..................................................4 2.1 Protocol Customization ......................................5 3. Key-chains vs. Key-table Comparison .............................6 3.1 Organization ................................................5 3.2 Missing Attributes ..........................................6 4. YANG Module .....................................................8 5. Usage ..........................................................14 6. Security Considerations ........................................15 7. IANA Considerations ............................................19 8. References .....................................................19 8.1 Normative References .......................................19 8.2 Informative References .....................................19 1. Introduction [RFC7210] defines a standards track key table that is used to store information for routing protocol authentication, including key values, cryptographic algorithms, timing attributes, and their relationships to allow different routing protocols to perform key selection, authentication, and smooth key rollover that ultimate provides routing protocol message security. This document defines a YANG [RFC6020] data model that corresponds to [RFC7210] and enables the use of NETCONF [RFC6241] and YANG to manage routing protocol authentication data. An earlier version of the key table YANG model [I-D.chen-rtg-key- table-yang] augments from the key-chain YANG model [I-D.acee-rtg- yang-key-chain]. However, because the key-chain YANG model organizes keys in groups, which is different from the key definitions in [RFC7210], this document proposes a new key-table YANG model that is structurally more consistent with the key database defined in [RFC7210]. 1.1. Terminology The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119]. Chen Expires in 6 months [Page 3] Internet Draft Key Table YANG November 2, 2015 1.2. Tree Diagram A simplified graphical representation of the data model is presented in Section 2. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Curly braces "{" and "}" contain names of optional features that make the corresponding node conditional. o Abbreviations before data node names: "rw" means configuration (read-write), and "ro" state data (read-only). o Symbols after data node names: "?" means an optional node and "*" denotes a "list" or "leaf-list". o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. 2. Design of the Data Model This data model is based on the key table defined in [RFC7210]. Because [RFC7210] defines a table that allows protocols to customize certain fields, the data model comes in two parts, the base model and the customizable part. The base model defines the attributes in [RFC7210] that are immutable across all protocols, such as admin-key- name and send-lifetime-start. The customizable part defines the attributes that are different across protocols, such as the local- key-name, peer-key-name, and peers field. These customizable attributes are defined as YANG grouping statements that can be used and incorporated into protocol-specific key table modules. 2.1. Base Model [RFC7210] defines a single table in which the rows represent the individual key entries of the key table. As such, the base model consists of one single top-level container named "key-table", in which a YANG list named "security-association-entry" is defined. The entries in the "security-association-entry" YANG list represents the rows that correspond to the cryptographic keys in [RFC7210] key table. The base model further defines each "security-association-entry" to Chen Expires in 6 months [Page 4] Internet Draft Key Table YANG November 2, 2015 consist of attributes that are common across all protocols: o admin-key-name o key o interfaces o send-lifetime-start o send-lifetime-end o accept-lifetime-start o accept-lifetime-end Additionally, the base model also defines two attributes, "peers" and "protocol-specific-info", as placeholders left for each protocol to define, as prescribed by [RFC7210]. module: ietf-key-table +--rw key-table +--rw security-association-entry* [admin-key-name] +--rw admin-key-name string +--rw peers +--rw interfaces | +--rw (interface-options) | +--:(all-interfaces) | | +--rw all? empty | +--:(interface-list) | +--rw interface* if:interface-ref +--rw protocol identityref +--rw protocol-specific-info +--rw key yang:hex-string +--rw send-lifetime-start lifetime-type +--rw send-lifetime-end lifetime-type +--rw accept-lifetime-start lifetime-type +--rw accept-lifetime-end lifetime-type 2.2. Protocol Customization Besides the attributes defined in the base model, for each row in the key table, [RFC7210] also defines the following attributes for which the format and range of valid values are protocol-specific. o local key name o peer key name Chen Expires in 6 months [Page 5] Internet Draft Key Table YANG November 2, 2015 o key derivation function o cryptographic algorithm o direction After a routing protocol augments the base model to incorporate the attributes above, the result is a key table with all the necessary attributes for routing protocol authentication, as shown in the key table below with RSVP customization. module: ietf-key-table +--rw key-table +--rw security-association-entry* [admin-key-name] +--rw admin-key-name string +--rw interfaces | +--rw (interface-options) | +--:(all-interfaces) | | +--rw all? empty | +--:(interface-list) | +--rw interface* if:interface-ref +--rw protocol identityref +--rw protocol-specific-info +--rw key yang:hex-string +--rw send-lifetime-start lifetime-type +--rw send-lifetime-end lifetime-type +--rw accept-lifetime-start lifetime-type +--rw accept-lifetime-end lifetime-type +--rw peers augment /keytable:key-table/keytable:security-association-entry + /keytable:peers: | +--rw rsvp-security-association? leafref augment /keytable:key-table/keytable:security-association-entry: +--rw kdf? key-derivation-function-type +--rw alg-id? cryptographic-algorithm-type +--rw direction? enumeration module: example-rsvp-key-table +--rw example-rsvp-key-table +--rw rsvp-security-association-entry* [name] +--rw name string +--rw rsvp-local-key-name? uint64 +--rw rsvp-peer-key-name? uint64 Chen Expires in 6 months [Page 6] Internet Draft Key Table YANG November 2, 2015 3. Key-chain vs. Key-table Comparison The key-chain YANG model also proposes a YANG model for key management. This section compares the key-chain model and the key- table model proposed in this document. 3.1. Organization The key-chain YANG model groups several keys into a single key chain. It is the key chain that is referenced and applied by routing protocols. Consequently, the key-chain YANG model defines a hierarchical database, which consists of a top-level key-chain database, and each key-chain database consists of the actual keys that are used by a protocol. A routing protocol that requires encryption or authentication must reference a key-chain instead of the individual keys. In contrast, [RFC7210] defines a single flat database of keys and their attributes. [RFC7210] does not require that an implementation of key management explicitly group a set of keys into a separate entity that routing protocols reference and use. Consequently, the key-table base model defined in this document presents a flat view of the key database. For routing protocol customization, the key-table base model can also be adapted to hierarchical key management as described in the key- chain YANG model. Section 5 provides an example of adapting a hierarchical key management model into the key-table model. 3.2. Missing Attributes The key-chain YANG model defines only a subset of key attributes defined in [RFC7210]. Consequently, the key-chain YANG model can only support specific types of deployments requiring authentication. A list of key attributes defined in [RFC7210] and in this document, but not defined in [key-chain], are as follows: o Peer key name o Interfaces o Protocol o Key derivation function o Direction Chen Expires in 6 months [Page 7] Internet Draft Key Table YANG November 2, 2015 In addition to the list above, [key-chain] also does not define attributes that [RFC7210] defined but left the detailed definitions to individual routing protocols. Similar to [RFC7210], this document defines YANG constructs for these attributes and intends for routing protocols to provided the details. The attributes in question are as follows: o Peers o ProtocolSpecificInfo 4. YANG Module file "ietf-key-table@2015-08-28.yang" module ietf-key-table { namespace "http://www.example.com/ietf-key-table"; prefix "keytable"; import ietf-yang-types { prefix "yang"; } import ietf-routing { prefix "rt"; } import ietf-interfaces { prefix "if"; } organization "Ericsson"; contact "I. Chen - ing-wher.chen@ericsson.com"; description "A key table YANG data model based on RFC 7210"; revision 2015-08-28 { description "Revision 3. " + "Making RFC 7210 a global generic table."; reference "RFC 7210"; } Chen Expires in 6 months [Page 8] Internet Draft Key Table YANG November 2, 2015 revision 2015-06-29 { description "Revision 2."; reference "RFC 7210"; } /* Identities */ identity key-derivation-function { description "Base identity from which key derivation function " + "identities are derived"; } identity kdf-none { base key-derivation-function; description "This identity represents a cryptographic key that is" + "used directly, without a key derivation function."; } identity kdf-aes-128-cmac { base key-derivation-function; description "This identity represents the key derivation function that " + "uses AES-CMAC using 128-bit keys (RFC 4493)."; } identity kdf-hmac-sha-1 { base key-derivation-function; description "This identity represents the key derivation function that " + "uses HMAC using the SHA-1 hash (RFC 2104)."; } identity cryptographic-algorithm { description "Base identity from which cryptographic algorithms " + "are derived"; } identity algid-aes-128-cmac { base cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "AES-CMAC using 128-bit keys (RFC 4493)."; } Chen Expires in 6 months [Page 9] Internet Draft Key Table YANG November 2, 2015 identity algid-aes-128-cmac-92 { base cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "AES-128-CMAC truncated to 96 bits (RFC 5926)."; } identity algid-hmac-sha-1-96 { base cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "HMAC SHA-1 truncated to 96 bits (RFC 2104)."; } identity all-routing-protocols { base rt:routing-protocol; description "All routing protocols"; } /* Typedefs */ typedef routing-protocol-type { type identityref { base rt:routing-protocol; } description "This type identifies the routing protocol"; } typedef key-derivation-function-type { type identityref { base key-derivation-function; } description "This type identifies the key derivation function"; } typedef cryptographic-algorithm-type { type identityref { base cryptographic-algorithm; } description "This type identifies the cryptographic algorithm"; } typedef lifetime-type { type string { pattern '{4}{2}{2}{2}{2}Z'; Chen Expires in 6 months [Page 10] Internet Draft Key Table YANG November 2, 2015 } description "This type identifies a time in the format YYYYMMDDHHSSZ, " + "where the first four digits specify the year, " + "the next two digits specify the month, " + "the next two digits specify the day, " + "the next two digits specify the hour, " + "the next two digits specify the second, " + "ending with the letter 'Z' as a clear indication " + "that the time is in Coordinated Universal Time (UTC)."; } /* Groupings */ grouping key-properties-grp { description "A grouping that to specify the properties of a key. " + "This is defined as a grouping so that different " + "routing protocols can further refine the values of " + "each individual key properties."; leaf kdf { type key-derivation-function-type; description "Specify the key derivation function to be used " + "with this key."; } leaf alg-id { type cryptographic-algorithm-type; description "Specify the cryptographic algorithm to be used" + "with this key."; } leaf direction { type enumeration { enum "in" { description "The key is used for inbound traffic."; } enum "out" { description "The key is used for outbound traffic."; } enum "both" { description "The key is used for both inbound and outbound " + "traffic."; } enum "disabled" { Chen Expires in 6 months [Page 11] Internet Draft Key Table YANG November 2, 2015 description "The key is disabled and cannot be used for " + "either inbound or outbound traffic."; } } description "The value of the direction must be one of 'in', 'out', " + "'both', and 'disabled'. The actual allowed value " + "is left for routing protocols to define."; } } /* The key-table model */ container key-table { description "The key table of all managed cryptographic keys " + "of a device."; list security-association-entry { key "admin-key-name"; description "A key table entry that specifies a key " + "and its attributes."; leaf admin-key-name { type string; description "A human-readable string that identifies the key."; } container peers { description "Specify the peer systems that also have this key " + "in their database. The format of this field is " + "left to protocols to define."; } container interfaces { description "Specify the interfaces to which they key may be applied."; choice interface-options { mandatory true; description "The option to apply this key to all interfaces or " + "to a pre-defined list of interfaces."; case all-interfaces { leaf all { type empty; description "This key applies to all interfaces."; } Chen Expires in 6 months [Page 12] Internet Draft Key Table YANG November 2, 2015 } case interface-list { leaf-list interface { type if:interface-ref; description "This key applies to the identified interfaces."; } } } } leaf protocol { type identityref { base rt:routing-protocol; } mandatory true; description "Specify a single routing protocol where this key " + "may be used to provide cryptographic protection."; } container protocol-specific-info { description "This field contains protocol-specified information " + "that maybe useful for a protocol to apply the key " + "correctly. This field is left for each protocol " + "to define."; } leaf key { type yang:hex-string; mandatory true; description "The key"; } leaf send-lifetime-start { type lifetime-type; mandatory true; description "Specify the earliest date and time at which this key " + "should be considered for use when sending traffic."; } leaf send-lifetime-end { type lifetime-type; mandatory true; description "Specify the latest date and time at which this key " + "should be considered for use when sending traffic."; } leaf accept-lifetime-start { type lifetime-type; Chen Expires in 6 months [Page 13] Internet Draft Key Table YANG November 2, 2015 mandatory true; description "Specify the earliest date and time at which this key " + "should be considered for processing received traffic."; } leaf accept-lifetime-end { type lifetime-type; mandatory true; description "Specify the latest date and time at which this key " + "should be considered for processing received traffic."; } } } } 5. Usage A routing protocol that requires cryptographic key authentication should customize the key table base model such that the resulting YANG modules describe all the necessary attributes and also the valid values of these attributes. An an example, the customized example-ospf-key-table YANG module below augments the key table base model to include "key-derivation- function", "cryptofgraphic-algorithm", and "direction" attributes, as well as specifying the valid valuesfor those attributes. The module below further uses the "peers" field in the base key table to reference keys that are organized into key chains as expected by the existing OSPF YANG module [I-D.ospf-yang]. module example-ospf-key-table { namespace "http://www.example.com/example-ospf-key-table"; prefix "ospf-keytable"; import ietf-key-table { prefix "keytable"; } import ietf-routing { prefix "rt"; } organization "Ericsson"; contact Chen Expires in 6 months [Page 14] Internet Draft Key Table YANG November 2, 2015 "I. Chen - ing-wher.chen@ericsson.com"; description "OSPF's customized key table"; revision 2015-08-28 { description "Initial revision"; reference ""; } /* Identities */ identity ospf-cryptographic-algorithm { base keytable:cryptographic-algorithm; description "Base identity from which OSPF cryptographic algorithm " + "identities are derived"; } identity ospf-algid-md5 { base ospf-cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "MD5"; } identity ospf-algid-hmac-md5 { base ospf-cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "HMAC-MD5"; } identity ospf-algid-sha-1 { base ospf-cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "SHA-1"; } identity ospf-algid-hmac-sha-1 { base ospf-cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "HMAC-SHA-1"; } identity ospf-algid-hmac-sha-1-12 { Chen Expires in 6 months [Page 15] Internet Draft Key Table YANG November 2, 2015 base ospf-cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "HMAC-SHA-1-12"; } identity ospf-algid-hmac-sha-256 { base ospf-cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "HMAC-SHA-256"; } identity ospf-algid-hmac-sha-384 { base ospf-cryptographic-algorithm; description "This identity represents the cryptographic algorithm " + "HMAC-SHA-384"; } identity ospf-algid-hmac-sha-512 { base ospf-cryptographic-algorithm; description "This identity repesents the cryptographic algorithm " + "HMAC-SHA-512"; } /* Typedef */ typedef ospf-cryptographic-algorithm-type { type identityref { base ospf-cryptographic-algorithm; } description "This type identifies the cryptographic algorithm"; } augment "/keytable:key-table/keytable:security-association-entry" { when "keytable:protocol == 'rt:ospfv2' or " + "keytable:protocol == 'rt:ospfv3'" { description "Applies only to OSPFv2 and OSPFv3."; } uses keytable:key-properties-grp { refine "kdf" { must ". == 'keytable:kdf-none'" { description "KDF is not used."; Chen Expires in 6 months [Page 16] Internet Draft Key Table YANG November 2, 2015 } } refine "alg-id" { must ". == 'ospf-algid-md5' or " + ". == 'ospf-algid-hmac-md5' or " + ". == 'ospf-algid-sha-1' or " + ". == 'ospf-algid-hmac-sha-1' or " + ". == 'ospf-algid-hmac-sha-1-12' or " + ". == 'ospf-algid-hmac-sha-256' or " + ". == 'ospf-algid-hmac-sha-384' or " + ". == 'ospf-algid-hmac-sha-512' or " { description "Only ospf-cryptographic-algorithms are valid."; } } refine "direction" { must ". == 'keytable:both'" { description "Key applies to both directions."; } } } description "Customize OSPF protocol specific attributes"; } augment "/keytable:key-table" + "/keytable:security-association-entry" + "/keytable:peers" { when "../keytable:protocol == 'rt:ospfv2' or " + "../keytable:protocol == 'rt:ospfv3'" { description "Applies only to OSPFv2 and OSPFv3."; } description "Reference to the apropriate key chain"; leaf key-chain { type leafref { path "/example-ospf-key-chains/ospf-key-chain/name"; } description "The name of the key chain"; } leaf security-association { type leafref { path "/example-ospf-key-chains" + "/ospf-key-chain[name = current()/../key-chain]" + "/ospf-security-association-entry/name"; Chen Expires in 6 months [Page 17] Internet Draft Key Table YANG November 2, 2015 } description "The security association within the key chain"; } } container example-ospf-key-chains { description "A container of OSPF key chains modeled after " + "ietf-key-chains"; list ospf-key-chain { key "name"; leaf name { type string; description "Name of the key chain"; } list ospf-security-association-entry { key "name"; leaf name { type string; description "The name of the security assocation"; } leaf ospf-local-key-name { type uint8; mandatory true; description "The 8-bit key ID for sending a message, " + "as defined in RFC 2328 Appendix D.3"; } leaf ospf-peer-key-name { type leafref { path "../ospf-local-key-name"; } description "The 8-bit key ID when receiving a message, " + "as defined in RFC 2328 Appendix D.3. " + "Because OSPF uses the same key for sending " + "and receiving, the value of this leaf " + "should be identical to the value of " + "ospf-local-key-name."; } description "An OSPF security association, i.e. key"; } description Chen Expires in 6 months [Page 18] Internet Draft Key Table YANG November 2, 2015 "An OSPF key chain"; } } } 6. Security Consideration. TBD. 7. IANA Considerations TBD. 8. References 8.1. Normative References [RFC7210] Housley, R., Polk, T., Hartman, S., and D. Zhang, "Database of Long-Lived Symmetric Cryptographic Keys", RFC 7210, April 2014, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 8.2. Informative References [I-D.acee-rtg-yang-key-chain] Lindem, A., Qu, Y., Yeung, D., Chen, I., Zhang, J., and Y. Yang, "Key Chain YANG Data Model", draft-acee-rtg-yang-key-chain-09 (work in progress), October 2015. [I-D.ospf-yang] Yeung, D., Qu, Y., Zhang, J., Bogdanovic, D., and K. Sreenivasa, "draft-ietf-ospf-yang-02 (work in progress)", September 2015. Chen Expires in 6 months [Page 19] Internet Draft Key Table YANG November 2, 2015 Author's Address I. Chen Ericsson Email: ing-wher.chen@ericsson.com Chen Expires in 6 months [Page 20]