< 上一个 | 内容 | 下一个 >

‌9.8 File Download function set‌

9.8.1 Introduction

This subclause describes the mechanisms used to support secure, interoperable, remote software download to IEEE 2030.5 devices. This function set may also be used for remote download of other file artifacts such as log files, configuration files, security credential files, etc. Three resources constitute the File Download function set: the FileList resource, the File resource, and the FileStatus resource.

There are two primary actors involved in a file download: the loading device (LD) and the file server (FS). A FS is any device serving this function set.

To accommodate sleepy end devices, IEEE 2030.5 supports only a polled mode of file download.

9.8.2 File list resource

9.8.2.1 Overview

A FileList resource contains zero or more File resources available to be loaded by client devices. A File resource contains various meta-data describing the file and a link to the file binary artifact.

9.8.2.2 List ordering

File resources are ordered within a FileList as follows:

Table 36 —File download list ordering

The main use case for this ordering is to enable client devices (of specific manufacturer and model) to query the FileList for available file types with a version newer than the file currently on the device.

‌9.8.2.3 Application guidelines/behavior

9.8.2.3.1 Introduction

This standard designates files resident on the LD as activated or non-activated. A non-activated file is a file that has been physically loaded onto the LD, but not yet placed into operation. An activated file is a file that has been both physically loaded onto the LD and placed into operation. An example use of the activation state is the scenario in which an operator first must load and confirm load of new software images to a large set of devices (as non-activated, not running) before setting that software image to an activated state (the running image).

A FileList MUST contain File resources for each file made available by the FS for download by LDs. The FileList MAY be discoverable as specific to a device (FunctionSetAssignment accessed via an EndDevice) and/or MAY be discoverable to all devices via DeviceCapabilities.

The LD issues discovery requests to locate available FS (DNS-SD subtype “file”). The LD MUST first determine if there exists a FunctionSetAssignment, containing a FileList, for the device. If such a FileList exists, the LD MUST use this FileList exclusively. If a Time resource is specified within this same FunctionSetAssignment, the LD MUST use this Time resource as the reference for file activation time. If the LD does not locate a FunctionSetAssignment directing the LD to a specific FileList, the LD MUST attempt discovery of a FileList provided by any device’s DeviceCapabilities resource.

If the LD locates more than one File resource satisfying its File query, it is up to the LD to determine the appropriate File selection. Any algorithm used to make this selection is out of scope of this standard.

If the LD is unable to make a selection between multiple files, the LD SHOULD issue an FE_FILE_MULTIPLE_FILES LogEvent.

An LD MUST poll for available files at least once every 24 hours.

File content is transferred using either HTTP or HTTPS. The latter SHOULD be used when encryption over the air/wire is desired. The choice is left to the manufacturer. An LD SHALL provide the ability to fully receive and store a non-activated file while the current activated file remains operational. For example, an LD SHALL be able to load a new software image (a non-activated file) while the current software image executes. In the case of a software image, the activated file is the running image.

IEEE 2030.5 deployments could contain clients and servers of vastly differing capabilities: from constrained embedded devices to cloud-based services. It is thus important that FSs and LDs be provided ways to control the rate at which files are transferred. The HTTP Range and Content-Range entity headers are used to support incremental loading of large files. LDs SHOULD use the Range entity header, within HTTP GET requests for file content, to support file loading via a sequence of one or more HTTP requests. An FS MUST be able to process the Range entity header within HTTP GET requests for file content, and MUST support Range entity header processing for at least a single range of bytes. An FS MUST include the Content-Range entity header within HTTP responses for file content when an LD requests a specific range. An LD SHOULD be able to process Content-Range entity headers within HTTP responses for file content.

The HTTP ETag entity header is used to allow LDs to detect any modification to a resource. This is of particular importance to detect changes in file content during a long-running (multi-GET) file load. An FS MUST maintain a unique entity-tag value for each version of a file referenced by a specific URI. Per IETF RFC 7232, the entity-tag value MUST change if the underlying bits of the file change. The FS MUST include an ETag entity header (indicating the file entity-tag value) in all GET responses containing file content. An LD MUST detect a change in file ETag value. An LD MUST abort the file load if the ETag has changed, and SHOULD restart the file load (now based on the new ETag). Note that this approach for file modification detection was decided, in the general case, to be more bandwidth efficient than forcing the LD to include an If-Match or If-Range entity header on all GET requests for file content.

For previously loaded, non-activated files for which an activation time has not been acquired, the LD MUST poll the File resource at least once every 24 hours for inclusion of a file activation time. The LD SHOULD cease attempting to acquire activation time after five unsuccessful attempts or if a new File of same type has been loaded (whichever condition occurs first). If the LD is unable to acquire an activation time after five attempts, the LD MUST cease any further attempts and consider the activation failed.

An FS SHOULD maintain internal estimates of its current resource usage. If an FS determines that it is unable to service an incoming HTTP request, the FS SHOULD issue a response indicating 503 error and SHOULD include the Retry-After entity header (providing guidance to the LD for retry attempt). The Retry-After entity header SHOULD provide a best estimate as to when the FS expects it will be able to service the LD request.

An LD SHOULD implement handling for 503 errors and SHOULD implement handling of the Retry-After entity header. If the LD does not support processing of the Retry-After entity header, the LD MUST wait at least 30 seconds before retrying the file content request.

An LD SHOULD negotiate a desired TCP window size with the FS.

Files SHOULD be treated as raw binary, thus a Content-Type entity header of “application/octet-stream” SHOULD be used.

9.8.2.3.2 File formats

IEEE Std 2030.5 makes no requirements upon the internal structure of files. A file is simply a manufacturer-defined sequence of binary octets whose internal details are completely defined by the manufacturer and out of scope of this standard.

IEEE 2030.5 does, however, require a file be digitally signed to protect the file from undetected modification and provide file origin authentication.

9.8.2.3.3 File signatures

Files SHALL be signed and signatures verified using approved algorithms specified in NIST SP800-131A. Cryptographic strength MUST be at least a minimum of 128-bit. This standard does not otherwise prescribe specific cryptographic mechanisms via which the file is signed or signature verified, does not prescribe the format of the file signing trust chain, and does not prescribe how that trust chain is managed on the LD. The signature of the file SHALL be calculated over the entire contents of the file excluding the signature octets.

9.8.2.3.4 Loading files containing security credentials

File loads containing IEEE 2030.5 security artifacts (type = 1 or any manufacturer defined file type containing credentials, key material, etc.) MUST be protected to at least the current level of security associated with the artifact being loaded. Such a file load MUST be secured using an HTTPS connection.

9.8.2.3.5 File query parameters

Beyond the standard IEEE 2030.5 list query parameters for result start/length/etc., a FileList supports additional query parameters to support filtering of Files result sets. These file query parameters, modeled after several of the elements within the File resource, are:

 type

 lFDI

 mfHwVer

 mfID

 mfModel

 mfSerNum

 mfVer

All of the query parameter values MUST adhere to identical syntax and semantics as used for the correspondingly named elements of the File resource described in the supplemental material of IEEE Std 2030.5.

An FS MUST be able to process all file query parameters. LD usage of any of the file query parameters is OPTIONAL.

File query parameters MUST be applied to a File List before the standard list query parameters (i.e., the standard query parameters are used to page the list resulting after the file query parameters are applied).

The set of file query parameters MUST be interpreted as a Boolean expression, with each file query parameter considered a clause of that expression, and each clause connected by a logical AND operand.

Each file query parameter MUST provide an exact match with its File equivalent for its clause to evaluate to true. There is one exception to this case: the mfVer MUST be evaluated as a GREATER THAN logical operand versus its File equivalent.

Omission of a query parameter MUST be interpreted as a match, regardless the File’s corresponding value.

9.8.2.4 LogEvents

Loading and activation of files is a long-running operation. Diagnosing problems can be challenging. LDs SHOULD implement the Log Event function set. If an LD does implement the LogEvents for this function set, the LD SHALL implement all of the following LogEvents:

Table 37 —FileDownload LogEvents

9.8.3 File status resource

9.8.3.1 Overview

The FileStatus resource enables LDs to provide a means to track the progress of any file load operations and also a means to diagnose failed file load operations.

9.8.3.2 List ordering

This resource does not contain any lists, so no ordering is specified.

9.8.3.3 Application guidelines/behavior

An LD SHOULD implement a SelfFileStatus resource or an LD SHOULD support PUT to a remote FileStatus (on an EndDevice server). The SelfFileStatus and FileStatus resources SHOULD be updated whenever a status transition occurs (as a File load and activation flow executes). Status is discussed in the definition of FileStatus (see the supplemental material of IEEE Std 2030.5).

9.8.3.4 LogEvents

There are no LogEvents generated by this resource.

< 上一个 | 内容 | 下一个 >