8.7 Software Package file format

8.7.1 Overview

The Software Package file format describes a standard format to share files for the software update. This enables Update Clients to use software from different vendors (i.e., it supports identification of the package, compatibility with the device, storage of the deployment and of supplementary files).

The Software Package is shared as a single ZIP file with all the content described in this section. The recommended file extension is “.uadipkg”. In some cases, parts of the ZIP file can be removed. For example, to retrieve just a lean metadata-only package with information about available updates without having to download many full Software Packages. Another example is removing the SUPPLEMENT folder to make the package smaller if the entire Software Package is deployed to the device.

8.7.2 Folder structure

On the root level, the Software Package can have the following folders:

The optional CONTENT folder holds the files or folders that are transferred to the device. The content of this folder is defined by the author of the Software Package. For Cached-Loading and Direct-Loading, this folder can contain a single file that shall be transferred to the device. Alternatively, it can contain multiple files, if the entire Software Package is sent to the device (see use case 8.2.2.14).

The mandatory META folder holds the Software Package’s metadata. It shall at least have the file package_metadata.json. This file describes what’s in the Software Package and to which components it is compatible (see use case 8.2.2.16).

The optional SUPPLEMENT folder can contain supplementary documents for use by the Update Client. These can include license details, release notes, or manuals related to the software. An Update Client can present them to the user as part of the software update (see use case 8.2.2.19).

The optional META-INF folder contains the digital signatures of the Software Package (see 8.7.4 8.2.2.20, 8.2.2.21).

In case of a Solution Package the optional SUBPACKAGES folder contains the content of the Software Packages that belong to the solution (see use case 8.2.2.22).

8.7.3 Package metadata

The package metadata file describes the identity of the Software Package, the target for the installation, the compatibility to the device and optionally the usage of individual files within the Software Package. The package_metadata.json is stored in the META folder.

The JSON schema for the package_metadata.json file associated with this version of the specification can be found here:

https://reference.opcfoundation.org/files/uamodel.di.packagemetadata.jsonschema.json?u=http://opcfoundation.org/UA/DI/&v=1.05.0

The JSON schema associated with the latest version of the specification can be found here:

https://reference.opcfoundation.org/files/uamodel.di.packagemetadata.jsonschema.json?u=http://opcfoundation.org/UA/DI/

The JSON schema follows the conventions for the Compact DataEncoding defined in OPC 10000-6.

The elements of the JSON schema are described in Table 120, Table 124, Table 126, Table 128, Table 130, Table 132, Table 134, Table 136, Table 138 and Table 140.

A Software Package is uniquely defined with the ManufacturerUri, PackageType, TargetProductCodes, PackageRevision and Name.

The PackageMetadata structure and all contained types are encoded using the JSON VerboseEncoding.

Note: The following tables describe the package_metadata.json with structures and enumerations as a separate OPC UA namespace. These types typically do not show up in the AddressSpace of an OPC UA Server.

The compatibility declaration describes the compatibility of a Software Package with a component on the server that supports the SoftwareUpdate AddIn.

This can be simple terms like a minimum SoftwareRevision or a specific HardwareRevision of the component. Or relations to other objects in the AddressSpace e.g. to describe the existence and version of an attached hardware or to restrict the use of an application to a specific firmware version of a device.

Typically, the compatibility declaration outlines the relationship between variables and the corresponding component on the server. However, certain compatibilities can only be articulated through associated components e.g. the device hosting the application or a necessarily attached hardware. For those cases the compatibility declaration can incorporate paths following the UpdateParentReferenceType references (see 8.6.1).

The UpdateParentReferenceType enables the definition of a tree of object on the server which is utilized to describe compatibility. Parent objects are referenced as “..” while child objects are indicated by the BrowseName of the node being referenced. The elements within this path are interconnected using a slash (“/”).

Examples:

“ManufacturerUri”, “ProductCode”, “SoftwareRevision” identify properties of the component that should be updated.

“../ManufacturerUri” and “../ProductCode” identify a specific parent component (e.g. the device that hosts the application).

“../ProfinetExtension/SoftwareRevision” can identify the firmware version of a hardware which is connected to the parent.

8.7.4 Package signature

To prove authenticity and integrity the Software Packages can be signed.

Initially the Software Package should be signed by the author (e.g., the manufacturer signs a firmware for its devices when it is created). This signature proves that it is really from that author (authenticity) and that is not altered on the way to the client (integrity) (see use case 8.2.2.20).

The verification of these signatures can be done by the Update Client or by the device if the whole update package is deployed.

Typically, a PKI with a certificate hierarchy is used. In this case, the entire certificate chain shall be stored in the signature. Consequently, only the root certificate is required for verification.

Additional signatures can be added by machine builders or plant operators to approve a Software Package for use in a specific plant. With this in place the Update Client and OPC UA servers can be configured to only allow updates of Software Packages with an approval signature of a specific certificate hierarchy (see use case 8.2.2.21).

To create a signed Software Package, it is stored as a standard ASiC-E (Associated Signature Container) container and signed with a CAdES (CMS Advanced Electronic Signatures) signature.

Note: These *AdES signatures are commonly used for advanced digital signatures in engineering environments. Examples are FDI, Profinet or OPC UA FX descriptors. To be easier usable on constrained devices the Software Packages use the binary CAdES persistence instead of the XML based XAdES. ASiC-E is a minimalistic ZIP container from the same family of standards.

With ASiC-E the folder structure of the ZIP file does not change. ASiC-E adds one additional folder “META-INF” with the signature information and a mimetype file in the root folder. These signatures also remain intact if individual files are removed or if the folders are unzipped.

Depending on the industry and environment where the devices are used there are different requirements to the level of security of the signatures. Therefore, the CAdES signatures support different levels which all can be used for the Software Packages. The more advanced options extend the basic option so that all packages remain compatible and usable with any update client.

For the verification of the signature, all certificates up to the root certificate are required. To ensure ease of handling, the entire certificate chain should therefore be incorporated within the CAdES signature.

All security relevant details are described in the publicly available ETSI standards (see ASiC-E, CAdES).

Note: If the complete Software Package is transferred to the device the verification also shall be done on the device. For this case certificates are distributed and updated on all device in the plant. Solutions for certificate distribution are covered in detail in OPC 10000-12 and OPC 10000-21.

Note: To create and maintain keys and certificates for the signatures, a PKI (public key infrastructure) should be used. Since this has no impact on the singing and verification described in this document, it is out of scope of this specification.

8.7.5 Solution packages

A Solution Package can be used to combine several Software Packages. This can have several reasons:

Easier distribution of multiple Software Packages as a single file (e.g., a complete machine with several devices or one device with several updateable components).

Only a specific combination of Software Packages shall be installed (could be verified using a signature at the Solution Package).

A combination of several Software Packages shall be installed to a device as a single file. The device is then responsible for distribution / installation of the subpackages.

A Solution Package can include an assignment information that declares which subpackage shall be installed to which targets on the device. A target can be either a specific instance or a type. If a type is specified, the package should be installed to all instances of that type. Example: A FieldBus head with OPC UA Server manages the firmware update of the connected IO modules.

A Solution Package also contains the standard package_metadata.json file with manufacturer and optional version information about the solution. Here the PackageType shall be set to Solution.

If there are several components in a Device that support the Software Update the CanUpdateReferenceType can be used to describe which subcomponents can be updated via the Solution Package.

If a precise assignment of the contained Software Packages is required, the Assignments element of the PackageMetadata can be used. The structures for the Assignment are defined in Table 136.

PackageTarget can describe either a single or multiple targets for the subpackage. For example, TargetType describes multiple targets (all instances of that ObjectType), while the combination of SerialNumber, ProductCode, and ManufacturerUri uniquely identifies a single target. The following options can be used to filter the list of targets:

If no target is specified, the subpackage shall be installed on all matching target nodes.

If a TargetType is specified, all targes that are subtypes of the specified ObjectType shall be updated.

If a TargetNode is specified, only this node shall be updated.

If a ProductInstanceUri is specified, only the target with the specified ProductInstanceUri in its IVendorNameplateType shall be updated.

If AssetId is specified, only the target with the specified AssetId in its ITagNameplate shall be updated.

If ManufacturerUri and ProductCode are specified, all targets identified with these properties in its IVendorNameplateType shall be updated.

If ManufacturerUri, ProductCode and SerialNumber are specified, only the target identified with these properties in its IVendorNameplateType shall be updated.

If an FxPath is specified, the target is identified following the AssetConnectors (see OPC 10000-81) identified by its type and either its Id or its Name.

If AssetsTypes of OPC 10000-81 are used, TargetScope can be used to restrict the installation to targets which are connected to that asset. This can, for example, be combined with FxPath.

If a TargetBrowsePath is specified, the target is identified by the specified path. This path starts at the Objects Node and shall only result in a single node.

If the distribution of the packages is done by the Update Client and the package shall be installed on a specific server, the TargetServer contains the ApplicationUri of that server.