}
<IP_ADDRESS> Get Request Fields
repeated string param_paths
This field is a set of Object Paths, Object Instance Paths, Parameter Paths, or Search Paths to Objects and Parameters in an Agent’s Instantiated Data Model.
fixed32 max_depth
This field limits the maximum depth of each returned
result_params
tree to the depth specified by
max_depth
value. A value of 0
returns the
complete tree of all Objects and Sub-Objects of all the Path Names
mentioned in param_paths
.
R-GET.5 - If the
max_depth
field is present and contains a value other than
0, then the Agent MUST limit the tree depth of the resolved Sub-Objects
included in the resolved_path_results
field of the Response
to the specified value.
<IP_ADDRESS> Get Response Fields
repeated RequestedPathResult req_path_results
A repeated set of RequestedPathResult
messages for each
of the Path Names given in the associated Get request.
<IP_ADDRESS>.1 RequestedPathResult Field
string requested_path
This field contains one of the Path Names or Search Paths given in
the param_path
field of the associated Get Request.
fixed32 err_code
This field contains a numeric code (Error Codes) indicating the type of error that caused the Get to fail on this Path Names. A value of 0 indicates the Path Name could be read successfully.
R-GET.0 - If
requested_path
contains a Path Name (that is not a Search
Path) that does not match any Object or Parameter in the Agent’s
Instantiated Data Model, or requested_path
contains a
Search Path that does not match any Object or Parameter in the Agent’s
Supported Data Model, the Agent MUST use the
7026 - Invalid Path
error in this
RequestedPathResult
.
R-GET.1 - If the Controller
making the Request does not have Read permission on an Object or
Parameter matched through the requested_path
field, the
Object or Parameter MUST be treated as if it is not present in the
Agent’s Supported data model.
string err_msg
This field contains additional information about the reason behind the error.
repeated ResolvedPathResult resolved_path_results
This field contains one message of type ResolvedPathResult for each
Path Name resolved by the Path Name or Search Path given by
requested_path
.
R-GET.1a - If the
requested_path
is a valid Search Path (i.e., properly
formatted and in the Agent’s supported data model) but did not resolve
to any Objects in the Agent’s Instantiated Data Model, the
resolved_path_results
set MUST be empty and is not
considered an error.
R-GET.1b - If the
requested_path
is a valid Object Path (i.e., properly
formatted and in the Agent’s supported data model), which is not a
Search Path, but the Object does not have any Sub-Objects or Parameters,
the resolved_path_results
set MUST be empty and is not
considered an error.
<IP_ADDRESS>.1.1 ResolvedPathResult Fields
string resolved_path
This field contains a Path Name to an Object or Object Instance that
was resolved from the Path Name or Search Path given in
requested_path
.
R-GET.2 - If the
requested_path
included a Path Name to a Parameter, the
resolved_path
MUST contain only the Path Name to the parent
Object or Object Instance of that Parameter.
map<string, string> result_params
This field contains a set of mapped key/value pairs listing a
Parameter Path (relative to the Path Name in resolved_path
)
to each of the Parameters and their values of the Object given in
resolved_path
. Refer to Parameter and
Argument Value Encoding for details of how Parameter values are
encoded as Protocol Buffers v3 strings.
R-GET.3 - If the
requested_path
included a Path Name to a Parameter,
result_params
MUST contain only the Parameter included in
that Path Name.
R-GET.4 - If the Controller does
not have Read permission on any of the Parameters specified in
result_params
, these Parameters MUST NOT be returned in
this field. This MAY result in this field being empty.
<IP_ADDRESS> Get Message Supported Error Codes
Appropriate error codes for the Get Message include
7000-7006
, 7008
, 7010
,
7016
, 7026
and 7800-7999
.
7.5.2 The GetInstances Message
The GetInstances Message takes a Path Name to an Object and requests that the Agent return the Instances of that Object that exist and possibly any Multi-Instance Sub-Objects that exist as well as their Instances. This is used for getting a quick map of the Multi-Instance Objects (i.e., Tables) the Agent currently represents, and their Unique Key Parameters, so that they can be addressed and manipulated later.
GetInstances takes one or more Path Names to Multi-Instance Objects
in a Request to an Agent. In addition, both GetInstances and
GetSupportedDM (below) make use of a flag called
first_level_only
, which determines whether or not the
Response should include all of the Sub-Objects that are children of the
Object specified in obj_path
. A value of true
means that the Response returns data only for the Object
specified. A value of false means that all Sub-Objects will be resolved
and returned.
<IP_ADDRESS> GetInstances Examples
For example, if a Controller wanted to know only the current instances of Wi-Fi SSID Objects that exist on an Agent (that has 2 SSIDs), it would send a GetInstances Request as:
get_instances {
obj_paths: "Device.WiFi.SSID."
first_level_only: true
}
The Agent’s Response would contain:
get_instances_resp {
req_path_results {
requested_path: "Device.WiFi.SSID."
curr_insts {
instantiated_obj_path: "Device.WiFi.SSID.1."
unique_keys {
key: "Alias"
value: "UserWiFi1"
}
unique_keys {
key: "Name"
value: "UserWiFi1"
}
unique_keys {
key: "BSSID"
value: "00:11:22:33:44:55"
}
}
curr_insts {
instantiated_obj_path: "Device.WiFi.SSID.2."
unique_keys {
key: "Alias"
value: "UserWiFi2"
}
unique_keys {
key: "Name"
value: "UserWiFi2"
}
unique_keys {
key: "BSSID"
value: "11:22:33:44:55:66"
}
}
}
}
In another example, the Controller wants to get all of the Instances
of the Device.WiFi.AccessPoint
table, plus all of the
instances of the AssociatedDevice Object and AC Object (Sub-Objects of
AccessPoint). It would issue a GetInstances Request with the
following:
get_instances {
obj_paths: "Device.WiFi.AccessPoint."
first_level_only: false
}
The Agent’s Response will contain an entry in curr_insts
for all of the Instances of the Device.WiFi.AccessPoint
table, plus the Instances of the Multi-Instance Sub-Objects
.AssociatedDevice.
and .AC.
:
get_instances_resp {
req_path_results {
requested_path: "Device.WiFi.AccessPoint."
curr_insts {
instantiated_obj_path: "Device.WiFi.AccessPoint.1."
unique_keys {
key: "Alias"
value: "cpe-alias-1"
}
unique_keys {
key: "SSIDReference"
value: "Device.WiFi.SSID.1"
}
}
curr_insts {
instantiated_obj_path: "Device.WiFi.AccessPoint.1.AssociatedDevice.1."
unique_keys {
key: "MACAddress"
value: "11:22:33:44:55:66"
}
}
curr_insts {
instantiated_obj_path: "Device.WiFi.AccessPoint.1.AC.1."
unique_keys {
key: "AccessCategory"
value: "BE"
}
}
curr_insts {
instantiated_obj_path: "Device.WiFi.AccessPoint.2."
unique_keys {
key: "Alias"
value: "cpe-alias-2"
}
unique_keys {
key: "SSIDReference"
value: "Device.WiFi.SSID.2"
}
}
curr_insts {
instantiated_obj_path: "Device.WiFi.AccessPoint.2.AssociatedDevice.1."
unique_keys {
key: "MACAddress"
value: "11:22:33:44:55:66"
}
}
curr_insts {
instantiated_obj_path: "Device.WiFi.AccessPoint.2.AC.1."
unique_keys {
key: "AccessCategory"
value: "BE"
}
}
}
}
Or more, if more Object Instances exist.
<IP_ADDRESS> GetInstances Request Fields
repeated string obj_paths
This field contains a repeated set of Path Names or Search Paths to Multi-Instance Objects in the Agent’s Instantiated Data Model.
bool first_level_only
This field, if true
, indicates that the Agent returns
only those instances in the Object(s) matched by the Path Name or Search
Path in obj_path
, and not return any child Objects.
<IP_ADDRESS> GetInstances Response Fields
repeated RequestedPathResult req_path_results
This field contains a RequestedPathResult message for each Path Name or Search
string requested_path
This field contains one of the Path Names or Search Paths given in
obj_path
of the associated GetInstances Request.
fixed32 err_code
This field contains a numeric code (Error Codes) indicating the type of error that caused the GetInstances to fail on this Path Name. A value of 0 indicates the Path Name could be read successfully.
R-GIN.0 - If the Controller
making the Request does not have Read permission on an Object or
Parameter used for matching through the requested_path
field, any otherwise matched Object MUST be treated as if it is not
present in the Agent’s Instantiated Data Model
string err_msg
This field contains additional information about the reason behind the error.
repeated CurrInstance curr_insts
This field contains a message of type CurrInstance
for
each Instance of all of the Objects matched by
requested_path
that exists in the Agent’s Instantiated Data
Model.
<IP_ADDRESS>.0.1 CurrInstance Fields
string instantiated_obj_path
This field contains the Object Instance Path of the Object.
map<string, string> unique_keys
This field contains a map of key/value pairs for all of this Object’s Unique Key Parameters that are supported by the Agent.
R-GIN.1 - If the Controller does
not have Read permission on any of the Parameters specified in
unique_keys
, these Parameters MUST NOT be returned in this
field.
<IP_ADDRESS> GetInstances Error Codes
Appropriate error codes for the GetInstances Message include
7000-7006
, 7008
, 7016
,
7018
, 7026
and 7800-7999
.
7.5.3 The GetSupportedDM Message
GetSupportedDM (referred to informally as GSDM) is used to retrieve the Objects, Parameters, Events, and Commands in the Agent’s Supported Data Model. This allows a Controller to learn what an Agent understands, rather than its current state.
The GetSupportedDM Message is different from other USP Messages in
that it only returns information about the Agent’s Supported Data Model.
This means that Path Names to Multi-Instance Objects only address the
Object itself, rather than Instances of the Object, and those Path Names
that contain Multi-Instance Objects in the Path Name use the
{i}
identifier to indicate their place in the Path Name as
specified in TR-106 [38].
The obj_paths
field takes a list of Object Paths, either
from the Supported Data Model or the Instantiated Data Model.
For example, a Path Name to the AssociatedDevice
Object
(a child of the .WiFi.AccessPoint
Object) could be
addressed in the Supported Data Model as
Device.WiFi.AccessPoint.{i}.AssociatedDevice.{i}.
but in
addition to this notation the omission of the final {i}.
is
also allowed, such as
Device.WiFi.AccessPoint.{i}.AssociatedDevice.
. Both of
these syntaxes are supported and equivalent.
Alternatively an Instantiated Data Model Object Path can be used as
long as the Object exists, such as
Device.WiFi.AccessPoint.1.AssociatedDevice.
. The Agent will
use the Supported Data Model pertaining to this particular Object when
processing the Message.
If the Agent encounters a diverging Supported Data Model, e.g. due to
the use of different Mounted Objects underneath a Mountpoint, the Agent
will skip the traversal of the children Objects, populate the Response’s
divergent_paths
element with all divergent Object Instance
Paths, and continue processing with the next unambiguous Object. The
Supported Data Model of such divergent Objects can only be obtained by
specifically using Object Instance Paths in the obj_paths
field of a GetSupportedDM request.
The Agent’s Response returns all Path Names in the
supported_obj_path
field according to its Supported Data
Model.
To clarify the difference between an Instantiated Data Model Object Path and a Supported Data Model Object Path:
- If a
{i}
is encountered in the Object Path, it cannot be followed by an Instance Identifier. - If the Object Path ends with an Instance Identifier, it is treated as an Instantiated Data Model Object Path.
- If the Object Path contains a
{i}
, it is a Supported Data Model Object Path.
<IP_ADDRESS> GetSupportedDM Examples
For example, the Controller wishes to learn the Wi-Fi capabilities the Agent represents. It could issue a GetSupportedDM Request as:
get_supported_dm {
obj_paths : "Device.WiFi."
first_level_only : false
return_commands : false
return_events : false
return_params : false
}
The Agent’s Response would be:
get_supported_dm_resp {
req_obj_results {
req_obj_path: "Device.WiFi."
data_model_inst_uri: "urn:broadband-forum-org:tr-181-2-12-0"
supported_objs {
supported_obj_path: "Device.WiFi."
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.Radio.{i}."
access: OBJ_READ_ONLY
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.Radio.{i}.Stats"
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.SSID.{i}."
access: OBJ_ADD_DELETE
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.SSID.{i}.Stats"
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}."
access: OBJ_ADD_DELETE
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}.Security."
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}.WPS."
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}.AssociatedDevice.{i}."
access: OBJ_READ_ONLY
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}.AssociatedDevice.{i}.Stats."
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}.AC.{i}."
access: OBJ_READ_ONLY
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}.AC.{i}.Stats."
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}.Accounting."
access: OBJ_READ_ONLY
is_multi_instance: false
}
supported_objs {
supported_obj_path: "Device.WiFi.EndPoint.{i}."
access: OBJ_ADD_DELETE
is_multi_instance: true
}
## And continued, for Device.WiFi.EndPoint.{i}. Sub-Objects such as Device.WiFi.EndPoint.{i}.Stats., Device.WiFi.EndPoint.{i}/// .Security., etc.
}
}
In another example request:
get_supported_dm {
obj_paths : "Device.WiFi."
first_level_only : true
return_commands : true
return_events : true
return_params : true
}
The Agent’s response would be:
get_supported_dm_resp {
req_obj_results {
req_obj_path: "Device.WiFi."
data_model_inst_uri: "urn:broadband-forum-org:tr-181-2-12-0"
supported_objs {
supported_obj_path: "Device.WiFi."
access: OBJ_READ_ONLY
is_multi_instance: false
supported_params {
param_name: "RadioNumberOfEntries"
access: PARAM_READ_ONLY
value_type : PARAM_UNSIGNED_INT
value_change : VALUE_CHANGE_ALLOWED
}
supported_params {
param_name: "SSIDNumberOfEntries"
access: PARAM_READ_ONLY
value_type : PARAM_UNSIGNED_INT
value_change : VALUE_CHANGE_ALLOWED
}
## Continued for all Device.WiFi. Parameters
supported_commands {
command_name: "NeighboringWiFiDiagnostic()"
output_arg_names: "Status"
output_arg_names: "Result.{i}.Radio"
output_arg_names: "Result.{i}.SSID"
output_arg_names: "Result.{i}.BSSID"
output_arg_names: "Result.{i}.Mode"
output_arg_names: "Result.{i}.Channel"
## Continued for other NeighboringWiFiDiagnostic() output arguments
command_type : CMD_ASYNC
}
}
## followed by its immediate child objects with no details
supported_objs {
supported_obj_path: "Device.WiFi.Radio.{i}."
access: OBJ_READ_ONLY
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.SSID.{i}."
access: OBJ_ADD_DELETE
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.AccessPoint.{i}."
access: OBJ_ADD_DELETE
is_multi_instance: true
}
supported_objs {
supported_obj_path: "Device.WiFi.EndPoint.{i}."
access: OBJ_ADD_DELETE
is_multi_instance: true
}
}
}
<IP_ADDRESS> GetSupportedDM Request Fields
repeated obj_paths
This field contains a repeated set of Path Names to Objects in the
Agent’s Supported or Instantiated Data Model. For Path Names from the
Supported Data Model the omission of the final {i}.
is
allowed.
bool first_level_only
This field, if true
, indicates that the Agent returns
only those objects matched by the Path Name or Search Path in
obj_path
and its immediate (i.e., next level) child
objects. The list of child objects does not include commands, events, or
Parameters of the child objects regardless of the values of the
following elements:
bool return_commands
This field, if true
, indicates that, in the
supported_objs
, the Agent should include a
supported_commands
field containing Commands supported by
the reported Object(s).
bool return_events
This field, if true
, indicates that, in the
supported_objs
, the Agent should include a
supported_events
field containing Events supported by the
reported Object(s).
bool return_params
This field, if true
, indicates that, in the
supported_objs
, the Agent should include a
supported_params
field containing Parameters supported by
the reported Object(s).
<IP_ADDRESS> GetSupportedDMResp Fields
repeated RequestedObjectResult req_obj_results
This field contains a repeated set of messages of type
RequestedObjectResult
.
<IP_ADDRESS>.1 RequestedObjectResult Fields
string req_obj_path
This field contains one of the Path Names given in
obj_path
of the associated GetSupportedDM Request.
fixed32 err_code
This field contains a numeric code (Error Codes) indicating the type of error that caused the GetSupportedDM to fail on this Path Name. A value of 0 indicates the Path Name could be read successfully.
R-GSP.0 - If the Controller
making the Request does not have Read permission on an Object or
Parameter matched through the requested_path
field, the
Object or Parameter MUST be treated as if it is not present in the
Agent’s Supported Data Model.
string err_msg
This field contains additional information about the reason behind the error.
string data_model_inst_uri
This field contains a Uniform Resource Identifier (URI) to the Data
Model associated with the Object specified in obj_path
.
repeated SupportedObjectResult supported_objs
The field contains a message of type
SupportedObjectResult
for each reported Object.
<IP_ADDRESS>.1.1 SupportedObjectResult Fields
In the case of a diverging Supported Data Model, only the
supported_obj_path
, access
,
is_multi_instance
, and divergent_paths
fields
will be populated for the divergent Object.
string supported_obj_path
This field contains the Full Object Path Name of the reported Object in Supported Data Model notation.
ObjAccessType access
The field contains an enumeration of type ObjAccessType specifying the access permissions that are specified for this Object in the Agent’s Supported Data Model. This usually only applies to Multi-Instance Objects. This may be further restricted to the Controller based on rules defined in the Agent’s Access Control List. It is an enumeration of:
OBJ_READ_ONLY (0)
OBJ_ADD_DELETE (1)
OBJ_ADD_ONLY (2)
OBJ_DELETE_ONLY (3)
bool is_multi_instance
This field, if true
, indicates that the reported Object
is a Multi-Instance Object.
repeated SupportedParamResult supported_params
The field contains a message of type
SupportedParamResult
for each Parameter supported by the
reported Object. If there are no Parameters in the Object, this should
be an empty list.
repeated SupportedCommandResult supported_commands
The field contains a message of type
SupportedCommandResult
for each Command supported by the
reported Object. If there are no Parameters in the Object, this should
be an empty list.
repeated SupportedEventResult supported_events
The field contains a message of type
SupportedEventResult
for each Event supported by the
reported Object. If there are no Parameters in the Object, this should
be an empty list.
repeated string divergent_paths
The field contains an Object Instance Path for each divergent Path Name.
Note: The divergent_paths
field was added in USP
1.2. An Agent that supports versions before USP 1.2 would not know to
send the divergent_paths
field and thus an empty list will
be seen by the Controller.
<IP_ADDRESS>.1.2 SupportedParamResult Fields
string param_name
This field contains the Relative Path of the Parameter.
ParamAccessType access
The field contains an enumeration of type ParamAccessType specifying the access permissions that are specified for this Parameter in the Agent’s Supported Data Model. This may be further restricted to the Controller based on rules defined in the Agent’s Access Control List. It is an enumeration of:
PARAM_READ_ONLY (0)
PARAM_READ_WRITE (1)
PARAM_WRITE_ONLY (2)
ParamValueType value_type
This field contains an enumeration of type ParamValueType specifying the primitive (or base) data type of this Parameter in the Agent’s Supported Data Model. It is an enumeration of:
PARAM_UNKNOWN (0)
PARAM_BASE_64 (1)
PARAM_BOOLEAN (2)
PARAM_DATE_TIME (3)
PARAM_DECIMAL (4)
PARAM_HEX_BINARY (5)
PARAM_INT (6)
PARAM_LONG (7)
PARAM_STRING (8)
PARAM_UNSIGNED_INT (9)
PARAM_UNSIGNED_LONG (10)
Note: The value_type field was added in USP 1.2, and the PARAM_UNKNOWN enumerated value is present for backwards compatibility purposes. An Agent that supports versions before USP 1.2 would not know to send the value_type and thus a 0 value (PARAM_UNKNOWN) will be seen by the Controller.
Note: This refers to the data type of the Parameter as implemented on the device, even though the value itself is transmitted as a Protocol Buffers string.
ValueChangeType value_change
This field contains an enumeration of type ValueChangeType specifying whether or not the Agent will honor or ignore a ValueChange Subscription for this Parameter. The value of this field does not impact the ability for a Controller to create a ValueChange Subscription that references the associated Parameter, it only impacts how the Agent handles the Subscription. It is an enumeration of:
VALUE_CHANGE_UNKNOWN (0)
VALUE_CHANGE_ALLOWED (1)
VALUE_CHANGE_WILL_IGNORE (2)
Note: The value_change field was added in USP 1.2, and the VALUE_CHANGE_UNKNOWN enumerated value is present for backwards compatibility purposes. An Agent that supports versions before USP 1.2 would not know to send the value_change and thus a 0 value (VALUE_CHANGE_UNKNOWN) will be seen by the Controller.
<IP_ADDRESS>.1.3 SupportedCommandResult Fields
string command_name
This field contains the Relative Path of the Command.
repeated string input_arg_names
This field contains a repeated set of Relative Paths for the input arguments of the Command, which can include Objects and Object Instances where the names are represented in Supported Data Model notation.
Note: This field only contains the Path Name of the supported
Input arguments without details about the supported number of instances,
mandatory arguments or expected data types. Those details are
implementation specific and not detailed as part of the
SupportedCommandResult
.
repeated string output_arg_names
This field contains a repeated set of Relative Paths for the output arguments of the Command, which can include Objects and Object Instances where the names are represented in Supported Data Model notation.
CmdType command_type
This field contains an enumeration of type CmdType specifying the type of execution for the Command. It is an enumeration of:
CMD_UNKNOWN (0)
CMD_SYNC (1)
CMD_ASYNC (2)
Note: The command_type field was added in USP 1.2, and the CMD_UNKNOWN enumerated value is present for backwards compatibility purposes. An Agent that supports versions before USP 1.2 would not know to send the command_type and thus a 0 value (CMD_UNKNOWN) will be seen by the Controller.
<IP_ADDRESS>.1.4 SupportedEventResult
string event_name
This field contains the Relative Path of the Event.
repeated string arg_names
This field contains a repeated set of Relative Paths for the arguments of the Event.
<IP_ADDRESS> GetSupportedDM Error Codes
Appropriate error codes for the GetSupportedDM Message include
7000-7006
, 7008
, 7016
,
7026
, and 7800-7999
.
Note: when using error 7026
(Invalid path), it is
important to note that in the context of GetSupportedDM this applies to
the Agent’s Supported Data Model.
7.5.4 GetSupportedProtocol
The GetSupportedProtocol Message is used as a simple way for the Controller and Agent to learn which versions of USP each supports to aid in interoperability and backwards compatibility.
<IP_ADDRESS> GetSupportedProtocol Request Fields
string controller_supported_protocol_versions
A comma separated list of USP Protocol Versions (major.minor) supported by this Controller.
<IP_ADDRESS> GetSupportedProtocolResponse Fields
string agent_supported_protocol_versions
A comma separated list of USP Protocol Versions (major.minor) supported by this Agent.
7.5.5 The Register Message
The Register message is an Agent to Controller message used to register new Service Elements.
See Software Modularization and USP-Enabled Applications Theory of Operation appendix for more information on when to use the Register message.
<IP_ADDRESS> Register Examples
A USP Agent can register several Service Elements with one or multiple Register Request messages.
header {
msg_id: "94521"
msg_type: REGISTER
}
body {
request {
register {
allow_partial: true
reg_paths {
path: "Device.Time."
}
reg_paths {
path: "Device.WiFi.DataElements."
}
}
}
}
In case the registration was successful, the USP Controller will respond with a Register Response message.
header {
msg_id: "94521"
msg_type: REGISTER_RESP
}
body {
response {
register_resp {
registered_path_results {
requested_path: "Device.Time."
oper_status {
oper_success {
registered_path: "Device.Time."
}
}
}
registered_path_results {
requested_path: "Device.WiFi.DataElements."
oper_status {
oper_success {
registered_path: "Device.WiFi.DataElements."
}
}
}
}
}
}
In case the registration failed partially, because the “Device.WiFi.DataElements.” object was already registered, the USP Controller will respond with the following Register Response message.
header {
msg_id: "94521"
msg_type: REGISTER_RESP
}
body {
response {
register_resp {
registered_path_results {
requested_path: "Device.Time."
oper_status {
oper_success {
registered_path: "Device.Time."
}
}
}
registered_path_results {
requested_path: "Device.WiFi.DataElements."
oper_status {
oper_failure {
err_code: 7029
err_msg: "Device.WiFi.DataElements. object path has already been registered"
}
}
}
}
}
}
If allow_partial
was set to false
in the
Register Request and the registration failed, the USP Controller would
instead respond with a USP Error message.
header {
msg_id: "94521"
msg_type: ERROR
}
body {
error {
err_code: 7029
err_msg: "Device.WiFi.DataElements. object path has already been registered"
}
}
<IP_ADDRESS> Register Request Fields
bool allow_partial
The Register message contains a boolean allow_partial
to
indicate whether the registration must succeed completely or is allowed
to fail partially. If allow_partial
is false
,
nothing will be registered if one of the provided paths fails to be
registered (e.g. due to an already existing registration) and the USP
Controller will respond with a USP Error message. If
allow_partial
is true
, the USP Controller will
try to register every path individually and will always respond with a
RegisterResp message, even if none of the requested paths can be
registered.
R-REG.0 - If the
allow_partial
field is set to true
and no
other exceptions are encountered, the Controller treats each of the
reg_paths independently. The Controller MUST complete the registration
of each reg_path regardless of the inability to register one of the
others.
R-REG.1 - If the
allow_partial
field is set to false
, and no
other exceptions are encountered, the Controller treats each of the
reg_paths holistically. A failure to handle one of the reg_paths will
cause the Register Message to fail and return an Error Message.
repeated RegistrationPath reg_paths
This field contains a repeated set of RegistrationPaths for each path the USP Agent wants to register.
<IP_ADDRESS>.1 RegistrationPath Fields
string path
This field contains the Object Path the USP Agent wants to register.
R-REG.2 - The path field MUST contain an Object Path without any instance numbers. This path MUST NOT not use the Supported Data Model notation (with {i}), meaning that it is not allowed to register a sub-object to a multi-instance object.
<IP_ADDRESS> Register Response Fields
repeated RegisteredPathResult registered_path_results
This field contains a repeated set of RegisteredPathResults for each path the USP Agent tried to register.
<IP_ADDRESS> RegisteredPathResult Fields
string requested_path
This field contains the value of the entry of the path (in the Register Request) associated with this RegisteredPathResult.
OperationStatus oper_status
This field contains a message of type OperationStatus.
<IP_ADDRESS>.1 OperationStatus Fields
oneof oper_status
This field contains a message of one of the following types.
OperationFailure oper_failure
Used when the path specified in requested_path failed to be registered.
OperationSuccess oper_success
Used when the path specified in requested_path was successfully registered.
<IP_ADDRESS>.2 OperationFailure Fields
fixed32 err_code
This field contains a numeric code (Error Codes) indicating the type of error that caused the registration to fail.
string err_msg
This field contains additional information about the reason behind the error.
<IP_ADDRESS>.3 OperationSuccess Fields
string registered_path
This field returns the path that was registered.
<IP_ADDRESS> Register Message Supported Error Codes
Appropriate error codes for the Register Message include 7000-7008, 7016, 7028-7029 and 7800-7999.
7.5.6 The Deregister Message
The Deregister message is an Agent to Controller message used to deregister a previously registered data model at the USP Controller. When a USP Agent terminates, all Services elements will be deregistered automatically by the USP Controller.
A USP Agent can choose to deregister its Service Elements during normal operation or when it terminates.
Note: A Deregister Request does not contain a boolean
allow_partial
, but the Controller will handle each path in
the Deregister Request individually. In other words,
allow_partial
is implicitly set to true
during
the deregistration. The USP Controller will provide information about
the success or failure to deregister each requested path in the
Deregister Response message.
<IP_ADDRESS> Deregister Examples
A USP Agent can deregister several Service Elements with a Deregister Request message.
header {
msg_id: "94522"
msg_type: DEREGISTER
}
body {
request {
deregister {
paths: "Device.Time."
paths: "Device.WiFi.DataElements."
}
}
}
In case the deregistration was successful, the USP Controller will respond with a Deregister Response message.
header {
msg_id: "94522"
msg_type: DEREGISTER_RESP
}
body {
response {
deregister_resp {
deregistered_path_results {
requested_path: "Device.Time."
oper_status {
oper_success {
deregistered_path: "Device.Time."
}
}
}
deregistered_path_results {
requested_path: "Device.WiFi.DataElements."
oper_status {
oper_success {
deregistered_path: "Device.WiFi.DataElements."
}
}
}
}
}
}
<IP_ADDRESS> Deregister Request Fields
repeated string paths
This field contains a set of paths that the USP Agent wants to deregister.
R-DEREG.1 - A USP Agent MUST only deregister Service Elements that it registered with a previous Register message.
R-DEREG.2 - An empty path field MUST be interpreted to deregister all Service Elements belonging to the USP Agent.
R-DEREG.3 - A USP Agent MAY deregister one or more Service Elements with one Deregister Request message containing multiple path fields.
Note: The path field contains an Object Path without any instance numbers. This path doesn’t contain any sub-objects to a multi-instance object.
<IP_ADDRESS> Deregister Response Fields
repeated DeregisteredPathResult deregistered_path_results
This field contains a repeated set of DeregisteredPathResults for each path the USP Agent tried to deregister.
R-DEREG.4 - A USP Controller MUST always respond with a Deregister Response message to a Deregister Request. USP Error messages are not used.
<IP_ADDRESS> DeregisteredPathResult Fields
string requested_path
This field contains the value of the entry of the path (in the Deregister Request) associated with this DeregisteredPathResult.
OperationStatus oper_status
This field contains a message of type OperationStatus.
<IP_ADDRESS>.1 OperationStatus Fields
oneof oper_status
This field contains a message of one of the following types.
OperationFailure oper_failure
Used when the path specified in requested_path failed to be deregistered.
OperationSuccess oper_success
Used when the path specified in requested_path was successfully deregistered.
<IP_ADDRESS>.2 OperationFailure Fields
fixed32 err_code
This field contains a numeric code (Error Codes) indicating the type of error that caused the deregistration to fail.
string err_msg
This field contains additional information about the reason behind the error.
<IP_ADDRESS>.3 OperationSuccess Fields
string deregistered_path
This field returns the path that was deregistered.
<IP_ADDRESS> Deregister Message Supported Error Codes
Appropriate error codes for the Deregister Message include 7000-7008, 7016, 7030 and 7800-7999.
7.6 Notifications and Subscription Mechanism
A Controller can use the Subscription mechanism to subscribe to certain events that occur on the Agent, such as a Parameter change, Object removal, wake-up, etc. When such event conditions are met, the Agent may either send a Notify Message to the Controller, update its own configuration, or perform both actions depending on the Subscription’s configuration.
7.6.1 Using Subscription Objects
Subscriptions are maintained in instances of the Multi-Instance
Subscription Object in the USP data model. The normative requirements
for these Objects are described in the data model Parameter descriptions
for Device.LocalAgent.Subscription.{i}.
in the Device:2
Data Model [39].
R-NOT.0 - The Agent and
Controller MUST follow the normative requirements defined in the
Device.LocalAgent.Subscription.{i}.
Object specified in the
Device:2 Data Model [39].
R-NOT.0a - When considering the time needed to make a state change and trigger a Notification, an implementation SHOULD make changes to its state and initiate a Notification with a window no longer than 10 seconds.
Note: Those familiar with Broadband Forum TR-069 [37] will recall that a notification for a value change caused by an Auto-Configuration Server (ACS - the CWMP equivalent of a Controller) are not sent to the ACS. Since there is only a single ACS notifying the ACS of value changes it requested is unnecessary. This is not the case in USP: an Agent should follow the behavior specified by a subscription, regardless of the originator of that subscription.
<IP_ADDRESS> ReferenceList Parameter
All subscriptions apply to one or more Objects or Parameters in the
Agent’s Instantiated Data Model. These are specified as Path Names or
Search Paths in the ReferenceList
Parameter. The
ReferenceList
Parameter may have different meaning
depending on the nature of the notification subscribed to.
For example, a Controller wants to be notified when a new Wi-Fi
station joins the Wi-Fi network. It uses the Add Message to create an
instance of a Subscription Object with
Device.WiFi.AccessPoint.1.AssociatedDevice.
specified in
the ReferenceList
Parameter and ObjectCreation
as the NotificationType
.
In another example, a Controller wants to be notified whenever an
outside source changes the SSID of a Wi-Fi network. It uses the Add
Message to create an instance of a Subscription Object with
Device.WiFi.SSID.1.SSID
specified in the
ReferenceList
and ValueChange
as the
NotificationType
.
<IP_ADDRESS> TriggerAction Parameter
Subscriptions can be used to define the actions to be performed by
the Agent when an event occurs. This is defined in the
TriggerAction
Parameter. The default is for the Agent to
send a Notify Message, but it
could also perform an update of its own configuration, or both sending
the Notify and performing the configuration.
For example, an Agent may be configure with a Subscription for the
Device.LocalAgent.Threshold.{i}.Triggered!
event such that
when it occurs the Agent both sends a Notify message and configures the
Device.BulkData.Profile.{i}.Enable
to start sending BukData
reports (if defined to do so in the TriggerConfigSettings
Parameter of the Subscription).
7.6.2 Responses to Notifications and Notification Retry
The Notify request contains a flag, send_resp
, that
specifies whether or not the Controller should send a response Message
after receiving a Notify request. This is used in tandem with the
NotifRetry
Parameter in the subscription Object - if
NotifRetry
is true
, then the Agent sends its
Notify requests with send_resp : true
, and the Agent
considers the notification delivered when it receives a response from
the Controller. If NotifRetry
is false
, the
Agent does not need to use the send_resp
flag and should
ignore the delivery state of the notification.
If NotifRetry
is true
, and the Agent does
not receive a response from the Controller, it begins retrying using the
retry algorithm below. The subscription Object also uses a
NotifExpiration
Parameter to specify when this retry should
end if no success is ever achieved.
R-NOT.1 - When retrying notifications, the Agent MUST use the following retry algorithm to manage the retransmission of the Notify request.
The retry interval range is controlled by two Parameters, the minimum wait interval and the interval multiplier, each of which corresponds to a data model Parameter, and which are described in the table below. The factory default values of these Parameters MUST be the default values listed in the Default column. They MAY be changed by a Controller with the appropriate permissions at any time.
| Descriptive Name | Symbol | Default | Data Model Parameter Name |
|---|---|---|---|
| Minimum wait interval | m | 5 seconds | Device.LocalAgent.Controller.{i}.USPNotifRetryMinimumWaitInterval |
| Interval multiplier | k | 2000 | Device.LocalAgent.Controller.{i}.USPNotifRetryIntervalMultiplier |
| Retry Count | Default Wait Interval Range (min-max seconds) | Actual Wait Interval Range (min-max seconds) |
|---|---|---|
| #1 | 5-10 | m - m.(k/1000) |
| #2 | 10-20 | m.(k/1000) - m.(k/1000)^2 |
| #3 | 20-40 | m.(k/1000)^2 - m.(k/1000)^3 |
| #4 | 40-80 | m.(k/1000)^3 - m.(k/1000)^4 |
| #5 | 80-160 | m.(k/1000)^4 - m.(k/1000)^5 |
| #6 | 160-320 | m.(k/1000)^5 - m.(k/1000)^6 |
| #7 | 320-640 | m.(k/1000)^6 - m.(k/1000)^7 |
| #8 | 640-1280 | m.(k/1000)^7 - m.(k/1000)^8 |
| #9 | 1280-2560 | m.(k/1000)^8 - m.(k/1000)^9 |
| #10 and subsequent | 2560-5120 | m.(k/1000)^9 - m.(k/1000)^10 |
R-NOT.2 - Beginning with the
tenth retry attempt, the Agent MUST choose from the fixed maximum range.
The Agent will continue to retry a failed notification until it is
successfully delivered or until the NotifExpiration
time is
reached.
R-NOT.3 - Once a notification is successfully delivered, the Agent MUST reset the retry count to zero for the next notification Message.
R-NOT.4 - If a reboot of the Agent occurs, the Agent MUST reset the retry count to zero for the next notification Message.
7.6.3 Notification Types
There are several types events that can cause a Notify request. These
include those that deal with changes to the Agent’s Instantiated Data
Model (ValueChange
, ObjectCreation
,
ObjectDeletion
), the completion of an asynchronous
Object-defined operation (OperationComplete
), a
policy-defined OnBoardRequest
, and a generic
Event
for use with Object-defined events.
<IP_ADDRESS> ValueChange
The ValueChange
notification is subscribed to by a
Controller when it wants to know that the value of a single or set of
Parameters has changed from the state it was in at the time of the
subscription or to a state as described in an expression, and then each
time it transitions from then on for the life of the subscription. It is
triggered when the defined change occurs, even if it is caused by the
originating Controller.
<IP_ADDRESS> ObjectCreation and ObjectDeletion
These notifications are used for when an instance of the subscribed
to Multi-Instance Objects is added or removed from the Agent’s
Instantiated Data Model. Like ValueChange
, this
notification is triggered even if the subscribing Controller is the
originator of the creation or deletion or the instance was created or
deleted implicitly, e.g. due to a configuration or status change or
indirectly via an unrelated USP Message.
The ObjectCreation
notification also includes the
Object’s Unique Key Parameters and their values.
<IP_ADDRESS> OperationComplete
The OperationComplete
notification is used to indicate
that an asynchronous Object-defined operation finished (either
successfully or unsuccessfully). These operations may also trigger other
Events defined in the data model (see below).
<IP_ADDRESS> OnBoardRequest
An OnBoardRequest
notification is used by the Agent when
it is triggered by an external source to initiate the request in order
to communicate with a Controller that can provide on-boarding procedures
and communicate with that Controller (likely for the first time).
R-NOT.5 - An Agent MUST send an
OnBoardRequest
notify request in the following
circumstances:
When the
SendOnBoardRequest()
command is executed. This sends the notification request to the Controller that is the subject of that operation. TheSendOnBoardRequest()
operation is defined in the Device:2 Data Model [39]. This requirement applies only to those Controller table instances that have theirEnabled
Parameter set totrue
.When instructed to do so by internal application policy (for example, when using DHCP discovery defined above).
Note: as defined in the Subscription table, OnBoardRequest is not included as one of the enumerated types of a Subscription, i.e., it is not intended to be the subject of a Subscription.
R-NOT.6 If a response is required, the OnBoardRequest MUST follow the Retry logic defined above.
<IP_ADDRESS> Event
The Event
notification is used to indicate that an
Object-defined event was triggered on the Agent. These events are
defined in the data model and include what Parameters, if any, are
returned as part of the notification.
7.6.4 The Notify Message
<IP_ADDRESS> Notify Examples
In this example, a Controller has subscribed to be notified of
changes in value to the Device.DeviceInfo.FriendlyName
Parameter. When it is changed, the Agent sends a Notify Request to
inform the Controller of the change.
header {
msg_id: "33936"
msg_type: NOTIFY
}
body {
request {
notify {
subscription_id: "vc-1"
send_resp: true
value_change {
param_path: "Device.DeviceInfo.FriendlyName"
param_value: "MyDevicesFriendlyName"
}
}
}
}
header {
msg_id: "33936"
msg_type: NOTIFY_RESP
}
body {
response {
notify_resp {
subscription_id: "vc-1"
}
}
}
In another example, the event “Boot!”, defined in the
Device.
Object, is triggered. The Agent sends a Notify
Request to the Controller(s) subscribed to that event.
header {
msg_id: "26732"
msg_type: NOTIFY
}
body {
request {
notify {
subscription_id: "boot-1"
send_resp: true
event {
obj_path: "Device."
event_name: "Boot!"
params {
key: "Cause"
value: "LocalReboot"
}
params {
key: "CommandKey"
value: "controller-command-key"
}
params {
key: "ParameterMap"
value: '{"Device.LocalAgent.Controller.1.Enable":"True","Device.LocalAgent.Controller.2.Enable":"False"}'
}
params {
key: "FirmwareUpdated"
value: "false"
}
}
}
}
}
header {
msg_id: "26732"
msg_type: NOTIFY_RESP
}
body {
response {
notify_resp {
subscription_id: "boot-1"
}
}
}
<IP_ADDRESS> Notify Request Fields
string subscription_id
This field contains the locally unique opaque identifier that was set by the Controller when it created the Subscription on the Agent.
R-NOT.7 - The
subscription_id
field MUST contain the Subscription ID of
the Subscription Object that triggered this notification. If no
subscription_id is available (for example, for OnBoardRequest
notifications), this field MUST be set to an empty string.
bool send_resp
This field lets the Agent indicate to the Controller whether or not it expects a response in association with the Notify request.
R-NOT.8 - When
send_resp
is set to false, the Controller SHOULD NOT send a
response or error to the Agent. If a response is still sent, the
responding Controller MUST expect that any such response will be
ignored.
oneof notification
Contains one of the following Notification messages:
Event event
ValueChange value_change
ObjectCreation obj_creation
ObjectDeletion obj_deletion
OperationComplete oper_complete
OnBoardRequest on_board_req
<IP_ADDRESS>.1 Event Fields
string obj_path
This field contains the Object or Object Instance Path of the Object
that caused this event (for example,
Device.LocalAgent.
).
string event_name
This field contains the name of the Object defined event that caused
this notification (for example, Boot!
).
map<string, string> parameters
This field contains a set of key/value pairs of Parameters associated with this event. Refer to Parameter and Argument Value Encoding for details of how Parameter values are encoded as Protocol Buffers v3 strings.
<IP_ADDRESS>.2 ValueChange Fields
string param_path
This field contains the Path Name of the changed Parameter.
string param_value
This field contains the value of the Parameter specified in
param_path
. Refer to Parameter and
Argument Value Encoding for details of how Parameter values are
encoded as Protocol Buffers v3 strings.
<IP_ADDRESS>.3 ObjectCreation Fields
string obj_path
This field contains the Path Name of the created Object Instance.
map<string, string> unique_keys
This field contains a map of key/value pairs for all of this Object’s Unique Key Parameters that are supported by the Agent.
<IP_ADDRESS>.4 ObjectDeletion Fields
string obj_path
This field contains the Path Name of the deleted Object Instance.
<IP_ADDRESS>.5 OperationComplete Fields
string command_name
This field contains the Relative Path of the Object defined command
that caused this notification (i.e., Download()
).
string obj_path
This field contains the Object or Object Instance Path to the Object that contains this operation.
string command_key
This field contains the command key set during an Object defined Operation that caused this notification.
oneof operation_resp
Contains one of the following messages:
OutputArgs req_output_args
CommandFailure cmd_failure
<IP_ADDRESS>.5.1 OutputArgs Fields
map<string, string> output_args
This field contains a map of key/value pairs indicating the output
arguments (relative to the command specified in the
command_name
field) returned by the method invoked in the
Operate Message. Refer to Parameter and Argument Value Encoding for details of
how argument values are encoded as Protocol Buffers v3 strings.
<IP_ADDRESS>.5.2 CommandFailure Fields
fixed32 err_code
This field contains a numeric code (see Error Codes) indicating the type of the error that
caused the operation to fail. Appropriate error codes for CommandFailure
include 7002-7008
, 7016
, 7022
,
7023
, and 7800-7999
. Error 7023
is reserved for asynchronous operations that were canceled by a
Controller invoking the Cancel() command on the appropriate Request
Object (see Asynchronous Operations).
string err_msg
This field contains additional (human readable) information about the reason behind the error.
<IP_ADDRESS>.6 OnBoardRequest Fields
string oui
This field contains the Organizationally Unique Identifier associated with the Agent.
string product_class
This field contains a string used to provide additional context about the Agent.
string serial_number
This field contains a string used to provide additional context about the Agent.
string agent_supported_protocol_versions
A comma separated list of USP Protocol Versions (major.minor) supported by this Agent.
<IP_ADDRESS> Notify Response Fields
string subscription_id
This field contains the Subscription ID that was received with the Notify Request.
R-NOT.9 -The Agent SHOULD ignore the subscription_id field.
Note: The requirement in the previous versions of the specification requiring the Agent to check this subscription_id field has been deprecated. However for backward compatibility the Controller is still required to send the matching subscription_id.
R-NOT.10 - The Controller MUST populate the subscription_id field with the same Subscription ID as was presented in the Notify Request.
<IP_ADDRESS> Notify Error Codes
Appropriate error codes for the Notify Message include
7000-7006
, and 7800-7999
.
7.7 Defined Operations Mechanism
Additional methods (operations) are and can be defined in the USP data model. Operations are generally defined on an Object, using the “command” attribute, as defined in [38]. The mechanism is controlled using the Operate Message in conjunction with the Multi-Instance Request Object.
7.7.1 Synchronous Operations
A synchronous operation is intended to complete immediately following
its processing. When complete, the output arguments are sent in the
Operate response. If the send_resp
flag is false, the
Controller doesn’t need the returned information (if any), and the Agent
does not send an Operate Response.
7.7.2 Asynchronous Operations
An asynchronous operation expects to take some processing on the
system the Agent represents and will return results at a later time.
When complete, the output arguments are sent in a Notify
(OperationComplete
) request to any Controllers that have an
active subscription to the operation and Object(s) to which it
applies.
When a Controller using the Operate request specifies an operation
that is defined as asynchronous, the Agent creates an instance of the
Request Object in its data model, and includes a reference to the
created Object in the Operate response. If the send_resp
flag is false
, the Controller doesn’t need the Request
details, and intends to ignore it.
The lifetime of a Request Object expires when the operation is complete (either by success or failure). An expired Request Object is removed from the Instantiated Data Model.
R-OPR.0 - When an Agent receives an Operate Request that addresses an asynchronous operation, it MUST create a Request Object in the Request table of its Instantiated Data Model (see the Device:2 Data Model [39]). When the Operation is complete (either success or failure), it MUST remove this Object from the Request table.
If any Controller wants a notification that an operation has
completed, it creates a Subscription Object with the
NotificationType
set to OperationComplete
and
with the ReferenceList
Parameter including a Path Name to
the specified command. The Agent processes this Subscription when the
operation completes and sends a Notify Message, including the
command_key
value that the Controller assigned when making
the Operate request.
A Controller can cancel a request that is still present in the
Agent’s Device.LocalAgent.Request.
table by invoking the
Device.LocalAgent.Request.{i}.Cancel()
command through
another Operate Message.
<IP_ADDRESS> Persistance of Asynchronous Operations
Synchronous Operations do not persist across a reboot or restart of the Agent or its underlying system. It is expected that Asynchronous Operations do not persist, and a command that is in process when the Agent is rebooted can be expected to be removed from the Request table, and is considered to have failed. If a command is allowed or expected to be retained across a reboot, it will be noted in the command description.
7.7.3 Operate Requests on Multiple Objects
Since the Operate request can take a Path Name expression as a value
for the command field, it is possible to invoke the same operation on
multiple valid Objects as part of a single Operate request. Responses to
requests to Operate on more than one Object are handled using the
OperationResult
field type, which is returned as a repeated
set in the Operate Response. The success or failure of the operation on
each Object is handled separately and returned in a different
OperationResult
entry. For this reason, operation failures
are never conveyed in an Error Message - in reply to an Operate request,
Error is only used when the Message itself fails for one or more
reasons, rather than the operation invoked.
Note: This specification does not make any requirement on the order in which commands on multiple objects selected with a Path Name expression are executed.
R-OPR.1 - When processing Operate
Requests on multiple Objects, an Agent MUST NOT send an Error Message
due to a failed operation. It MUST instead include the failure in the
cmd_failure
field of the Operate response.
R-OPR.2 - For asynchronous operations the Agent MUST create a separate Request Object for each Object and associated operation matched in the command field.
7.7.4 Event Notifications for Operations
When an operation triggers an Event notification, the Agent sends the Event notification for all subscribed recipients as described in Notifications and Subscription Mechanism.
7.7.5 Concurrent Operations
If an asynchronous operation is triggered multiple times by one or more Controllers, the Agent has the following options:
- Deny the new operation (with, for example,
7005 Resources Exceeded
) - The operations are performed in parallel and independently.
- The operations are queued and completed in order.
R-OPR.3 - When handling
concurrently invoked operations, an Agent MUST NOT cancel an operation
already in progress unless explicitly told to do so by a Controller with
permission to do so (i.e., via the
Device.LocalAgent.Request.{i}.Cancel()
operation).
7.7.6 Operate Examples
In this example, the Controller requests that the Agent initiate the
SendOnBoardRequest() operation defined in the
Device.LocalAgent.Controller.
Object.
header {
msg_id: "42314"
msg_type: OPERATE
}
body {
request {
operate {
command: 'Device.LocalAgent.Controller.[EndpointID=="controller"].SendOnBoardRequest()'
command_key: "onboard_command_key"
send_resp: true
}
}
}
header {
msg_id: "42314"
msg_type: OPERATE_RESP
}
body {
response {
operate_resp {
operation_results {
executed_command: "Device.SelfTestDiagnostics()"
req_obj_path: "Device.LocalAgent.Request.1"
}
}
}
}
7.7.7 The Operate Message
<IP_ADDRESS> Operate Request Fields
string command
This field contains a Command Path or Search Path to an Object defined Operation in one or more Objects.
string command_key
This field contains a string used as a reference by the Controller to match the operation with notifications.
bool send_resp
This field lets the Controller indicate to Agent whether or not it expects a response in association with the operation request.
R-OPR.4 - When
send_resp
is set to false
, the target Endpoint
SHOULD NOT send an OperateResp
Message to the source
Endpoint. If an error occurs during the processing of an
Operate
Message, the target Endpoint SHOULD send an
Error
Message to the source Endpoint. If a response is
still sent, the responding Endpoint MUST expect that any such response
will be ignored.
Note: The requirement in the previous versions of the
specification also discouraged the sending of an Error
Message, however the Controller issuing the Operate
might
want to learn about and handle errors occurring during the processing of
the Operate
request but still ignore execution
results.
map<string, string> input_args
This field contains a map of key/value pairs indicating the input arguments (relative to the Command Path in the command field) to be passed to the method indicated in the command field.
R-OPR.5 - A Command
can have mandatory input_args
as defined in the Supported
Data Model. When a mandatory Input argument is omitted from the
input_args
field, the Agent MUST respond with an
Error
of type 7004 Invalid arguments
and stop
processing the Operate
Message.
R-OPR.6 - When an unrecognized
Input argument is included in the input_args
field, the
Agent MUST ignore the Input argument and continue processing the
Operate
Message.
R-OPR.7 - When a non-mandatory
Input argument is omitted from the input_args
field, the
Agent MUST use a default value for the missing Input argument and
continue processing the Operate
Message.
Refer to Parameter and Argument Value Encoding for details of how argument values are encoded as Protocol Buffers v3 strings.
<IP_ADDRESS> Operate Response Fields
repeated OperationResult operation_results
This field contains a repeated set of OperationResult
messages.
<IP_ADDRESS>.1 OperationResult Fields
string executed_command
This field contains a Command Path to the Object defined Operation
that is the subject of this OperateResp
message.
oneof operate_resp
This field contains a message of one of the following types.
string req_obj_path
OutputArgs req_output_args
CommandFailure cmd_failure
<IP_ADDRESS>.1.1 Using req_obj_path
The req_obj_path field, when used as the operate_resp
,
contains an Object Instance Path to the Request Object created as a
result of this asynchronous operation.
<IP_ADDRESS>.1.2 OutputArgs Fields
map<string, string> output_args
This field contains a map of key/value pairs indicating the output
arguments (relative to the command specified in the command
field) returned by the method invoked in the Operate Message. Refer to
Parameter and
Argument Value Encoding for details of how argument values are
encoded as Protocol Buffers v3 strings.
<IP_ADDRESS>.1.3 CommandFailure Fields
fixed32 err_code
This field contains a numeric code (see Error Codes) indicating the type of the error that caused the operation to fail.
string err_msg
This field contains additional (human readable) information about the reason behind the error.
<IP_ADDRESS> Operate Message Error Codes
Appropriate error codes for the Operate Message include
7000-7008
, 7016
, 7022
,
7026
, 7027
, and 7800-7999
.
7.8 Error Codes
USP uses error codes with a range 7000-7999 for both Controller and Agent errors. The errors appropriate for each Message (and how they must be implemented) are defined in the message descriptions below.
| Code | Name | Applicability | Description |
|---|---|---|---|
7000 |
Message failed | Error Message | This error indicates a general failure that is described in an err_msg field. |
7001 |
Message not supported | Error Message | This error indicates that the attempted message was not understood by the target Endpoint. |
7002 |
Request denied (no reason specified) | Error Message | This error indicates that the target Endpoint cannot or will not process the message. |
7003 |
Internal error | Error Message | This error indicates that the message failed due to internal hardware or software reasons. |
7004 |
Invalid arguments | Error Message | This error indicates that the message failed due to invalid values in the USP message. |
7005 |
Resources exceeded | Error Message | This error indicates that the message failed due to memory or processing limitations on the target Endpoint. |
7006 |
Permission denied | Error Message | This error indicates that the source Endpoint does not have the authorization for this action. |
7007 |
Invalid configuration | Error Message | This error indicates that the message failed because processing the message would put the target Endpoint in an invalid or unrecoverable state. |
7008 |
Invalid path syntax | any requested_path | This error indicates that the Path Name used was not understood by the target Endpoint. |
7009 |
Parameter action failed | Set | This error indicates that the Parameter failed to update for a general reason described in an err_msg field. |
7010 |
Unsupported parameter | Add, Set | This error indicates that the requested Path Name associated with this ParamError or ParameterError did not match any instantiated Parameters. |
7011 |
Invalid type | Add, Set | This error indicates that the received string can not be interpreted as a value of the correct type expected for the Parameter. |
7012 |
Invalid value | Add, Set | This error indicates that the requested value was not within the acceptable values for the Parameter. |
7013 |
Attempt to update non-writeable parameter | Add, Set | This error indicates that the source Endpoint attempted to update a Parameter that is not defined as a writeable Parameter. |
7014 |
Value conflict | Add, Set | This error indicates that the requested value would result in an invalid configuration based on other Parameter values. |
7015 |
Operation error | Add, Set, Delete | This error indicates a general failure in the creation, update, or deletion of an Object that is described in an err_msg field. |
7016 |
Object does not exist | Any | This error indicates that the requested Path Name did not address an Object in the Agent’s Instantiated Data Model. |
7017 |
Object could not be created | Add | This error indicates that the operation failed to create an instance of the specified Object. |
7018 |
Object is not a table | Add, GetInstances | This error indicates that the requested Path Name is not a Multi-Instance Object. |
7019 |
Attempt to create non-creatable object | Add | This error indicates that the source Endpoint attempted to create an Object that is not defined as able to be created. |
7020 |
Object could not be updated | Set | This error indicates that the requested Object in a Set request failed to update. |
7021 |
Required parameter failed | Add, Set | This error indicates that the request failed on this Object because one or more required Parameters failed to update. Details on the failed Parameters are included in an associated ParamError or ParameterError message. |
7022 |
Command failure | Operate | This error indicates that an command initiated in an Operate Request failed to complete for one or more reasons explained in the err_msg field. |
7023 |
Command canceled | Operate | This error indicates that an asynchronous command initiated in an Operate Request failed to complete because it was cancelled using the Cancel() operation. |
7024 |
Delete failure | Delete | This error indicates that this Object Instance failed to be deleted. |
7025 |
Object exists with duplicate key | Add, Set | This error indicates that an Object already exists with the Unique Keys specified in an Add or Set Message. |
7026 |
Invalid path | Any | This error indicates that the Object, Parameter, or Command Path Name specified does not match any Objects, Parameters, or Commands in the Agent’s Supported Data Model |
7027 |
Invalid command arguments | Operate | This error indicates that an Operate Message failed due to invalid or unknown arguments specified in the command. |
7028 |
Register failure | Register | This error indicates that a path in a Register Request failed to be registered for one or more reasons explained in the err_msg field. |
7029 |
Already in use | Register | This error indicates that a path in a Register Request failed to be registered, because it was registered by a different USP Agent |
7030 |
Deregister failure | Deregister | This error indicates that a path in a Deregister Request failed to be deregistered for one or more reasons explained in the err_msg field. |
7031 |
Path already registered | Deregister | This error indicates that a path in a Deregister Request failed to be deregistered, because it was registered by a different USP Agent. |
7100-7199 |
USP Record error codes | - | These errors are listed and described in USP Record Errors. |
7200-7299 |
Data model defined error codes | - | These errors are described in the data model. |
7800-7999 |
Vendor defined error codes | - | These errors are described in Vendor Defined Error Codes. |
7.8.1 Vendor Defined Error Codes
Implementations of USP MAY specify their own error codes for use with
Errors and Responses. These codes use the 7800-7999
series.
There are no requirements on the content of these errors.
8 Authentication and Authorization
USP contains mechanisms for Authentication and Authorization, and Encryption. Encryption can be provided at the MTP layer, the USP layer, or both. Where Endpoints can determine (through Authentication) that the termination points of the MTP and USP messages are the same, MTP encryption is sufficient to provide end-to-end encryption and security. Where the termination points are different (because there is a proxy or other intermediate device between the USP Endpoints), USP layer End to End Message Exchange is required, or the intermediate device must be a trusted part of the end-to-end ecosystem.
8.1 Authentication
Authentication of Controllers is done using X.509 certificates as defined in [20] and [27]. Authentication of Agents is done either by using X.509 certificates or shared secrets. X.509 certificates, at a minimum, need to be usable for Securing MTPs with TLS or DTLS protocols. It is recommended that Agents implement the ability to encrypt all MTPs using one of these two protocols, enable it by default, and not implement the ability to disable it.
In order to support various authentication models (e.g., trust
Endpoint identity and associated certificate on first use; precise
Endpoint identity is indicated in a certificate issued by a trusted
Certificate Authority; trust that MTP connection is being made to a
member of a trusted domain as verified by a trusted Certificate
Authority (CA)), this specification provides guidance based on
conditions under which the Endpoint is operating, and on the Endpoint’s
policy for storing certificates of other Endpoints or certificates of
trusted CAs. The Device.LocalAgent.Certificate.
Object can
be implemented if choosing to expose these stored certificates through
the data model. See the Theory of Operations, Certificate
Management subsection, below for additional information.
R-SEC.0 - Prior to processing a USP Message from a Controller, the Agent MUST either:
- have the Controller’s certificate information and have a cryptographically protected connection between the two Endpoints, or
- have a Trusted Broker’s certificate information and have a cryptographically protected connection between the Agent and the Trusted Broker
R-SEC.0a - Whenever a X.509
certificate is used to authenticate a USP Endpoint, the certificate MUST
contain a representation of the Endpoint ID in the
subjectAltName
extension. This representation MUST be
either the URN form of the Endpoint ID with a type
uniformResourceIdentifier
attribute OR, in the specific
case where the Endpoint ID has an authority-scheme
of
fqdn
, the instance-id
portion of the Endpoint
ID with a type dNSName
attribute. When this type of
authentication is used at the MTP layer, USP Endpoints MUST check the
from_id
field of received USP Records and MUST NOT process
Records that do not match the Endpoint ID found in the certificate.
TLS and DTLS both have handshake mechanisms that allow for exchange
of certificate information. If the MTP connection is between the Agent
and Controller (for example, without going through any application-layer
proxy or other intermediate application-layer middle-box), then a secure
MTP connection will be sufficient to ensure end-to-end protection, and
the USP Record can use payload_security
“PLAINTEXT”
encoding of the Message. If the middle-box is part of a trusted
end-to-end ecosystem, the MTP connection may also be considered
sufficient. Otherwise, the USP Record will use End to End Message
Exchange.
Whether a Controller requires Agent certificates is left up to the Controller implementation.
8.2 Role Based Access Control (RBAC)
It is expected that Agents will have some sort of Access Control List (ACL) that will define different levels of authorization for interacting with the Agent’s data model. This specification refers to different levels of authorization as “Roles”. The Agent may be so simple as to only support a single Role that gives full access to its data model; or it may have just an “untrusted” Role and a “full access” Role. Or it may be significantly more complex with, for example, “untrusted” Role, different Roles for parents and children in a customer household, and a different Role for the service provider Controller. These Roles may be fully defined in the Agent’s code, or Role definition may be allowed via the data model.
R-SEC.1 - An Agent MUST confirm a Controller has the necessary permissions to perform the requested actions in a Message prior to performing that action.
R-SEC.1a - Agents SHOULD
implement the Controller
Object with the
AssignedRole
Parameter (with at least read-only data model
definition) and InheritedRole
Parameter (if allowed Roles
can come from a trusted CA), so users can see what Controllers have
access to the Agent and their permissions. This will help users identify
rogue Controllers that may have gained access to the Agent.
See the Theory of Operations, Roles (Access Control) and Assigning Controller Roles subsections, below for additional information on data model elements that can be implemented to expose information and allow control of Role definition and assignment.
8.3 Trusted Certificate Authorities
An Endpoint can have a configured list of trusted Certificate Authority (CA) certificates. The Agent policy may trust the CA to authorize authenticated Controllers to have a specific default Role, or the policy may only trust the CA to authenticate the Controller identity. The Controller policy may require an Agent certificate to be signed by a trusted CA before the Controller exchanges USP Messages with the Agent.
R-SEC.2 - To confirm a certificate was signed by a trusted CA, the Endpoint MUST contain information from one or more trusted CA certificates that are either pre-loaded in the Endpoint or provided to the Endpoint by a secure means. At a minimum, this stored information will include a certificate fingerprint and fingerprint algorithm used to generate the fingerprint. The stored information MAY be the entire certificate.
This secure means can be accomplished through USP (see Theory of
Operations), Certificate Management subsection, making use of the
Device.LocalAgent.Certificate.
Object), or through a
mechanism external to USP. The stored CA certificates can be root or
intermediate CAs.
R-SEC.3 - Where a CA is trusted to authenticate Controller identity, the Agent MUST ensure that the Controller certificate conforms with the R-SEC.0a requirement.
R-SEC.4 - Where a CA is trusted
to authorize a Controller Role, the Agent MUST ensure either that the
Controller certificate matches the certificate stored in the
Credential
Parameter of the
Device.LocalAgent.Controller.
entry specific to that
Controller OR that the Controller certificate itself is suitable for
authentication as per the R-SEC.0a requirement.
Note that trusting a CA to authorize a Controller Role requires the
Agent to maintain an association between a CA certificate and the
Role(s) that CA is trusted to authorize. If the Agent allows CAs to
authorize Roles, the Agent will need to identify specific CA
certificates in a Controller’s chain of trust that can authorize Roles.
The specific Role(s) associated with such a CA certificate can then be
inherited by the Controller. The
Device.LocalAgent.ControllerTrust.Credential.
Object can be
implemented to expose and allow control over trust and authorization of
CAs.
Note that if an Agent supports and has enabled a Trust on First Use (TOFU) policy, it is possible for Controllers signed by unknown CAs to be granted the “untrusted role”. See Figure 22 and Figure 23 and the penultimate bullet in the Assigning Controller Roles section below for more information related to TOFU and the “untrusted” role.
8.4 Trusted Brokers
An Endpoint can have a configured list of Trusted Broker
certificates. The Endpoint policy would be to trust the broker to vouch
for the identity of Endpoints it brokers – effectively authenticating
the from_id
contained in a received USP Record. The Agent
policy may trust the broker to authorize all Controllers whose Records
transit the broker to have a specific default Role.
R-SEC.4a - To confirm a certificate belongs to a Trusted Broker, the Endpoint MUST contain information from one or more Trusted Broker certificates that are either pre-loaded in the Endpoint or provided to the Endpoint by a secure means. This stored information MUST be sufficient to determine if a presented certificate is the Trusted Broker certificate.
This secure means of loading certificate information into an Agent can be accomplished through USP (see Theory of Operations section related to Certificate Management), or through a mechanism external to USP.
Note that trusting a broker to authorize a Controller Role requires
the Agent to maintain an association between a Trusted Broker
certificate and the Role(s) that Trusted Broker is trusted to authorize.
The Device.LocalAgent.ControllerTrust.Credential.
Object
can be implemented to expose and allow control over identifying Trusted
Brokers. The AllowedUses
Parameter is used to indicate
whether an entry is a Trusted Broker.
R-SEC.4b - A Trusted Broker MUST confirm the identity of all clients by exclusively allowing authentication via unique client certificates that identify the USP Endpoint. Also the confidentiality of all communications MUST be guaranteed by a Trusted Broker, i.e. there MUST NOT be any possibility to forward the communication between Endpoints to another party.
R-SEC.4c - A Trusted Broker MUST
guarantee that USP Records sent from clients contain the correct value
for the from_id
field, tying it to the identity provided
during the connection establishment. A Trusted Broker MUST NOT inspect
USP payloads contained in USP Records.
8.5 Self-Signed Certificates
R-SEC.5 - An Endpoint that generates a self-signed certificate MUST ensure that the certificate is suitable for USP authentication as per the R-SEC.0a requirement.
Self-signed certificates supplied by Controllers can only be meaningfully used in cases where a person is in a position to provide Authorization (what Role the Controller is trusted to have). Whether or not an Agent allows self-signed certificates from a Controller is a matter of Agent policy.
R-SEC.6 - If an Agent allows Controllers to provide self-signed certificates, the Agent MUST assign such Controllers an “untrusted” Role on first use.
That is, the Agent will trust the certificate for purpose of encryption, but will heavily restrict what the Controller is authorized to do. See Figure 22 and Figure 23 and the penultimate bullet in the Assigning Controller Roles section below for more information related to TOFU and the “untrusted” role.
R-SEC.7 - If an Agent allows Controllers to provide self-signed certificates, the Agent MUST have a means of allowing an external entity to change the Role of each such Controller.
Controller policy related to trust of Agent self-signed certificates is left to the Controller. Controllers may be designed to refuse self-signed certificates (thereby refusing to control the Agent), they may have a means of allowing a person to approve controlling the Agent via the Controller, or they may automatically accept the Agent.
R-SEC.8 - An Endpoint that accepts self-signed certificates MUST maintain the association of accepted certificate and Endpoint IDs.
Self-signed certificates require a “trust on first use” (TOFU) policy
when using them to authenticate an Endpoint’s identity. An external
entity (a trusted Controller or user) can then authorize the
authenticated Endpoint to have certain permissions. Subsequent to the
first use, this same self-signed certificate can be trusted to establish
the identity of that Endpoint. However, authentication of the Endpoint
can only be subsequently trusted if the association of certificate to
identity is remembered (i.e., it is known this is the same certificate
that was used previously by that Endpoint). If it is not remembered,
then every use is effectively a first use and would need to rely on an
external entity to authorize permissions every time. The
Device.LocalAgent.Certificate.
Object can be implemented if
choosing to expose and allow control of remembered certificates in the
data model.
8.6 Agent Authentication
R-SEC.9 - Controllers MUST authenticate Agents either through X.509 certificates, a shared secret, or by trusting a Trusted Broker to vouch for Agent identity.
When authentication is done using X.509 certificates, it is up to Controller policy whether to allow for Agents with self-signed certificates or to require Agent certificates be signed by a CA.
Note that allowing use of, method for transmitting, and procedure for handling shared secrets is specific to the MTP used, as described in Message Transfer Protocols. Shared secrets that are not unique per device are not recommended as they leave devices highly vulnerable to various attacks – especially devices exposed to the Internet.
R-SEC.10 - An Agent certificate MUST be suitable for USP authentication as per the R-SEC.0a requirement.
R-SEC.10a - The certificate
subjectAltName
extension MUST be used to authenticate the
USP Record from_id
for any Records secured with an Agent
certificate.
Agent certificates can be used to secure Records by encrypting at the MTP layer and/or encrypting at the USP layer.
Some Controller implementations may allow multiple Agents to share a single certificate with a wildcarded Endpoint ID.
R-SEC.11 - If a single
certificate is shared among multiple Agents, those Agents MUST include a
wild-carded instance-id
in the Endpoint ID in the
subjectAltName
extension with identical
authority-scheme
and authority-id
.
Use of a shared certificate is not recommended, and which portion of
the instance-id
can be wildcarded may be specific to the
authorizing CA or to the authority-id
and
authority-scheme
values of the Endpoint ID. Wildcards can
only be allowed in cases where the assigning entity is explicitly
identified. Controllers are not required to support wildcarded
certificates.
R-SEC.12 - If a wildcard
character is present in the instance-id
of an Endpoint ID
in a certificate subjectAltName
extension, the
authority-scheme
MUST be one of “oui”, “cid”, “pen”, “os”,
or “ops”. In the case of “os” and “ops”, the portion of the
instance-id
that identifies the assigning entity MUST NOT
be wildcarded.
8.7 Challenge Strings and Images
It is possible for the Agent to allow an external entity to change a Controller Role by means of a Challenge string or image. This Challenge string or image can take various forms, including having a user supply a passphrase or a PIN. Such a string could be printed on the Agent packaging, or supplied by means of a SMS to a phone number associated with the user account. These Challenge strings or images can be done using USP operations. Independent of how challenges are accomplished, following are some basic requirements related to Challenge strings and images.
R-SEC.13 - The Agent MAY have factory-default Challenge value(s) (strings or images) in its configuration.
R-SEC.14 - A factory-default Challenge value MUST be unique to the Agent. Re-using the same passphrase among multiple Agents is not permitted.
R-SEC.15 - A factory-default Challenge value MUST NOT be derivable from information the Agent communicates about itself using any protocol at any layer.
R-SEC.16 - The Agent MUST limit the number of tries for the Challenge value to be supplied successfully.
R-SEC.17 - The Agent SHOULD have policy to lock out all use of Challenge values for some time, or indefinitely, if the number of tries limit is exceeded.
See the Theory of Operations, Challenges subsection, below for a description of data model elements that need to be implemented and are used when doing challenges through USP operations.
8.8 Analysis of Controller Certificates
An Agent will analyze Controller certificates to determine if they are valid, are appropriate for authentication of Controllers, and to determine what permissions (Role) a Controller has. The Agent will also determine whether MTP encryption is sufficient to provide end-to-end protection of the Record and Message, or if USP layer End to End Message Exchange is required.
The diagrams in this section use the database symbol to identify where the described information can be represented in the data model, if an implementation chooses to expose this information through the USP protocol.
8.8.1 Receiving a USP Record
R-SEC.19 - An Agent capable of obtaining absolute time SHOULD wait until it has accurate absolute time before contacting a Controller. If an Agent for any reason is unable to obtain absolute time, it can contact the Controller without waiting for accurate absolute time. If an Agent chooses to contact a Controller before it has accurate absolute time (or if it does not support absolute time), it MUST ignore those components of the Controller certificate that involve absolute time, e.g. not-valid-before and not-valid-after certificate restrictions.
R-SEC.20 - An Agent that has obtained accurate absolute time MUST validate those components of the Controller certificate that involve absolute time.
R-SEC.21 – An Agent MUST clear all cached encryption session and Role authorization information when it reboots.
R-SEC.22 - When an Agent receives a USP Record, the Agent MUST execute logic that achieves the same results as in the mandatory decision flow elements (identified with “MUST”) from Figure 19 and Figure 20.
R-SEC.22a - When an Agent receives a USP Record, the Agent SHOULD execute logic that achieves the same results as in the optional decision flow elements (identified with “OPT”) from Figure 19 and Figure 20.
8.8.2 Sending a USP Record
R-SEC.23 - When an Agent sends a USP Record, the Agent MUST execute logic that achieves the same results as in the mandatory decision flow elements (identified with “MUST”) from Figure 21.
R-SEC.23a - When an Agent sends a USP Record, the Agent SHOULD execute logic that achieves the same results as in the optional decision flow elements (identified with “OPT”) from Figure 21.
8.8.3 Checking a Certificate
R-SEC.24 - When an Agent analyzes a Controller certificate for authentication and determining permissions (Role), the Agent MUST execute logic that achieves the same results as in the mandatory decision flow elements (identified with “MUST”) from Figure 22 and Figure 23.
R-SEC.24a - When an Agent analyzes a Controller certificate for authentication and determining permissions (Role), the Agent SHOULD execute logic that achieves the same results as in the optional decision flow elements (identified with “OPT”) from Figure 22 and Figure 23.
R-SEC.25 - When determining the inherited Role to apply based on Roles associated with a trusted CA, only the first matching CA in the chain will be used.
8.8.4 Using a Trusted Broker
Support for Trusted Broker logic is optional.
R-SEC.26 - If Trusted Brokers are supported, and a Trusted Broker is encountered (from the optional “OPT” “Trusted Broker cert?” decision diamonds in Figure 20, Figure 21) the Agent MUST execute logic that achieves the same results as in the mandatory decision flow elements (identified with “MUST”) from Figure 24 for a received USP Record and Figure 25 for sending a USP Record.
R-SEC.26a - If Trusted Brokers are supported, and a Trusted Broker is encountered (from the optional “OPT” “Trusted Broker cert?” decision diamonds in Figure 20, Figure 21) the Agent SHOULD execute logic that achieves the same results as in the optional decision flow elements (identified with “OPT”) from Figure 24 for a received USP Record and Figure 25 for sending a USP Record.
8.9 Theory of Operations
The following theory of operations relies on Objects, Parameters,
events, and operations from the LocalAgent
Object of the
Device:2 Data Model [39].
8.9.1 Data Model Elements
These data model elements play a role in reporting on and allowing control of trusted Controllers and the permissions they have to read and write parts of the Agent’s data model, and allowing an Agent to establish trust with a Controller.
LocalAgent.Controller.{i}.AssignedRole
ParameterLocalAgent.Controller.{i}.InheritedRole
ParameterLocalAgent.Controller.{i}.Credential
Parameter
From component ControllerTrust
:
- Object
LocalAgent.ControllerTrust.
- Parameters
UntrustedRole
,BannedRole
,SecuredRoles
,TOFUAllowed
,TOFUInactivityTimer
- Commands
RequestChallenge()
,ChallengeResponse()
- Object
LocalAgent.ControllerTrust.Role.{i}.
- Object
LocalAgent.ControllerTrust.Credential.{i}.
- Object
LocalAgent.ControllerTrust.Challenge.{i}.
The Object LocalAgent.Certificate.
can be used to manage
Controller and CA certificates, along with the
LocalAgent.AddCertificate()
and
LocalAgent.Controller.{i}.AddMyCertificate()
commands.
For brevity, Device.LocalAgent.
is not placed in front
of all further Object references in this Security section. However, all
Objects references are under Device.LocalAgent.
. This
section does not describe use of Parameters under other top level
components.
8.9.2 Roles (Access Control)
Controller permissions are conveyed in the data model through Roles.
<IP_ADDRESS> Role Definition
A Role is described in the data model through use of the
ControllerTrust.Role.{i}.
Object. Each entry in this Object
identifies the Role it describes, and has a Permission.
Sub-Object for the Targets
(data model Path Names that the
related permissions apply to), permissions related to Parameters,
Objects, instantiated Objects, and commands identified by the
Targets
Parameter, and the relative Order
of
precedence among Permission.
entries for the Role (the
larger value of this Parameter takes priority over an entry with a
smaller value in the case of overlapping Targets
entries
for the Role).
The permissions of a Role for the specified Target
entries are described by Param
, Obj
,
InstantiatedObj
, and CommandEvent
Parameters.
Each of these is expressed as a string of 4 characters where each
character represents a permission (“r
” for Read,
“w
” for Write, “x
” for Execute”, and
“n
” for Notify). The 4 characters are always presented in
the same order in the string (rwxn
) and the lack of a
permission is signified by a “-
” character (e.g.,
r--n
). How these permissions are applied to Parameters,
Objects, and various Messages is described in the data model description
of these Parameters.
An Agent that wants to allow Controllers to define and modify Roles
will implement the ControllerTrust.Role.{i}.
Object with
all of the Parameters listed in the data model. In order for a
Controller to define or modify Role entries, it will need to be assigned
a Role that gives it the necessary permission. Care should be taken to
avoid defining this Role’s permissions such that an Agent with this Role
can modify the Role and no longer make future modifications to the
ControllerTrust.Role.{i}.
Object.
A simple Agent that only wants to inform Controllers of pre-defined
Roles (with no ability to modify or define additional Roles) can
implement the ControllerTrust.Role.
Object with read-only
data model definition for all entries and Parameters. A simple Agent
could even implement the Object with read-only data model definition and
just the Alias
and Role
Parameters, and no
Permission.
Sub-Object; this could be sufficient in a case
where the Role names convey enough information (e.g., there are only two
pre-defined Roles named "Untrusted"
and
"FullAccess"
).
<IP_ADDRESS> Special Roles
Three special Roles are identified by the UntrustedRole
,
BannedRole
and SecuredRoles
Parameters under
the ControllerTrust.
Object. An Agent can expose these
Parameters with read-only data model implementation if it simply wants
to tell Controllers the names of these specific Roles.
The UntrustedRole
is the Role the Agent will
automatically assign to any Controller that has not been authorized for
a different Role. Any Agent that has a means of allowing a Controller’s
Role to be changed (by users through a Challenge string, by other
Controllers through modification of
Controller.{i}.AssignedRole
, or through some other external
means) and that allows “unknown” Controllers to attach will need to have
an “untrusted” Role defined; even if the identity of this Role is not
exposed to Controllers through implementation of the
UntrustedRole
Parameter.
The BannedRole
(if implemented) is assigned
automatically by the Agent to Controllers whose certificates have been
revoked. If it is not implemented, the Agent can use the
UntrustedRole
for this, as well. It is also possible to
simply implement policy for treatment of invalid or revoked certificates
(e.g., refuse to connect), rather than associate them with a specific
Role. This is left to the Agent policy implementation.
The SecuredRoles
(if implemented) is the Role assigned
to Controllers that are authorized to have access to
secured
Parameter values. If the SecuredRoles
is not assigned to a given Controller, or if the
SecuredRoles
is not implemented, then secured
Parameters are to be considered as hidden
, in which case
the Agent returns a null value, e.g. an empty string, to this
Controller, regardless of the actual value. Only Controllers with a
secured Role assigned (and the appropriate permissions set), are able to
have access to secured parameter values.
<IP_ADDRESS> A Controller’s Role
A Controller’s assigned Roles can be conveyed by the
Controller.{i}.AssignedRole
Parameter. This Parameter is a
list of all Role values assigned to the Controller through means other
than ControllerTrust.Credential.{i}.Role
. A Controller’s
inherited Roles (those inherited from
ControllerTrust.Credential.{i}.Role
as described in the
next section) need to be maintained separately from assigned Roles and
can be conveyed by the Controller.{i}.InheritedRole
Parameter. Where multiple assigned and inherited Roles have overlapping
Targets
entries, the resulting permission is the union of
all assigned and inherited permissions. For example, if two Roles have
the same Targets
with one Role assigning the
Targets
Param
a value of r---
and
the other Role assigning Param
a value of
---n
, the resulting permission will be r--n
.
This is done after determining which
ControllerTrust.Role.{i}.Permission.{i}
entry to apply for
each Role for specific Targets
, in the case where a Role
has overlapping Permission.{i}.Targets
entries for the same
Role.
For example, Given the following
ControllerTrust.Role.{i}.
entries:
i=1, Role = "A"; Permission.1.: Targets = "Device.LocalAgent.", Order = 3, Param = "r---"
i=1, Role = "A"; Permission.2.: Targets = "Device.LocalAgent.Controller.", Order = 55, Param = "r-xn"
i=3, Role = "B"; Permission.1: Targets = "Device.LocalAgent.", Order = 20, Param = "r---"
i=3, Role = "B"; Permission.5: Targets = "Device.LocalAgent.Controller.", Order = 78, Param = "----"
and Device.LocalAgent.Controller.1.AssignedRole
=
“Device.LocalAgent. ControllerTrust.Role.1., Device.LocalAgent.
ControllerTrust.Role.3.”
When determining permissions for the
Device.LocalAgent.Controller.
table, the Agent will first
determine that for Role A Permission.2 takes precedence over
Permission.1 (55 > 3). For B, Permission.5 takes precedence over
Permission.1 (78 > 20). The union of A and B is “r-xn” + “—-” =
“r-xn”.
<IP_ADDRESS> Role Associated with a Credential or Challenge
The ControllerTrust.Credential.{i}.Role
Parameter value
is inherited by Controllers whose credentials have been validated using
the credentials in the same entry of the
ControllerTrust.Credential.{i}.
table. Whenever
ControllerTrust.Credential.{i}.
is used to validate a
certificate, the Agent writes the current value of the associated
ControllerTrust.Credential.{i}.Role
into the
Controller.{i}.InheritedRole
Parameter. For more
information on use of this table for assigning Controller Roles and
validating credentials, see the sections below.
The ControllerTrust.Challenge.{i}.Role
Parameter is a
Role that is assigned to Controllers that send a successful
ChallengeResponse()
command. For more information on use of
challenges for assigning Controller Roles, see the sections below.
8.9.3 Assigning Controller Roles
As mentioned above, the Controller.{i}.AssignedRole
Parameter can be used to expose the Controller’s assigned Role via the
data model.
Note: Even if it is not exposed through the data model, the Agent is expected to maintain knowledge of the permissions assigned to each known Controller.
Controllers can be assigned Roles through a variety of methods,
depending on the data model elements an Agent implements and the Agent’s
coded policy. Note that it is possible for an Agent to maintain trusted
CA credentials with associated permissions (as described by the
ControllerTrust.Credential.{i}.
Object) and various default
permission definitions (as identified by the UntrustedRole
and BannedRole
Parameters) without exposing these through
the data model. If the data is maintained but not exposed, the same
methods can still be used.
Figure 22 and Figure 23 in the above Analysis of Controller Certificates section identify points in the decision logic where some of the following calls to data model Parameters can be made. The following bullets note when they are identified in one of these figures.
Another Controller (with appropriate permission) can insert a Controller (including the
AssignedRole
Parameter value) into theController.{i}.
table, or can modify theAssignedRole
Parameter of an existingController.{i}.
entry. TheInheritedRole
value cannot be modified by another Controller.If credentials in an entry in a
ControllerTrust.Credential.{i}.Credential
Parameter with an associatedControllerTrust.Credential.{i}.Role
Parameter are used to successfully validate the certificate presented by the Controller, the Controller inherits the Role from the associatedControllerTrust.Credential.{i}.Role
. The Agent writes this value to theController.{i}.InheritedRole
Parameter. This step is shown in Figure 23.A Controller whose associated certificate is revoked by a CA can be assigned the role in
BannedRole
, if this Parameter or policy is implemented. In this case, the value ofBannedRole
must be the only value inController.{i}.AssignedRole
(all other entries are removed) andController.{i}.InheritedRole
must be empty (all entries are removed). This step is shown in Figure 22. In the case of a Controller that has not previously been assigned a Role or who has been assigned the value ofUntrustedRole
:If the Controller’s certificate is validated by credentials in a
ControllerTrust.Credential.{i}.Credential
Parameter but there is no associatedControllerTrust.Credential.{i}.Role
Parameter (or the value is empty) andController.{i}.AssignedRole
is empty, then the Controller is assigned the role inUntrustedRole
(written to theController.{i}.AssignedRole
Parameter). This step is shown in Figure 23. Note that assigningUntrustedRole
means there needs to be some implemented way to elevate the Controller’s Role, either by another Controller manipulating the Role, implementing Challenges, or some non-USP method.If the Controller’s certificate is self-signed or is validated by credentials not in
ControllerTrust.Credential.{i}.
, the Agent policy may be to assign the role inUntrustedRole
. The optional policy decision (whether or not to allow Trust on First Use (TOFU), which can be codified in the data model with the ControllerTrust.TOFUAllowed flag) is shown in Figure 22; Figure 23 shows the Role assignment.If the Agent implements the
RequestChallenge()
andChallengeResponse()
commands, a Controller assigned the role inUntrustedRole
can have permission to read one or moreControllerTrust.Challenge.{i}.Alias
andDescription
values and issue the commands. Roles with more extensive permissions can have permission to read additionalControllerTrust.Challenge.{i}.Alias
andDescription
values. A successful Challenge results in the Controller being assigned the associated Role value.
8.9.4 Controller Certificates and Certificate Validation
When an Agent is presented with a Controller’s certificate, the Agent will always attempt to validate the certificate to whatever extent possible. Figure 20, Figure 22 and Figure 23 identify points in the decision logic where data model Parameters can be used to influence policy decisions related to Controller certificate analysis.
Note that it is possible for an Agent to maintain policy of the type
described by the UntrustedRole
, BannedRole
,
and the information described by
ControllerTrust.Credential.{i}.
and
Controller.{i}.Credential
without exposing these through
the data model. If the policy concepts and data are maintained but not
exposed, the same methods can still be used. It is also possible for an
Agent to have policy that is not described by any defined data model
element.
8.9.5 Challenges
An Agent can implement the ability to provide Controllers with challenges via USP, in order to be trusted with certain Roles. It is also possible to use non-USP methods to issue challenges, such as HTTP digest authentication with prompts for login and password.
To use the USP mechanism, the RequestChallenge()
and
ChallengeResponse()
commands and
ControllerTrust.Challenge.{i}.
Object with at least the
Alias
, Role
, and Description
Parameters needs to be implemented. The functionality implied by the
other ControllerTrust.Challenge.{i}.
Parameters needs to be
implemented, but does not have to be exposed through the data model.
A Controller that sends a Get Message on
Device.ControllerTrust.Challenge.{i}.
will receive all
entries and Parameters that are allowed for its current assigned Role.
In the simplest case, this will be a single entry and only Alias and
Description will be supplied for that entry. It is important to restrict
visibility to all other implemented Parameters to highly trusted Roles,
if at all.
The Controller can display the value of Description
to
the user and allow the user to indicate they want to request the
described challenge. If multiple entries were returned, the user can be
asked to select which challenge they want to request, based on the
description. An example of a description might be “Request
administrative privileges” or “Request guest privilege”.
When the user indicates to the Controller which challenge they want,
the Controller sends RequestChallenge()
with the Path Name
of the Challenge
Object Instance associated with the
desired Description
. The Agent replies with the associated
Instruction
, InstructionType
,
ValueType
and an auto-generated ChallengeID
.
The Controller presents the value of Instruction
to the
user (in a manner appropriate for InstructionType
).
Examples of an instruction might be “Enter passphrase printed on bottom
of device” or “Enter PIN sent to registered email address”. The user
enters a string per the instructions, and the Controller sends this
value together with the ChallengeID
in
ChallengeResponse()
.
If the returned value matches Value
, the Agent gives a
successful response - otherwise it returns an unsuccessful response. If
successful, the ControllerTrust.Challenge.{i}.Role
replaces
an UntrustedRole
in
Controller.{i}.AssignedRole
or is appended to any other
Controller.{i}.AssignedRole
value.
The number of times a ControllerTrust.Challenge.{i}.
entry can be consecutively failed (across all Controllers, without
intermediate success) is defined by Retries
. Once the
number of failed consecutive attempts equals Retries
, the
ControllerTrust.Challenge.{i}.
cannot be retried until
after LockoutPeriod
has expired.
Type values other than Passphrase
can be used and
defined to trigger custom mechanisms, such as requests for emailed or
SMS-provided PINs.
8.9.6 Certificate Management
If an Agent wants to allow certificates associated with Controllers
and CAs to be exposed through USP, the Agent can implement the
Controller.{i}.Credential
and
ControllerTrust.Credential.{i}.Credential
Parameters, which
require implementation of the LocalAgent.Certificate.
Object. Allowing management of these certificates through USP can be
accomplished by implementing LocalAgent.AddCertificate()
,
Controller.{i}.AddMyCertificate()
and
Certificate.{i}.Delete()
commands.
To allow a Controller to check whether the Agent has correct
certificates, the Certificate.{i}.GetFingerprint()
command
can be implemented.
8.9.7 Application of Modified Parameters
It is possible that various Parameters related to authentication and
authorization may change that would impact cached encrypted sessions and
Role permissions for Controllers. Example of such Parameters include
Controller.{i}.AssignedRole
,
Controller.{i}.Credential
,
ControllerTrust.Role.
definition of a Role, and
ControllerTrust.Credential.{i}.Role
.
There is no expectation that an Agent will apply these changes to cached sessions. It is up to the Agent to determine whether or not it will detect these changes and flush cached session information. However, it is expected that a reboot will clear all cached session information.
Annex A: Bulk Data Collection
Note: This Annex has been re-written in the 1.2 version of the USP specification to include the previously-defined USP Event Notification aspects of Bulk Data Collection and the new MQTT aspects of Bulk Data Collection, in addition to the already defined HTTP Bulk Data Collection mechanism.
This section discusses the Theory of Operation for USP specific mechanisms related to the collection and transfer of bulk data using either HTTP, MQTT, or USP Event Notifications. This includes an explanation of how the Agent can be configured to enable the collection of bulk data using HTTP, MQTT, or USP Event Notifications via the BulkData Objects, which are defined in the Device:2 Data Model [39].
A.1 Introduction
The general concept behind the USP Bulk Data collection mechanism is that a USP Controller can configure an Agent to consistently deliver a bulk data report at a specific interval. For large populations, this is a more efficient mechanism when compared to the alternative of polling each individual Agent for the data. There are four key aspects of configuring the bulk data collection mechanism on an Agent:
What data needs to be collected :: The set of Object/Parameter Path Names that dictate the set of Parameters that will be included in each Bulk Data report. Anything included in this set should be considered a filter that is applied against the Instantiated Data Model at the time of report generation, which means that the generation of the report is not contingent upon the Path Name being present in the Instantiated Data Model at the time of report generation.
How often does the data need to be collected :: The interval and time reference that dictates the frequency and cycle of report generation. For example, the interval could be set to 15 minutes while the time reference could be set to 42 minutes past 1 AM, which would mean that the report is generated every 15 minutes at 42 past the hour, 57 past the hour, 12 past the hour, and 27 past the hour.
Where does the data need to be sent :: The destination of where the report needs to be delivered after it has been generated. This is specific to the Bulk Data collection mechanism being used: HTTP vs MQTT vs USP Event Notification.
How does the data get sent :: The protocol used to send the data across the wire, the encoding of the data, and the format of the data. From a Protocol perspective, the HTTP Bulk Data collection mechanism utilizes either the HTTP or HTTPS protocols, the MQTT Bulk Data Collection mechanism utilizes the MQTT protocol, and the USPEventNotif Bulk Data collection mechanism utilizes the existing USP communications channel related to the USP Controller that owns the bulk data profile. From a data encoding perspective, both Bulk Data collection mechanisms support the CSV and JSON options as described later. From a data formatting perspective, both Bulk Data collection mechanisms support the Object Hierarchy and Name Value Pair report formats, also described later.
The Bulk Data collection mechanism is configured within an Agent by
creating a Bulk Data Profile. A Bulk Data Profile defines the
configuration of the four key aspects (as mentioned above) for a given
Bulk Data Report. Meaning, the Bulk Data Profile defines the protocol to
use (HTTP vs MQTT vs USPEventNotif), the data encoding to use (CSV vs
JSON), the report format to use (Object Hierarchy vs Name Value Pair),
the destination of the report, the frequency of the report generation,
and the set of Parameters to include in the report. Furthermore, the
Bulk Data Profile has a Controller
Parameter that is a
read-only Parameter and is set by the Agent based on the Controller that
created the Bulk Data Profile. The Controller Parameter represents the
owner of the Profile, which is used when determining permissions. When
the Agent generates the Bulk Data Report it uses the permissions
associated with the referenced Controller to determine what is included
in the Report (Objects and Parameters that fail the permissions check
are simply filtered out of the Report).
Note: When a Bulk Data Collection Profile is either created or updated the Agent performs validation checks for the associated Objects and Parameters against the Supported Data Model at the time of the operation.
Note: When a Bulk Data Collection Report is generated the Agent performs permission checks for the associated Objects and parameters against the Instantiated Data Model, filtering out any Object instances or Parameters that are not present at that time.
A.2 HTTP Bulk Data Collection
The Bulk Data Collection mechanism that utilizes an out-of-band HTTP/HTTPS communications mechanism for delivering the Bulk Data Report.
A.2.1 Enabling HTTP/HTTPS Bulk Data Communication
HTTP/HTTPS communication between the Agent and Bulk Data Collector is
enabled by either configuring an existing BulkData.Profile
Object Instance for the HTTP/HTTPS transport protocol or adding and
configuring a new BulkData.Profile
Object Instance using
the Add Message. For example:
.BulkData.Profile.1
.BulkData.Profile.1.Enable=true
.BulkData.Profile.1.Protocol = "HTTP"
.BulkData.Profile.1.ReportingInterval = 300
.BulkData.Profile.1.TimeReference = "0001-01-01T00:00:00Z"
.BulkData.Profile.1.HTTP.URL = "https://bdc.acme.com/somedirectory"
.BulkData.Profile.1.HTTP.Username = "username"
.BulkData.Profile.1.HTTP.Password = "password"
.BulkData.Profile.1.HTTP.Method = "POST"
.BulkData.Profile.1.HTTP.UseDateHeader = true
The configuration above defines a profile that transfers data from
the Agent to the Bulk Data Collector using secured HTTP. In addition the
Agent will provide authentication credentials (username, password) to
the Bulk Data Collector, if requested by the Bulk Data Collector.
Finally, the Agent establishes a communication session with the Bulk
Data Collector every 300 seconds in order to transfer the data defined
by the .BulkData.Report.
Object Instance.
Once the communication session is established between the Agent and Bulk Data Collector the data is transferred from the Agent using the POST HTTP method with a HTTP Date header and no compression.
R-BULK.0 - In many scenarios Agents will utilize “chunked” transfer encoding. As such, the Bulk Data Collector MUST support the HTTP transfer-coding value of “chunked”.
A.2.2 Use of the URI Query Parameters
The HTTP Bulk Data transfer mechanism allows Parameters to be used as HTTP URI query parameters. This is useful when Bulk Data Collector utilizes the specific parameters that the Agent reports for processing (e.g., logging, locating directories) without the need for the Bulk Data Collector to parse the data being transferred.
R-BULK.1 - The Agent MUST transmit the device’s Manufacturer OUI, Product Class and Serial Number or the USP Endpoint ID as part of the URI query parameters. The data model Parameters are encoded as:
.DeviceInfo.ManufacturerOUI -> oui
.DeviceInfo.ProductClass -> pc
.DeviceInfo.SerialNumber -> sn
.LocalAgent.EndpointID -> eid
As such, the values of the device’s OUI, Serial Number and Product Class are formatted in the HTTP request URI as follows:
POST https://<bulk data collector url>?oui=00256D&pc=Z&sn=Y
If the USP Endpoint ID is used the HTTP request URI is formatted as:
POST https://<bulk data collector url>?eid=os::000256:asdfa99384
Note: If the USP Endpoint ID should be transmitted together with
the device’s Manufacturer OUI, Product Class and Serial Number (e.g. to
distinguish multiple bulk data collection instances on the same device),
then the USP Endpoint ID has to be configured as additional URI
parameter in the
.BulkData.Profile.{i}.HTTP.RequestURIParameter.{i}.
table.
Configuring the URI query parameters for other Parameters requires
that instances of a
.BulkData.Profile.{i}.HTTP.RequestURIParameter.{i}.
Object
Instance be created and configured with the requested parameters. The
additional parameters are appended to the required URI query
parameters.
Using the example to add the device’s current local time to the required URI parameters, the HTTP request URI would be as follows:
POST https://<bulk data collector url>?oui=00256D&pc=Z&sn=Y&ct=2015-11-01T11:12:13Z
By setting the following Parameters using the Add Message as follows:
.BulkData.Profile.1.HTTP.RequestURIParameter 1.Name ="ct"
.BulkData.Profile.1.HTTP.RequestURIParameter.1.Reference ="Device.Time.CurrentLocalTime"
A.2.3 Use of HTTP Status Codes
The Bulk Data Collector uses standard HTTP status codes, defined in
the HTTP specification, to inform the Agent whether a bulk data transfer
was successful. The HTTP status code is set in the response header by
the Bulk Data Collector. For example, “200 OK
” status code
indicates an upload was processed successfully,
“202 Accepted
” status code indicates that the request has
been accepted for processing, but the processing has not been completed,
“401 Unauthorized
” status code indicates user
authentication failed and a “500 Internal Server Error
”
status code indicates there is an unexpected system error.
A.2.3.1 HTTP Retry Mechanism
R-BULK.2 - When the Agent receives an unsuccessful HTTP status code and the HTTP retry behavior is enabled, the Agent MUST try to redeliver the data. The retry mechanism employed for the transfer of bulk data using HTTP uses the same algorithm as is used for USP Notify retries.
The retry interval range is controlled by two Parameters, the minimum wait interval and the interval multiplier, each of which corresponds to a data model Parameter, and which are described in the table below. The factory default values of these Parameters MUST be the default values listed in the Default column. They MAY be changed by a Controller with the appropriate permissions at any time.
| Descriptive Name | Symbol | Default | Data Model Parameter Name |
|---|---|---|---|
| Minimum wait interval | m | 5 seconds | Device.BulkData.Profile.{i}.HTTP.RetryMinimumWaitInterval |
| Interval multiplier | k | 2000 | Device.BulkData.Profile.{i}.HTTP.RetryIntervalMultiplier |
| Retry Count | Default Wait Interval Range (min-max seconds) | Actual Wait Interval Range (min-max seconds) |
|---|---|---|
| #1 | 5-10 | m - m.(k/1000) |
| #2 | 10-20 | m.(k/1000) - m.(k/1000)2 |
| #3 | 20-40 | m.(k/1000)2 - m.(k/1000)3 |
| #4 | 40-80 | m.(k/1000)3 - m.(k/1000)4 |
| #5 | 80-160 | m.(k/1000)4 - m.(k/1000)5 |
| #6 | 160-320 | m.(k/1000)5 - m.(k/1000)6 |
| #7 | 320-640 | m.(k/1000)6 - m.(k/1000)7 |
| #8 | 640-1280 | m.(k/1000)7 - m.(k/1000)8 |
| #9 | 1280-2560 | m.(k/1000)8 - m.(k/1000)9 |
| #10 and subsequent | 2560-5120 | m.(k/1000)9 - m.(k/1000)10 |
R-BULK.3 - Beginning with the tenth retry attempt, the Agent MUST choose from the fixed maximum range. The Agent will continue to retry a failed bulk data transfer until it is successfully delivered or until the next reporting interval for the data transfer becomes effective.
R-BULK.4 - Once a bulk data transfer is successfully delivered, the Agent MUST reset the retry count to zero for the next reporting interval.
R-BULK.5 - If a reboot of the Agent occurs, the Agent MUST reset the retry count to zero for the next bulk data transfer.
A.2.3.2 Processing of Content for Failed Report Transmissions
When the content (report) cannot be successfully transmitted,
including retries, to the data collector, the
NumberOfRetainedFailedReports
Parameter of the
BulkData.Profile
Object Instance defines how the content
should be disposed based on the following rules:
- When the value of the
NumberOfRetainedFailedReports
Parameter is greater than0
, then the report for the current reporting interval is appended to the list of failed reports. How the content is appended is dependent on the type of encoding (e.g., CSV, JSON) and is described further in corresponding encoding section. - If the value of the
NumberOfRetainedFailedReports
Parameter is-1
, then the Agent will retain as many failed reports as possible. - If the value of the NumberOfRetainedFailedReports Parameter is
0
, then failed reports are not to be retained for transmission in the next reporting interval. - If the Agent cannot retain the number of failed reports from previous reporting intervals while transmitting the report of the current reporting interval, then the oldest failed reports are deleted until the Agent is able to transmit the report from the current reporting interval.
- If the value
BulkData.Profile
Object Instance’sEncodingType
Parameter is modified any outstanding failed reports are deleted.
A.2.4 Use of TLS and TCP
The use of TLS to transport the HTTP Bulk Data is RECOMMENDED, although the protocol MAY be used directly over a TCP connection instead. If TLS is not used, some aspects of security are sacrificed. Specifically, TLS provides confidentiality and data integrity, and allows certificate-based authentication in lieu of shared secret-based authentication.
R-BULK.6 - Certain restrictions on the use of TLS and TCP are defined as follows:
- The Agent MUST support TLS version 1.2 or later (with backward compatibility to TLS 1.2).
- If the Collection Server URL has been specified as an HTTPS URL, the Agent MUST establish secure connections to the Collection Server, and MUST start the TLS session negotiation with TLS 1.2 or later.
Note: If the Collection Server does not support TLS 1.2 or higher with a cipher suite supported by the Agent, it may not be possible for the Agent to establish a secure connection to the Collection Server.
Note: TLS_RSA_WITH_AES_128_CBC_SHA is the only mandatory TLS 1.2 cipher suite.
- The Agent SHOULD use the [22] Server Name TLS extension to send the host portion of the Collection Server URL as the server name during the TLS handshake.
- If TLS 1.2 (or a later version) is used, the Agent MUST authenticate the Collection Server using the certificate provided by the Collection Server. Authentication of the Collection Server requires that the Agent MUST validate the certificate against a root certificate. To validate against a root certificate, the Agent MUST contain one or more trusted root certificates that are either pre-loaded in the Agent or provided to the Agent by a secure means outside the scope of this specification. If as a result of an HTTP redirect, the Agent is attempting to access a Collection Server at a URL different from its pre-configured Collection Server URL, the Agent MUST validate the Collection Server certificate using the redirected Collection Server URL rather than the pre-configured Collection Server URL.
- If the host portion of the Collection Server URL is a DNS name, this MUST be done according to the principles of RFC 6125 [23], using the host portion of the Collection Server URL as the reference identifier.
- If the host portion of the Collection Server URL is an IP address, this MUST be done by comparing the IP address against any presented identifiers that are IP addresses.
Note: the terms “reference identifier” and “presented identifier” are defined in RFC 6125 [23].
Note: wildcard certificates are permitted as described in RFC 6125 [23].
- An Agent capable of obtaining absolute time SHOULD wait until it has accurate absolute time before contacting the Collection Server. If a Agent for any reason is unable to obtain absolute time, it can contact the Collection Server without waiting for accurate absolute time. If a Agent chooses to contact the Collection Server before it has accurate absolute time (or if it does not support absolute time), it MUST ignore those components of the Collection Server certificate that involve absolute time, e.g. not-valid-before and not-valid-after certificate restrictions.
- Support for Agent authentication using client-side certificates is NOT RECOMMENDED. Instead, the Collection Server SHOULD authenticate the Agent using HTTP basic or digest authentication to establish the identity of a specific Agent.
A.2.5 Bulk Data Encoding Requirements
When utilizing the HTTP Bulk Data collection option, the encoding
type is sent as a media type within the report. For CSV the media type
is text/csv
as specified in RFC 4180 [18] and for JSON the media type is
application/json
as specified in RFC 7159 [29]. For example, a CSV encoded report
using charset=UTF-8
would have the following Content-Type
header:
Content-Type: text/csv; charset=UTF-8
R-BULK.7 - The
“media-type
” field and “charset
” Parameters
MUST be present in the Content-Type header.
In addition the report format that was used for encoding the report is included as an HTTP custom header with the following format:
BBF-Report-Format: <ReportFormat>
The <ReportFormat> field is represented as a token.
For example a CSV encoded report using a ReportFormat for ParameterPerRow would have the following BBF-Report-Format header:
BBF-Report-Format: "ParameterPerRow"
R-BULK.8 - The BBF-Report-Format custom header MUST be present when transferring data to the Bulk Data Collector from the Agent using HTTP/HTTPS.
A.3 MQTT Bulk Data Collection
The Bulk Data Collection mechanism that utilizes an out-of-band MQTT communications mechanism for delivering the Bulk Data Report.
A.3.1 Enabling MQTT Bulk Data Communication
Bulk Data communications that utilizes MQTT for transferring the Bulk
Data Report between the Agent and a Bulk Data Collector, is enabled by
either configuring an existing BulkData.Profile
Object
Instance for the MQTT transport protocol or adding and configuring a new
BulkData.Profile
Object Instance using the Add Message. For example:
.BulkData.Profile.1
.BulkData.Profile.1.Enable = true
.BulkData.Profile.1.Name = "MQTT Profile 1"
.BulkData.Profile.1.Protocol = "MQTT"
.BulkData.Profile.1.EncodingType = "JSON"
.BulkData.Profile.1.ReportingInterval = 300
.BulkData.Profile.1.TimeReference = "0001-01-01T00:00:00Z"
.BulkData.Profile.1.MQTT.Reference = "Device.MQTT.Client.1"
.BulkData.Profile.1.MQTT.PublishTopic = "/bulkdata"
.BulkData.Profile.1.MQTT.PublishQoS = 1
.BulkData.Profile.1.MQTT.PublishRetain = false
The configuration above defines a profile that transfers data from the Agent to a Bulk Data Collector via the MQTT protocol. The Agent utilizes the referenced MQTT Client instance to determine the MQTT broker for this Bulk Data Collection Profile. The Agent sends the Bulk Data Report to the reference MQTT Broker by issuing an MQTT PUBLISH message to the PublishTopic every 300 seconds (ReportingInterval). The Bulk Data Collector would subscribe to the PublishTopic in order to receive the Bulk Data Reports.
A.3.2 Determining Successful Transmission
Delivering a Bulk Data Collection report using MQTT means that successful transmission of the report is tied to the successful delivery of the MQTT PUBLISH message, which is determined by the PublishQoS configured as part of the Bulk Data Collection Profile.
A.3.2.1 Retrying Failed Transmissions
Delivering a Bulk Data Collection report using MQTT means that any failed transmissions are retried based on the referenced MQTT Client and the associated QoS value contained within the MQTT PUBLISH message, which is determined by the PublishQoS parmater. Furthermore, the CleanSession (MQTT 3.1 and MQTT 3.1.1) and CleanStart (MQTT 5.0) flags determine if unacknowledged PUBLISH messages are re-delivered on client reconnect. For MQTT 3.1 there is also the MessageRetryTime defined in the referenced MQTT Client that determines how frequently an unacknowledged PUBLISH message should be retried.
A.3.2.2 Processing of Content for Failed Report Transmissions
When the content (report) cannot be successfully transmitted,
including retries, to the MQTT broker, the
NumberOfRetainedFailedReports
Parameter of the
BulkData.Profile
Object Instance defines how the content
should be disposed based on the following rules:
- When the value of the
NumberOfRetainedFailedReports
Parameter is greater than0
, then the report for the current reporting interval is appended to the list of failed reports. How the content is appended is dependent on the type of encoding (e.g., CSV, JSON) and is described further in corresponding encoding section. - If the value of the
NumberOfRetainedFailedReports
Parameter is-1
, then the Agent will retain as many failed reports as possible. - If the value of the NumberOfRetainedFailedReports Parameter is
0
, then failed reports are not to be retained for transmission in the next reporting interval. - If the Agent cannot retain the number of failed reports from previous reporting intervals while transmitting the report of the current reporting interval, then the oldest failed reports are deleted until the Agent is able to transmit the report from the current reporting interval.
- If the value
BulkData.Profile
Object Instance’sEncodingType
Parameter is modified any outstanding failed reports are deleted.
A.3.3 Bulk Data Encoding Requirements
When utilizing the MQTT Bulk Data collection option with a MQTT 5.0
Client connection, the encoding type is sent as a media type within the
MQTT PUBLISH message header and the Content Type property. For CSV the
media type is text/csv
as specified in RFC 4180 [18] and for JSON the media type is
application/json
as specified in RFC 7159 [29]. For example, a CSV encoded report
using charset=UTF-8
would have the following Content Type
property:
text/csv; charset=UTF-8
R-BULK.8a - The
“media-type
” field and “charset
” parameters
MUST be present in the Content Type property when using MQTT 5.0.
When utilizing the MQTT Bulk Data collection option with a MQTT 3.1
or MQTT 3.1.1 client connection, the encoding type is not sent in the
MQTT PUBLISH message; instead the receiving Bulk Data Collector will
need to know how the .BulkData.Profile
Object Instance is
configured.
In addition the data layout is not included in the MQTT PUBLISH
message; instead the receiving Bulk Data Collector will need to know how
the .BulkData.Profile.{i}.CSVEncoding.ReportFormat
or
.BulkData.Profile.{i}.JSONEncoding.ReportFormat
Parameter
is configured.
A.4 USPEventNotif Bulk Data Collection
The Bulk Data Collection mechanism that utilizes the existing USP communications channel for delivering the Bulk Data Report via a Notify Message that contains a Push! Event.
A.4.1 Enabling USPEventNotif Bulk Data Communication
Bulk Data communications using a USP Event notification that utilizes
the Notify Message between the
Agent and a Controller, acting as a Bulk Data Collector, is enabled by
either configuring an existing BulkData.Profile
Object
Instance for the USPEventNotif transport protocol or adding and
configuring a new BulkData.Profile
Object Instance using
the Add Message. For example:
.BulkData.Profile.1
.BulkData.Profile.1.Enable = true
.BulkData.Profile.1.Name = "USP Notif Profile 1"
.BulkData.Profile.1.Protocol = "USPEventNotif"
.BulkData.Profile.1.EncodingType = "JSON"
.BulkData.Profile.1.ReportingInterval = 300
.BulkData.Profile.1.TimeReference = "0001-01-01T00:00:00Z"
The configuration above defines a profile that transfers data from
the Agent to a Controller that is acting as the Bulk Data Collector. The
Controller that receives an Event notification is dictated by the
Agent’s currently defined Subscriptions Notifications and Subscription Mechanism. The Agent
utilizes the existing communications session with the Controller acting
as the Bulk Data Collector every 300 seconds in order to transfer the
data defined by the .BulkData.Profile
Object Instance.
The data is transferred from the Agent using the USP Notify Message
and a .BulkData.Profile.1.Push!
Event notification.
A.4.2 Determining Successful Transmission
Delivering a Bulk Data Collection report using the USP Notify Message
and a .BulkData.Profile.1.Push!
Event notification means
that successful transmission of the report is tied to the successful
delivery of the notification itself Responses to Notifications and Notification
Retry.
A.4.2.1 Retrying Failed Transmissions
Delivering a Bulk Data Collection report using the USP Notify Message
and a .BulkData.Profile.1.Push!
Event notification means
that any failed transmissions are retried based on the notification
retry requirements R-NOT.1
through R-NOT.4 Responses to
Notifications and Notification Retry.
Furthermore, the NumberOfRetainedFailedReports
Parameter
of the BulkData.Profile
Object Instance does not pertain to
the USPEventNotif Bulk Data Collection mechanism as each report is
wholly contained within a USP Notify Message. This means that the
notification retry mechanism will determine the life of each individual
failed report, and that each reporting interval will generate a new
report that is delivered via a new USP Notify Message.
A.4.3 Bulk Data Encoding Requirements
When utilizing the USPEventNotif Bulk Data collection option, the
encoding type is not sent in the USP Event notification; instead the
receiving Controller will need to know how the
.BulkData.Profile
Object Instance is configured.
In addition the data layout is not included in the USP Event
notification; instead the receiving Controller will need to know how the
.BulkData.Profile.{i}.CSVEncoding.ReportFormat
or
.BulkData.Profile.{i}.JSONEncoding.ReportFormat
Parameter
is configured.
A.5 Using Wildcards to Reference Object Instances in the Report
When the Agent supports the use of the Wildcard value “*” in place of
instance identifiers for the Reference Parameter, then all Object
Instances of the referenced Parameter are encoded. For example to encode
the “BroadPktSent
” Parameter for all Object Instances of
the MoCA Interface Object the following will be configured:
.BulkData.Profile.1.Parameter.1.Name = ""
.BulkData.Profile.1.Parameter.1.Reference = "Device.MoCA.Interface.*.Stats.BroadPktSent"
A.6 Using Alternative Names in the Report
Alternative names can be defined for the Parameter name in order to
shorten the name of the Parameter. For example instead of encoding the
full Parameter name
“Device.MoCA.Interface.1.Stats.BroadPktSent
” could be
encoded with a shorter name “BroadPktSent
”. This allows the
encoded data to be represented using the shorter name. This would be
configured as:
.BulkData.Profile.1.Parameter.1.Name = "BroadPktSent"
.BulkData.Profile.1.Parameter.1.Reference = "Device.MoCA.Interface.1.Stats.BroadPktSent"
In the scenario where there are multiple instances of a Parameter
(e.g., “Device.MoCA.Interface.1.Stats.BroadPktSent
”,
“Device.MoCA.Interface.2.Stats.BroadPktSent
”) in a Report,
the content of the Name parameter SHOULD be unique (e.g.,
BroadPktSent.1
, BroadPktSent.2
).
A.6.0.1 Using Object Instance Wildcards and Parameter Partial Paths with Alternative Names
Wildcards for Object Instances can be used in conjunction with the use of alternative names by reflecting Object hierarchy of the value of the Reference Parameter in the value of the Name Parameter.