Device Service
This chapter describes the Device Service. The Device Service is not a standard FIDO service, but a proprietary nevisFIDO functionality.
The Device Service is an HTTP API to be used by the Nevis Mobile Authentication SDK, so it is aimed for mobile applications. Other applications, such as administration web applications, should not try to use it. It is presented here for reference.
This service is in experimental state and can be modified or dropped in future releases without notice.
A device represents a mobile device. A mobile device has FIDO UAF credentials and dispatch targets. The Authentication Mobile SDK allows the definition of multiple accounts in a device and thus the FIDO UAF credentials and dispatch targets of a device can be associated with multiple identities.
The Device Service consists of three parts or endpoints: the Get, Modify and Delete Device.
Get Device Credentials
This section describes the Get Device Credentials part of the Device Service.
Base URL
All URLs referenced in this section have the following base:
https://fido.siven.ch/nevisfido/devices/credentials/{deviceId}
deviceId is the identifier of the device to be retrieved.
HTTP Methods
GET is the only supported HTTP method.
Request Headers
The following request headers are mandatory:
| Name | Description |
|---|---|
Device-Signature | The Device-Signature value is a JWS (JSON Web Signature) using compact serialization. It must be signed with the signature key of a dispatch target defined in the device. |
Accept | Accept header, must be application/jose;charset=UTF-8. |
The payload of the JWS in the Device-Signature has the following format:
| Attribute | Type | Description | Optional |
|---|---|---|---|
dispatchTargetId | String | The identifier of the dispatch target that was used to sign this JSON payload. | false |
requestId | String | A unique identifier for this JSON payload. It can contain up to 64 characters. | false |
creationTimeInEpochMillis | Number | The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch. | false |
Response Headers
The following response headers will be set:
| Name | Description |
|---|---|
Content-Type | Content type header, fixed to application/jose;charset=UTF-8. |
Invalid JWS Error
If there is a big divergence between the clock of nevisFIDO and the clock of the mobile device, the server will refuse to accept the request. If this is detected, the content of the WWW-Authenticate header will be:
JWS error="device_signature_expired", error_description="The device signature expired"
By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.
Response Body
The body of the response message is encrypted using the standard JWE using compact serialization. The contents can only be decrypted using the encryption key of the dispatch target that signed the contents of the Device-Signature header.
The response contains the information of the device. The format of the decrypted payload is:
| Attribute | Type | Description |
|---|---|---|
deviceId | String | The identifier of the device. |
fidoUafCredentials | Array | An array containing FidoUafCredential (see below) objects. |
dispatchTargets | Array | An array containing DispatchTarget (see below) objects. |
The FidoUafCredential format is:
| Attribute | Type | Description |
|---|---|---|
keyId | String | The key identifier of the FIDO UAF credential. It is encoded in base 64 URL. |
aaid | String | The AAID of the authenticator associated with this FIDO UAF credential. |
The DispatchTarget format is:
| Attribute | Type | Description |
|---|---|---|
id | String | The identifier of the dispatch target. |
name | String | The user-friendly name of the dispatch target. |
target | String | The target (FCM registration target) of the dispatch target. It will not be present if there is no target defined for the dispatch target. |
Example Request
GET /nevisfido/devices/dc210afa-cce6-4192-8780-bc1b11dfdbd1 HTTP/1.1
Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiYmUzYzhiZjgtODE4NC00YTY5LWFiNzYtOGEzNzdlODYyYzRlIiwicmVxdWVzdElkIjoiZTQ5YWEyNjUtOTMxNC00OTI4LWEyNjItZGEyMThlN2IzZTgzIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg3MDQ1OH0.IG8_15_AmWqVJSr7VtwIOvJLZMrXCXi0SNDgz4B_qmW-8dXjAASzAFQN04nL7quNKc2rP1nzE2f-64DS9sQGK9G8nbvMlKXTxPb4-iv38mKJcaKTrLVBwm3NvZaUeOpUkBEWtUH0ekGA1YjHsazvHB9nKFaeejNRjDbLFOXY1QVlQytiE6ZCfkEVLALpehfsRBZIYnRDOyA3Z2aVpIpAKLLWShfDqsyxZ0b2bIi8xmteq3ax-ntddxQpJsNkD_nA7nv-1MGWHwoyM5LJ5XXHkIm3N6pXGxBoJdyW8Qsok_gmELLDX1cIQbNfTQFraHpc7ucoQ0URXHJ3tJsL_L5HhQ
Accept: application/jose;charset=UTF-8
Host: fido.siven.ch
cURL:
$ curl 'https://fido.siven.ch/nevisfido/devices/dc210afa-cce6-4192-8780-bc1b11dfdbd1' -i -X GET \
-H 'Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiYmUzYzhiZjgtODE4NC00YTY5LWFiNzYtOGEzNzdlODYyYzRlIiwicmVxdWVzdElkIjoiZTQ5YWEyNjUtOTMxNC00OTI4LWEyNjItZGEyMThlN2IzZTgzIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg3MDQ1OH0.IG8_15_AmWqVJSr7VtwIOvJLZMrXCXi0SNDgz4B_qmW-8dXjAASzAFQN04nL7quNKc2rP1nzE2f-64DS9sQGK9G8nbvMlKXTxPb4-iv38mKJcaKTrLVBwm3NvZaUeOpUkBEWtUH0ekGA1YjHsazvHB9nKFaeejNRjDbLFOXY1QVlQytiE6ZCfkEVLALpehfsRBZIYnRDOyA3Z2aVpIpAKLLWShfDqsyxZ0b2bIi8xmteq3ax-ntddxQpJsNkD_nA7nv-1MGWHwoyM5LJ5XXHkIm3N6pXGxBoJdyW8Qsok_gmELLDX1cIQbNfTQFraHpc7ucoQ0URXHJ3tJsL_L5HhQ' \
-H 'Accept: application/jose;charset=UTF-8'
The payload inside the JWS of the Device-Signature header:
{
"dispatchTargetId" : "be3c8bf8-8184-4a69-ab76-8a377e862c4e",
"requestId" : "e49aa265-9314-4928-a262-da218e7b3e83",
"creationTimeInEpochMillis" : 1700726870458
}
Example Response
HTTP/1.1 200 OK
Date: Thu, 23 Nov 2023 08:07:50 GMT
Content-Type: application/jose;charset=UTF-8
Content-Length: 859
eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.SiJ1iw5RyiZNnf3m75K_xA-c7nNKjgCykdk1HiCV1gSH1uzp8L60pLmx-yJJGZXoPPpKM_AIjE9u_Q1cKk53Ms7YsUiCWNrs3YE-Ag3MUNt5zokGEx4WgOW9UH30XXBOd8UJdxaHHHqhcn7lobv5TQwUmoaLCFTh4oYIiky3SQooSODE0pItnXCAySd65GSGvYfVTd3CT6l74mBXEM3OcHiyHJxu6aRUzFDnOKiL_pBsdq6fe2s2Do5KhYAZdWPN8RdyTAmyK6wvgU40LLl0BmbEGksN4GLl3b4fXMVrE_j3sHRR5AEUbp5OTrgNC5gIipYDztMw-SPyAju074PJjg.ov12iXmAKOqfutco.-MJ278nBxlXjfo8lSrmGgu4TWgsVFpMnJAquSo2I78kvvcJMrOi1nUf0w8WsAU5dMdeoRCpDTHYlcVzRS_WnYcTIU6fWlglSKNgHNAcIkVnjemhhMF_VglNUjqVQcSJfwi6CI7MXJK8kCkxNenNd2uNIxdooiaj_LlLX_jMrOe-R54TK4ThoQ6e61vRNdjPWMJ_m3YDxb-3HSMvJs7qJvOoz8zcgwKzQ7yEeet3sP7yli7DAJQGg_ZKD6CgRWC53qZpS7jH-bTiFRFizHZLA8S_kmj_xw-fnWirJt_mGA0nbktN8SDF6adrbYuA338Rq_F-_45kCgPQmG5MMR1xgx633fzWlWIHxi1B55yLLxB-50TTuMBgdiTKxEeelflhsIn_ihVIfNGZRygaUxz3Ek2qGI38Tt5lQB7Xq_Q7L.OZv_j8miGp7yS0ntpc73iw
The decrypted JWE in the body is:
{
"deviceId" : "e5ed8c10-3fad-46c2-9261-d6b1a8166593",
"fidoUafCredentials" : [ {
"keyId" : "dGhpc2lzdGhla2V5SUQx",
"aaid" : "F1D0#0001"
}, {
"keyId" : "dGhlIGtleUlEIDI",
"aaid" : "F1D0#0003"
} ],
"dispatchTargets" : [ {
"id" : "d22e5c94-3bcf-4dbc-ac10-27cfdd421de0",
"name" : "My Android home phone",
"target" : "921207f5-b0e0-46a5-a05d-b52318a96e07"
} ]
}
HTTP Status Codes
The following HTTP status codes are returned by the Get Device Credentials part/endpoint of the Device Service:
| HTTP Code | Description |
|---|---|
| 200 | Ok The server successfully found the device information. |
| 400 | Bad Request The JWS in the Device-Signature header is not properly formatted. |
| 401 | Unauthorized The request was not authorized. The provided JWS in the Device-Signature header is not valid. |
| 403 | Forbidden The dispatch target used to sign the JWS of the Device-Signature header is not part of the requested device. |
| 406 | Not Acceptable The Accept header is not properly set to application/jose;charset=UTF-8. |
| 500 | Internal Server Error The server could not process the request because of an unexpected error. |
Modify Device Credentials
This section describes the Modify Credentials part of the Device Service.
Base URL
All URLs referenced in this section have the following base:
https://fido.siven.ch/nevisfido/devices/credentials/{deviceId}
deviceId is the identifier of the device to be modified.
HTTP Methods
PATCH is the only supported HTTP method.
Request Headers
The following request headers are mandatory:
| Name | Description |
|---|---|
Content-Type | Content type header, must be application/jose;charset=UTF-8. |
Request Body
The Modify Dispatch Target Service body is a JWS (JSON Web Signature) using compact serialization. The JWS must be signed with the private key of a dispatch target defined in the device.
eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJzaWduaW5nRGlzcGF0Y2hUYXJnZXRJZCI6IjcxMjBhODliLTMyZjItNDRiMi05Yzg4LWE4YmI0YjA1ZWM3MCIsInJlcXVlc3RJZCI6ImIxYmZlZWRmLWEwMDUtNDliYy04MjY2LTRjZmY4Mzg3YWUyYSIsImNyZWF0aW9uVGltZUluRXBvY2hNaWxsaXMiOjE3MDA3MjY4NzA3MjEsIm5hbWUiOiJNeSBuZXcgUGhvbmUiLCJ0YXJnZXQiOiJlMjdhMzE0NC1kMDRiLTQzYzctYWYwOC1lYjBhZjI0YTE5MDgiLCJvcGVyYXRpb24iOiJEaXNwYXRjaFRhcmdldFVwZGF0ZSJ9.mtC_CkOXelno9AuyfMmTdm9ZLnwGTwdpcGEh3kRnV8qSXHCurz7r6rlUZo3KR7aWWzMr28g-sFoSIxJ62Rizw_X28lUFCFQ1eXBOwMbQb-X_Avf2qGtakKVG6C3duedT6ToZOB8CPXjmddbfYfrZDGM8XIcP_4EKPeHIgKvUs9q0PFxKScNN715nR6WWkbkyXHCuspRqALQt1Cl_hPhYgTdX2mv9A56P7Cfxb7xnXeIatr25-hIDW4TjzSPJSYJKpLxQpnGdWyNt1sctLSKvmd5tVLRp_gRiejOI0Yg-UMM0jDvP3MEm79G7eImJ1UzwmOFe5Zes0vkpbTRJqzQ0wA
There are two type of modification operations that can be performed (specified by the operation attribute).
The sections below describe the payload inside the JWS for each operation.
Update Dispatch Targets
This operation will update all the dispatch targets in the device.
| Attribute | Type | Description | Optional |
|---|---|---|---|
signingDispatchTargetId | String | The identifier of the dispatch target that was used to sign this JSON payload. | false |
requestId | String | A unique identifier for this JSON payload. It can contain up to 64 characters. | false |
creationTimeInEpochMillis | Number | The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch. | false |
operation | String | The name of the operation. It must be set to DispatchTargetUpdate. | false |
name | Array | The new value for the name to set for all the dispatch targets in the device. If not provided, no name will be modified. | true |
target | Array | The new value for the target (FCM registration token) to set for all the dispatch targets in the device. If not provided, no target will be modified. | true |
Delete FIDO UAF Credentials and Dispatch Targets
Deletes the specified FIDO UAF credentials and dispatch targets defined in the device.
| Attribute | Type | Description | Optional |
|---|---|---|---|
signingDispatchTargetId | String | The identifier of the dispatch target that was used to sign this JSON payload. | false |
requestId | String | A unique identifier for this JSON payload. It can contain up to 64 characters. | false |
creationTimeInEpochMillis | Number | The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch. | false |
operation | String | The name of the operation. It must be set to Delete. | false |
keyIds | Array | An array with the key IDs of the FIDO UAF credentials to be removed. The key IDs are expressed as base 64 URL strings. | true |
dispatchTargetIds | Array | An array with the identifiers (IDs) of the dispatch targets to be removed. | true |
Response Headers
The response message has no body. Therefore, no headers will be set in the response, except if there is a big divergence between the clock of nevisFIDO and the clock of the mobile device. In this case, the server will refuse to accept the request. If this is detected, the content of the WWW-Authenticate header will be:
JWS error="device_signature_expired", error_description="The device signature expired"
By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.
Response Body
The response message has no body.
Example Request
PATCH /nevisfido/devices/9ddaaccf-8985-45f5-b201-c8fcdeb34aae HTTP/1.1
Content-Type: application/jose;charset=UTF-8
Host: fido.siven.ch
Content-Length: 740
eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJzaWduaW5nRGlzcGF0Y2hUYXJnZXRJZCI6IjcxMjBhODliLTMyZjItNDRiMi05Yzg4LWE4YmI0YjA1ZWM3MCIsInJlcXVlc3RJZCI6ImIxYmZlZWRmLWEwMDUtNDliYy04MjY2LTRjZmY4Mzg3YWUyYSIsImNyZWF0aW9uVGltZUluRXBvY2hNaWxsaXMiOjE3MDA3MjY4NzA3MjEsIm5hbWUiOiJNeSBuZXcgUGhvbmUiLCJ0YXJnZXQiOiJlMjdhMzE0NC1kMDRiLTQzYzctYWYwOC1lYjBhZjI0YTE5MDgiLCJvcGVyYXRpb24iOiJEaXNwYXRjaFRhcmdldFVwZGF0ZSJ9.mtC_CkOXelno9AuyfMmTdm9ZLnwGTwdpcGEh3kRnV8qSXHCurz7r6rlUZo3KR7aWWzMr28g-sFoSIxJ62Rizw_X28lUFCFQ1eXBOwMbQb-X_Avf2qGtakKVG6C3duedT6ToZOB8CPXjmddbfYfrZDGM8XIcP_4EKPeHIgKvUs9q0PFxKScNN715nR6WWkbkyXHCuspRqALQt1Cl_hPhYgTdX2mv9A56P7Cfxb7xnXeIatr25-hIDW4TjzSPJSYJKpLxQpnGdWyNt1sctLSKvmd5tVLRp_gRiejOI0Yg-UMM0jDvP3MEm79G7eImJ1UzwmOFe5Zes0vkpbTRJqzQ0wA
cURL:
$ curl 'https://fido.siven.ch/nevisfido/devices/9ddaaccf-8985-45f5-b201-c8fcdeb34aae' -i -X PATCH \
-H 'Content-Type: application/jose;charset=UTF-8' \
-d 'eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJzaWduaW5nRGlzcGF0Y2hUYXJnZXRJZCI6IjcxMjBhODliLTMyZjItNDRiMi05Yzg4LWE4YmI0YjA1ZWM3MCIsInJlcXVlc3RJZCI6ImIxYmZlZWRmLWEwMDUtNDliYy04MjY2LTRjZmY4Mzg3YWUyYSIsImNyZWF0aW9uVGltZUluRXBvY2hNaWxsaXMiOjE3MDA3MjY4NzA3MjEsIm5hbWUiOiJNeSBuZXcgUGhvbmUiLCJ0YXJnZXQiOiJlMjdhMzE0NC1kMDRiLTQzYzctYWYwOC1lYjBhZjI0YTE5MDgiLCJvcGVyYXRpb24iOiJEaXNwYXRjaFRhcmdldFVwZGF0ZSJ9.mtC_CkOXelno9AuyfMmTdm9ZLnwGTwdpcGEh3kRnV8qSXHCurz7r6rlUZo3KR7aWWzMr28g-sFoSIxJ62Rizw_X28lUFCFQ1eXBOwMbQb-X_Avf2qGtakKVG6C3duedT6ToZOB8CPXjmddbfYfrZDGM8XIcP_4EKPeHIgKvUs9q0PFxKScNN715nR6WWkbkyXHCuspRqALQt1Cl_hPhYgTdX2mv9A56P7Cfxb7xnXeIatr25-hIDW4TjzSPJSYJKpLxQpnGdWyNt1sctLSKvmd5tVLRp_gRiejOI0Yg-UMM0jDvP3MEm79G7eImJ1UzwmOFe5Zes0vkpbTRJqzQ0wA'
The payload inside the JWS for the update dispatch targets operation:
{
"signingDispatchTargetId" : "7120a89b-32f2-44b2-9c88-a8bb4b05ec70",
"requestId" : "b1bfeedf-a005-49bc-8266-4cff8387ae2a",
"creationTimeInEpochMillis" : 1700726870721,
"name" : "My new Phone",
"target" : "e27a3144-d04b-43c7-af08-eb0af24a1908",
"operation" : "DispatchTargetUpdate"
}
The payload inside the JWS for the delete FIDO UAF credentials and dispatch targets operation:
{
"signingDispatchTargetId" : "d0de0bd2-4ee7-4b1b-bfcb-7555001c717a",
"requestId" : "9a6680d1-48b5-46cb-91ed-f1fa612ede36",
"creationTimeInEpochMillis" : 1700726870820,
"dispatchTargetIds" : [ "6594fa3e-bec2-460f-b505-e0b8a05e534b", "d92a26b6-3321-48ba-9c7f-33511266ce1d" ],
"keyIds" : [ "NmUwNTYzMzUtMmI2Ny00NmM2LWIwMjgtMzk4MjhjYzk4YTA3" ],
"operation" : "Delete"
}
Example Response
HTTP/1.1 204 No Content
Date: Thu, 23 Nov 2023 08:07:50 GMT
HTTP Status Codes
The following HTTP status codes are returned by the Modify Device Credentials part/endpoint of the Dispatch Target Service:
| HTTP Code | Description |
|---|---|
| 204 | No Content The server successfully modified the device information. |
| 400 | Bad Request The provided payload is not properly formatted. |
| 401 | Unauthorized The request was not authorized. It was not possible to verify the signature of the request. |
| 403 | Forbidden The dispatch target used to sign the JWS is not part of the requested device. |
| 415 | Unsupported Media Type The Content-Type header is not properly set to application/jose;charset=UTF-8. |
| 422 | Unprocessable Entity The request could not be processed. For example, because the provided name in the dispatch target modification is already in use by another dispatch target of the user. |
| 500 | Internal Server Error The server could not process the request because of an unexpected error. |
Delete Device Credentials
This section describes the Delete Device Credentials part of the Device Service.
Base URL
All URLs referenced in this section have the following base:
https://fido.siven.ch/nevisfido/devices/credentials/{deviceId}
deviceId is the identifier of the device to be retrieved.
HTTP Methods
DELETE is the only supported HTTP method.
Request Headers
The following request headers are mandatory:
| Name | Description |
|---|---|
Device-Signature | The Device-Signature value is a JWS (JSON Web Signature) using compact serialization. It must be signed with the signature key of a dispatch target defined in the device. |
The payload of the JWS in the Device-Signature has the following format:
| Attribute | Type | Description | Optional |
|---|---|---|---|
dispatchTargetId | String | The identifier of the dispatch target that was used to sign this JSON payload. | false |
requestId | String | A unique identifier for this JSON payload. It can contain up to 64 characters. | false |
creationTimeInEpochMillis | Number | The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch. | false |
Response Headers
The response message has no body. Therefore, no headers will be set in the response, except if there is a big divergence between the clock of nevisFIDO and the clock of the mobile device. In this case, the server will refuse to accept the request. If this is detected, the content of the WWW-Authenticate header will be:
JWS error="device_signature_expired", error_description="The device signature expired"
By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.
Response Body
The response message has no body.
Example Request
DELETE /nevisfido/devices/73ff33b7-e43a-4efb-8abc-58c9629c72e2 HTTP/1.1
Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiOGZiZGY0MjktNzQ4Ny00NjhjLWJmZjctODU4MjdkOTdhYjZlIiwicmVxdWVzdElkIjoiYWMwNGYzMTAtYjliZi00MDE1LTljMGEtNDMwYzYwNjFmZDJlIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg2ODk2M30.i1AyFTlvsEH2go1bjS91c3uA6czhyY0IkVC_OEkfkbWPsp6NnMtwbFGgryG3Io4gIVONviE87oP7Z3Mtiq4SKR03SaQH40G4zhQjSpvh_AR2-McurfpnlFNmIqSlYLWpyDs4ZC28iysNtUk2fvhVlI9wqTCq1zG5m853w98qFpOmzG6taDcbtBpxh2mrGSP4Sn4cScI3kbvUmky98bsubByCLdMS_YzWFBra2MrlctiBgdVQoLIy-d0l4YAsJq3IsROuEL-DfuXfRpIE7LYOfk9zW3PxfLMhUTlAXqBvzCbhPdepyI-kkyHazt1WpifsRxtzp11P1-snGJndvTdv6Q
Host: fido.siven.ch
cURL:
$ curl 'https://fido.siven.ch/nevisfido/devices/73ff33b7-e43a-4efb-8abc-58c9629c72e2' -i -X DELETE \
-H 'Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiOGZiZGY0MjktNzQ4Ny00NjhjLWJmZjctODU4MjdkOTdhYjZlIiwicmVxdWVzdElkIjoiYWMwNGYzMTAtYjliZi00MDE1LTljMGEtNDMwYzYwNjFmZDJlIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg2ODk2M30.i1AyFTlvsEH2go1bjS91c3uA6czhyY0IkVC_OEkfkbWPsp6NnMtwbFGgryG3Io4gIVONviE87oP7Z3Mtiq4SKR03SaQH40G4zhQjSpvh_AR2-McurfpnlFNmIqSlYLWpyDs4ZC28iysNtUk2fvhVlI9wqTCq1zG5m853w98qFpOmzG6taDcbtBpxh2mrGSP4Sn4cScI3kbvUmky98bsubByCLdMS_YzWFBra2MrlctiBgdVQoLIy-d0l4YAsJq3IsROuEL-DfuXfRpIE7LYOfk9zW3PxfLMhUTlAXqBvzCbhPdepyI-kkyHazt1WpifsRxtzp11P1-snGJndvTdv6Q'
The payload inside the JWS of the Device-Signature header:
{
"dispatchTargetId" : "8fbdf429-7487-468c-bff7-85827d97ab6e",
"requestId" : "ac04f310-b9bf-4015-9c0a-430c6061fd2e",
"creationTimeInEpochMillis" : 1700726868963
}
Example Response
HTTP/1.1 204 No Content
Date: Thu, 23 Nov 2023 08:07:49 GMT
HTTP Status Codes
The following HTTP status codes are returned by the Delete Device Credential part/endpoint of the Dispatch Target Service:
| HTTP Code | Description |
|---|---|
| 204 | No Content The server successfully deleted device information. |
| 400 | Bad Request The JWS in the Device-Signature header is not properly formatted. |
| 401 | Unauthorized The request was not authorized. The provided JWS in the Device-Signature header is not valid. |
| 403 | Forbidden The dispatch target used to sign the JWS of the Device-Signature header is not part of the requested device. |
| 500 | Internal Server Error The server could not process the request because of an unexpected error. |
Get Device Out-of-Band Operations
This section describes the Get Device Out-of-Band Operations part of the Device Service.
It is used to retrieve the out-of-band operations that have not timed-out and whose token has not been redeemed.
Base URL
All URLs referenced in this section have the following base:
https://fido.siven.ch/nevisfido/devices/oobOperations/{deviceId}
deviceId is the identifier of the device associated with the operations to be retrieved.
HTTP Methods
GET is the only supported HTTP method.
Request Headers
The following request headers are mandatory:
| Name | Description |
|---|---|
Device-Signature | The Device-Signature value is a JWS (JSON Web Signature) using compact serialization. It must be signed with the signature key of a dispatch target defined in the device. |
Accept | Accept header, must be application/jose;charset=UTF-8. |
The payload of the JWS in the Device-Signature has the following format:
| Attribute | Type | Description | Optional |
|---|---|---|---|
dispatchTargetId | String | The identifier of the dispatch target that was used to sign this JSON payload. | false |
requestId | String | A unique identifier for this JSON payload. It can contain up to 64 characters. | false |
creationTimeInEpochMillis | Number | The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch. | false |
Response Headers
The following response headers will be set:
| Name | Description |
|---|---|
Content-Type | Content type header, fixed to application/jose;charset=UTF-8. |
Invalid JWS Error
If there is a big divergence between the clock of nevisFIDO and the clock of the mobile device, the server will refuse to accept the request. If this is detected, the content of the WWW-Authenticate header will be:
JWS error="device_signature_expired", error_description="The device signature expired"
By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.
Response Body
The body of the response message is encrypted using the standard JWE using compact serialization. The contents can only be decrypted using the encryption key of the dispatch target that signed the contents of the Device-Signature header.
The response contains the information of the device. The format of the decrypted payload is:
| Attribute | Type | Description |
|---|---|---|
deviceId | String | The identifier of the device. |
operations | Array | An array containing DeviceOobOperation (see below) objects. |
The DeviceOobOperation format is:
| Attribute | Type | Description | Optional |
|---|---|---|---|
creationTimeInEpochMillis | Number | The creation time of the operation. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch. | false |
dispatcher | String | The name of the dispatcher for the operation. firebase-cloud-messaging for push messages, png-qr-code for QR code, link for an operation transmitted through a URL. | false |
outOfBandPayload | String | The JSON string containing the out-of-band payload. This value can be provided to the Nevis Mobile SDK to obtain an OutOfBandPayload object. | false |
additionalInformation | String | The additional information provided to the dispatcher. Currently this only contains the value of the notification when the Firebase Cloud Messaging dispatcher has been used with the operation. | true |
Example Request
GET /nevisfido/devices/oobOperations/baf18de4-0b9e-498f-bd40-1c2468957f58 HTTP/1.1
Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiZjI1NmYyZDMtYWYyOS00NjE4LWFmMmYtNmQ4MWI5ZGYwNzkzIiwicmVxdWVzdElkIjoiZjc3OGMyMjctMzE1Yi00YjkzLTkzMGItZjVhOWVmMmFjMjU3IiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwNjcwOTkwMjY4OH0.OxCcv1rtE4Whcai-QF5h-Pjkh1OjdfnEuywP46Emb9uDBQt_y7TuKjGc9OUfMMM1k5YCi7E9KT_qTdQwV202R-OKtlp8CKmLIag_4Kdz22i9SmDKy_BH4nfrC2swROoYbnmGsMfua39xgygbORgOJaOcHcFwG0CWcD-O31Par532TO-E-wDv2ZPXWxC_RAD_qDKKYG9DA72FRPj-teI43cBnRxknUCa9ogh-oqWmGb7VH_h6xNogpxosFpIggQJksCpHt1oNGB0VlPfYUNhLl6QnyGXpUAJipgq3T3Rp4J1WLJCQjWQd7SdIfPQCKcwH1As59lKi1ybzhRQ5vLYzVQ
Accept: application/jose;charset=UTF-8
Host: fido.siven.ch
cURL:
$ curl 'https://fido.siven.ch/nevisfido/devices/oobOperations/baf18de4-0b9e-498f-bd40-1c2468957f58' -i -X GET \
-H 'Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiZjI1NmYyZDMtYWYyOS00NjE4LWFmMmYtNmQ4MWI5ZGYwNzkzIiwicmVxdWVzdElkIjoiZjc3OGMyMjctMzE1Yi00YjkzLTkzMGItZjVhOWVmMmFjMjU3IiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwNjcwOTkwMjY4OH0.OxCcv1rtE4Whcai-QF5h-Pjkh1OjdfnEuywP46Emb9uDBQt_y7TuKjGc9OUfMMM1k5YCi7E9KT_qTdQwV202R-OKtlp8CKmLIag_4Kdz22i9SmDKy_BH4nfrC2swROoYbnmGsMfua39xgygbORgOJaOcHcFwG0CWcD-O31Par532TO-E-wDv2ZPXWxC_RAD_qDKKYG9DA72FRPj-teI43cBnRxknUCa9ogh-oqWmGb7VH_h6xNogpxosFpIggQJksCpHt1oNGB0VlPfYUNhLl6QnyGXpUAJipgq3T3Rp4J1WLJCQjWQd7SdIfPQCKcwH1As59lKi1ybzhRQ5vLYzVQ' \
-H 'Accept: application/jose;charset=UTF-8'
The payload inside the JWS of the Device-Signature header:
{
"dispatchTargetId" : "f256f2d3-af29-4618-af2f-6d81b9df0793",
"requestId" : "f778c227-315b-4b93-930b-f5a9ef2ac257",
"creationTimeInEpochMillis" : 1706709902688
}
Example Response
HTTP/1.1 200 OK
Date: Wed, 31 Jan 2024 14:05:02 GMT
Content-Type: application/jose;charset=UTF-8
Content-Length: 1626
eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.fJqZWT_uANHsMhw628ymd-_zov1GeRV_J--__mMt_ciwCNeyDlMqINHCw-DtL8zhNh184OFFwPKSnOquEqDLG_ppeaCd_9Hexs33ODzvhIMqQW_lsSH_DHxD5Su8JTtpqNXIo3H7QymIatwhMgozB8Q15_5rMoabLzbcrU8TsPdvMA15dRa4suLS1V9x8UPbHPZLSrEoKVDJQx01FPb3zMSFEPQlQMITp9QnkoLLTE6PWqzbFgb9FlMafl5tMlhyxVdw5NueM7lLr3vhaMnpKEEgFnM_bnsb3FrpYXHgHCsRY1NLwZ6qQI1-TY7ELCIKKaspLRnRY729pQYmSpKpaQ.dFBaUSCaoD1Tkwd0.l_Cva9IA-ENGDjx7kIFgg9q6lnPUFmjhRLmGSkRHna95cwKMBYe3X3QBiOlawMyVBZ8YH_wQlav1UHgX8uUl0o3itD9yNWUESAyN3Soh5YlJGEnSk8rawqQbse_vk60TO-2a5G8LGVn3j21T70k3mMf148sVX-jzGPeRPLfkz1mHIKIx3aI0sLkp-6wLP__Wz0SpRGpix3brUte1bRXxjB9Bv9wnqUG77WyMZyZmf5ev98pP_uu4pLI-mE_V8jjVAhjveUThV2XE2XXG5LHI-WMzh2dZ7i0Htrxfz_a-eBYJ9FBetCy3b9XwMzLrp56SQOI0CEJHX6QDhevqeRCkB26dRJTHYcRjbhJh8cV5XDdeZdrTOTbnA_WtX4pCrg5_l3yv5C5Ru03z3p7RaafmPyv9Icd0vHzlX7SJLja6mgrLU8Ru2OQlHwI7EMO8-QReC9GuPwUYeDXthXDAfq4ubiOLKeFG7Cs1k5OWuXa4H1GKWLHHU1Lod3AVjMRoC3vqec-zrAlU9jRSFD-anlH1-FrKXVfC38zY1qNN4vS3Es-qK_UhFZ-ryCdaisW52HfSkTXi6LaDzHgGUV3NfipgVinCIPkHJXL_jbiN42IIhFUQzGT4UF_5ODYgrnoVJtzHmHD47-HsIpTiO267J9HfpWZHyGWgYF7oWK09N6XPH37bG_c1a2124IHPSsD0mwpxnqVSxkoLD-pDOkfrDn5LRTuDJRVdOdaFi_Iale3sG5a4bynzRzFBnMiRrwO57EE3NMneFIzj2tYXZVG3XHOGP5SVfNMJQFdYUJ-C49tjfo87UxGddTfrEvGzSU_orG1zRJtcnngFK6C9ArmYktmQL_UrFuBAPuOtFfsJkKRjaxNR_nKvTk6OljAKy0DKPHP33tdv75YFzU292SolnSFKaNFlnG_Pz3NoWqRNSya7EMR6EOT-FdLUkTQAQEWa6sQclxOxDsTGM-RYykUhLv6HUfAN8Fhdjqoe9FVrdYQmWjfnDvO9SIZTpsLyckCi71N3XNQuteRfuVWbLRtlvFnQMgdd5j6-2FupJymIJM9NOKrpNoFRejLUAc4q4-404_FnO0kYVPyUfxYPU2BLMJdxrhfgWITyScWNjWFOz_z7JPcigkvIodQ-DHAb4M6bfyTUU7o-i8E-aYjbaseYE4jEf1dcXgE9-q2e6R86wM0.1hjpZj-Ocx4trKVFGr5Tjg
The decrypted JWE in the body is:
{
"deviceId" : "62ced878-6720-4278-aaf9-ecb0207adb79",
"operations" : [ {
"dispatcher" : "firebase-cloud-messaging",
"outOfBandPayload" : {
"nma_data" : {
"token" : "0e88d42d-8e2a-498d-8cdc-3caaa274a45f",
"redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
"attributeName" : "some additional data included in the push notification"
},
"nma_data_content_type" : "application/json",
"nma_data_version" : "1"
},
"additionalInformation" : {
"notification" : {
"title" : "Dirk Gently Bank - Confirm the payment"
}
},
"creationTimeInEpochMillis" : 1706709902722
}, {
"dispatcher" : "png-qr-code",
"outOfBandPayload" : {
"nma_data" : {
"token" : "2850d884-eb30-49f6-823d-1fabfd8f6bd3",
"redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
"attributeName" : "some additional data included in the QR code"
},
"nma_data_content_type" : "application/json",
"nma_data_version" : "1"
},
"creationTimeInEpochMillis" : 1706709902722
} ]
}
HTTP Status Codes
The following HTTP status codes are returned by the Get Device Out-of-Band Operations endpoint of the Device Service:
| HTTP Code | Description |
|---|---|
| 200 | Ok The server successfully found the out-of-band operations associated with the device. |
| 400 | Bad Request The JWS in the Device-Signature header is not properly formatted. |
| 401 | Unauthorized The request was not authorized. The provided JWS in the Device-Signature header is not valid. |
| 403 | Forbidden The dispatch target used to sign the JWS of the Device-Signature header is not part of the requested device. |
| 406 | Not Acceptable The Accept header is not properly set to application/jose;charset=UTF-8. |
| 500 | Internal Server Error The server could not process the request because of an unexpected error. |