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.Group
  89
  90                         Choose authentication login group.
  91
  92                 string OpenConnect.PKCSClientCert
  93
  94                         Informational field containing a PKCS#1/PKCS#8/PKCS#12
  95                         URL or a path name for the PKCS#1/PKCS#8/PKCS#12 client
  96                         certificate.
  97
  98                 string OpenConnect.PKCSPassword
  99
 100                         Password for decrypting PKCS#8/PKCS#12 client
 101                         certificate.
 102
 103                 string OpenConnect.SecondPassword
 104
 105                         Second factor password for authentication.
 106
 107                 string OpenConnect.ServerCert
 108
 109                         Return the OpenConnect server hash used to identify
 110                         the final server after possible web authentication
 111                         logins, selections and redirections.
 112
 113                 boolean OpenConnect.UseSecondPassword
 114
 115                         Indicates that second factor password is used
 116                         for selected authentication group.
 117
 118                 string OpenConnect.VPNHost
 119
 120                         Return the final VPN server to use after possible
 121                         web authentication logins, selections and redirections.
 122
 123                 string OpenVPN.PrivateKeyPassword
 124
 125                         Return the private key password used to decrypt the
 126                         encrypted OpenVPN private key file.
 127
 128                 boolean AllowStoreCredentials
 129
 130                         Indicates to the receiving UI whether the values
 131                         entered by the user can be stored for future use.
 132                         "Requirement" should be set to "control". A "Value"
 133                         of true indicates that the option to store the
 134                         credentials can be offered to the user, false
 135                         indicates that no such option should be presented.
 136
 137                 boolean AllowRetrieveCredentials
 138
 139                         Tells the receiving UI whether to attempt to retrieve
 140                         previously stored values. "Requirement" should be set
 141                         to "control". "Value" should be set to true if
 142                         previously stored values can be used, false otherwise.
 143
 144                 boolean KeepCredentials
 145
 146                         Indicates to the receiving UI whether to keep ("Value"
 147                         is set "true") or clear ("Value" is set "false") the
 148                         credentials or not. "Requirement" should be set to
 149                         "control". By default this is not required to be set
 150                         and is handled only when explicitly defined as "true".
 151                         This is useful in case of having both the
 152                         AllowStoreCredentials and the AllowRetrieveCredentials
 153                         set as "false", but clearing credentials is not
 154                         required. In such case the value can be explicitly set
 155                         to "true". An example case is when the password for
 156                         encrypted Private Key is requested.
 157
 158                 string VpnAgent.AuthFailure
 159
 160                         Informational field that can be used to indicate VPN
 161                         agent that previous authentication has failed and new
 162                         credentials should be requested from user. Additional
 163                         information about the failure can be added as "Value".
 164
 165 Arguments       string Type
 166
 167                         Contains the type of a field. For example "password",
 168                         "response", "boolean" or plain "string".
 169
 170                 string Requirement
 171
 172                         Contains the requirement option. Valid values are
 173                         "mandatory", "optional", "alternate", "informational"
 174                         and "control".
 175
 176                         The "alternate" value specifies that this field can be
 177                         returned as an alternative to another one.
 178
 179                         All "mandatory" fields must be returned, while the
 180                         "optional" can be returned if available.
 181
 182                         Nothing needs to be returned for "informational", as it
 183                         is here only to provide an information so a value is
 184                         attached to it.
 185
 186                         A "control" argument is used to specify behaviour. The
 187                         effect will depend on the field name and value, but
 188                         control fields will not usually be presented directly
 189                         to the user, and are not expected to be returned.
 190
 191                 array{string} Alternates
 192
 193                         Contains the list of alternate field names this
 194                         field can be represented by.
 195
 196                 string Value
 197
 198                         Contains data as a string, relatively to an
 199                         "informational" argument.
 200
 201 Examples        Requesting a username and password for L2TP network
 202
 203                         RequestInput("/vpn1",
 204                                 { "Username" : { "Type"        : "string",
 205                                                  "Requirement" : "mandatory"
 206                                                 } }
 207                                 { "Password" : { "Type"        : "password",
 208                                                  "Requirement" : "mandatory"
 209                                                 } }
 210                                 { "SaveCredentials" : { "Type" : "boolean",
 211                                                 "Requirement" : "optional"
 212                                                 }
 213                                 }
 214                         ==> { "Username" : "foo", "Password" : "secret123",
 215                                 "SaveCredentials" : true }
 216
 217                 Requesting a OpenConnect cookie
 218
 219                         RequestInput("/vpn2",
 220                                 { "OpenConnect.Cookie" : { "Type" : "string",
 221                                                  "Requirement" : "mandatory"
 222                                                         } }
 223                                 { "Host" : { "Type" : "string",
 224                                          "Requirement" : "informational"
 225                                                         } }
 226                                 { "Name" : { "Type" : "string",
 227                                          "Requirement" : "informational"
 228                                                         } }
 229                         ==> { "OpenConnect.Cookie" : "0123456@adfsf@asasdf" }
 230
 231                 Requesting a username and password but without allowing
 232                 the values entered by the user to be stored.
 233
 234                         RequestInput("/vpn3",
 235                                 { "Username" : { "Type" : "string",
 236                                                 "Requirement" : "mandatory"
 237                                                         } }
 238                                 { "Password" : { "Type" : "password",
 239                                                 "Requirement" : "mandatory"
 240                                                         } }
 241                                 { "AllowStoreCredentials" : { "Type" : "boolean",
 242                                                 "Requirement" : "control",
 243                                                 "Value" : false
 244                                                         } }
 245                 ==> { "Username" : "foo", "Password" : "secret123" }