rpc Resolve(ResolveRequest) returns (ResolveResponse)

Spec: 7.2 QUERY OPERATION (OC_RESOLUTION)

A query operation consists of a client sending a query request to the responsible server and the server returning the query result to the client. Query requests are used to retrieve identifier elements assigned to any given identifier.

rpc AddElement(AddElementRequest) returns (AddElementResponse)

Spec: 7.7.1 ADD ELEMENT(S) (OC_ADD_ELEMENT)

Clients add elements to existing identifier records by sending ADD_ELEMENT requests to the responsible server. The Message Header of the ADD_ELEMENT request must set its to OC_ADD_ELEMENT.

rpc RemoveElement(RemoveElementRequest) returns (RemoveElementResponse)

Spec: 7.7.2 REMOVE ELEMENT(S) (OC_REMOVE_ELEMENT)

Clients remove existing elements by sending REMOVE_ELEMENT requests to the responsible server. The Message Header of the REMOVE_ELEMENT request must set its to OC_REMOVE_ELEMENT.

rpc ModifyElement(ModifyElementRequest) returns (ModifyElementResponse)

Spec: 7.7.3 MODIFY ELEMENT(S) (OC_MODIFY_ELEMENT)

Clients can make modifications to an existing element by sending MODIFY_ELEMENT requests to the responsible server. The Message Header of the MODIFY_ELEMENT request must set its to OC_MODIFY_ELEMENT.

rpc CreateDoid(CreateDoidRequest) returns (CreateDoidResponse)

Spec: 7.7.4 CREATE IDENTIFIER (OC_CREATE_ID)

Clients can create new identifiers by sending CREATE_ID requests to the responsible server.

rpc DeleteDoid(DeleteDoidRequest) returns (DeleteDoidResponse)

Spec: 7.7.5 DELETE IDENTIFIER (OC_DELETE_ID)

Clients delete existing identifiers by sending DELETE_ID requests to the responsible DO-IRP server. The Message Header of the DELETE_ID request must set its to OC_DELETE_ID.

rpc ChallengeResponse(ChallengeResponseRequest) returns (ChallengeResponseResponse)

Spec: 7.5 CLIENT AUTHENTICATION

Clients are asked to authenticate themselves as administrators when querying for any element with ADMIN_READ but no PUBLIC_READ permission. Client authentication is also required for any administration requests that require administrator privileges. This includes adding, removing, or modifying identifiers or elements.

Client authentication consists of multiple messages exchanged between the client and server. Such messages include the challenge from the server to the client to authenticate the client, the challenge-response from the client in response to the server’s challenge, and the verification request and response message if secret key authentication takes place. Messages exchanged during the authentication are correlated via a unique assigned by the server. For each authentication session, the server needs to maintain the state information that includes the server’s challenge, the challenge-response from the client, as well as the original client request.

The authentication starts with a response message from the server that contains a challenge to the client. The client must respond to the challenge with a challenge-response message. The server validates the challenge-response, either by verifying the digital signature inside the challenge- response, or by sending a verification request to another server (herein referred to as the verification server), that maintains the secret key for the administrator. The purpose of the challenge and the challenge-response is to prove to the server that the client possesses the private key (or the secret key) of the administrator. If the authentication fails, an error response will be sent back with the set to RC_AUTHEN_FAILED.

Upon successful client authentication, the server must also make sure that the administrator is authorized for the request. If the administrator has sufficient privileges, the server will process the request and send back the result. If the administrator does not have sufficient privileges, the server will return an error message with set to RC_INVALID_ADMIN.

Authentication is not about encryption (although encryption may be used in the process) and is accomplished by use of a Message Authentication Code or digital signature verification.

The following sections provide details of each message exchanged during the authentication process.

7.5.1 CHALLENGE FROM SERVER TO CLIENT

The Message Header of the CHALLENGE must keep the same as the original request and set the to RC_AUTH_NEEDED. If the message is not already part of an established session, the server must assign a non-zero unique in the Message Envelope to keep track of the authentication. It must also set the RD flag of the (see section 6.2.2.3) in the Message Header, regardless of whether the original request had the RD bit set or not. The Message Body of the server’s CHALLENGE is defined as follows:

<Message Body of Server’s Challenge> ::=

where

Message Digest of the request message, as defined in section 6.2.3. A 4-byte unsigned integer followed by a random string generated by the server via a secure random number generator. The integer specifies the number of octets in the random string. The size of the random string should be no less than 16 octets.

Note that the server will not sign the challenge if the client did not request the server to do so. If the client worries about whether it is speaking to the right server, it may ask the server to sign the . If the client requested the server to sign the but failed to validate the server’s signature, the client should discard the server’s response and reissue the request to the server.

7.5.2 CHALLENGE-RESPONSE FROM CLIENT TO SERVER

The Message Header of the CHALLENGE_RESPONSE must set its to OC_CHALLENGE_RESPONSE and its to 0.

Types

Error

ResolveResult

ServiceReferral

Field	Description
`message` string	Spec: A UTF8-String that explains the error.
`indexes` uint32[]	Spec: An optional field. Each index in the list is a 4-byte unsigned integer that refers to an element that contributed to the error. An example would be a server that is asked to add three elements, with indexes 1, 2, and 3, and elements with indexes of 1 and 2 already in existence. In this case, the server could return an error message with set to RC_ELEMENT_ALREADY_EXIST and add index 1 and 2 to the . Note that the server is not obligated to return the complete list of indexes that may have caused the error.

Field	Description
`record` DoidRecord

Spec: 7.4 SERVICE REFERRAL AND PREFIX REFERRAL

A server may receive requests for identifiers that are managed by some other server or service. When this happens, the server has the option to either return a referral message that directs the client to the proper DO-IRP service, or simply return an error message with set to RC_SERVER_NOT_RESP. Service referral also happens when ownership of identifiers moves from one service to another. It may also be used by any DO-IRP service to indicate that some or all of its service may be performed by another DO-IRP service. Prefix referral in particular is used to indicate that a given prefix or prefixes may be resolvable and administered at a different service.

DO-IRP servers use the HS_SITE.PREFIX and HS_SERV.PREFIX element types in order to determine whether to send an RC_PREFIX_REFERRAL request. When a DO-IRP server is asked to resolve a prefix identifier 0.NA/., and the server does not have any information about 0.NA/. but does have 0.NA/ and the record for 0.NA/ includes HS_SITE.PREFIX and/or HS_SERV.PREFIX elements, those elements are returned to the client as a prefix referral response.

Since this behavior is purely in the server, server configuration can override this. This specification does not define under what conditions servers will send other prefix referral or service referral responses.

The Message Header of a service referral must maintain the same as the one in the original request and set its to RC_SERVICE_REFERRAL or RC_PREFIX_REFERRAL. The Message Body of any service referral or prefix referral is defined as follows:

::= [ ] [ ]

Field	Description
`referralDoid` string	Spec: A UTF8-String that identifies the identifier (e.g., a service identifier) that maintains the referral information (i.e., the service information of the DO-IRP service to which it corresponds).
`elements` Element[]	Spec: An optional field that must be empty if the is provided. When not empty, it consists a list of HS_SITE or HS_SERV elements, or, in the case of a prefix referral, HS_SITE.PREFIX or HS_SERV.PREFIX elements.

ResolveRequest

Spec: 7.2.1 QUERY REQUEST (OC_RESOLUTION)

The Message Header of any query request must set its to OC_RESOLUTION (defined in section 6.2.2.1) and to 0.

The Message Body for any query request is defined as follows:

::=

Field	Description
`header` MessageHeader
`doid` string	Spec: A UTF8-String (as defined in section 6.1.4) that specifies the identifier to be resolved.
`indexes` uint32[]	Spec: Each number in the integer array is an index and refers to an element to be retrieved. Set to an empty array to ask for all the elements regardless of their index.
`types` string[]	Spec: Each UTF8-String in the list specifies a type. This tells the server to return all elements whose type is listed in the list. If a UTF8-String ends with the “.” (0x2E) character, the server must return all elements whose type is under the type hierarchy specified in the UTF8-String. This means that the type is either exactly the supplied UTF8-String omitting the terminal “.” character, or starts with the supplied UTF8- String including the “.” character. The may be empty. In this case, the server must return all elements regardless of their type.

ResolveResponse

Spec: 7.2.2 SUCCESSFUL QUERY RESPONSE

The Message Header of any query response must set its to OC_RESOLUTION. A successful query response must set its to RC_SUCCESS.

The message body of the successful query response is defined as follows:

::= [ ]

where

Optional field as defined in section 6.2.3. A UTF8-String that specifies the identifier queried by the client. A 4-byte unsigned integer followed by a list of elements. The integer specifies the number of elements in the list. The encoding of each element follows the specification given earlier (see section 4.1). The integer is set to zero if there is no element that satisfies the query.

7.2.3 UNSUCCESSFUL QUERY RESPONSE

If a server cannot fulfill a client’s request, it must return an error message. The general format for any error message from the server is specified in section 7.3 of this document.

For example, a server must return an error message if the queried identifier does not exist in its database. The error message will have an empty message body and have its set to RC_ID_NOT_FOUND.

Note that a server should NOT return an RC_ID_NOT_FOUND message if the server is not responsible for the identifier being queried. It is possible that the queried identifier exists but is managed by another DO-IRP server (under some other DO-IRP service). When this happens, the server should either send a service referral (see section 7.4) or simply return an error message with set to RC_SERVER_NOT_RESP. See the requests for OC_HOME_PREFIX, OC_UNHOME_PREFIX, and OC_LIST_HOMED_PREFIXES for administering which prefixes for which a server considers itself responsible.

If the identifier exists, but there are no elements which match the client’s query, then the server must return an RC_ELEMENT_NOT_FOUND message.

The server may return an error message with set to RC_SERVER_BUSY if the server is too busy to process the request. Like RC_ID_NOT_FOUND, an RC_SERVER_BUSY message also has an empty message body.

Servers should return an RC_ACCESS_DENIED message if the request does not have its PO flag set and asks for a specific element (via the index) that has neither PUBLIC_READ nor ADMIN_READ permission.

A server may ask its client to authenticate itself as the administrator during the resolution. This happens if the request does not have its PO flag set and any element in the query has ADMIN_READ permission, but no PUBLIC_READ permission. Details of client authentication are described in section 7.5

Field	Description
`header` MessageHeader
`error` Error
`result` ResolveResult	contains and
`serviceReferral` ServiceReferral	a service referral (see section 7.4)

AddElementRequest

AddElementResponse

RemoveElementRequest

RemoveElementResponse

ModifyElementRequest

ModifyElementResponse

CreateDoidRequest

CreateDoidResponse

DeleteDoidRequest

Spec: 7.7.5 DELETE IDENTIFIER (OC_DELETE_ID)

Clients delete existing identifiers by sending DELETE_ID requests to the responsible DO-IRP server. The Message Header of the DELETE_ID request must set its to OC_DELETE_ID.

The Message Body of any DELETE_ID request is defined as follows:

::=

The server that receives the DELETE_ID request must first authenticate the client as the administrator with the DELETE_ID privilege. Upon successful authentication, the server will proceed to delete the identifier along with any elements assigned to the identifier. If successful, the server will return an RC_SUCCESS message to the client.

Each DELETE_ID request must be carried out as a transaction. If any part of the DELETE_ID process fails, the entire operation must be rolled back. For example, if the server fails to remove any elements assigned to the identifier (before deleting the identifier), it must return an error message without deleting the identifier. A DELETE_ID request that asks to delete a non-existing identifier will also be treated as an error. The server will return an error message with the set to RC_ID_NOT_EXIST.

DELETE_ID requests can also be used to delete prefix identifiers.

Field	Description
`header` MessageHeader
`doid` string	Spec: A UTF8-String that specifies the identifier.

DeleteDoidResponse

ChallengeResponseRequest

Spec: 7.5.2 CHALLENGE-RESPONSE FROM CLIENT TO SERVER

The Message Header of the CHALLENGE_RESPONSE must set its to OC_CHALLENGE_RESPONSE and its to 0. It must also keep the same (in the Message Envelope) as specified in the challenge from the server.

The Message Body of the CHALLENGE_RESPONSE request is defines as follows:

::=

Field	Description
`header` MessageHeader
`authenticationType` string	Spec: A UTF8-String that identifies the type of authentication key used by the client. The field is set to “HS_SECKEY” if the client chooses to use a secret key for its authentication. The field is set to “HS_PUBKEY” if a public key is used instead.
`keyIdentifier` string	Spec: A UTF8-String that identifies the identifier that holds the public or secret key of the administrator.
`keyIndex` uint32	Spec: A 4-byte unsigned integer that specifies the index of the element (of the ) that holds the public or secret key of the administrator.
`challengeResponse` bytes	Spec: A 4-byte unsigned integer indicating the length of the following byte array, which contains either the Message Authentication Code (MAC) or the digital signature over the challenge from the server. The used to produce the MAC or signature is the concatenation of the bytes of the from the CHALLENGE message, excluding the initial 4 length bytes, followed by the from the CHALLENGE message, excluding the initial byte.

ChallengeResponseResponse

DoidRecord

Spec: 4 DATA MODEL

Each identifier may have a set of elements assigned to it, which are collectively known as the identifier’s “Identifier Record”. There is no inherent limit to the number of elements in each identifier record. Records can optionally contain an element which is a signature certifying the contents of the record; additionally, if requested by a client, messages used to transmit records shall be signed for security. Each such element has a specified “type” which is represented by a unique identifier of its own. DO-IRP servers maintain these Identifier Records and typically return an instance of each such requested Identifier Record in response to a request for resolution of that designated identifier. More tailored requests can result in specific elements of an identifier record being shown in a given returned identifier record.

4.1 IDENTIFIER RECORD

An identifier record thus consists of one or more elements, each of which contains multiple fields including its type, a value associated with that type, and a unique index number that distinguishes that element from other elements in the record, especially those with the same type. The specific type shown in an element may define the syntax, structure, possible semantics, or any other necessary descriptive characteristics of the element’s value field. Each element also contains a set of administrative information such as a timestamp, Time to Live (“TTL”) and certain associated permissions. Pre-defined types are discussed in section 4.3.

Figure 4.1 below shows the identifier “35.1234/abc” with a sample record with three elements with indexes 1,2 and 3; The element 1 is shown in detail below.

Identifier “35.1234/abc” | | V

: 3
: 2
————————————————————-

: 1
: 0.TYPE/URL
: http://www.dlib.org/dlib…
: {Relative: 24 hours}
: PUBLIC_READ, ADMIN_WRITE
: 927314334000

Figure 4.1: Identifier “35.1234/abc” and its set of three elements

Figure 4.1 shows a single element whose index is set to 1. The type for this element is URL [5], which is represented in the system by the resolvable identifier 0.TYPE/URL. In general, a type is represented as a unique identifier and will either be a system type or a user created type. The URL data as stated in the field is “http://www.dlib.org/dlib… “. The TTL (time to live) entry suggests that the record should be cached no more than 24 hours before the source of the information should be consulted again. The field grants anyone permission to read; but only the administrator has permission to update that particular element.

Field	Description
`doid` string
`elements` Element[]
`createdAt` uint32	The following two timestamp fields are not in the spec, added for convenience. Both are 4-byte unsigned integers representing the elapsed time since 00:00:00 UTC, January 1970 in seconds. the created time of the identifier
`updatedAt` uint32	last time the identifier was updated at the server

Element

Spec: 4.1 IDENTIFIER RECORD

Thus, an element may be thought of as group of fields which are defined below, along with the standard binary encoding of an element used by the DO-IRP protocol.

Field	Description
`index` uint32	Spec: An unsigned 32-bit integer that uniquely differentiates an element from all the other elements in the identifier record. The index 0 is reserved. For maximum compatibility with existing implementations, indexes greater than or equal to 2^31 (which would represent negative values if interpreted as signed integers) should not be used.
`type` string	Can be set to enum `Type`’s names (not values!)
`permission` uint32	an eight-bit bit-mask for access control of the element, see `Permission` for details
`ttl` Ttl	TTL of the element, see `Ttl` for details
`createdAt` uint32	A 4-byte unsigned integer that records the created of the identifier. The field contains elapsed time since 00:00:00 UTC, January 1970 in seconds. This field is not in the spec, added for convenience.
`updatedAt` uint32	Spec: A 4-byte unsigned integer that records the last time the element was updated at the server. The field contains elapsed time since 00:00:00 UTC, January 1970 in seconds.
`hsAdmin` HsAdmin	HS_ADMIN
`hsSite` HsSite	HS_SITE, HS_SITE.PREFIX
`hsServ` HsServ	HS_SERV, HS_SERV.PREFIX
`hsPubkey` HsPubkey	HS_PUBKEY
`hsSeckey` HsSeckey	HS_PUBKEY
`hsVlist` HsVlist	HS_VLIST
`hsAlias` HsAlias	HS_ALIAS

MessageHeader

Spec: 6.2.2 MESSAGE HEADER

The Message Header contains the common data elements among any protocol operation. It has a fixed size of 24 octets and consists of eight fields.

0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 .—————————————————————.

OpCode
ResponseCode
—————————————————————
OpFlag
—————————————————————
SiteInfoSerialNumber
—————————————————————
ExpirationTime
—————————————————————
BodyLength
‘—————————————————————’

Figure 6.2.2: Message Header Fields

Every message that is not truncated must have a Message Header. If a message has to be truncated for its transmission, the Message Header must appear in the first truncated portion of the message.

This is different from the Message Envelope, which appears in each truncated portion of the message.

Field	Description
`responseCode` ResponseCode
`opFlag` uint32	Spec: 6.2.2.3 The is a 32-bit bit-mask that defines various control options for protocol operation. The following figure shows the location of each option flag in the field. 1 1 1 1 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 .—————————————————————. \|AT \|CT \|ENC\|REC\|CA \|CN \|KC \|PO \|RD \|OWE\|MNS\|DNR\| Reserved \| \|—————————————————————\| \| Reserved \| ‘—————————————————————’ Figure 6.2.2.3: Option flags in the field AT AuThoritative bit. A request with the AT bit set (to 1) indicates that the request should be directed to the primary service site (instead of any mirroring sites). A response message with the AT bit set (to 1) indicates that the message is returned from a primary server (within the primary service site) CT CerTified bit. A request with the CT bit set (to 1) asks the server to sign its response with its digital signature by including a Message Credential (see section 6.2.4). A response with the CT bit set (to 1) indicates that the message is signed. The server must sign its response if the request has its CT bit set (to 1). If the server fails to provide a valid signature in its response, the client should discard the response and treat the request as failed. ENC ENCryption bit. A request with the ENC bit set (to 1) requires the server to encrypt its response using the pre-established session key. REC RECursive bit. A request with the REC bit set (to 1) asks the server to forward the query on behalf of the client if the request has to be processed by another DO-IRP server. The server may honor the request by forwarding the request to the appropriate server and passing on any result back to the client. The server may also deny any such request by sending a response with set to RC_SERVER_NOT_RESP. CA Cache Authentication. This bit is reserved. CN ContiNuous bit. A message with the CN bit set (to 1) tells the message recipient that more messages that are part of the same request (or response) will follow. This happens if a request (or response) has data that is sent as multiple messages. Unlike truncation at the level of the Message Envelope, which breaks down a single message into multiple for reasons of transport such as UDP message size, this indicates a request or response that is deliberately sent as multiple messages. This is used for example for the responses to requests to list identifiers. KC Keep Connection bit. A message with the KC bit set requests that the message recipient keep the TCP connection open (after the response is sent back). This allows the same TCP connection to be used for multiple operations. PO Public Only bit. Used by query operations only. A query request with the PO bit set (to 1) indicates that the client is only asking for elements that have the PUB_READ permission. A request with PO bit set to zero asks for all the elements regardless of their read permission. If any of the elements require ADMIN_READ permission, the server must authenticate the client as an administrator. RD Request-Digest bit. A request with the RD bit set (to 1) asks the server to include in its response the message digest of the request. A response message with the RD bit set (to 1) indicates that the first field in the Message Body contains the message digest of the original request. The message digest can be used to check the integrity of the server response. Details of these are discussed in section 6.2.3. OWE Overwrite when exists. When this bit is set on a request with OpCode OC_CREATE_ID or OC_ADD_ELEMENT, elements which already exist will be overwritten by the elements presented in the request. Otherwise the request will result in an error. MNS Mint new suffix. When this bit is set on a request to create an identifier, the “identifier” field of the request will be considered the initial portion of the eventual identifier, which will be extended by the server to a new complete identifier. The initial portion should contain the slash. DNR Do not refer. When this bit is set, a request which would normally result in a service referral or prefix referral response, will instead be applied on the server where the request is
`siteInfoSerialNumber` uint32	Spec: 6.2.2.4 The is a two-byte unsigned integer. The in a request refers to the of the HS_SITE element used by the client (to access the server). Servers can check the in the request to find out if the client has up-to-date service information. When possible, the server should fulfill a client’s request even if the service information used by the client is out-of-date. However, the response message should specify the latest version of service information in the field. Clients with out-of-date service information can update the service information. If the server cannot fulfill a client’s request due to expired service information, it should reject the request and return an error message with set to RC_EXPIRED_SITE_INFO.
`recursionCount` uint32	Spec: 6.2.2.5 The is a one-byte unsigned integer that specifies the number of service recursions. Service recursion happens if the server has to forward the client’s request to another server. Any request directly from the client must have its set to 0. If the server has to send a recursive request on behalf of the client, it must increment the by Any response from the server must maintain the same as the one in the request. To prevent an infinite loop of service recursion, the server should be configurable to stop sending a recursive request when the reaches a certain value.
`expirationTime` uint32	Spec: 6.2.2.6 The is a 4-byte unsigned integer that specifies the time when the message should be considered expired, relative to January 1st, 1970 GMT, in seconds. It is set to zero if no expiration is expected.

Services

DoIrpService