1English
2=======
3
4Windows
5-------
6
7Start the installer of AusweisApp2 using the command line to configure the
8installation process and preset system-wide default settings.
9The return value of msiexec indicates the result of the installation [#msiexecreturnvalues]_.
10In addition to the usual arguments [#standardarguments]_, the following command
11contains all supported arguments, which are explained below.
12
13.. code-block:: winbatch
14
15  msiexec /i AusweisApp2-X.YY.Z.msi /quiet INSTALLDIR="C:\AusweisApp2" SYSTEMSETTINGS=false DESKTOPSHORTCUT=false AUTOSTART=false AUTOHIDE=false REMINDTOCLOSE=false ASSISTANT=false TRANSPORTPINREMINDER=false CUSTOMPROXYTYPE="HTTP" CUSTOMPROXYHOST="proxy.example.org" CUSTOMPROXYPORT=1337 UPDATECHECK=false ONSCREENKEYBOARD=true SHUFFLESCREENKEYBOARD=true HISTORY=false ENABLECANALLOWED=true SKIPRIGHTSONCANALLOWED=true LAUNCH=true
16
17INSTALLDIR
18  States the installation directory. If not specified, the folder
19  "C:\\Program Files (x86)\\AusweisApp2" is used.
20
21SYSTEMSETTINGS
22  Concerns the settings of firewall rules of the Windows Firewall. When not
23  specifying the argument, firewall rules are created (true). By indicating
24  SYSTEMSETTINGS=false, no firewall rules are created.
25
26DESKTOPSHORTCUT
27  By specifying DESKTOPSHORTCUT=false, no desktop shortcut is created. Without
28  specifying the argument, the desktop shortcut is created for all users (true).
29
30AUTOSTART
31  Setting AUTOSTART=true creates autostart entry for all users. Users are unable
32  to deactivate the autostart function in the AusweisApp2. Not specified, no
33  autostart entry is created (false). In that case, users are able to activate the
34  autostart function in the AusweisApp2.
35
36AUTOHIDE
37  Concerns the automatic minimization after a successful authentication. Not
38  specified, it is activated (true). Setting AUTOHIDE=false, it is deactivated.
39  Users can adjust this setting to their preferences.
40
41REMINDTOCLOSE
42  Closing the AusweisApp2 by clicking on the X, the user is notified that only the
43  user interface is closed and that the AusweisApp2 is still available in the info
44  tray. At this point, it is possible to prevent future notifications. Setting
45  REMINDTOCLOSE=false deactivates this notification from the outset. Not
46  specified, it is activated (true).
47
48ASSISTANT
49  Starting the AusweisApp2 for the first time, the user interface is displayed and
50  the installation wizard is shown. With each subsequent start, the AusweisApp2
51  is started in the background, without the installation wizard being shown. By
52  indicating ASSISTANT=false, the AusweisApp2 is started in the background without
53  the installation wizard from the outset. Not specified, the installation
54  wizard is activated (true).
55
56TRANSPORTPINREMINDER
57  Prior to the first authentication, the user is asked once whether they have
58  changed their Transport PIN. Setting TRANSPORTPINREMINDER=false deactivates this
59  reminder. Not specified, the reminder is activated (true).
60
61CUSTOMPROXYTYPE
62  Part of a proxy configuration. Valid values are SOCKS5 and HTTP.
63  All proxy parameters have to be set to use the proxy (see
64  CUSTOMPROXYHOST and CUSTOMPROXYPORT). You can disable the proxy after installation
65  with a checkbox in the settings.
66
67CUSTOMPROXYHOST
68  Part of a proxy configuration. Sets the Host of the proxy. All proxy parameters have
69  to be set to use the proxy (see CUSTOMPROXYTYPE and CUSTOMPROXYPORT).
70  You can disable the proxy after installation with a checkbox in the settings.
71
72CUSTOMPROXYPORT
73  Part of a proxy configuration. Sets the port of the proxy. Only values between
74  1 and 65536 are valid. All proxy parameters have to be set to use the proxy (see
75  CUSTOMPROXYTYPE and CUSTOMPROXYHOST). You can disable the proxy after installation
76  with a checkbox in the settings.
77
78UPDATECHECK
79  Upon opening the user interface of the AusweisApp2, an update check is started,
80  provided that at least 24 hours have elapsed since the last update check. If a
81  newer version is available, the user is notified accordingly. Setting
82  UPDATECHECK to false or true deactivates or activates the update check
83  respectively. Users are unable to change this setting in the AusweisApp2. Not
84  specified, the update check is activated, but users can adjust the settings.
85  The UPDATECHECK parameter affects neither updates of the service
86  provider list nor updates of card reader information.
87
88ONSCREENKEYBOARD
89  An on-screen keyboard is available to enter PIN, CAN or PUK. It is deactivated or
90  activated by setting ONSCREENKEYBOARD to false or true. Users are able to adjust
91  the setting.
92
93SHUFFLESCREENKEYBOARD
94  If the on-screen keyboard is activated, the number keys can be arranged at random.
95  By setting SHUFFLESCREENKEYBOARD to false or true, the random arrangement can be
96  deactivated or activated. Users are able to adjust the setting.
97
98HISTORY
99  Each authentication is saved in the history. No personal data is saved, only the
100  time of authentication, the provider and the selected fields (without
101  content). Indicating HISTORY as false or true, the history function is
102  deactivated or activated. Users are able to adjust the settings.
103
104ENABLECANALLOWED
105  Enables support for the CAN allowed mode. If the provider got issued a corresponding authorization
106  certificate the ID card can be read by entering the CAN instead of the PIN.
107
108SKIPRIGHTSONCANALLOWED
109  Skips the page with the authorization certificate in the CAN allowed mode and asks directly for
110  the CAN.
111
112LAUNCH
113  Starts the AusweisApp2 after the installation has finished.
114
115Alternatively, Orca [#orca]_ can be used to create an MST file that defines the
116above arguments. The arguments are available in the "Directory" and "Property"
117tables. The MST file can be transferred with the following command:
118
119.. code-block:: winbatch
120
121  msiexec /i AusweisApp2-X.YY.Z.msi /quiet TRANSFORMS=file.mst
122
123In order to optimize the start of the AusweisApp2 on systems with no graphics
124acceleration, the system variable "QT_QUICK_BACKEND" can be set to the value
125"software". In this case, the AusweisApp2 does not attempt to use graphics
126acceleration and starts directly with the alternative software renderer.
127
128macOS
129-----
130
131MacOS does not provide a command line installation. However, some of the above
132settings can be specified system-wide by a plist file in the
133/Library/Preferences directory. This plist file must be manually stored by the
134administrator of the system and will be used by all (future) installations of
135AusweisApp2. All not mentioned settings are not supported on macOS. The name of
136the file must be "com.governikus.AusweisApp2.plist". The content is shown below:
137
138.. code-block:: xml
139
140  <?xml version="1.0" encoding="UTF-8"?>
141  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
142  <plist version="1.0">
143  <dict>
144    <key>autoCloseWindow</key>
145    <false/>
146    <key>remindToClose</key>
147    <false/>
148    <key>showSetupAssistant</key>
149    <false/>
150    <key>transportPinReminder</key>
151    <false/>
152    <key>customProxyType</key>
153    <string>HTTP</string>
154    <key>customProxyHost</key>
155    <string>proxy.example.org</string>
156    <key>customProxyPort</key>
157    <integer>1337</integer>
158    <key>autoUpdateCheck</key>
159    <false/>
160    <key>keylessPassword</key>
161    <true/>
162    <key>shuffleScreenKeyboard</key>
163    <true/>
164    <key>history.enable</key>
165    <false/>
166    <key>enableCanAllowed</key>
167    <true/>
168    <key>skipRightsOnCanAllowed</key>
169    <true/>
170  </dict>
171  </plist>
172
173The description for each value is applicable for both Windows and macOS,
174although the naming of the attributes differs, as shown in the following table:
175
176======================= =======================
177macOS                   Windows
178======================= =======================
179autoCloseWindow         AUTOHIDE
180remindToClose           REMINDTOCLOSE
181showSetupAssistant      ASSISTANT
182transportPinReminder    TRANSPORTPINREMINDER
183customProxyType         CUSTOMPROXYTYPE
184customProxyPort         CUSTOMPROXYPORT
185customProxyHost         CUSTOMPROXYHOST
186autoUpdateCheck         UPDATECHECK
187keylessPassword         ONSCREENKEYBOARD
188shuffleScreenKeyboard   SHUFFLESCREENKEYBOARD
189history.enable          HISTORY
190enableCanAllowed        ENABLECANALLOWED
191skipRightsOnCanAllowed  SKIPRIGHTSONCANALLOWED
192======================= =======================
193
194It might be necessary to force a reload of the data cached by the operating
195system: :code:`killall -u $USER cfprefsd`
196
197.. [#msiexecreturnvalues] https://docs.microsoft.com/en-us/windows/desktop/msi/error-codes
198.. [#standardarguments] https://docs.microsoft.com/en-us/windows/desktop/msi/standard-installer-command-line-options
199.. [#orca] https://docs.microsoft.com/en-us/windows/desktop/Msi/orca-exe
200
201
202Operational Environment Requirements
203------------------------------------
204
205Required authorization for installation and execution
206'''''''''''''''''''''''''''''''''''''''''''''''''''''
207
208Administrator privileges are required to install the AusweisApp2.
209
210The execution of the AusweisApp2 does not require administrator privileges.
211
212Used network ports
213''''''''''''''''''
214
215All network ports used by the AusweisApp2 are listed in :numref:`porttable_en`.
216:numref:`communicationmodel_en` shows a schematic representation of the
217individual connections made by the AusweisApp2.
218
219The AusweisApp2 starts a HTTP-Server on port 24727.
220The server binds only to the localhost network interface.
221The availability of the local server is necessary for the online eID function,
222because providers will redirect the user with a HTTP redirect to the
223local server to continue the authentication process in the AusweisApp2 (eID1).
224The server is also used to offer other local applications to use the
225AusweisApp2 via a websocket interface (SDK function, eID-SDK).
226Therefore local incoming network connections to TCP Port 24727 must be
227permitted.
228
229Broadcast on UDP port 24727 in the local subnet have to be receivable by the
230AusweisApp2 to use the "Smartphone as Card Reader" functionality.
231It may be necessary to deactive AP isolation on your router.
232
233.. _communicationmodel_en:
234.. figure:: CommunicationModel_en.pdf
235
236    Communication model of the AusweisApp2
237
238The installer of the AusweisApp2 provides an option to register all needed
239firewall rules in the Windows Firewall.
240If the rules are not registered, the user will be prompted by the Windows
241Firewall to allow the outgoing connections once the AusweisApp2 tries to
242connect to a server.
243These prompts are suppressed by registering the firewall rules during
244installation.
245No rules have to be added to the Windows Firewall for the local connections
246eID1 and eID-SDK  (when using the standard settings).
247
248In table :numref:`firewalltable_en` all firewall rules registered by the
249installer are listed.
250
251TLS connections
252'''''''''''''''
253
254Transmitted TLS certificates are solely validated via the interlacing with
255the authorization certificate issued by the german eID PKI.
256CA certificates in the Windows truststore are thus ignored.
257It is therefore generally not possible to use the AusweisApp2 behind a
258TLS termination proxy.
259
260.. raw:: latex
261
262    \begin{landscape}
263
264.. _porttable_en:
265.. csv-table:: Network connections of the AusweisApp2
266   :header: "Reference", "Protocol", "Port", "Direction", "Optional", "Purpose", "Note"
267   :widths: 8, 8, 8, 8, 8, 35, 25
268
269   "eID1",	TCP, 24727,  "incoming", "no",	"Online eID function, eID activation [#TR-03124]_",											    "Only accessible from localhost [#TR-03124]_"
270   "eID2",	TCP, 443,    "outgoing", "no",	"Online eID function, connection to the provider, TLS-1-2 channel [#TR-03124]_",						    "TLS certificates interlaced with authorization certificate [#TR-03124]_"
271   "eID3",	TCP, 443,    "outgoing", "no",	"Online eID function, connection to eID-Server, TLS-2 channel [#TR-03124]_",								    "TLS certificates interlaced with authorization certificate [#TR-03124]_"
272   "eID-SDK",	TCP, 24727,  "incoming", "no",	"Usage of the SDK functionality",													    "Only accessible from localhost [#TR-03124]_"
273   "SaC1",	UDP, 24727,  "incoming", "yes",	"Smartphone as Card Reader, detection [#TR-03112]_",											    "Broadcasts"
274   "SaC2",	TCP, ,       "outgoing", "yes",	"Smartphone as Card Reader, usage [#TR-03112]_",											    "Connection in local subnet"
275   "Update",	TCP, 443,    "outgoing", "yes",	"Updates [#govurl]_ of provider and card reader information as well as informations on new AusweisApp2 versions [#updatecheck]_ .", "TLS certificates will be validated against CA certificates included in the AusweisApp2. CA certificates provided by the OS are ignored."
276
277.. [#TR-03124] See TR-03124 specification from the BSI
278.. [#TR-03112] See TR-03112-6 specifiaction from the BSI
279.. [#govurl] All updates are based on the URL https://appl.governikus-asp.de/ausweisapp2/
280.. [#updatecheck] Automatic checks for new AusweisApp2 versions can be deactivated, see commandline parameter
281    UPDATECHECK.
282
283.. _firewalltable_en:
284.. csv-table:: Firewall rules of the AusweisApp2
285   :header: "Name", "Protocol", "Port", "Direction", "Connection reference"
286   :widths: 25, 15, 15, 15, 30
287   :align: left
288
289   "AusweisApp2-Firewall-Rule", TCP, \*, "outgoing", "eID2, eID3, SaC2, Update"
290   "AusweisApp2-SaC", UDP, 24727, "incoming", "SaC1"
291
292.. raw:: latex
293
294    \end{landscape}
295