doc/vpn-agent-api.txt

   1 Agent hierarchy
   2 ===============
   3
   4 Service         unique name
   5 Interface       net.connman.vpn.Agent
   6 Object path     freely definable
   7
   8 Methods         void Release()
   9
  10                         This method gets called when the service daemon
  11                         unregisters the agent. An agent can use it to do
  12                         cleanup tasks. There is no need to unregister the
  13                         agent, because when this method gets called it has
  14                         already been unregistered.
  15
  16                 void ReportError(object service, string error)
  17
  18                         This method gets called when an error has to be
  19                         reported to the user.
  20
  21                         A special return value can be used to trigger a
  22                         retry of the failed transaction.
  23
  24                         Possible Errors: net.connman.vpn.Agent.Error.Retry
  25
  26                 dict RequestInput(object service, dict fields)
  27
  28                         This method gets called when trying to connect to
  29                         a service and some extra input is required. For
  30                         example a password or username.
  31
  32                         The return value should be a dictionary where the
  33                         keys are the field names and the values are the
  34                         actual fields. Alternatively an error indicating that
  35                         the request got canceled can be returned.
  36
  37                         Most common return field names are "Username" and of
  38                         course "Password".
  39
  40                         The dictionary arguments contains field names with
  41                         their input parameters.
  42
  43                         Possible Errors: net.connman.vpn.Agent.Error.Canceled
  44
  45                 void Cancel()
  46
  47                         This method gets called to indicate that the agent
  48                         request failed before a reply was returned.
  49
  50 Fields          string Username
  51
  52                         Username for authentication. This field will be
  53                         requested when connecting to L2TP and PPTP.
  54
  55                 string Password
  56
  57                         Password for authentication.
  58
  59                 boolean SaveCredentials
  60
  61                         Tells if the user wants the user credentials
  62                         be saved by connman-vpnd.
  63
  64                 string Host
  65
  66                         End point of this VPN link i.e., the VPN gateway
  67                         we are trying to connect to.
  68
  69                 string Name
  70
  71                         Name of the VPN connection we are trying to connect to.
  72
  73                 string OpenConnect.CACert
  74
  75                         Informational field containing a path name for an
  76                         additional Certificate Authority file.
  77
  78                 string OpenConnect.ClientCert
  79
  80                         Informational field containing a pkcs11 URL or a path
  81                         name for the client certificate.
  82
  83                 string OpenConnect.Cookie
  84
  85                         Return the OpenConnect cookie value that is used for
  86                         authenticating the VPN session.
  87
  88                 string OpenConnect.PKCSClientCert
  89
  90                         Informational field containing a PKCS#1/PKCS#8/PKCS#12
  91                         URL or a path name for the PKCS#1/PKCS#8/PKCS#12 client
  92                         certificate.
  93
  94                 string OpenConnect.PKCSPassword
  95
  96                         Password for decrypting PKCS#8/PKCS#12 client
  97                         certificate.
  98
  99                 string OpenConnect.ServerCert
 100
 101                         Return the OpenConnect server hash used to identify
 102                         the final server after possible web authentication
 103                         logins, selections and redirections.
 104
 105                 string OpenConnect.VPNHost
 106
 107                         Return the final VPN server to use after possible
 108                         web authentication logins, selections and redirections.
 109
 110                 string OpenVPN.PrivateKeyPassword
 111
 112                         Return the private key password used to decrypt the
 113                         encrypted OpenVPN private key file.
 114
 115                 boolean AllowStoreCredentials
 116
 117                         Indicates to the receiving UI whether the values
 118                         entered by the user can be stored for future use.
 119                         "Requirement" should be set to "control". A "Value"
 120                         of true indicates that the option to store the
 121                         credentials can be offered to the user, false
 122                         indicates that no such option should be presented.
 123
 124                 boolean AllowRetrieveCredentials
 125
 126                         Tells the receiving UI whether to attempt to retrieve
 127                         previously stored values. "Requirement" should be set
 128                         to "control". "Value" should be set to true if
 129                         previously stored values can be used, false otherwise.
 130
 131                 boolean KeepCredentials
 132
 133                         Indicates to the receiving UI whether to keep ("Value"
 134                         is set "true") or clear ("Value" is set "false") the
 135                         credentials or not. "Requirement" should be set to
 136                         "control". By default this is not required to be set
 137                         and is handled only when explicitly defined as "true".
 138                         This is useful in case of having both the
 139                         AllowStoreCredentials and the AllowRetrieveCredentials
 140                         set as "false", but clearing credentials is not
 141                         required. In such case the value can be explicitly set
 142                         to "true". An example case is when the password for
 143                         encrypted Private Key is requested.
 144
 145                 string VpnAgent.AuthFailure
 146
 147                         Informational field that can be used to indicate VPN
 148                         agent that previous authentication has failed and new
 149                         credentials should be requested from user. Additional
 150                         information about the failure can be added as "Value".
 151
 152 Arguments       string Type
 153
 154                         Contains the type of a field. For example "password",
 155                         "response", "boolean" or plain "string".
 156
 157                 string Requirement
 158
 159                         Contains the requirement option. Valid values are
 160                         "mandatory", "optional", "alternate", "informational"
 161                         and "control".
 162
 163                         The "alternate" value specifies that this field can be
 164                         returned as an alternative to another one.
 165
 166                         All "mandatory" fields must be returned, while the
 167                         "optional" can be returned if available.
 168
 169                         Nothing needs to be returned for "informational", as it
 170                         is here only to provide an information so a value is
 171                         attached to it.
 172
 173                         A "control" argument is used to specify behaviour. The
 174                         effect will depend on the field name and value, but
 175                         control fields will not usually be presented directly
 176                         to the user, and are not expected to be returned.
 177
 178                 array{string} Alternates
 179
 180                         Contains the list of alternate field names this
 181                         field can be represented by.
 182
 183                 string Value
 184
 185                         Contains data as a string, relatively to an
 186                         "informational" argument.
 187
 188 Examples        Requesting a username and password for L2TP network
 189
 190                         RequestInput("/vpn1",
 191                                 { "Username" : { "Type"        : "string",
 192                                                  "Requirement" : "mandatory"
 193                                                 } }
 194                                 { "Password" : { "Type"        : "password",
 195                                                  "Requirement" : "mandatory"
 196                                                 } }
 197                                 { "SaveCredentials" : { "Type" : "boolean",
 198                                                 "Requirement" : "optional"
 199                                                 }
 200                                 }
 201                         ==> { "Username" : "foo", "Password" : "secret123",
 202                                 "SaveCredentials" : true }
 203
 204                 Requesting a OpenConnect cookie
 205
 206                         RequestInput("/vpn2",
 207                                 { "OpenConnect.Cookie" : { "Type" : "string",
 208                                                  "Requirement" : "mandatory"
 209                                                         } }
 210                                 { "Host" : { "Type" : "string",
 211                                          "Requirement" : "informational"
 212                                                         } }
 213                                 { "Name" : { "Type" : "string",
 214                                          "Requirement" : "informational"
 215                                                         } }
 216                         ==> { "OpenConnect.Cookie" : "0123456@adfsf@asasdf" }
 217
 218                 Requesting a username and password but without allowing
 219                 the values entered by the user to be stored.
 220
 221                         RequestInput("/vpn3",
 222                                 { "Username" : { "Type" : "string",
 223                                                 "Requirement" : "mandatory"
 224                                                         } }
 225                                 { "Password" : { "Type" : "password",
 226                                                 "Requirement" : "mandatory"
 227                                                         } }
 228                                 { "AllowStoreCredentials" : { "Type" : "boolean",
 229                                                 "Requirement" : "control",
 230                                                 "Value" : false
 231                                                         } }
 232                 ==> { "Username" : "foo", "Password" : "secret123" }