TR069协议格式化签名数据包（一）

Annex E. Signed Package Format (1)
TR069协议格式化签名数据包（一）

E.1 Introduction
This document specifies a signed package format that MAY be used to securely download files into a recipient device. The format allows one or more files to be encapsulated within a single signed package.

The package format allows the recipient to authenticate the source, and contains instructions for the recipient to extract and install the contents.

The signed package format is intended to be used for download from a server via HTTP, HTTPS, or FTP file transfer, or via other means of file transfer from a remote or local source

这篇文档定义了一种格式化的签名数据包可以用来进行安全的文件下载。这种格式化允许一个或多个数据包放到一个单独的包中。

这个被签名的数据包允许接收者验证被下载的文件的内容完整性、准确性，防止因为数据错误造成的设备更新失败，接收者按照数据包中包含的说明信息执行相关文件下载或安装等命令。

这个签名数据包可以用来通过HTTP、HTTPS、FTP或其他方式到远程服务器下载文件。

E.2 Signed Package Format Structure
The basic format of a signed package file is shown in Figure 8.
Figure 8 – Signed package format

固定长的包头｜命令列表｜签名数据｜所负载的文件用来安装到设备中

Fiexd length header | Commander list | Signatures | Payload files
A general description of each of the signed package format components is given in Table 70.
Table 70 – Signed package component summary


一个签名包的基本格式见图八

签名包的每个组件的描述见表70

Component Description
Header The header is a fixed-length structure including a preamble, format version, and the lengths of the command list and payload components.

Command list The command list contains a sequence of instructions to be followed in extracting and installing the files contained within the package.
Each command is in the form of a type-length-value (TLV).

Signatures This section of the package contains a PKCS #7 digital signature block containing a set of zero or more digital signatures as described in section E.5.

Payload files This section of the package contains one or more files to be installed following the instructions in the command list.
This document does not define any specific payload file formats.


组件 描述
包头 头是一个固定长度的结构包含一个序列，格式化版本，命令列表的长度，负载组件。
命令列表 命令列表包含一组用来安装或者提取文件的指令说明。
每一个命令由一个type-length-value (TLV)格式构成。
签名 签名部分包含一个文件的PKCS #7数字签名块，详细说明见
E.5章的描述。
负载文件 文件部分包含一个或多个由命令列表指定的文件。
本文挡没有定义文件的特殊格式。

E.2.1 Encoding Conventions
The following encoding conventions are used throughout this specification unless explicitly stated
otherwise:
• Multi-octet numeric values are encoded in network byte order (big endian format).
• File or directory path names are specified in UNIX format (e.g., “/dir/dir/base.ext”).

如下的编码规定贯穿全文，除非有其他明确规定，如下：
•多字节数值按照网络字节规定（长字节序列格式化）
•文件和路径名按照UNIX系统格式定义(例如 “/dir/dir/base.ext”)

E.3 Header Format
The signed package header is a fixed-length 24-octet structure. The format of the header is defined in Table 71.
Table 71 – Signed package header format

签名数据包是一个固定长度24字节的结构，该数据包包头结构定义见表71。
表71——签名数据包包头格式

域 类型 描述
Field Type Description
Preamble 8 octets A fixed sequence of octets containing the following hexadecimal values:
32 57 49 52 45 5F 53 50
An interpreter of the signed package format MUST verify that the preamble
contains exactly this sequence of values for the package to be considered valid.
序文 8字节 一个包含如下固定序列字节的16进制值：
32 57 49 52 45 5F 53 50
签名数据包必须包含以上序列方为有效。
Major version 32-bit integer Value indicating the major component of the package format version. An implementation conforming to this specification has a major version of 1 (one).
Changes to the major version denote incompatible changes to this format.

主版本号 32比特整型 该值指明数据包主要组件格式化版本。
规定有一个值为1的主版本。
改变主版本号要指明改变中的冲突
Minor version 32-bit integer Value indicating the minor component of the package format version. An
implementation conforming to this specification has a minor version of 0 (zero).
Changes to the minor version denote compatible changes to the package format.
An implementation implementing this version of the specification SHOULD be capable of interpreting packages encoded using a format with a different minor
version value.

次版本号 32比特整型 该值指明数据包次要组件的格式化版本。
规定有一个值为0的次要版本。
改变次版本号要指明改变中的冲突。
这个版本号应该能够区分使用其他次版本号编码的数据包
Command list length 32-bit integer Length in octets of the command list. The command list length MUST be less than 216.

命令列表长度 32比特整型 命令列表的长度必须小于2的16次方
Payload length 32-bit integer Length in octets of the payload, including all files contained within it.
负载文件长度 32比特整型 该长度为所有文件长度之和

E.4 Command List Format
Each command in the command list has a format specified in Table 72.

Table 72 – Command format
Field Type Description
Type 32-bit integer Specifies the particular command.
Length 32-bit integer Specifies the length in octets of the Value field. The total length of the command
is Length + 8 octets.

Value (Conditional) Zero or more octets of parameters associated with the particular command type.

域 类型 描述
类型 32字节整形 用来说明命令类型
长度 32字节整形 用来说明类型值的长度，命令的总长度应为该长度+8个字节
值 0或者更多字节的参数，该值与特殊的命令类型相关联

If a recipient of this file format finds a Type value that is unknown to it, it MUST ignore the command and continue parsing the remainder of the package, using the Length value to skip to the next command, if any.

如果接收者发现一种未知的类型，它必须忽略该命令，继续解析其他部分，利用如上表的长度跳到下一个命令。

E.4.1 Command Types
The command list contains two types of commands: package parameters and actions to be taken. Examples of package parameters include the software version of a contained software image or a timeout for the remainder of the download. Examples of actions are add, remove, and move. The actions taken together in the order specified in the command list define the sequence of modifications to the file system required to extract and install the contained files.

命令列表包含两种类型的命令：包参数和可执行行为。包参数例如：软件镜象的版本、下载超时。可执行的行为例如：增加、移除、移动。这些行为放到一起为了实现文件系统提取、安装等等一系列的修改需求。

The file-related commands have two variants: one that operates on explicit files and another that operates on versioned files. The name of a versioned file has a fixed “base” up to 8 characters in length, and an ”extension” that is 3 characters in length. Each time the content of a versioned file is updated, the file extension is changed to a new value that indicates the file version. Because of this, if an upgrade needs to replace a versioned file, any existing file with the same base name but different extension MUST be removed.

文件相关命令有两种类型：一种操作基于确定的文件，另一种含有版本的文件。含有版本的文件的名字有一个固定名超过八个字节长，和一个扩展名3个字节长，每次一个含有版本的文件内容被更新 ，文件的扩展名会改为一个新的值，该值表明版本。因此，如果一个含有版本的文件需要改变版本，固定名不变，但扩展名会被移除。

E.4.2 End Command
This command signifies the end of the command list. This command need not be present in a command list, but if encountered a recipient MUST stop parsing the remainder of the command list portion of the package.

The Length parameter for this command MUST be 0 (zero), indicating that no Value field follows.

这个命令用来表明命令列表结束。这个命令不需要出现在命令列表中，除非要求接收者必须停止解析剩余的包的部分。

这个命令参数的长度必须为0，表明后面没有任何值。

Extract and Add Commands

The extract and add commands include Extract File, Extract Versioned File, Add File, and Add Versioned File.

The extract commands instruct the recipient to remove any existing file of the same name and replace it with the specified file in the payload.

The add commands instruct the recipient to first check for an existing file of the same name, and only install the new file if no existing file can be found.

提取和添加命令包含提取文件和提取版本文件，添加文件和添加版本文件几种类型。

提取命令指示接收者移除任何含有指定名字的文件，然后用负载文件替换它

添加命令指示接收者首先检查含有指定文件名的文件，如果不存在的话再安装新文件

For the versioned file variants of these commands, the above operations consider an existing file as any file that has the same base name as the specified file. That is, the Extract Versioned File command removes all existing files with the same base name and any extension prior to installing the new file. Similarly, the Add Versioned File command checks for any file with the same base name as the specified file, regardless of extension, and only installs the new file if no such file can be found.

When a new file is to be created in a directory that does not exist, the recipient MUST create the required directory.

All of the extract and add commands include information in the Value portion of the command. The format of this information is defined in Table 74.

对于含有版本的文件包含如下几种命令，上面的操作考虑存在的文件中是否含有指定的文件名，提取含有版本的文件命令要根据文件固定名移除含有指定文件名以及版本比指定文件更早的文件。类似的，添加含有版本的文件命令，首先要根据固定名检查是否含有与指定文件名相同的文件，忽略扩展名（版本），如果不含有指定文件则安装该文件。

当一个新的文件需要的目录不存在，接收者必须创建该目录。

所有的提取和添加命令都包含命令“值”的信息。表74定义了该命令 “值”的格式化格式。

Table 74 – Value format for the extract and add commands

域 类型 描述
Flags 32-bit integer A bit-field defined as follows:
Bit 0 (LSB): Unsafe Flag. A 1 (one) value of this flag indicates that if this
command completes successfully, but a subsequent command in the
command list fails, the recipient device will be left in an unsafe state, and
SHOULD follow its procedures for recovery of its file system to a known
safe state.
All other bits are reserved and MUST be set to 0 (zero) and MUST be ignored by
the recipient.

标志 32比特整型 比特0(LSB)：不安全标志。
1代表命令执行成功
但是如果命令列表随后的命令出现失败，接收者将进入不安全状态，后面的过程文件系统将进入一个安全状态。
其他的比特作为保留必须至为0，这些比特将被接收者忽略。
Path Offset 32-bit integer The offset in octets from the beginning of the Value field to the Path field in this
command.
路径偏移量 32比特整型 这个偏移量为从起始到该命令的“路径”域
Path Length 32-bit integer The length of the Path field in octets.
路径长度 32比特整型 “路径”域的长度
Hash Type 32-bit integer Type of hash algorithm used in creating the Hash field. The following values are
currently defined:
1 = SHA-1. When set to this value, the Hash field contains the 20-octet SHA-1
hash of the specified file. The Hash Length value in this case MUST be set to 20
(decimal).
All other values are reserved.
哈希类型 32比特整型 哈希算法的类型用来创建“哈希”域
当前使用的类型为
1 = SHA-1. 当设置这个值，哈希域包含20个字节的文件SHA-1哈希值 。
哈希的长度必须至为20（十进制）
所有其他的值别忽略。
Hash Offset 32-bit integer The offset in octets from the beginning of the Value field to the Hash field in this
command.
哈希偏移量 32比特整型 该偏移量为从开始到该命令的“哈希”域
Hash Length 32-bit integer The length of the Hash field in octets.
哈希长度 32比特整型 “哈希”域的长度
File Offset 32-bit integer The offset in octets from the beginning of the payload portion of the package to
the beginning of the specified file.
文件偏移量 32比特整型 该偏移量为从负载部分的开始到指定文件的开始
File Length 32-bit integer The length of the file payload in octets. The actual contents of the file are found
in the file payload portion of the package.
文件长度 32比特整型 该长度为负载文件的长度
Path String of length
Path Length Path of the specified file, including the directory tree and file name.
路径 指定文件的路径包含，路径树以及文件名
Hash Octet string of
length Hash
Length Hash of the payload file using the hash algorithm defined in the Hash Type field.
The hash of the payload file is included in the command because the signatures
validate only the package header and command list. By including the file hash in
the command, the signature ensures the validity of the file contents.
哈希值 负载文件的哈希值使用“哈希类型”域指定的哈希算法。用来验证文件是否有效。通过进行哈希值的比较判断文件是否为有效文件