Authorized Operations

The Authorized Operations system allows FAE (support personnel) to securely request permission to perform sensitive operations on a device. The device will not complete the operation until appropriate permission has been given.

Sensitive Operations

The sensitive operations will vary by model type.

Connected Logger

The sensitive operations supported by the Connected Logger are:

Operation	Key
Enable debug mode	enable_debug_mode
Factory reset	factory_reset
Reset device password	reset_device_password

Workflow

Request Lifecycle

#	Entity	Action
1	FAE	Logs in to the support tool and requests an operation for a specific Device.
2	Spoke Zone	Queues the request.
3	Spoke Zone	Emails the requesting FAE to confirm that the request is pending.
4	Device User	Approves or rejects the requested Device and operation in Spoke Zone.
5	Spoke Zone	Records the approval or rejection.
6	Spoke Zone	Emails the requesting FAE the approval or rejection result.
7	Spoke Zone	Issues a short-lived, single-use authorization if the request is approved.
8	Device	Begins the authorization exchange and provides a fresh nonce to the support tool.
9	Support tool	Sends the request ID and nonce to Spoke Zone using the FAE’s existing login session.
10	Spoke Zone	Validates the approved request and consumes its authorization.
11	Spoke Zone	Signs the device’s CPU ID and nonce and returns the signature.
12	Spoke Zone	Records the authorization exchange.
13	Support tool	Relays the signature to the Device.
14	Device	Verifies the signature and performs the operation.

Roles and Permissions

FAE

Support personnel who log in to the support tool and have permission to request or trigger authorized operations on the devices their organization can access.

A user may submit authorized operation requests when they have read-write permission and a super user has enabled Authorized Operation Requests in their user permissions. Super users have it enabled by default.

A user can access the devices of their own organization and of every organization below it; a super user can access every device.

Device User

Any user with read-write access to the device and the Authorized Operation Requests permission who approves or rejects an operation for the device.

Support tool

The support tool is an authenticated client that the FAE logs in to. It relays requests and responses using the FAE’s session and does not hold an unlock secret.

API

POST /api/v2/authorized-operation-requests

• The authenticated FAE submits the device ID and operation key; the support tool reads the device ID from the logger.
• Requires the FAE to have the Authorized Operation Requests permission and read-write access to the device; without the permission, Cloud returns 403 Forbidden.
• Cloud returns 404 Not Found for a device the FAE cannot access, the same as for a device that does not exist.
• Cloud returns 400 Bad Request if the device has no CPU ID, since the exchange signs it.
• Cloud queues the request, returns its request ID, and emails the FAE a pending receipt.

GET /api/v2/devices/:deviceId/authorized-operation-requests

• Returns full details for every request status to support review and audit.
• Requires the caller to have the Authorized Operation Requests permission and read-write access to the device; without the permission, Cloud returns 403 Forbidden.

PATCH /api/v2/authorized-operation-requests/:requestId

• Accepts an approved boolean in the JSON body to approve or reject the request.
• Requires the caller to have the Authorized Operation Requests permission and read-write access to the device; without the permission, Cloud returns 403 Forbidden.
• Cloud returns 403 Forbidden if the caller created the request, unless the caller is a Super user.
• Cloud records one decision per request and emails the FAE.
• Cloud returns 409 Conflict if the request cannot be decided, with a details.reason in the error:
  • already-decided: the request has already been decided.
  • expired: the request expired before a decision; the FAE must create a new request.

POST /api/v2/authorized-operation-requests/:requestId/exchange

• Accepts the device’s fresh 16-byte nonce for the approved request, as base64 in the nonce field of the JSON body.
• Uses the FAE’s existing login session; the support tool, not the FAE, talks to the device.
• Any user with the Authorized Operation Requests permission who can access the device may exchange the request, not only the FAE who created it. The requester must still have that permission too; otherwise, Cloud returns 403 Forbidden.
• Cloud returns 404 Not Found if the request does not exist, or its device is one the user cannot access.
• Cloud accepts the exchange only once per request, and records who exchanged it and when; the device’s request list returns both.
• Cloud returns 409 Conflict if the request cannot be exchanged, with a details.reason the support tool can check:
  • not-approved: the request has not been approved.
  • already-used: the approval has already been used.
  • expired: the request expired before a decision, or the approval expired before the exchange; the FAE must create a new request.
• Cloud returns 429 Too Many Requests if a user sends more than 10 exchange requests in a minute.
  • Every exchange request by the user counts, whatever the request ID or the response.
  • Wait for the number of seconds in the Retry-After response header, then send the exchange again.
• Cloud validates the request, signs the device’s CPU ID together with the nonce, and returns the signature in a JSON response.
  • The signed bytes are the CPU ID’s ASCII characters exactly as Spoke Zone stores them (for example 0x00112233445566778899AABBCCDDEEFF), followed by the 16 decoded nonce bytes. Letter case matters.
  • Cloud reads the CPU ID from the request’s device, so it never passes through the support tool; a device with no CPU ID gets 400 Bad Request.
  • Signing the CPU ID stops an approval for one device from unlocking another.
  • The signature is RSA 2048 with SHA-256 and PKCS#1 v1.5 padding (RSASSA-PKCS1-v1_5), returned as base64; the support tool relays the decoded 256 bytes to the device.
• The support tool relays the signature to the device, which rebuilds the same bytes from the CPU ID in its registers and its nonce, and verifies the signature using the Authorized Operations signing certificate.

Open Questions

• How should we handle the risk of device enumeration when FAEs do not have direct access to devices?
  • The email can omit device details beyond the device ID, which the FAE already has.
  • Should the API also avoid revealing whether a device ID exists?
  • Is it worth trying to protect against enumeration attacks?