A YANG Data Model for a Transport Services API at Endpoints
draft-jholland-taps-api-yang-01
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Author | Jake Holland | ||
| Last updated | 2019-03-09 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-jholland-taps-api-yang-01
Taps J. Holland
Internet-Draft Akamai Technologies, Inc.
Intended status: Standards Track March 09, 2019
Expires: September 10, 2019
A YANG Data Model for a Transport Services API at Endpoints
draft-jholland-taps-api-yang-01
Abstract
This document defines a YANG data model that provides a data
structure that can be used to configure an implementation of the
Transport Services Interface to establish connections suitable for
sending and receiving data over the internet or local networks. This
document is intended to supplement or merge with draft-ietf-taps-
interface.
Status of This Memo
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). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on September 10, 2019.
Copyright Notice
Copyright (c) 2019 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
(https://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
Holland Expires September 10, 2019 [Page 1]
Internet-Draft TAPS API Yang Model March 2019
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. A Note On The Use Of YANG . . . . . . . . . . . . . . . . 3
2. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Basic Client Connection . . . . . . . . . . . . . . . . . 4
3.2. Customized Connections . . . . . . . . . . . . . . . . . 5
3.2.1. Prohibit Specific Interface . . . . . . . . . . . . . 5
3.2.2. Require Wi-Fi . . . . . . . . . . . . . . . . . . . . 6
3.3. Send and Receive Multicast . . . . . . . . . . . . . . . 6
4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 16
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
7. Normative References . . . . . . . . . . . . . . . . . . . . 17
Appendix A. Future Work . . . . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction
This document is an attempt to concretize the properties and objects
of the TAPS interface described in [I-D.ietf-taps-interface], under
the architecture described in [I-D.ietf-taps-arch].
A TAPS-compliant implementation SHOULD provide a language-appropriate
way to configure a PreConnection using YANG instance data for this
model, and SHOULD provide an API that outputs the YANG instance data
for an established Connection.
An implementation MAY also provide appropriate APIs for directly
editing the objects without using YANG. It's RECOMMENDED where
possible to use names that mechanically translate to the names in the
YANG data model, using capitalization and punctuation conventions as
expected for the language of the implementation.
Non-TAPS extensions to API objects that directly edit TAPS properties
are RECOMMENDED to include "ext", "EXT", or "Ext" as a prefix to any
extension properties or methods, to avoid colliding with future TAPS
extensions.
The key words "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] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Holland Expires September 10, 2019 [Page 2]
Internet-Draft TAPS API Yang Model March 2019
1.1. A Note On The Use Of YANG
Although YANG was originally designed to model data for NETCONF, YANG
can be used in other ways as well, as described by Section 4.1 of
[RFC7950].
This usage is not primarily targeted at NETCONF, but rather at
Application Programming Interfaces for libraries that set up
connections for sending and receiving data over the internet.
However, use of YANG in this context provides a semantically clear,
well defined, extensible, cross-platform method for configuring
connection objects suitable for replacing BSD sockets in a wide
variety of applications.
2. Tree Diagram
Tree diagrams used in this document follow the notation defined in
[RFC8340].
module: ietf-taps-api
+--rw preconnection
+--rw properties* [type preference]
| +--rw type identityref
| +--rw preference preference-level
| +--rw iftype* identityref
| +--rw ifref* if:interface-ref
| +--rw address* inet:ip-address
| +--rw port* inet:port-number
| +--rw host* inet:host
+--rw security
+--rw credentials* [identity algorithm]
| +--rw identity string
| +--rw algorithm identityref
| +--rw pre-shared-key? string
| +--rw private-key? string
| +--rw private-key-callback-handle? string
| +--rw public-key? string
+--rw session-cache-capacity? uint32
+--rw session-cache-lifetime? uint32
Tree Diagram
3. Examples
Holland Expires September 10, 2019 [Page 3]
Internet-Draft TAPS API Yang Model March 2019
3.1. Basic Client Connection
The API is designed to allow defaults to fill out almost everything.
This example shows the minimal preconnection configuration input data
to open a reliable transfer to example.com, via any supported
reliable transport protocol on the default port or ports.
{
"ietf-taps-api:preconnection":{
"properties":[
{
"type":"remote-host",
"preference":"require",
"host":["example.com"]
}
]
}
}
Basic Client Connection
Due to the defaults recommended in (TBD: fix reference) Section 5 of
draft-ietf-taps-interface-02, implementations SHOULD treat this basic
example equivalently to the same example with the defaults explicitly
provided:
Holland Expires September 10, 2019 [Page 4]
Internet-Draft TAPS API Yang Model March 2019
{
"ietf-taps-api:preconnection":{
"properties":[
{
"type":"remote-host",
"host":["example.com"],
"preference":"require"
},
{
"type":"reliable",
"preference":"require"
},
{
"type":"preserve-order",
"preference":"require"
},
{
"type":"congestion-control",
"preference":"require"
}
]
}
}
Basic Client Connection Explicitly Declaring Defaults
3.2. Customized Connections
In some cases, applications may have explicit preferences, either
dynamically inferred from past statistics or configured via system or
app preferences of some kind.
These examples demonstrates adding constraints on the endpoints when
opening a connection.
3.2.1. Prohibit Specific Interface
In this example, an app needs to avoid using a local proxy for a
specific set of connections, so it might configure those connections
to prohibit connecting through a specific loopback interface:
Holland Expires September 10, 2019 [Page 5]
Internet-Draft TAPS API Yang Model March 2019
{
"ietf-taps-api:preconnection":{
"properties":[
{
"type":"remote-host",
"preference":"require",
"host":["example.com"]
},
{
"type":"local-interface-selection",
"preference":"prohibit",
"ifref":["lo0"]
}
]
}
}
Figure 1: Customized to avoid lo0
3.2.2. Require Wi-Fi
This example demonstrates an app that requires the use of a wireless
interface:
{
"ietf-taps-api:preconnection":{
"properties":[
{
"type":"remote-host",
"preference":"require",
"host":["example.com"]
},
{
"type":"local-interface-selection",
"preference":"require",
"iftype":["iana-if-type:capwapDot11Profile"]
}
]
}
}
Figure 2: Customized to require wireless.
3.3. Send and Receive Multicast
Sending to a multicast group is the same as any non-reliable, non-
ordered connection:
Holland Expires September 10, 2019 [Page 6]
Internet-Draft TAPS API Yang Model March 2019
{
"ietf-taps-api:preconnection":{
"properties":[
{
"type":"local-address",
"preference":"require",
"address":["192.0.2.15"]
},
{
"type":"remote-host",
"preference":"require",
"host":["232.252.0.2"]
},
{
"type":"remote-port",
"preference":"require",
"port":["30000"]
},
{
"type":"udp",
"preference":"require"
}
]
}
}
Figure 3: PreConnection for Sending Multicast
Receiving multicast is similar. It may use remote-endpoint to
specify a source-specific multicast subscription, or exclude it to
specify any-source multicast.
Holland Expires September 10, 2019 [Page 7]
Internet-Draft TAPS API Yang Model March 2019
{
"ietf-taps-api:preconnection":{
"properties":[
{
"type":"remote-host",
"preference":"require",
"host":["192.0.2.15"]
},
{
"type":"local-address",
"preference":"require",
"address":["232.252.0.2"]
},
{
"type":"local-port",
"preference":"require",
"port":["30000"]
},
{
"type":"udp",
"preference":"require"
}
]
}
}
Figure 4: PreConnection for Source-specific Multicast Receive
4. YANG Module
<CODE BEGINS> file ietf-taps-api@2019-03-09.yang
module ietf-taps-api {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-taps-api";
prefix "taps";
import ietf-inet-types {
prefix "inet";
reference "RFC 6991 Section 4";
}
import ietf-interfaces {
prefix "if";
reference "RFC 8343 Section 5";
}
import iana-if-type {
Holland Expires September 10, 2019 [Page 8]
Internet-Draft TAPS API Yang Model March 2019
prefix "ianaift";
reference "RFC 7224 Section 2";
}
organization "IETF";
contact
"Author: Jake Holland
<mailto:jholland@akamai.com>
";
description
"This module contains the definition for the TAPS
interface.
Copyright (c) 2018 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
draft-jholland-taps-api-yang,
see the internet draft itself for full legal notices.";
revision 2019-03-09 {
description "Draft -01 revision.";
reference
"draft-jholland-taps-api-yang";
}
typedef preference-level {
type enumeration {
enum require {
description
"select only options providing this property, fail otherwise";
}
enum prefer {
description
"prefer options providing this property, proceed otherwise";
}
enum ignore {
description
"cancel any system default preference for this property";
Holland Expires September 10, 2019 [Page 9]
Internet-Draft TAPS API Yang Model March 2019
}
enum avoid {
description
"prefer options not providing the property,
proceed otherwise";
}
enum prohibit {
description
"select only options not proiding ths property, fail
otherwise";
}
}
description
"This value represents the preference level of a property.";
}
identity connection-config-property {
description "Base identity for configuring connections";
}
identity transport-property {
base connection-config-property;
description "Base identity for transport properties";
}
identity local-endpoint-property {
base connection-config-property;
description "Base identity for local endpoint properties";
}
identity local-address {
base local-endpoint-property;
description
"Identity for the address of a local endpoint";
}
identity local-port {
base local-endpoint-property;
description
"Identity for the port of a local endpoint";
}
identity remote-endpoint-property {
base connection-config-property;
description "Base identity for remote endpoint properties";
}
identity remote-host {
Holland Expires September 10, 2019 [Page 10]
Internet-Draft TAPS API Yang Model March 2019
base remote-endpoint-property;
description
"Identity for the host of a remote endpoint";
}
identity remote-port {
base remote-endpoint-property;
description
"Identity for the port of a remote endpoint";
}
identity reliable {
base transport-property;
description "Reliable Transport";
}
identity per-message-reliable {
base transport-property;
description "Per-message Reliable Transport";
}
identity preserve-order {
base transport-property;
description "Per-message Reliable Transport";
}
identity zero-rtt-establishment {
base transport-property;
description
"Use 0-RTT session establishment with an idempotent Message";
}
identity multistream-connections-in-group {
base transport-property;
description "Multistream Connections in Group";
}
identity control-checksum-coverage {
base transport-property;
description "Control checksum coverage on sending or receiving
TBD: draft-ietf-taps-interface-02#section-5.2.6 seems to
indicate some parameters are in order with this type,
not sure exactly what it should look like? Use case?";
}
identity congestion-control {
base transport-property;
description "Congestion control";
}
identity local-interface-selection {
base transport-property;
description "Interface Instance or Type
TBD: should this be a local-endpoint-property?";
}
Holland Expires September 10, 2019 [Page 11]
Internet-Draft TAPS API Yang Model March 2019
identity provisioning-domain {
base transport-property;
description "Base for provisioning domain.
TBD: add relevant provisioning domain types";
reference "RFC 7556: Multiple Provisioning Domain Architecture";
}
identity transport-protocol {
base transport-property;
description "Identity for a transport selection.
TBD: finish the rest of the protocols in
https://tools.ietf.org/html/rfc8095#section-3.1
maybe add quic, maybe use as external augment demo.
note: this isn't in taps-interface, but is available in
e.g. NEAT-project/neat/examples/client.c";
reference "Section 3 of RFC 8095: Existing Transport Protocols";
}
identity tcp {
base transport-protocol;
description "Identity for TCP";
reference "RFC 793: Transmission Control Protocol.
See also RFC 7414: A Roadmap for TCP Specification Documents.";
}
identity mptcp {
base transport-protocol;
description "Identity for MPTCP";
reference
"RFC 6824: TCP Extensions for Multipath Operation";
}
identity udp {
base transport-protocol;
description "Identity for UDP";
reference "TBD";
}
identity udp-lite {
base transport-protocol;
description "Identity for UDP-Lite";
reference "TBD";
}
identity sctp {
base transport-protocol;
description "Identity for SCTP";
reference "TBD";
}
identity dccp {
base transport-protocol;
description "Identity for DCCP";
Holland Expires September 10, 2019 [Page 12]
Internet-Draft TAPS API Yang Model March 2019
reference "TBD";
}
identity tls {
base transport-protocol;
description "Identity for TLS";
reference "TBD";
}
identity rtp {
base transport-protocol;
description "Identity for RTP";
reference "TBD";
}
identity http {
base transport-protocol;
description "Identity for HTTP";
reference "TBD";
}
identity flute {
base transport-protocol;
description "Identity for FLUTE";
reference "TBD";
}
identity norm {
base transport-protocol;
description "Identity for NORM";
reference "TBD";
}
identity icmp {
base transport-protocol;
description "Identity for ICMP";
reference "TBD";
}
identity security-algorithm {
description "Base identity for security algorithms.";
}
identity cipher-suite {
base security-algorithm;
description "Base identity for security cipher suites.";
}
identity signature-algorithm {
base security-algorithm;
description "Base identity for security signature algorithms.";
}
identity ed25519 {
Holland Expires September 10, 2019 [Page 13]
Internet-Draft TAPS API Yang Model March 2019
base signature-algorithm;
description "Identity for ED25519";
}
identity TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 {
base cipher-suite;
description "Identity for ECDHE ECDSA with ChaCha20, Poly1305,
and SHA256";
}
grouping security-credentials {
description "security credentials";
leaf identity {
type string;
description "identity for security credentials";
}
leaf algorithm {
type identityref {
base security-algorithm;
}
description "security algorithm for credentials";
}
leaf pre-shared-key {
type string;
description "pre-shared key for security credentials";
}
leaf private-key {
type string;
description "private key for security credentials";
}
leaf private-key-callback-handle {
type string;
description "private key callback handle for
externally managed security credentials";
}
leaf public-key {
type string;
description "public key for security credentials";
}
}
container preconnection {
Holland Expires September 10, 2019 [Page 14]
Internet-Draft TAPS API Yang Model March 2019
/* config true; */
description "preconnection config for a taps connection";
list properties {
key "type preference";
description "list of transport property constraints.";
leaf type {
type identityref {
base "connection-config-property";
}
description "type of the property";
}
leaf preference {
type preference-level;
/* TBD: would be nice if i could set default and have
less verbose config file.
default require; */
description "preference level for the property";
}
leaf-list iftype {
when "derived-from-or-self(../type,
'taps:local-interface-selection')";
type identityref {
base "ianaift:iana-interface-type";
}
description "interface type constraint for local
interface selection";
reference "RFC 7224 Section 2";
}
leaf-list ifref {
when "derived-from-or-self(../type,
'taps:local-interface-selection')";
type if:interface-ref {
require-instance false;
}
description "specific interface constraint for local
interface selection.";
}
leaf-list address {
when "derived-from-or-self(../type,
'taps:local-address')";
type inet:ip-address;
description "ip address of local endpoint";
}
Holland Expires September 10, 2019 [Page 15]
Internet-Draft TAPS API Yang Model March 2019
leaf-list port {
when "derived-from-or-self(../type,
'taps:local-port') or
derived-from-or-self(../type,
'taps:remote-port')";
type inet:port-number;
description "port value of an endpoint port";
}
leaf-list host {
when "derived-from-or-self(../type,
'taps:remote-host')";
type inet:host;
description "host value of a remote endpoint";
}
}
container security {
description "Security properties for the connection";
list credentials {
key "identity algorithm";
uses security-credentials;
description "security credentials";
}
leaf session-cache-capacity {
type uint32;
description "Max number of cache elements";
}
leaf session-cache-lifetime {
type uint32;
description "Number of seconds of session cache lifetime";
}
}
}
}
<CODE ENDS>
Figure 5: TAPS Interface YANG model
5. Security Considerations
This document describes a configuration system for an API that may
replace sockets. All security considerations applicable to socket
programming should be carefully considered by implementors.
Holland Expires September 10, 2019 [Page 16]
Internet-Draft TAPS API Yang Model March 2019
(TBD: surely there is a sane reference, but also fill this out with
something less laughable. In particular, enumerate which options
should be privileged operations or not to preserve the security of
BSD sockets, such as it is. And maybe another layer of restriction
recommendations for sandboxed or browser systems.)
6. IANA Considerations
IANA is requested to add the YANG model in Section 4 to the yang-
parameters registry.
+-----------+-------------------------------------------+
| Field | Value |
+-----------+-------------------------------------------+
| Name | ietf-taps-api |
| Namespace | urn:ietf:params:xml:ns:yang:ietf-taps-api |
| Prefix | taps |
| Reference | [TBD: this document] |
+-----------+-------------------------------------------+
7. Normative References
[I-D.ietf-taps-arch]
Pauly, T., Trammell, B., Brunstrom, A., Fairhurst, G.,
Perkins, C., Tiesel, P., and C. Wood, "An Architecture for
Transport Services", draft-ietf-taps-arch-02 (work in
progress), October 2018.
[I-D.ietf-taps-interface]
Trammell, B., Welzl, M., Enghardt, T., Fairhurst, G.,
Kuehlewind, M., Perkins, C., Tiesel, P., and C. Wood, "An
Abstract Application Layer Interface to Transport
Services", draft-ietf-taps-interface-02 (work in
progress), October 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013,
<https://www.rfc-editor.org/info/rfc6991>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
Holland Expires September 10, 2019 [Page 17]
Internet-Draft TAPS API Yang Model March 2019
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>.
[RFC8343] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
<https://www.rfc-editor.org/info/rfc8343>.
[RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of
Documents Containing YANG Data Models", BCP 216, RFC 8407,
DOI 10.17487/RFC8407, October 2018,
<https://www.rfc-editor.org/info/rfc8407>.
Appendix A. Future Work
TBD if adopted:
o Review [RFC8407] guidelines for YANG authors and reviewers, make
sure they are followed.
o Start a reference implementation. No doubt it will highlight many
model problems.
o add the rest of the properties in draft-ietf-taps-interface
o many more config examples with use cases
o Look into providing explicit layers that support some kind of
pass-thru, instead of having all properties in big groups of
properties.
Author's Address
Jake Holland
Akamai Technologies, Inc.
150 Broadway
Cambridge, MA 02144
United States of America
Email: jakeholland.net@gmail.com
Holland Expires September 10, 2019 [Page 18]