← Back to packages

Package doirp_v3.v1.element

Message HsAdmin

Message HsPubkey

Message HsServ

Message ServiceInterface

Message ServerRecord

Message HsSite

Enum Permission

Enum Type

Enum Type

Enum TransportProtocol

Enum HashOption

Messages

message HsAdmin doirp_v3/v1/element/hs_admin.proto

规范:4.3.1 IDENTIFIER ADMINISTRATOR: HS_ADMIN

对标识符记录或 DO-IRP 服务进行管理操作(如添加、删除、修改元素)只能由已认证且具备 足够权限的管理员执行。

“管理员”被定义为一个由标识符和该标识符记录内的元素索引表示的实体。这个标识符+索引指向的 元素必须包含用于身份验证挑战的公钥或密钥。

已认证的管理员是指能够证明其持有与管理员标识符索引所指的公钥匹配的私钥,或对应的密钥的实体。

管理员对某标识符记录的权限在该记录中的一个或多个 HS_ADMIN 元素里定义。每个 HS_ADMIN 元素 可定义一组拥有相同管理权限的管理员。拥有不同权限的多个管理员可以对应多个 HS_ADMIN 元素。 DO-IRP 服务器在执行任何管理请求前会使用 HS_ADMIN 元素对管理员进行认证。但作为实现选项,没有 HS_ADMIN 的标识符记录仍可由合格的 DO-IRP 服务器管理员修改。

HS_ADMIN 元素的 字段为 HS_ADMIN,其 字段包含以下条目(以二进制编码):

规范: 16 位位掩码,定义 指定的管理员(或管理员集合)的管理权限;具体权限见下文。

Field Type Description
1 permission uint32

See Permission enum below for details.

2 admin_ref doirp_v3.v1.common.ElementRef

规范: 指定记录的管理员。由管理员的标识符和元素索引组成,编码方式为:4 字节长度 + UTF-8 字节序列 + 4 字节无符号整数(该管理员标识符记录中被引用元素的索引)。被引用的元素必须是 身份认证元素(如 HS_PUBKEY 或 HS_SECKEY),或 HS_VLIST 元素(列出一个或多个管理员身份 认证元素引用的管理员组)。详见下文 HS_VLIST 段落及 4.2.8 节。索引值为 0 表示引用该管理员 标识符记录中的所有元素,即可使用其中所有 HS_SECKEY 或 HS_PUBKEY 元素。

message HsPubkey doirp_v3/v1/element/hs_pubkey.proto

规范:4.3.6 IDENTITY: HS_PUBKEY

HS_PUBKEY 元素存储公钥。可用作管理身份(在 HS_ADMIN 或 HS_VLIST 中引用以授权),或在 DO-IRP 认证中标识管理身份。引用格式为标识符与元素索引的组合,常写作 :

元素的 以二进制编码公钥:首先是描述密钥类型的 UTF8 字符串;然后是 2 字节预留选项; 最后是若干带长度前缀的字节数组(数量取决于密钥类型),包含公钥本身。

Field Type Description
1 type string

描述密钥类型的 UTF8 字符串,详见 Type

2 option uint32

预留的 2 字节选项

3 bytes repeated bytes

根据密钥类型决定数量的字节数组,包含公钥本身。

message HsServ doirp_v3/v1/element/hs_serv.proto

规范:4.3.4 SERVICE IDENTIFIER: HS_SERV

任意 DO-IRP 服务都可由一个或多个 HS_SITE 元素描述。这些 HS_SITE 元素可以直接放在相应的前缀 标识符上,或通过在前缀记录中使用 HS_SERV 元素增加一层间接引用。HS_SERV 的值是一个服务标识符, 其记录包含定义 DO-IRP 服务的 HS_SITE 元素,从而可在独立记录中维护 HS_SITE。

使用服务标识符可在多个前缀间共享服务信息,也便于集中修改服务配置(如新增站点),而无需逐个 前缀修改。

虽不常见,但前缀标识符可同时包含多个 HS_SITE 和 HS_SERV 元素。这种情况下,该前缀的服务信息 应视为:前缀记录中的所有 HS_SITE 元素,与所有 HS_SERV 元素指向的服务信息的拼接。

使用服务标识符有若干注意事项:应避免多级服务标识符重定向(效率低下,虽不被视为错误);应检测 服务标识符的循环引用或指向不存在标识符的 HS_SERV,并返回错误。

规范:4.3.5 SERVICE IDENTIFIER: HS_SERV.PREFIX

HS_SERV.PREFIX 对应 HS_SITE.PREFIX 的角色与 HS_SERV 对应 HS_SITE 类似。若前缀标识符包含 HS_SERV.PREFIX,其值为一个标识符,其记录通过一个或多个 HS_SITE.PREFIX(或递归的 HS_SERV.PREFIX) 描述客户端可用于解析原始前缀派生前缀的服务信息。

Field Type Description
1 service_doid string

该标识符的记录中包含定义 DO-IRP 服务的 HS_SITE 元素。

message ServiceInterface (Nested in doirp_v3.v1.element.HsSite.ServerRecord ) doirp_v3/v1/element/hs_site.proto

规范: 组成: [ ]

4 字节整数(三元组数量)+ 多个三元组,每个三元组描述一条服务接口。

Field Type Description
1 type doirp_v3.v1.element.HsSite.ServerRecord.ServiceInterface.Type

规范: 为 1 字节位掩码,指示接口用于管理(0x01)、解析(0x02)或二者(0x03)。

2 transport_protocol doirp_v3.v1.element.HsSite.ServerRecord.ServiceInterface.TransportProtocol

规范: 亦为 1 字节位掩码,指示协议:UDP(0x00)、TCP(0x01)、HTTP(0x02)、HTTPS(0x03);补充:gRPC(0x04)。

3 port_number uint32

规范: 为 4 字节无符号整数,指定接口端口;常用端口:UDP/TCP 2641,HTTP 8000。

message ServerRecord (Nested in doirp_v3.v1.element.HsSite ) doirp_v3/v1/element/hs_site.proto

规范: 包含:

Field Type Description
1 id uint32

规范: 4 字节无符号整数,唯一标识站点下的服务器进程。无需从 1 开始也不要求连续,仅用于区分服务器。 同一台机器可运行多台服务器, 不同即可。

2 address string

此处以文本表示

3 public_key doirp_v3.v1.element.HsPubkey

规范: 4 字节整数 + 公钥字节数组(服务器认证密钥)。整数表示后续数组长度。公钥数组由:描述密钥类型 的 UTF8 字符串、2 字节预留选项、以及若干带长度前缀的字节数组(取决于密钥类型)组成。 当前类型:DSA_PUB_KEY(选项后 4 个数组,存 q,p,g,y),RSA_PUB_KEY(选项后 2 个数组:指数、 模数,随后一个空数组即四个 0)。未来可扩展其他类型。

该公钥可用于验证 DO-IRP 服务器的服务响应。

4 service_interface repeated doirp_v3.v1.element.HsSite.ServerRecord.ServiceInterface

服务器提供的服务接口列表

message HsSite doirp_v3/v1/element/hs_site.proto

规范:4.3.2 SERVICE SITE INFORMATION: HS_SITE

HS_SITE 提供 DO-IRP 服务信息,告知客户端如何联系服务,包括服务器地址、协议版本、公钥。 每个前缀标识符应在记录中包含一个或多个 HS_SITE 元素,称为该前缀的服务信息,指明可对基于 该前缀的标识符进行创建、更新、删除、解析的服务器位置。解析不存在的标识符时,本地 HS_SITE 所述服务会返回 “identifier not found”;解析不属于指定 LIS 的非法标识符也将得到同样响应。

服务信息由系统管理员维护,必须反映其管理的每个前缀的 DO-IRP 服务配置。通过 HS_SERV (服务标识符,见 4.3.4)可以增加一层间接引用,让多个前缀共享一组 HS_SITE。客户端依赖服务信息 定位负责的 DO-IRP 服务器以发送请求,并可用其验证服务器响应。

HS_SITE 元素的 为 HS_SITE, 由下列二进制字段组成:

规范: 2 字节值,标识 HS_SITE 元素 编码格式的版本号,用于向后兼容。

注意此版本号与请求/响应消息中使用的 DO-IRP 协议版本不同。

Field Type Description
1 version uint32

当前版本号:1

2 protocol_version_major uint32

规范: 2 字节整数,表示该站点服务器支持的最高 DO-IRP 协议版本,高字节为主版本,低字节为次版本。 DO-IRP 3.0 的消息格式详见 6.2。该字段不是本文档的规范版本,而是前缀管理员为本地服务实现 指定的协议版本。支持本文描述的 DO-IRP 3.0 的本地服务应在 HS_SITE 中写 3.0。

3 protocol_version_minor uint32
4 serial_number uint32

应由 IRS 服务端自动递增

5 primary_mask uint32

规范: 8 位掩码,标识 DO-IRP 服务的主站点。首位为 ,指示该 HS_SITE 是否为主站点 (可执行管理操作)。次位为 ,指示是否存在多个主站点;0 表示仅有一个主站点、 所有管理在此进行,非 0 表示有多个主站点,可分别管理服务下的标识符。

6 hash_option doirp_v3.v1.element.HsSite.HashOption

服务站点在多服务器间分配标识符的哈希方式;单服务器场景无意义。

7 hash_filter string

预留 UTF8 字符串

8 attributes map<string, string>

这里用 map 表示,便于使用

9 server_records repeated doirp_v3.v1.element.HsSite.ServerRecord

每个 描述服务中的一台服务器

Enums

enum Permission doirp_v3/v1/element/hs_admin.proto

The set of possible permissions for an administrator. This is for generating consts, won't be used directly in .proto files.

Name Number Description
PERMISSION_UNSPECIFIED 0
PERMISSION_ADD_IDENTIFIER 1

规范:Add_Identifier (0x0001) 设在前缀标识符记录上时,允许已认证管理员在该前缀下创建新标识符;仅对前缀记录有意义。

PERMISSION_DELETE_IDENTIFIER 2

规范:Delete_Identifier (0x0002) 允许已认证管理员删除该标识符记录。

PERMISSION_ADD_DERIVED_PREFIX 4

规范:Add_Derived_Prefix (0x0004) 设在前缀标识符记录上时,允许已认证管理员创建该前缀的派生前缀;仅对前缀记录有意义。

PERMISSION_RESERVED 8

规范:Reserved (0x0008) 历史保留位。

PERMISSION_MODIFY_ELEMENT 16

规范:Modify_Element (0x0010) 允许已认证管理员修改除 HS_ADMIN 以外的元素;HS_ADMIN 由另一组权限管理。

PERMISSION_DELETE_ELEMENT 32

规范:Delete_Element (0x0020) 允许已认证管理员删除除 HS_ADMIN 以外的元素。

PERMISSION_ADD_ELEMENT 64

规范:Add_Element (0x0040) 允许已认证管理员添加除 HS_ADMIN 以外的元素。

PERMISSION_MODIFY_ADMIN 128

规范:Modify_Admin (0x0080) 允许已认证管理员修改 HS_ADMIN 元素。

PERMISSION_REMOVE_ADMIN 256

规范:Remove_Admin (0x0100) 允许已认证管理员删除 HS_ADMIN 元素。

PERMISSION_ADD_ADMIN 512

规范:Add_Admin (0x0200) 允许已认证管理员新增 HS_ADMIN 元素。

PERMISSION_AUTHORIZED_READ 1024

规范:Authorized_Read (0x0400) 允许已认证管理员读取带 ADMIN_READ 且无 PUBLIC_READ 的元素;没有此权限则无法读取需认证的元素。

PERMISSION_LIST_IDENTIFIERS 2048

规范:List_Identifiers (0x0800) 允许已认证管理员列出指定前缀下的所有标识符(即便分布在多服务器上),不含派生前缀下的标识符。 属于前缀级设置,需配置在对应前缀标识符记录上。

PERMISSION_LIST_DERIVED_PREFIXES 4096

规范:List_Derived_Prefixes (0x1000) 允许管理员列出指定前缀的全部派生前缀;若这些派生前缀还有派生,也包含在列表中(同一 DO-IRP 服务内)。 属于前缀级设置,需配置在前缀标识符记录上。

enum Type doirp_v3/v1/element/hs_pubkey.proto

This is for generating consts, won't be used directly in .proto files.

Name Number Description
TYPE_DSA_PUB_KEY 0
TYPE_RSA_PUB_KEY 1

enum Type doirp_v3/v1/element/hs_site.proto

Name Number Description
TYPE_UNSPECIFIED 0
TYPE_ADMINISTRATION 1
TYPE_RESOLUTION 2
TYPE_BOTH 3

enum TransportProtocol doirp_v3/v1/element/hs_site.proto

Name Number Description
TRANSPORT_PROTOCOL_UDP 0
TRANSPORT_PROTOCOL_TCP 1
TRANSPORT_PROTOCOL_HTTP 2
TRANSPORT_PROTOCOL_HTTPS 3
TRANSPORT_PROTOCOL_GRPC 4

enum HashOption doirp_v3/v1/element/hs_site.proto

Name Number Description
HASH_OPTION_HASH_BY_PREFIX 0
HASH_OPTION_HASH_BY_SUFFIX 1
HASH_OPTION_HASH_BY_IDENTIFIER 2