Package doirp_v3.v1.element
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 元素的
规范:
| Field | Type | Description | |
|---|---|---|---|
| 1 | permission |
uint32
|
See |
| 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
认证中标识管理身份。引用格式为标识符与元素索引的组合,常写作
元素的
| Field | Type | Description | |
|---|---|---|---|
| 1 | type |
string
|
描述密钥类型的 UTF8 字符串,详见 |
| 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
|
规范: |
| 2 | transport_protocol |
doirp_v3.v1.element.HsSite.ServerRecord.ServiceInterface.TransportProtocol
|
规范: |
| 3 | port_number |
uint32
|
规范:
|
message ServerRecord (Nested in doirp_v3.v1.element.HsSite ) doirp_v3/v1/element/hs_site.proto
规范:
| Field | Type | Description | |
|---|---|---|---|
| 1 | id |
uint32
|
规范: |
| 2 | address |
string
|
此处以文本表示 |
| 3 | public_key |
doirp_v3.v1.element.HsPubkey
|
规范: 该公钥可用于验证 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 元素的
规范:
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 | protocol_version_minor |
uint32
|
|
| 4 | serial_number |
uint32
|
应由 IRS 服务端自动递增 |
| 5 | primary_mask |
uint32
|
规范:
8 位掩码,标识 DO-IRP 服务的主站点。首位为 |
| 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 |