doc/vpn-overview.txt

   1 VPN daemon overview
   2 *******************
   3
   4
   5 Manager interface
   6 =================
   7
   8 Manager interface described in vpn-manager-api.txt is to be used
   9 by both the connectivity UI and by ConnMan. The Create(),
  10 Remove(), RegisterAgent() and UnregisterAgent() functions are for
  11 UI usage. The GetConnections() method and ConnectionAdded() and
  12 ConnectionRemoved() signals are for ConnMan VPN plugin to use.
  13
  14 The UI should use the methods like this:
  15 - Ask VPN properties (like certs, usernames etc) from the user.
  16 - Call Manager.Create() to create a VPN connection (note that
  17   the system does not yet try to connect to VPN at this point)
  18 - Register an agent to vpnd so that vpnd can ask any extra
  19   parameters etc from the user if needed.
  20 - If the user wants to connect to VPN gateway, then the
  21   connection attempt should be done in ConnMan side as
  22   there will be a service created there.
  23 - If the user wishes to remove the VPN configuration, the UI
  24   can call the Manager.Remove() which removes the VPN connection.
  25   If the VPN was in use, the VPN connection is also disconnected.
  26 - When UI is terminated, the UI should call the UnregisterAgent()
  27
  28 The ConnMan calls VPN daemon like this:
  29 - There is a VPN plugin which at startup starts to listen the
  30   ConnectionAdded() and ConnectionRemoved() signals.
  31 - The VPN plugin will call GetConnections() in order to get
  32   available VPN connections. It will then create a provider service
  33   for each VPN connection that is returned.
  34 - User can then connect to the VPN by calling the service Connect()
  35   method
  36 - The existing ConnMan Manager.ConnectProvider() interface can still
  37   work by calling vpn.Manager.Create() and then call vpn.Connection.Connect()
  38   but this ConnectProvider() interface will be deprecated at some
  39   point.
  40
  41
  42
  43 Connection interface
  44 ====================
  45
  46 The Manager.Create() will return the object path of the created
  47 vpn.Connection object and place it in idle state. Note that
  48 vpn.Connection.PropertyChanged signal is not called when Connection
  49 object is created because the same parameters are returned via
  50 vpn.Manager.ConnectionAdded() signal.
  51 The vpn.Connection object can be connected using the Connect() method
  52 and disconnected by calling Disconnect() method. When the connection
  53 is established (meaning VPN client has managed to create a connection
  54 to VPN server), then State property is set to "ready" and PropertyChanged
  55 signal is sent. If the connection cannot be established, then
  56 State property is set to "failure".
  57 After successful connection, the relevant connection properties are sent
  58 by PropertyChanged signal; like IPv[4|6] information, the index of the
  59 VPN tunneling interface (if there is any), nameserver information,
  60 server specified routes etc.
  61
  62 VPN agent interface
  63 ===================
  64
  65 VPN agent interface described in vpn-agent-api.txt is used for
  66 interaction between the connectivity UI and ConnMan. A VPN agent
  67 registered via Management interface gets requests from the VPN plugins
  68 to input credentials or other authentication information for the VPN
  69 connection and offers information about the VPN to be connected.
  70
  71 In addition to basic credentials, there are additional types of optional
  72 and control parameters. The user can dictate whether to store the
  73 credentials with the optional SaveCredentials value. The VPN plugins can
  74 also define with the control values AllowStoreCredentials,
  75 AllowRetrieveCredentials and KeepCredentials how the VPN agent must
  76 handle the credentials. AllowStoreCredentials as false indicates that
  77 client cannot use SaveCredentials option. AllowRetrieveCredentials set
  78 as false, without AllowStoreCredentials set as false should not have
  79 that same effect and in that case user is allowed to save credentials.
  80
  81 These three control values become useful when a VPN has two or more
  82 sets of authentication credentials, second of which can be requested
  83 when the VPN detects a need for them. The first, main credentials,
  84 would be requested without these control values, so user is able to
  85 select whether the credentials are saved or not with SaveCredentials
  86 value. After the VPN initializes the connection and, e.g., needs to
  87 decrypt a private key file, a new request is sent to VPN agent. In this
  88 new request both AllowStoreCredentials and AllowRetrieveCredentials are
  89 set as false indicating that in no circumstances existing credentials
  90 stored are to be used and neither there should be option visible for
  91 the user to select saving of the credentials. Depending on VPN agent
  92 implementation these values can be interpreted as clearing of all the
  93 existing credentials related to the VPN connection from the credential
  94 storage. By including the KeepCredentials as true value the VPN can,
  95 however, tell the VPN agent not to clear the credentials for this VPN
  96 connection. The KeepCredentials is used to inform the VPN agent that
  97 these new, second/third/etc. credentials are only to be queried from
  98 the user and forgotten after that, when used in conjunction with the
  99 AllowStoreCredentials and AllowRetrieveCredentials set as false.