Home | History | Annotate | Download | only in seneschal 
      1 // Copyright 2017 The Chromium OS Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 syntax = "proto3";
      6 option optimize_for = LITE_RUNTIME;
      7 
      8 // This file defines messages for starting, stopping, and managing 9p servers
      9 // with access to the user's home directory.
     10 package vm_tools.seneschal;
     11 option go_package = "seneschal_proto";
     12 
     13 // Defines a path to be shared with a 9p server.
     14 message SharedPath {
     15   // Path to be shared.  Must be relative, must not have any ".." elements, and
     16   // must not end with ".".  The destination path is constructed by appending
     17   // the name of the storage location and this path to the root of the server.
     18   // So if |path| is "foo/bar" and the |storage_location| field of the
     19   // SharePathRequest is "DOWNLOADS", then the destination path will be
     20   // "/Downloads/foo/bar".  Any ancestor directories will be automatically
     21   // created but will not be writable unless they have been shared via a
     22   // SharePathRequest.
     23   string path = 1;
     24 
     25   // Whether the path should be writable by the server.  Due to limitations in
     26   // the way bind mounts interact with user namespaces, setting this to false
     27   // will not currently do anything.  All shared paths are writable.  Maybe
     28   // one day if the linux developers decide that dropping privileges should
     29   // not require having additional privileges that you wouldn't otherwise need
     30   // we can maybe do something useful with this.
     31   bool writable = 2;
     32 }
     33 
     34 // Defines the vsock address on which a server should listen for requests.
     35 // The server will always use context id 2 (VM host) as its address.
     36 message VsockAddress {
     37   // The port number on which the server should listen for requests.
     38   uint32 port = 1;
     39 
     40   // The context id from which this server should accept connections.
     41   uint32 accept_cid = 2;
     42 }
     43 
     44 // Defines the unix address on which a server should listen for requests.
     45 message UnixAddress {
     46   // The path on the system where the server should listen for requests.
     47   string path = 1;
     48 }
     49 
     50 // Defines the network address on which a server should listen for requests.
     51 // The server will always use localhost as its address.
     52 message NetworkAddress {
     53   // The port on which the server should listen for requests.
     54   uint32 port = 1;
     55 }
     56 
     57 // Indicates that the message includes a file descriptor on which the server
     58 // should listen for requests.
     59 message FileDescriptor {}
     60 
     61 // Information that must be included with every StartServer dbus request.
     62 message StartServerRequest {
     63   // The address on which the server should listen for requests.
     64   oneof listen_address {
     65     VsockAddress vsock = 1;
     66     UnixAddress unix_addr = 2;
     67     NetworkAddress net = 3;
     68     FileDescriptor fd = 4;
     69   }
     70 }
     71 
     72 // Information sent back by seneschal in response to a StartServer message.
     73 message StartServerResponse {
     74   // Set to true if the server was started successfully.
     75   bool success = 1;
     76 
     77   // The handle with which to refer to this server in future requests.  Only
     78   // valid if |success| is true.
     79   uint32 handle = 2;
     80 
     81   // The reason why the server failed to start, if any.  Only valid when
     82   // |success| is false.
     83   string failure_reason = 3;
     84 }
     85 
     86 // Information that must be included with every StopServer request.
     87 message StopServerRequest {
     88   // The handle to the server that should be stopped.
     89   uint32 handle = 1;
     90 }
     91 
     92 // Information sent back by seneschal when it receives a StopServer requests.
     93 message StopServerResponse {
     94   // If true, then the server was successfully stopped.
     95   bool success = 1;
     96 
     97   // The reason why the server could not be stopped, if any.  Only valid when
     98   // |success| is false.
     99   string failure_reason = 2;
    100 }
    101 
    102 // Information that must be included with every SharePath request.
    103 message SharePathRequest {
    104   // The handle to the server with whom the path should be shared.
    105   uint32 handle = 1;
    106 
    107   // The actual path to be shared.  Must be relative to |storage_location|
    108   // and must not contain any "../" elements or end with ".".
    109   SharedPath shared_path = 2;
    110 
    111   // The location where the path to be shared lives.
    112   enum StorageLocation {
    113     // The user's Downloads/ directory.
    114     DOWNLOADS = 0;
    115   }
    116   StorageLocation storage_location = 3;
    117 
    118   // The user's cryptohome.  This is the <hash> part of /home/user/<hash>.
    119   string owner_id = 4;
    120 }
    121 
    122 // Information sent back by seneschal when it receives a SharePath request.
    123 message SharePathResponse {
    124   // If true, then the path was shared successfully.
    125   bool success = 1;
    126 
    127   // The path relative to the server's root where the shared path can be
    128   // accessed.  Only valid if |success| is true.
    129   string path = 2;
    130 
    131   // The reason why the path could not be shared, if any.  Only valid when
    132   // |success| is false.
    133   string failure_reason = 3;
    134 }
    135