WorkflowController API

This section describes the API of the WorkflowController class. You should not create your own instance of the WorkflowController but use the static member of the SDKWrapper class instead.

import de.governikus.ausweisapp2.sdkwrapper.SDKWrapper.workflowController

import AusweisApp2SDKWrapper

let workflowController = AA2SDKWrapper.workflowController

isStarted

Indicates that the WorkflowController is ready to be used. When the WorkflowController is not in started state other API calls will fail.

val isStarted: Boolean

public var isStarted: Bool

start

Initialize the WorkflowController.

Before it is possible to use the WorkflowController it needs to be initialized. Make sure to call this function and wait for the onStarted callback before using it.

Note

Android only.

context: Android Context in which the WorkflowController lives.

fun start(context: Context)

public func start()

stop

Stop the WorkflowController.

When you no longer need the WorkflowController make sure to stop it to free up some resources.

fun stop()

public func stop()

registerCallbacks

Register callbacks with controller. See WorkflowController callbacks for more information about callbacks.

callbacks: Callbacks to register.

fun registerCallbacks(callbacks: WorkflowCallbacks)

public func registerCallbacks(_ callbacks: WorkflowCallbacks)

unregisterCallbacks

Unregister callback from controller.

callbacks: Callbacks to unregister.

fun unregisterCallbacks(callbacks: WorkflowCallbacks)

public func unregisterCallbacks(_ callbacks: WorkflowCallbacks)

startAuthentication

Starts an authentication workflow. This implements the command RUN_AUTH of the AusweisApp SDK.

The WorkflowController will call onAuthenticationStarted, when the authentication is started. If the authentication could not be started, you will get a callback to onAuthenticationStartFailed.

After calling this method, the expected minimal workflow is:

onAuthenticationStarted is called.
When onAccessRights is called, accept it via accept.
onInsertCard is called, when the user has not yet placed the phone on the card.
When onEnterPin is called, provide the PIN via setPin.
When the authentication workflow is finished onAuthenticationCompleted is called.

This command is allowed only if the SDK has no running workflow. Otherwise you will get a callback to onBadState.

tcTokenURL: URL to the TcToken of the eID service provider you want to authenticate against.
developerMode: Enable “Developer Mode” for test cards and disable some security checks according to BSI TR-03124-1.
status: True to enable automatic STATUS messages, which are delivered by callbacks to onStatus.

Note

iOS only.

userInfoMessages: Messages for the NFC system dialog. See AA2UserInfoMessages.

fun startAuthentication(
  tcTokenUrl: Uri,
  developerMode: Boolean = false,
  status: Boolean = true)

public func startAuthentication(
  withTcTokenUrl tcTokenUrl: URL,
  withDeveloperMode developerMode: Bool = false,
  withUserInfoMessages userInfoMessages: AA2UserInfoMessages? = nil,
  withStatusMsgEnabled status: Bool = true)

startChangePin

Start a PIN change workflow. This implements the command RUN_CHANGE_PIN of the AusweisApp SDK.

The WorkflowController will call onChangePinStarted, when the PIN change is started.

After calling this method, the expected minimal workflow is:

onChangePinStarted is called.
onInsertCard is called, when the user has not yet placed the card on the reader.
When onEnterPin is called, provide the PIN via setPin.
When onEnterNewPin is called, provide the new PIN via setNewPin.
When the PIN workflow is finished, onChangePinCompleted is called.

This command is allowed only if the SDK has no running workflow. Otherwise you will get a callback to onBadState.

status: True to enable automatic STATUS messages, which are delivered by callbacks to onStatus.

Note

iOS only.

userInfoMessages: Messages for the NFC system dialog. See AA2UserInfoMessages.

fun startChangePin(status: Boolean = true)

public func startChangePin(
  withUserInfoMessages userInfoMessages: AA2UserInfoMessages? = nil,
  withStatusMsgEnabled status: Bool = true)

setAccessRights

Set optional access rights. This implements the command SET_ACCESS_RIGHTS of the AusweisApp SDK.

If the SDK Wrapper asks for specific access rights in onAccessRights, you may modify the requested optional rights by setting a list of accepted optional rights here. When the command is successful you get a callback to onAccessRights with the updated access rights.

List of possible access rights are listed in AccessRight

This command is allowed only if the SDK Wrapper asked for access rights via onAccessRights. Otherwise you will get a callback to onBadState.

optionalAccessRights: List of enabled optional access rights. If the list is empty all optional access rights are disabled. See section AccessRight.

fun setAccessRights(optionalAccessRights: List<AccessRight>)

public func setAccessRights(_ optionalAccessRights: [AccessRight])

getAccessRights

Returns information about the requested access rights.

This implements the command GET_ACCESS_RIGHTS of the AusweisApp SDK.

Note

This command is allowed only if the SDK Wrapper called onAccessRights beforehand.

fun getAccessRights()

public func getAccessRights()

interrupt

Allows to interrupt the iOS NFC Dialog. This implements the command INTERRUPT of the AusweisApp SDK.

Your application may want to suppress the iOS NFC Dialog to display some UI elements to the user. The command is only permitted after being asked for PIN/CAN/PUK. The SDK will restart the iOS NFC scan as needed.

public func interrupt()

setPin

Set PIN of inserted card. This implements the command SET_PIN of the AusweisApp SDK.

If the SDK Wrapper calls onEnterPin you need to allow access to the card with the given PIN.

If your application provides an invalid PIN the SDK Wrapper will call onEnterPin again with a decreased Card.retryCounter.

If the value of Card.retryCounter is 1 the SDK will initially call onEnterCan. Once your application provides a correct CAN the SDK Wrapper will call onEnterPin again with a Card.retryCounter of 1. If the value of Card.retryCounter is 0 the SDK will initially call onEnterPuk. Once your application provides a correct PUK the SDK Wrapper will call onEnterPin again with a Card.retryCounter of 3.

This command is allowed only if the SDK Wrapper asked for a PIN via onEnterPin. Otherwise you will get a callback to onBadState.

pin: The Personal Identification Number (PIN) of the card. This must be 6 digits in an authentication workflow. If a pin change workflow is in progress the value must be 5 or 6 digits because of a possible transport PIN. Must be nil if the current reader has a keypad. See Reader.

fun setPin(pin: String?)

public func setPin(_ pin: String?)

setNewPin

Set new PIN for inserted card. This implements the command SET_NEW_PIN of the AusweisApp SDK.

If the SDK Wrapper calls onEnterNewPin you need to call this function to provide a new pin.

This command is allowed only if the SDK Wrapper asked for a new PIN via onEnterNewPin. Otherwise you will get a callback to onBadState.

newPin: The new personal identification number (PIN) of the card. Must only contain 6 digits. Must be nil if the current reader has a keypad. See Reader.

fun setNewPin(newPin: String?)

public func setNewPin(_ newPin: String?)

setPuk

Set PUK of inserted card. This implements the command SET_PUK of the AusweisApp SDK.

If the SDK Wrapper calls onEnterPuk you need to call this function to unblock setPin.

The workflow will automatically continue if the PUK was correct and the SDK Wrapper will call onEnterPin. If the correct PUK is entered the retryCounter will be set to 3.

If your application provides an invalid PUK the SDK Wrapper will call onEnterPuk again.

If the SDK Wrapper calls onEnterPuk with Card.inoperative set true it is not possible to unblock the PIN. You will have to show a message to the user that the card is inoperative and the user should contact the authority responsible for issuing the identification card to unblock the PIN.

This command is allowed only if the SDK Wrapper asked for a PUK via onEnterPuk. Otherwise you will get a callback to onBadState.

puk: The personal unblocking key (PUK) of the card. Must only contain 10 digits. Must be nil if the current reader has a keypad. See Reader.

fun setPuk(puk: String?)

public func setPuk(_ puk: String?)

setCan

Set CAN of inserted card. This implements the command SET_CAN of the AusweisApp SDK.

If the SDK Wrapper calls onEnterCan you need to call this function to unblock the last retry of setPin.

The CAN is required to enable the last attempt of PIN input if the retryCounter is 1. The workflow continues automatically with the correct CAN and the SDK Wrapper will call onEnterPin. Despite the correct CAN being entered, the retryCounter remains at 1. The CAN is also required, if the authentication terminal has an approved CAN-allowed right. This allows the workflow to continue without an additional PIN.

If your application provides an invalid CAN the SDK Wrapper will call onEnterCan again.

This command is allowed only if the SDK Wrapper asked for a CAN via onEnterCan. Otherwise you will get a callback to onBadState.

can: The card access number (CAN) of the card. Must only contain 6 digits. Must be nil if the current reader has a keypad. See Reader.

fun setCan(can: String?)

public func setCan(_ can: String?)

accept

Accept the current state. This implements the command ACCEPT of the AusweisApp SDK.

If the SDK Wrapper calls onAccessRights the user needs to accept or deny them. The workflow is paused until your application sends this command to accept the requested information. If the user does not accept the requested information your application needs to call cancel to abort the whole workflow.

This command is allowed only if the SDK Wrapper asked for access rights via onAccessRights. Otherwise you will get a callback to onBadState.

Note: This accepts the requested access rights as well as the provider’s certificate since it is not possible to accept one without the other.

fun accept()

public func accept()

cancel

Cancel the running workflow. This implements the command CANCEL of the AusweisApp SDK.

If your application sends this command the SDK will cancel the workflow. You may send this command in any state of a running workflow to abort it.

fun cancel()

public func cancel()

continueWorkflow

Resumes the workflow after a callback to onPause. This implements the command CONTINUE of the AusweisApp SDK.

fun continueWorkflow()

public func continueWorkflow()

getCertificate

Request the certificate of current authentication. This implements the command GET_CERTIFICATE of the AusweisApp SDK.

The SDK Wrapper will call onCertificate as an answer.

fun getCertificate()

public func getCertificate()

setCard

Insert “virtual” card.

name: Name of reader with a Card that shall be used.
simulator: Optional specific Filesystem data for Simulator reader. See Simulator.

fun setCard(name: String, simulator: Simulator? = nil)

public func setCard(name: String, simulator: Simulator? = nil)

getStatus

Request information about the current workflow and state of SDK. This implements the command GET_STATUS of the AusweisApp SDK.

The SDK Wrapper will call onStatus as an answer.

fun getStatus()

public func getStatus()

getInfo

Provides information about the employed AusweisApp. This implements the command GET_INFO of the AusweisApp SDK.

The SDK Wrapper will call WorkflowCallbacks.onInfo() as an answer.

fun getInfo()

public func getInfo()

getReader

Returns information about the requested reader. This implements the command GET_READER of the AusweisApp SDK.

If you explicitly want to ask for information of a known reader name you can request it with this command.

The SDK Wrapper will call onReader as an answer.

name: Name of the reader.

fun getReader(name: String)

public func getReader(name: String)

getReaderList

Returns information about all connected readers. This implements the command GET_READER_LIST of the AusweisApp SDK.

If you explicitly want to ask for information of all connected readers you can request it with this command.

The SDK Wrapper will call onReaderList as an answer.

fun getReaderList()

public func getReaderList()

onNfcTagDetected

Android only

Pass a detected NFC tag to the WorkflowController

Since only a foreground application can detect NFC tags, you need to pass them to the SDK for it to handle detected ID cards.

See Passing NFC tags to the WorkflowController on Android

tag: Detected ID card. ISO-DEP (ISO 14443-4) NFC tag

fun onNfcTagDetected(tag: Tag)