// Copyright 2019 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";
option optimize_for = LITE_RUNTIME;

// This file defines the messages used by the patchpanel D-Bus API. It is
// strongly recommended to not use the patchpanel D-Bus API directly and to
// instead use the thin client defined at platform2/patchpanel/client.h that
// provides additional functionalities and abstracts the details of the wire
// format. Access control for clients is defined in platform2/patchpanel/dbus.
package patchpanel;

// Notification that the ARC++ container is starting up.
// This is informational. The ARC boot and setup sequences do not require
// any information or permission from networking to continue.
message ArcStartupRequest {
  // The PID of the ARC++ container.
  // Required.
  int32 pid = 1;
}

// This is an intentionally empty mesage. ARC++ startup does not require
// any information from networking to proceed.
message ArcStartupResponse {
}

// Notification that the ARC++ container is shutting down.
message ArcShutdownRequest {
  // The PID of the ARC++ container; must match the PID that was sent at
  // startup.
  // Required.
  int32 pid = 1;
}

// This is an intentionally empty message. ARC++ startup does not require
// any information from networking to proceed.
message ArcShutdownResponse {
}

// Notification that the ARC VM is starting up.
// Unlike in the container case, Concierge needs to know which TAP devices
// it can use.
message ArcVmStartupRequest {
  // The content ID of the VM.
  uint32 cid = 1;
}

// Represents an IPv4 subnet given a base address and prefix length.
message IPv4Subnet {
  // The base address in network order.
  uint32 base_addr = 1;

  // The prefix length of the subnet.
  uint32 prefix_len = 2;
}

// Represents a network device (physical or virtual) managed by the networking
// daemon.
message NetworkDevice {
  // Identifies the guest for which the virtual device is used.
  enum GuestType {
    UNKNOWN = 0;
    ARC = 1;
    ARCVM = 2;
    TERMINA_VM = 3;
    PLUGIN_VM = 4;
  };

  // The name of the host device interface.
  string ifname = 1;

  // The assigned IPv4 address in network order.
  uint32 ipv4_addr = 2;

  // The subnet allocated for this device
  IPv4Subnet ipv4_subnet = 3;

  // The guest to which the device is bound, if applicable.
  GuestType guest_type = 4;
}

// Request to obtain the list of virtual network devices that patchpanel
// manages for guest OSes. This does not include physical or virtual (e.g. VPN)
// devices managed by shill or virtual devices in connected namespaces.
message GetDevicesRequest {}

message GetDevicesResponse {
  // The list of devices under patchpanel's management/control.
  repeated NetworkDevice devices = 1;
}

// Information required by Concierge to continue the ARC VM startup process.
message ArcVmStartupResponse {
  // The list of TAP devices to be used in the VM.
  repeated NetworkDevice devices = 1;
}

// Notification that the ARC VM is shutting down.
// This message should also be sent if the startup process fails so any
// allocated resources are properly freed.
message ArcVmShutdownRequest {
  // The CID of the ARC VM; must match the CID that was sent at
  // startup.
  // Required.
  uint32 cid = 1;
}

// Intentionally empty response.
message ArcVmShutdownResponse {
}

// Notification that a Termina VM is starting up.
message TerminaVmStartupRequest {
  // The content ID of the VM.
  uint32 cid = 1;
}

// Information required by Concierge to continue the Termina VM startup.
message TerminaVmStartupResponse {
  // The TAP device to be used for the VM.
  NetworkDevice device = 1;

  // The container subnet to be used for the lxd bridge.
  IPv4Subnet container_subnet = 2;
};

// Notification that the Termina VM is shutting down.
// This message must also be sent if the startup process fails so any
// allocated resources, including the subnets, are properly freed.
message TerminaVmShutdownRequest {
  // The CID of the Termina VM; must match the PID that was sent at
  // startup.
  // Required.
  uint32 cid = 1;
}

// Intentionally empty response.
message TerminaVmShutdownResponse {
}

// Notification that a Plugin VM is starting up.
message PluginVmStartupRequest {
  // The unique ID of the VM.
  uint64 id = 1;

  // The 1-based index of the desired subnet to allocate for use.
  // Optional.
  int32 subnet_index = 2;
}

// Information required by Concierge to continue the Plugin VM startup.
message PluginVmStartupResponse {
  // The TAP device to be used for the VM.
  NetworkDevice device = 1;
};

// Notification that the Plugin VM is shutting down.
// This message must also be sent if the startup process fails so any
// allocated resources, including the subnets, are properly freed.
message PluginVmShutdownRequest {
  // The unique ID of the Plugin VM; must match what was sent at startup.
  // Required.
  uint64 id = 1;
}

// Intentionally empty response.
message PluginVmShutdownResponse {
}

// Request to set the VPN routing policy for a socket. The socket file
// descriptor must be immediately appended to the DBUS message after the
// serialized SetVpnIntentRequest message. The request must be sent before
// the socket is connected.
message SetVpnIntentRequest {
  // Possible policies for VPN routing available to system processes.
  // The enum values defined here are not meaningful with respect to the actual
  // bits used inside the socket fwmark for encoding the VPN routing intent.
  enum VpnRoutingPolicy {
    // Let the routing layer apply the default policy for that process uid.
    // This is the default policy for newly created sockets. It is in general
    // incorrect to use this policy for the purpose of clearing any other VPN
    // policy after the socket became connected. Instead a new socket should
    // be made.
    DEFAULT_ROUTING = 0;
    // The socket traffic is always routed through the VPN if there is one.
    ROUTE_ON_VPN = 1;
    // The socket traffic is always routed through the physical network.
    BYPASS_VPN = 2;
  }

  VpnRoutingPolicy policy = 1;
}

// Response to a SetVpnIntentRequest.
message SetVpnIntentResponse {
  bool success = 1;
}

// Request for connecting and routing a network namespace. The client must
// append a valid file descriptor immediately after the serialized
// ConnectNamespaceRequest proto. This file descriptor must remain valid for as
// long as the client namespace needs to remain connected. Invalidating the file
// descriptor explicitly by closing it or implicitly when the client exits will
// trigger the teardown of the routing setup, the veth setup, and the release
// of the IPv4 subnet assigned to the namespace.
message ConnectNamespaceRequest {
  // The pid of the client network namespace.
  int32 pid = 1;

  // If the client sets this field to the name of a physical network device
  // managed by shill, the namespace egress traffic routed outside the device
  // will be routed using the routing table specific to that physical device.
  // If left empty, the namespace will be routed through the system highest
  // priority interface (physical or virtual).
  string outbound_physical_device = 2;

  // If true, traffic originated from managed OSs (Crostini, ARC, PluginVMs) and
  // from Chrome can be routed to this namespace, and traffic originated from
  // this namespace can be routed to these other privilege domains.
  bool allow_user_traffic = 3;

  // This field specifies the routing behavior to use when (1)
  // |outbound_physical_device| is empty and (2) the system's highest priority
  // network interface is a VPN. If true, egress traffic will be routed to the
  // VPN; if false, it will be left on the underlying physical interface.
  bool route_on_vpn = 4;

  // Specifies how the traffic flowing over the new virtual network should be
  // accounted, if applicable.
  // This field is required. The default behavior will be to treat unspecified
  // and UNKNOWN sources as SYSTEM traffic for accounting purposes.
  TrafficCounter.Source traffic_source = 5;
}

// Response to a ConnectNamespaceRequest. If the operation failed then all
// fields are left set to their default value (empty string or 0).
message ConnectNamespaceResponse {
  // The subnet allocated to the client namespace.
  IPv4Subnet ipv4_subnet = 1;

  // Name of the veth interface created in the client namespace.
  string peer_ifname = 2;

  // The IPv4 address in network order assigned to the interface inside the
  // client namespace.
  uint32 peer_ipv4_address = 3;

  // Name of the veth interface created in the host namespace.
  string host_ifname = 4;

  // The IPv4 address in network order assigned to the interface in the host
  // namespace.
  uint32 host_ipv4_address = 5;
}

// Represents the traffic usage ({tx, rx} x {packets, bytes}) between a source
// and a shill device (interface), since the system (CrOS) is booted up. A
// counter will keep growing until the system (CrOS) shuts down.
// Used in TrafficCountersResponse.
message TrafficCounter {
  // Possible traffic sources.
  enum Source {
    UNKNOWN = 0;
    // Traffic associated with user chronos.
    CHROME = 1;
    // Traffic associated with user debugd, cups, and tlsdate, i.e., other user
    // traffic except for that for user chronos.
    USER = 2;
    ARC = 3;
    CROSVM = 4;
    PLUGINVM = 5;
    UPDATE_ENGINE = 6;
    // As a source, VPN means traffic initiated by the VPN app/program and going
    // to the underlying physical network (or from physical network to the VPN
    // app/program).
    VPN = 7;
    // All other traffic.
    SYSTEM = 8;
  }

  // Counter values need to be 64bits as 32bits is not enough to account for
  // more than ~4GB of traffic.
  uint64 rx_bytes = 1;
  uint64 tx_bytes = 2;
  uint64 rx_packets = 3;
  uint64 tx_packets = 4;

  Source source = 5;
  // The shill device (interface) name (e.g., eth0) where the traffic leaves
  // from or comes in.
  string device = 6;
}

// Requests the traffic counters kept by patchpanel. |devices| is the set of
// interfaces for which counters should be returned, any unknown interfaces will
// be ignored. If |devices| is empty, counters for all known interfaces will be
// returned. Note that if an interface once appeared but does not exist now,
// counters for it will also be returned.
message TrafficCountersRequest {
  repeated string devices = 1;
}

// Response to a TrafficCountersRequest.
message TrafficCountersResponse {
  repeated TrafficCounter counters = 1;
}

// Request for opening and closing firewall port. If the request is valid,
// PatchPanel will run iptables commands following the request.
message ModifyPortRuleRequest {
  enum Operation {
    INVALID_OPERATION = 0;
    CREATE = 1;
    DELETE = 2;
  }

  enum RuleType {
    INVALID_RULE_TYPE = 0;
    ACCESS = 1;     // Equivalent of iptables 'ACCEPT'
    LOCKDOWN = 2;   // Equivalent of iptables 'DROP'
    FORWARDING = 3; // Equivalent of iptables 'DNAT'
  }

  enum Protocol {
    INVALID_PROTOCOL = 0;
    TCP = 1;
    UDP = 2;
  }

  // Arguments specifying the type of operation, rule and protocol.
  Operation op = 1;
  RuleType type = 2;
  Protocol proto = 3;

  // A network interface name, or empty if unspecified. This is optional for
  // ACCESS and FORWARDING, and is ignored for other rule types.
  string input_ifname = 4;

  // An IPv4 address, or empty if unspecified. This is optional for FORWARDING,
  // and is ignored for other rule types.
  string input_dst_ip = 5;

  // A port value in-between 1 and 65535. This is required for all rule types.
  uint32 input_dst_port = 6;

  // An IPv4 address, or empty if unspecified. This is required for FORWARDING,
  // and is ignored for other rule types.
  string dst_ip = 7;

  // A port value between 1 and 65535. This is required for FORWARDING, and is
  // ignored for other rule types.
  uint32 dst_port = 8;
}

// Response to a ModifyPortRuleRequest.
message ModifyPortRuleResponse {
  bool success = 1;
}

// Signal that is emitted when a device managed by patchpanel is added or
// removed.
message NetworkDeviceChangedSignal {
  enum Event {
    UNKNOWN_CHANGE = 0;
    DEVICE_ADDED = 1;
    DEVICE_REMOVED = 2;
  };

  NetworkDevice device = 1;
  Event event = 2;
}

// Signal for notifying an event about the layer 2 reachability of a neighbor
// monitored by NeighborLinkMonitor.
message NeighborReachabilityEventSignal {
  // Possible roles of a neighbor in the corresponding ipconfig.
  enum Role {
    INVALID_ROLE = 0;
    GATEWAY = 1;
    DNS_SERVER = 2;
    GATEWAY_AND_DNS_SERVER = 3;
  };

  // Possible event types. See the class comment of NeighborLinkMonitor for more
  // details about how these events are generated.
  enum EventType {
    INVALID_EVENT_TYPE = 0;
    // Indicates a failure is detected for this neighbor. After this event, no
    // more FAILED events will be generated for this neighbor until a RECOVERED
    // event happens.
    FAILED = 1;
    // Indicates this neighbor has recovered from the previous failure: the
    // layer 2 bidirectional reachability has been confirmed for a while. Note
    // that a new neighbor is considered as "reachable" so this event will not
    // be generated when we start to monitor a new neighbor.
    RECOVERED = 2;
  };

  // The interface index of the device that connects to this neighbor.
  int32 ifindex = 1;

  // Neighbor properties.
  string ip_addr = 2;
  Role role = 3;

  EventType type = 4;
}