Imported Upstream connman version 1.38

[platform/upstream/connman.git] / doc / vpn-agent-api.txt

diff --git a/doc/vpn-agent-api.txt b/doc/vpn-agent-api.txt
index 72bee9d..ffa6fad 100644 (file)
--- a/doc/vpn-agent-api.txt
+++ b/doc/vpn-agent-api.txt
@@ -78,13 +78,24 @@ Fields              string Username
                string OpenConnect.ClientCert
 
                        Informational field containing a pkcs11 URL or a path
                string OpenConnect.ClientCert
 
                        Informational field containing a pkcs11 URL or a path

-                        name for the client certificate.
+                       name for the client certificate.

 
                string OpenConnect.Cookie
 
                        Return the OpenConnect cookie value that is used for
                        authenticating the VPN session.
 
 
                string OpenConnect.Cookie
 
                        Return the OpenConnect cookie value that is used for
                        authenticating the VPN session.
 

+               string OpenConnect.PKCSClientCert
+
+                       Informational field containing a PKCS#1/PKCS#8/PKCS#12
+                       URL or a path name for the PKCS#1/PKCS#8/PKCS#12 client
+                       certificate.
+
+               string OpenConnect.PKCSPassword
+
+                       Password for decrypting PKCS#8/PKCS#12 client
+                       certificate.
+

                string OpenConnect.ServerCert
 
                        Return the OpenConnect server hash used to identify
                string OpenConnect.ServerCert
 
                        Return the OpenConnect server hash used to identify


@@ -96,6 +107,48 @@ Fields              string Username
                        Return the final VPN server to use after possible
                        web authentication logins, selections and redirections.
 
                        Return the final VPN server to use after possible
                        web authentication logins, selections and redirections.
 

+               string OpenVPN.PrivateKeyPassword
+
+                       Return the private key password used to decrypt the
+                       encrypted OpenVPN private key file.
+
+               boolean AllowStoreCredentials
+
+                       Indicates to the receiving UI whether the values
+                       entered by the user can be stored for future use.
+                       "Requirement" should be set to "control". A "Value"
+                       of true indicates that the option to store the
+                       credentials can be offered to the user, false
+                       indicates that no such option should be presented.
+
+               boolean AllowRetrieveCredentials
+
+                       Tells the receiving UI whether to attempt to retrieve
+                       previously stored values. "Requirement" should be set
+                       to "control". "Value" should be set to true if
+                       previously stored values can be used, false otherwise.
+
+               boolean KeepCredentials
+
+                       Indicates to the receiving UI whether to keep ("Value"
+                       is set "true") or clear ("Value" is set "false") the
+                       credentials or not. "Requirement" should be set to
+                       "control". By default this is not required to be set
+                       and is handled only when explicitly defined as "true".
+                       This is useful in case of having both the
+                       AllowStoreCredentials and the AllowRetrieveCredentials
+                       set as "false", but clearing credentials is not
+                       required. In such case the value can be explicitly set
+                       to "true". An example case is when the password for
+                       encrypted Private Key is requested.
+
+               string VpnAgent.AuthFailure
+
+                       Informational field that can be used to indicate VPN
+                       agent that previous authentication has failed and new
+                       credentials should be requested from user. Additional
+                       information about the failure can be added as "Value".
+

 Arguments      string Type
 
                        Contains the type of a field. For example "password",
 Arguments      string Type
 
                        Contains the type of a field. For example "password",


@@ -104,8 +157,8 @@ Arguments   string Type
                string Requirement
 
                        Contains the requirement option. Valid values are
                string Requirement
 
                        Contains the requirement option. Valid values are

-                       "mandatory", "optional", "alternate" or
-                       "informational".
+                       "mandatory", "optional", "alternate", "informational"
+                       and "control".

 
                        The "alternate" value specifies that this field can be
                        returned as an alternative to another one.
 
                        The "alternate" value specifies that this field can be
                        returned as an alternative to another one.


@@ -117,6 +170,11 @@ Arguments  string Type
                        is here only to provide an information so a value is
                        attached to it.
 
                        is here only to provide an information so a value is
                        attached to it.
 

+                       A "control" argument is used to specify behaviour. The
+                       effect will depend on the field name and value, but
+                       control fields will not usually be presented directly
+                       to the user, and are not expected to be returned.
+

                array{string} Alternates
 
                        Contains the list of alternate field names this
                array{string} Alternates
 
                        Contains the list of alternate field names this


@@ -156,3 +214,19 @@ Examples   Requesting a username and password for L2TP network
                                         "Requirement" : "informational"
                                                        } }
                        ==> { "OpenConnect.Cookie" : "0123456@adfsf@asasdf" }
                                         "Requirement" : "informational"
                                                        } }
                        ==> { "OpenConnect.Cookie" : "0123456@adfsf@asasdf" }

+
+               Requesting a username and password but without allowing
+               the values entered by the user to be stored.
+
+                       RequestInput("/vpn3",
+                               { "Username" : { "Type" : "string",
+                                               "Requirement" : "mandatory"
+                                                       } }
+                               { "Password" : { "Type" : "password",
+                                               "Requirement" : "mandatory"
+                                                       } }
+                               { "AllowStoreCredentials" : { "Type" : "boolean",
+                                               "Requirement" : "control",
+                                               "Value" : false
+                                                       } }
+               ==> { "Username" : "foo", "Password" : "secret123" }