Dispatch Target Management

caution

Dispatch target management is currently considered as an experimental feature. The implementation and public interfaces are likely to change in the future.

Description

Dispatch targets serve as receivers of out-of-band messages, as described in Out-of-Band Message Transmission. Dispatch target management deals with the administration and maintenance of such message receivers. The concept of dispatch targets is not part of the FIDO UAF specification but represents a Nevis proprietary concept. As dispatch targets only play a role in out-of-band scenarios, the whole concept can be disregarded in in-band only scenarios.

Dispatch target management is important for any Nevis Mobile Authentication client application that contains a FIDO UAF client and wants to be able to receive and handle out-of-band messages. The client application is responsible for administering the dispatch target represented by the application or the corresponding device. Administering dispatch targets includes the creation, modification as well as eventual deletion of dispatch targets.

If the dispatching takes place in the form of (mobile) push messages, the mobile client application is responsible for:

1. Registering itself as a dispatch target with the Nevis Mobile Authentication backend.
2. Updating the dispatch target information in the backend upon change (for example, if the push identifier on the mobile device changes).
3. Removing the dispatch target information upon deregistration.

As dispatch target management is independent of the UAF protocol, the responsible user must not have active UAF credentials or authenticators present when managing dispatch targets.

info

Note that the QR codes used in Nevis Mobile Authentication flows have no relation to dispatch targets (although technically QR codes could be considered as an out-of-band channel).

Prerequisites

• The user owns a device that is able to serve as dispatch target. Such a device could be, for example, a smartphone.
• The relying party mobile client application is able to generate additional key material, for encrypting the dispatch channel and certifying dispatch target updates.
• Nevis is configured to allow out-of-band dispatching of Nevis Mobile Authentication messages (see "Nevis Component Configuration Examples").

The following examples assumes the usage of push message dispatching to the Nevis Mobile Authentication client application.

Examples

Dispatch Target Registration

The numbers in the description below correspond with the numbers in the next figure.

1. The user performs and completes an in-band registration.
2. The mobile application creates two certificates:
   • One certificate is for decrypting the encrypted dispatch message.
   • Another certificate is for signing future updates regarding the dispatch target information.
3. The mobile application registers itself or the corresponding device as a dispatch target with the backend. Additionally, the application sends the public keys of the certificates generated in step 2.

Technical Flow

The technical flow in the next figure explains the component interaction in detail. The step numbers in the figure do not correlate with the simplified example above.

A client application must authenticate itself before it can access the (protected) Create Dispatch Target endpoint. But the client application must also be able to update dispatch target information at any given point in time, without the need for explicit user authentication. To support both scenarios, Nevis uses signature keys for the verification of the client against the backend - authentication credentials of the user are not required. This concept is necessary because third party push providers may change the push identifier of the mobile device/application at anytime during the life cycle of an application. An example of a third party push provider is Google Firebase Cloud Messaging.

The following table describes the steps in the previous figure. The numbers in the table correlate with the step numbers in the previous figure.

Nr.	Description	Endpoint	References
1.	The client application generates signature keys. These keys will be used to access the Update Dispatch Target endpoint, by signing the payload with the private key.	-	-
2.	The client generates encryption keys. These keys will be used to decrypt encrypted out-of-band messages.	-	-
3.	The client posts the dispatch target information to the Nevis backend. nevisProxy forwards the request to nevisFIDO. The signature and encryption public keys are part of the payload.The Create Dispatch Target endpoint requires authentication. Currently, this is done by executing an in-band authentication. For more information, see In-Band AuthenticationnevisFIDO Reference Guide:- Chapter "Dispatch Target Service"
4.	nevisFIDO stores the dispatch target in nevisIDM.	-	- Out-of-band dispatching data model
5.	nevisFIDO informs the client about the successful creation of the dispatch target.	-	-

Dispatch Target Modification

The numbers in the description below correspond with the numbers in the next figure.

1. The push identifier of the mobile phone/application changes. The mobile application is informed about the change.
2. The mobile application updates the dispatch target information on the Nevis backend.

Technical Flow

The technical flow in the next figure explains the component interaction in detail. The step numbers in the figure do not correlate with the simplified example above.

Dispatch target modification uses a special concept regarding endpoint protection and authentication, as previously outlined. The authentication is done with JWS (JSON Web Signature). The JSON payload is signed with the client's private key, whereas the verification of the payload happens with the client's public key stored in the backend. This makes it possible to update dispatch target information at any given point in time (even whilst running in the background) without any user interaction.

caution

Using JWS (JSON Web Signature) to verify a client means that the HTTP PATCH operation on the specific dispatch target endpoint is not protected by nevisAuth and is accessible without prior authentication!

For more information on JWS, see "`http://tools.ietf.org/html/rfc7515".

The following table describes the steps in the previous figure. The numbers in the table correlate with the step numbers in the previous figure.

Nr.	Description	Endpoint	References
1.	The client creates a JSON structure containing the changed data.	-	- Out-of-Band Message Transmission
2.	The client signs the structure using the locally stored signature private key.	-
3.	The client sends the JSON as payload to the Nevis backend. nevisProxy forwards the request to nevisFIDO.The backend expects the payload to be signed using JWS compact serialisation. For details, refer to RFC 7515: https://tools.ietf.org/html/rfc7515#section-4.1.9.	https://<nevisProxy-host>:<nevisProxy-port>/nevisfido/dispatch/targets/<id>	nevisFIDO Reference Guide:- Chapter "Dispatch Target Service"
4.	nevisFIDO loads the dispatch target information based on the dispatch target ID.	-	-
5.	nevisFIDO uses the signature public key to verify that the payload was signed by the correct mobile client.	-	-
6.	If the verification was successful, nevisFIDO updates the information in nevisIDM.	-	-
7.	The result of the operation is reported back to the client.	-	-

Dispatch Target Deletion

The numbers in the description below correspond with the numbers in the next figure.

1. The user starts the Deregistration process on the mobile device.
2. The mobile application removes the current device as dispatch target.
3. The mobile application performs the UAF credential Deregistration. For more information, see FIDO UAF Credential Deregistration.

caution

The deletion operation described in this section only affects the dispatch targets. The registered FIDO UAF credentials will stay in place and are not removed. To remove the registered FIDO UAF credentials, perform a Deregistration operation. Refer to the chapter FIDO UAF Credential Deregistration for additional details.

To find the FIDO UAF credentials that are associated with the dispatch target, you can use the deviceId attribute. The dispatch targets and FIDO UAF credentials that have the same deviceId value are stored on the same device. So if you want to remove all dispatch targets and corresponding FIDO UAF credentials on a given device, remove all elements with the same deviceId.
For details, see the nevisFIDO Reference Guide, sections "Registration Response Service"/"Request Body" and "Dispatch Target Service"/"Request Body".

Technical Flow

The technical flow in the next figure explains the component interaction in detail. The step numbers in the figure do not correlate with the simplified example above.

Dispatch target deletion is an important step in deregistration scenarios. As described in FIDO UAF Credential Deregistration, there is no direct relation between dispatch targets and UAF credentials. This means that the respective mobile client application must fully support and handle the deregistration procedure.

The following is only relevant if FIDO UAF authentication is used to protect the Delete Dispatch Target endpoint: As deleting dispatch targets requires authentication, the dispatch target deregistration must take place before the last authenticator has been removed from the client application. This impacts the complexity of the implementation on the client side: The client must be aware of its currently registered authenticators.

The following table describes the steps in the previous figure. The numbers in the table correlate with the step numbers in the previous figure.

Nr.	Description	Endpoint	References
1.	The client calls the Delete Dispatch Target endpoint with the HTTP DELETE method. nevisProxy forwards the request to nevisFIDO.The Delete Dispatch Target endpoint requires authentication. Currently, this happens by executing an in-band authentication. For more information, see In-Band AuthenticationnevisFIDO Reference Guide:- Chapter "Dispatch Target Service"	".	-
2.	nevisFIDO deletes the dispatch target in nevisIDM identified. The target-to-be-deleted is identified by its ID.	-	-
3.	nevisFIDO informs the client about the result of the operation.When the dispatch target deletion was successful, the client can proceed with the deregistration of its authenticators.	-	- FIDO UAF Credential Deregistration

Configuration Snippets

Refer to Nevis Component Configuration Examples for sample configuration snippets regarding all involved components.

In the configuration examples, it is assumed that the dispatch target endpoints are protected by using FIDO UAF in-band authentication.