USP Per-Device Unique Credentials — Software Design Document

This document describes the design and implementation of per-device unique BASIC-auth credentials (DEV-1799) for USP (TR-369) devices managed by the Friendly Technologies ACS.

It is the USP counterpart of TR-069 Per-Device Unique Credentials (DEV-1194). Both features store their credentials in the same cpe_credentials table and share the value generator and the profile-exclusion contract, but the steps between generation and enforcement differ: the two protocols authenticate at different moments and over different channels.

A USP agent authenticates to the ACS with the login/password of its security configuration (iot_sec_conf_details table), presented on the MQTT CONNECT (or STOMP CONNECT) frame. That login/password is shared by every device of the configuration, so any device holding it can connect under another device’s endpoint name.

When unique-credential generation is enabled on the security configuration a device authenticates against, the ACS:

The feature is opt-in per security configuration (iot_sec_conf_details.generate_unique_credentials column).

USP credentials live in the same cpe_credentials table as TR-069/TR-181 ones — one row per device, whatever the protocol. The diagram below is shared by both design documents.

A USP credentials row is created on the first registration that finds unique-credential generation enabled. It is identified by serial + group_id when provisioning, and by endpoint_name on every authentication and factory-reset path.

The flag is exposed to the outside by ACSWebService.saveOrUpdateSecurityConfiguration() and ACSWebService.getSecurityConfigurations(), as the generateUniqueCredentials field of SecurityConfigurationDetailsWs.

It is read at two different moments, off two different configuration rows:

Values are produced by the shared UniqueCredentialValueGenerator, exactly as for TR-069:

Setting it to 0 or less would leave the wait for a proof without any expiry at all, so such a value is refused: the default 60 seconds is used instead, and a single error line reports it.

Retention of credential rows after a device is deleted is shared with TR-069 and unchanged — see Retention Policy.

Provisioning — provisionCredentials in the diagrams — is the last step of registration (UspCpeRegistrationService), reached on both registration routes: with an OnBoardRequest and without one. A failure here does not fail the registration: a device whose credentials could not be provisioned is still a registered device, and the unique credentials stay unconfirmed so the next registration re-sends them.

Anything that leaves the unique credentials unconfirmed ends in the same retry: a push that never reached the device, a response that never came back, or a pair unconfirmed by a proved factory reset.

A device may have several MQTT clients or STOMP connections that have nothing to do with USP — the ACS itself creates an MQTT one when a BulkData profile points at a broker. Writing to the wrong object puts the secret where the device does not read it, while the ACS can still record the pair as delivered. The device is then refused on every connection — dropped in the factory-reset quarantine, or matching neither cpe_credentials nor the shared configuration if a foreign value was taken for its own.

UspCredentialParameterPathResolver therefore takes the object from what the agent states itself — Device.LocalAgent.MTP.{i}.MQTT.Reference or Device.LocalAgent.MTP.{i}.STOMP.Reference, a strong path reference to the MQTT client / STOMP connection the agent carries USP over.

Resolution ladder, strongest first:

When more than one MTP of the same protocol carries a reference, an enabled one is preferred, then the lowest MTP instance; the ambiguity is logged at warn: Device has 2 MTPs referencing a Device.MQTT.Client. object and nothing tells which one this connection arrived over, preferring an enabled one. A reference that is empty, or that does not name a plain instance path (an alias-addressed one, for instance), is treated as absent and the ladder continues.

The synchronous counterpart, findAgentTransportObjectPrefixes(cpeId), works from the cache alone and returns every MQTT client and STOMP connection the agent references — with no connection to ask, which MTP the device uses is not known. Used where a device round trip is impossible — see Profile Overwrite Protection.

The pair is written with an ordinary SetParameterValues provisioning task carrying both parameters, in plaintext (the device expects the value, not the ciphertext). Nothing is sent when the object cannot be resolved: the unique credentials stay unconfirmed and the next registration retries.

cpe_credentials.confirmed records that the ACS knows the device holds the pair. It is a latch, not an admission gate: authentication accepts the pair whether or not the flag is up, because presenting the pair proves the device holds it, while a task response only reports that it was sent.

Two routes raise it.

The completed task (confirmCredentialsSent, called from UspPostHandlerTaskProcessor for every completed SetParameterValuesProvision task):

A successful authentication (confirmAfterSuccessfulAuthentication): the device connected using its unique pair while the ACS still had it marked unconfirmed. Connecting with the pair proves the device has it, so the flag is raised.

The flag is raised only if it is still down, so a factory reset lowering it at that same moment is not overwritten. The event is logged at error: the ACS recovers by itself, but a confirmation that went missing is a fault on the delivery path. Look for USP device authenticated with unique credentials that were still unconfirmed … confirming them now.

Leaving the flag down would not lock the device out — authentication accepts its pair either way. It would cost the device the protection the flag provides: the factory-reset quarantine only holds devices whose pair is confirmed, so until the ACS knows the device has its pair, a client connecting with the shared credentials under that endpoint name is treated as a device still waiting for it, and the next registration pushes the pair to it. Every device is in that state until its first confirmation, and this route ends it on the device’s next connection rather than waiting for another push.

The unique-pair lookup runs first and is keyed by the endpoint the device connects as. It deliberately does not filter on cpe_credentials.confirmed. A unique-pair mismatch is not a rejection on its own: the shared credentials are what a factory reset leaves the device with. Matching them proves nothing by itself, so the connection is accepted provisionally and the proof is owed afterwards — see Factory Reset Quarantine.

If the stored pair cannot be decrypted, the device is disconnected outright: that is a corrupted stored pair on the ACS side, not a device that came back with its factory credentials.

A device that authenticates with the shared credentials while its unique credentials are still marked confirmed = 1 may have been factory reset, and is indistinguishable from any other client of the same configuration connecting under that endpoint name. It is held until it proves the reset.

A profile is declarative configuration the ACS owns, so it must never silently overwrite a device’s unique credentials. Two layers, mirroring TR-069:

Prevention. Credential parameters a profile carries for the object the agent uses as its USP transport are never sent to the device: they are dropped while the profile’s task for that device is being built, going by the cached Device.LocalAgent.MTP references. The profile itself is left as the operator configured it — only this device’s copy of the task loses them. A profile that configures the credentials of another MQTT client or STOMP connection — a bulk-data one, for example — is legitimate configuration and is still sent, and so is a profile for a device that has no unique credentials and is not due any. When the references are not known, the Username and Password of every MQTT client and STOMP connection the profile touches are dropped instead — nothing outside those objects is affected, and a device with no unique credentials is not filtered at all. Dropping too much only leaves a profile parameter unapplied, while letting one through can lock the device out. That is the one case reported at warn — ordinary exclusions are debug:

Recovery. If a profile’s credential parameter reaches the device anyway (due to some bug in the code or another reason), the completed task is inspected: the ACS resolves the device’s own object off the device, as a push does, and only if the profile wrote there does it lower confirmed and immediately re-send the correct value. Waiting for the next registration instead would leave the device holding a value the ACS does not have. If the object cannot be resolved just then, the pair is only marked unconfirmed and the next registration re-sends it — reported at warn as Cannot tell whether a profile task overwrote the unique credentials of cpe …. Recovery runs only for a pair already recorded as delivered; an unconfirmed one is on the ordinary re-send path anyway.

A device that still owes a factory reset proof is left alone. Nothing is sent to it, and confirmed is not lowered either. Whoever is on the other end got in on the shared credentials and has proved nothing, and keeping the pair away from such a client is exactly what the wait is for. The flag stays up because the stored pair is still the one the genuine device holds. Waiting costs nothing: a device that proves the reset has the pair re-sent then, and one that never proves it is disconnected. Logged at debug: Profile task carried the credential parameters of a USP device that still owes a factory reset proof, leaving its unique credentials untouched.

Generation is a per-configuration flag, iot_sec_conf_details.generate_unique_credentials. Turning it off stops new credentials: provisioning returns before it touches cpe_credentials, so no row is created for a device that has none, and an existing row is left exactly as it stands — not deleted, confirmed not lowered, nothing pushed, whatever that row’s confirmed says. Such a device also keeps the prevention layer of the profile protection: a row that still carries a username/password counts as unique-managed whatever the flag says, and that check never looks at confirmed either.

A device already running on its unique pair has nothing to fall back on — the ACS never sends the shared credentials to a device — so removing its credentials would reject it on its next CONNECT. Credentials are therefore retired only on a proved factory reset, the point at which the device’s state is known: the proof deletes them instead of unconfirming them when generation is disabled on the original_sec_conf_details_id configuration.

In practice:

A security configuration’s details row cannot be deleted while any cpe_credentials row still points at it through original_sec_conf_details_id. The attempt is refused and nothing is deleted — whether the details row was deleted on its own, together with the whole security configuration, or simply left out of a save, which deletes it just the same.

Every referencing row counts, whatever its cpe_id, cpe_deleted_at or confirmed hold: a device deleted from the ACS keeps its pair and relinks on its next registration, and an unconfirmed pair may well be in the device’s hands with only the delivery confirmation lost.

The reason is the one behind Retirement When Generation Is Disabled: the details row is what the ACS reads to place such a device in its domain, to tell whether generation is still on for it, and to decide whether a proved reset re-sends its pair or retires it. With the row gone those lookups come back empty, which is indistinguishable from generate_unique_credentials having been turned off, and the shared credentials the device would fall back to are gone with the row too.

The refusal is reported to the caller and logged at error by com.friendly.security:

Credential rows are removed by the paths that know the device’s state — a proved factory reset while generation is off, or the retention policy once the device has been deleted long enough — so the configuration becomes deletable once those have run.

Deleting a device from the ACS touches two columns only: cpe_id is set to NULL and cpe_deleted_at is stamped. The pair itself, its confirmed flag and its endpoint_name stay exactly as they were, so a device that comes back without a factory reset still authenticates with its own credentials. This is why every authentication and factory-reset path is keyed on endpoint_name and never on cpe_id.

The next registration relinks cpe_id, isp_id and original_sec_conf_details_id; endpoint_name is never rewritten on credentials that already exist.

Nothing has to be done per device, and devices that are offline pick it up on their next connection.

All lines below come from com.friendly.usp.core… and name the device by endpointName= and/or cpeId=. Most of them are debug; the level is given below only where it is warn or error.

The debug ones are off by default, because conf/logback-spring.xml sets com.friendly to INFO. One entry alongside the other <logger> elements turns on all of them:

That covers SecurityValidationVisitor and everything under …security.credentials (UspCpeCredentialsService, FactoryResetQuarantineService, UspCredentialParameterPathResolver) — name those four classes individually instead if a narrower switch is wanted. The one line from registration is an error and needs no change.

A device can lose its unique pair without a factory reset — a restored configuration, a firmware downgrade, an MQTT client or STOMP connection re-created without it. It then has no proof to offer and is dropped on every connection, since only a proof lowers confirmed.

No code change is needed, just run the following SQL query against the database:

Nothing caches that row, so it takes effect on the device’s next connection: the wait no longer starts, and registration re-sends the pair to a device now known not to hold it. A wait that has already started still expires on its own timeout first, so one more disconnect after the update is expected.

Use endpoint_name, never cpe_id — the latter is NULL once the device has been deleted from the ACS, which is one of the states this recovery is for.