Desktop
This chapter deals with the desktop specific properties of the AusweisApp2 SDK. The AusweisApp2 core is reachable over a WebSocket which is running by default since AusweisApp2 1.16.0. Subsequent sections deal with the SDK interface itself and explain which steps are necessary in order to talk to the AusweisApp2 SDK.
WebSocket
The AusweisApp2 uses the same default port as defined in TR-03124-1.
Your application can connect to ws://localhost:24727/eID-Kernel
to
establish a bidirectional connection.
You can check the version of AusweisApp2 by the Server
header of the HTTP
response or by an additional query to get the Status.
If the WebSocket handshake was succesful your application can send Commands and receive Messages. The AusweisApp2 will send an HTTP error 503 “Service Unavailable” if the WebSocket is disabled.
See also
User installed
Your application can connect to a user installed AusweisApp2. If the user already has an active workflow your request will be refused by an HTTP error 409 “Conflict”. Also it is not possible to connect multiple times to the WebSocket as only one connection is allowed and will be refused by an HTTP error 429 “Too Many Requests”. Once an application is connected to the WebSocket the graphical user interface of the AusweisApp2 will be blocked and shows a hint that another application uses the AusweisApp2.
Important
Please provide a User-Agent
in your HTTP upgrade request! The AusweisApp2
will show the content to the user as a hint which application uses the AusweisApp2.
Integrated
You can deliver separate AusweisApp2 binaries inside your own application or
start an already installed AusweisApp2.
If your application spawns a separate process you should provide the cmdline
parameter --port 0
to avoid conflicts with a user started AusweisApp2 and
other processes that uses a specified port.
The AusweisApp2 will create a text file in the system temporary directory to provide the selected port. The port filename contains the PID of the running process to allow multiple instances at the same time.
Example: $TMPDIR/AusweisApp2.12345.port
Your application can avoid the graphical interface of AusweisApp2 by providing the
cmdline parameter --ui websocket
.
Status
TR-03124-1 defined a query for status information. This is useful to fetch current version of installed AusweisApp2 to check if the version supports the WebSocket-API.
You can get this by a HTTP GET query to http://localhost:24727/eID-Client?Status
.
If you prefer the JSON syntax you can add it to the parameter ?Status=json
to get
the following information.
{
"Implementation-Title": "AusweisApp2",
"Implementation-Vendor": "Governikus GmbH & Co. KG",
"Implementation-Version": "1.16.0",
"Name": "AusweisApp2",
"Specification-Title": "TR-03124",
"Specification-Vendor": "Federal Office for Information Security",
"Specification-Version": "1.3"
}
Reader
The AusweisApp2 SDK uses PC/SC and paired Smartphones as card reader. If the user wants to use the “smartphone as card reader” feature it is necessary to pair the devices by the graphical interface of AusweisApp2. The AusweisApp2 SDK provides no API to pair those devices.