236 lines
10 KiB
ReStructuredText
236 lines
10 KiB
ReStructuredText
English
|
|
=======
|
|
|
|
Windows
|
|
-------
|
|
|
|
Start the installer of AusweisApp2 using the command line to configure the
|
|
installation process and preset system-wide default settings.
|
|
The return value of msiexec indicates the result of the installation [#msiexecreturnvalues]_.
|
|
In addition to the usual arguments [#standardarguments]_, the following command
|
|
contains all supported arguments, which are explained below.
|
|
|
|
.. code-block:: winbatch
|
|
|
|
msiexec /i AusweisApp2-X.YY.Z.msi /quiet INSTALL_ROOT="C:\AusweisApp2" SYSTEMSETTINGS=false DESKTOPSHORTCUT=false AUTOSTART=false AUTOHIDE=false REMINDTOCLOSE=false ASSISTANT=false TRANSPORTPINREMINDER=false UPDATECHECK=false ONSCREENKEYBOARD=true HISTORY=false
|
|
|
|
INSTALL_ROOT
|
|
States the installation directory. If not specified, the folder
|
|
"C:\\Program Files (x86)\\AusweisApp2" is used.
|
|
|
|
SYSTEMSETTINGS
|
|
Concerns the settings of firewall rules of the Windows Firewall. When not
|
|
specifying the argument, firewall rules are created (true). By indicating
|
|
SYSTEMSETTINGS=false, no firewall rules are created.
|
|
|
|
DESKTOPSHORTCUT
|
|
By specifying DESKTOPSHORTCUT=false, no desktop shortcut is created. Without
|
|
specifying the argument, the desktop shortcut is created for all users (true).
|
|
|
|
AUTOSTART
|
|
Setting AUTOSTART=true creates autostart entry for all users. Users are unable
|
|
to deactivate the autostart function in the AusweisApp2. Not specified, no
|
|
autostart entry is created (false). In that case, users are able to activate the
|
|
autostart function in the AusweisApp2.
|
|
|
|
AUTOHIDE
|
|
Concerns the automatic minimization after a successful authentication. Not
|
|
specified, it is activated (true). Setting AUTOHIDE=false, it is deactivated.
|
|
Users can adjust this setting to their preferences.
|
|
|
|
REMINDTOCLOSE
|
|
Closing the AusweisApp2 by clicking on the X, the user is notified that only the
|
|
user interface is closed and that the AusweisApp2 is still available in the info
|
|
tray. At this point, it is possible to prevent future notifications. Setting
|
|
REMINDTOCLOSE=false deactivates this notification from the outset. Not
|
|
specified, it is activated (true).
|
|
|
|
ASSISTANT
|
|
Starting the AusweisApp2 for the first time, the user interface is displayed and
|
|
the installation wizard is shown. With each subsequent start, the AusweisApp2
|
|
is started in the background, without the installation wizard being shown. By
|
|
indicating ASSISTANT=false, the AusweisApp2 is started in the background without
|
|
the installation wizard from the outset. Not specified, the installation
|
|
wizard is activated (true).
|
|
|
|
TRANSPORTPINREMINDER
|
|
Prior to the first authentication, the user is asked once whether they have
|
|
changed their transport PIN. Setting TRANSPORTPINREMINDER=false deactivates this
|
|
reminder. Not specified, the reminder is activated (true).
|
|
|
|
UPDATECHECK
|
|
Upon opening the user interface of the AusweisApp2, an update check is started,
|
|
provided that at least 24 hours have elapsed since the last update check. If a
|
|
newer version is available, the user is notified accordingly. Setting
|
|
UPDATECHECK to false or true deactivates or activates the update check
|
|
respectively. Users are unable to change this setting in the AusweisApp2. Not
|
|
specified, the update check is activated, but users can adjust the settings.
|
|
The UPDATECHECK parameter affects neither updates of the service
|
|
provider list nor updates of card reader information.
|
|
|
|
ONSCREENKEYBOARD
|
|
An on-screen keyboard is available to enter PIN, CAN or PUK. It is deactivated or
|
|
activated by setting ONSCREENKEYBOARD to false or true. Users are able to adjust
|
|
the settings.
|
|
|
|
HISTORY
|
|
Each authentication is saved in the history. No personal data is saved, only the
|
|
time of authentication, the service provider and the selected fields (without
|
|
content). Indicating HISTORY as false or true, the history function is
|
|
deactivated or activated. Users are able to adjust the settings.
|
|
|
|
Alternatively, Orca [#orca]_ can be used to create an MST file that defines the
|
|
above arguments. The arguments are available in the "Directory" and "Property"
|
|
tables. The MST file can be transferred with the following command:
|
|
|
|
.. code-block:: winbatch
|
|
|
|
msiexec /i AusweisApp2-X.YY.Z.msi /quiet TRANSFORMS=file.mst
|
|
|
|
macOS
|
|
-----
|
|
|
|
MacOS does not provide a command line installation. However, some of the above
|
|
settings can be specified system-wide by a plist file in the
|
|
/Library/Preferences directory. This plist file must be manually stored by the
|
|
administrator of the system and will be used by all (future) installations of
|
|
AusweisApp2. All not mentioned settings are not supported on macOS. The name of
|
|
the file must be "com.governikus.AusweisApp2.plist". The content is shown below:
|
|
|
|
.. code-block:: xml
|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
<plist version="1.0">
|
|
<dict>
|
|
<key>autoCloseWindow</key>
|
|
<false/>
|
|
<key>remindToClose</key>
|
|
<false/>
|
|
<key>showSetupAssistant</key>
|
|
<false/>
|
|
<key>transportPinReminder</key>
|
|
<false/>
|
|
<key>common.autoUpdateCheck</key>
|
|
<false/>
|
|
<key>common.keylessPassword</key>
|
|
<true/>
|
|
<key>history.enable</key>
|
|
<false/>
|
|
</dict>
|
|
</plist>
|
|
|
|
The description for each value is applicable for both Windows and macOS,
|
|
although the naming of the attributes differs, as shown in the following table:
|
|
|
|
====================== ====================
|
|
macOS Windows
|
|
====================== ====================
|
|
autoCloseWindow AUTOHIDE
|
|
remindToClose REMINDTOCLOSE
|
|
showSetupAssistant ASSISTANT
|
|
transportPinReminder TRANSPORTPINREMINDER
|
|
common.autoUpdateCheck UPDATECHECK
|
|
common.keylessPassword ONSCREENKEYBOARD
|
|
history.enable HISTORY
|
|
====================== ====================
|
|
|
|
.. [#msiexecreturnvalues] https://docs.microsoft.com/en-us/windows/desktop/msi/error-codes
|
|
.. [#standardarguments] https://docs.microsoft.com/en-us/windows/desktop/msi/standard-installer-command-line-options
|
|
.. [#orca] https://docs.microsoft.com/en-us/windows/desktop/Msi/orca-exe
|
|
|
|
|
|
Operational Environment Requirements
|
|
------------------------------------
|
|
|
|
Required authorization for installation and execution
|
|
'''''''''''''''''''''''''''''''''''''''''''''''''''''
|
|
|
|
Administrator privileges are required to install the AusweisApp2.
|
|
|
|
The execution of the AusweisApp2 does not require administrator privileges.
|
|
|
|
Used network ports
|
|
''''''''''''''''''
|
|
|
|
All network ports used by the AusweisApp2 are listed in :numref:`porttable_en`.
|
|
:numref:`communicationmodel_en` shows a schematic representation of the
|
|
individual connections made by the AusweisApp2.
|
|
|
|
The AusweisApp2 starts a HTTP-Server on port 24727.
|
|
The server binds only to the localhost network interface.
|
|
The availability of the local server is necessary for the online eID function,
|
|
because service providers will redirect the user with a HTTP redirect to the
|
|
local server to continue the authentication process in the AusweisApp2 (eID1).
|
|
The server is also used to offer other local applications to use the
|
|
AusweisApp2 via a websocket interface (SDK function, eID-SDK).
|
|
Therefore local incoming network connections to TCP Port 24727 must be
|
|
permitted.
|
|
|
|
Broadcast on UDP port 24727 in the local subnet have to be receivable by the
|
|
AusweisApp2 to use the "Smartphone as Card Reader" functionality.
|
|
It may be necessary to deactive AP isolation on your router.
|
|
|
|
.. _communicationmodel_en:
|
|
.. figure:: CommunicationModel_en.pdf
|
|
|
|
Communication model of the AusweisApp2
|
|
|
|
The installer of the AusweisApp2 provides an option to register all needed
|
|
firewall rules in the Windows Firewall.
|
|
If the rules are not registered, the user will be prompted by the Windows
|
|
Firewall to allow the outgoing connections once the AusweisApp2 tries to
|
|
connect to a server.
|
|
These prompts are suppressed by registering the firewall rules during
|
|
installation.
|
|
No rules have to be added to the Windows Firewall for the local connections
|
|
eID1 and eID-SDK (when using the standard settings).
|
|
|
|
In table :numref:`firewalltable_en` all firewall rules registered by the
|
|
installer are listed.
|
|
|
|
TLS connections
|
|
'''''''''''''''
|
|
|
|
Transmitted TLS certificates are solely validated via the interlacing with
|
|
the authorization certificate issued by the german eID PKI.
|
|
CA certificates in the Windows truststore are thus ignored.
|
|
It is therefore generally not possible to use the AusweisApp2 behind a
|
|
TLS termination proxy.
|
|
|
|
.. raw:: latex
|
|
|
|
\begin{landscape}
|
|
|
|
.. _porttable_en:
|
|
.. csv-table:: Network connections of the AusweisApp2
|
|
:header: "Reference", "Protocol", "Port", "Direction", "Optional", "Purpose", "Note"
|
|
:widths: 8, 8, 8, 8, 8, 35, 25
|
|
|
|
"eID1", TCP, 24727, "incoming", "no", "Online eID function, eID activation [#TR-03124]_", "Only accessible from localhost [#TR-03124]_"
|
|
"eID2", TCP, 443, "outgoing", "no", "Online eID function, connection to the service provider, TLS-1-2 channel [#TR-03124]_", "TLS certificates interlaced with authorization certificate [#TR-03124]_"
|
|
"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]_"
|
|
"eID-SDK", TCP, 24727, "incoming", "no", "Usage of the SDK functionality", "Only accessible from localhost [#TR-03124]_"
|
|
"SaC1", UDP, 24727, "incoming", "yes", "Smartphone as Card Reader, detection [#TR-03112]_", "Broadcasts"
|
|
"SaC2", TCP, , "outgoing", "yes", "Smartphone as Card Reader, usage [#TR-03112]_", "Connection in local subnet"
|
|
"Update", TCP, 443, "outgoing", "yes", "Updates [#govurl]_ of service 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."
|
|
|
|
.. [#TR-03124] See TR-03124 specification from the BSI
|
|
.. [#TR-03112] See TR-03112-6 specifiaction from the BSI
|
|
.. [#govurl] All updates are based on the URL https://appl.governikus-asp.de/ausweisapp2/
|
|
.. [#updatecheck] Automatic checks for new AusweisApp2 versions can be deactivated, see commandline parameter
|
|
UPDATECHECK.
|
|
|
|
.. _firewalltable_en:
|
|
.. csv-table:: Firewall rules of the AusweisApp2
|
|
:header: "Name", "Protocol", "Port", "Direction", "Connection reference"
|
|
:widths: 25, 15, 15, 15, 30
|
|
:align: left
|
|
|
|
"AusweisApp2-Firewall-Rule", TCP, \*, "outgoing", "eID2, eID3, SaC2, Update"
|
|
"AusweisApp2-Firewall-Rule-SaC-In", UDP, 24727, "incoming", "SaC1"
|
|
|
|
.. raw:: latex
|
|
|
|
\end{landscape}
|