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