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

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.

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.

Spec: An octet followed by a 4-byte integer that specifies the Time-To-Live of the element. It is used to describe how long the element should be cached by clients before the source of the information (i.e., the corresponding DO-IRP server) should again be consulted. A zero value for a TTL indicates that the element should only be used for the transaction in progress and should not be cached. Any non-zero TTL is defined in terms of a TTL type (specified in the first octet), followed by the TTL value (the 32-bit integer that follows the TTL type). The TTL type indicates whether the TTL value is relative (octet 0x00) or absolute (octet 0x01). An absolute TTL value is an unsigned integer which defines the time to live as an expiration in terms of seconds since 00:00:00 UTC, January 1st 1970. A relative TTL specifies the time to live in terms of the number of seconds elapsed since the element was obtained by the client from any DO-IRP server. A relative TTL which would be negative if interpreted as a signed integer indicates that the element should not be cached.

defines the permissions bit flags for elements

Spec: 4.3 PRE-DEFINED ELEMENT TYPES

Type is a required field in an element, although the exact type to be used is open-ended. Some types are defined in this document and have specific server and client processing semantics. DO- IRP implementations must use the defined types whenever applicable. New types can be defined if different processing rules were to apply; in such cases, those new types may be registered by an organization as identifiers for resolution using DO-IRP under a prefix controlled by the organization.

Types defined in this document are assumed to have an implicit prefix of “0.TYPE”, although the prefix is generally omitted when writing about the use of these types.

The following types have defined DO-IRP server and client processing semantics: HS_ADMIN, HS_SITE, HS_SITE.PREFIX, HS_SERV, HS_SERV.PREFIX, HS_PUBKEY, HS_SECKEY, and HS_VLIST.

Additionally, the types HS_ALIAS, HS_CERT, and HS_SIGNATURE, while not necessary for DO-IRP service use, are considered standard system types that cut across multiple applications; and all are registered under the prefix “0.TYPE”.

Historical note: the term HS in the name of these types comes from the legacy notation that identified these types as Handle System (HS) types.

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 .—————————————————————.

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.

Spec: 4.3.1 IDENTIFIER ADMINISTRATOR: HS_ADMIN

An administrative operation on an identifier record or on the DO-IRP service (e.g., add, delete or modify an element) can only be performed by an administrator that is authenticated and that has adequate privileges.

We defined an “administrator” as an entity represented by an identifier and an element index within that identifier record. This identifier-index is a reference to an element that must contain a public key or secret key to be used when challenging the entity to authenticate itself.

An authenticated administrator is an entity that has demonstrated that it possesses either the private key matching the public key, or the secret key, pointed to by the administrator’s identifier- index element reference.

The privileges or authorizations that an administrator has over an identifier record is specified in one or more elements of type HS_ADMIN within that identifier record. Each HS_ADMIN element can be used to define a set of administrators sharing the same administration privilege. Identifiers with multiple administrators of different privileges may have multiple HS_ADMIN elements. HS_ADMIN elements are used by DO-IRP servers to authenticate administrators before fulfilling any DO-IRP administration request. However, as an implementation option, an identifier record without an HS_ADMIN element can be modified by a qualified DO-IRP server administrator.

An HS_ADMIN element is one whose field is HS_ADMIN and whose field consists of the following entries encoded as binary data:

Spec: 4.3.2 SERVICE SITE INFORMATION: HS_SITE

HS_SITE is used to provide information about a DO-IRP service to inform a DO-IRP clients how to contact it. This information specifies the server’s address, its protocol version, its public key. Each prefix identifier should have one or more HS_SITE elements in its prefix identifier record. This is called the service information for the prefix and denotes, among other things, the location of servers where any existing identifier that is based on that prefix can be created, updated, deleted, or resolved. A user that tries to resolve an identifier that does not exist will get a “identifier not found” response from the local service specified in the HS_SITE information. Attempts to resolve an invalid identifier, namely one that does not exist within the designated LIS, will get a “identifier not found” response from that local service.

The service information is managed by the system administrator. It must reflect the configuration of the DO-IRP service for each of the prefixes it manages. An additional layer of indirection is provided by the use of HS_SERV, which is called a service identifier; HS_SERV allows multiple prefixes to reference a single set of HS_SITE elements, as described in section 4.3.4. DO-IRP clients depend on the service information to locate a responsible DO-IRP server before they can send their service requests. The service information can also be used by clients to authenticate any service response from the server.

An HS_SITE element is one whose field is HS_SITE and whose field consists of the following entries encoded as binary data:

Spec: 4.3.4 SERVICE IDENTIFIER: HS_SERV

Any DO-IRP service can be defined in terms of one or more HS_SITE elements. These HS_SITE elements may be assigned directly to the relevant prefix identifier, or an additional level of indirection may be introduced through the use of an HS_SERV element in the prefix identifier record. The value of the HS_SERV element contains the service identifier, meaning an identifier whose record contains the HS_SITE elements defining the DO-IRP service. This way, the HS_SITE elements can be maintained in a separate record

Use of service identifiers allows sharing of service information among multiple prefixes. It also allows changes to service configuration (e.g., adding a new site) to be made in one place rather than in every prefix identifier involved.

Although not typical, a prefix identifier may have multiple HS_SITE and multiple HS_SERV elements. In such a case the service information for the prefix should be considered as the concatenation of the HS_SITE elements in the prefix identifier record, together with the service information from all of the HS_SERV elements.

The use of service identifiers raises several special considerations. Multiple levels of service identifier redirection should be avoided due to their lack of efficiency, but are not signaled as an error. Looped reference of service identifiers or HS_SERV elements that refer to non-existent service identifiers should be caught and error conditions passed back to the user.

4.3.5 SERVICE IDENTIFIER: HS_SERV.PREFIX

HS_SERV.PREFIX serves the same role with respect to HS_SITE.PREFIX as HS_SERV serves with respect to HS_SITE. If a prefix identifier has an HS_SERV.PREFIX element, the data of that element is an identifier, whose corresponding record describes, via one or more HS_SITE.PREFIX elements and/or recursively via HS_SERV.PREFIX elements, the service information at which clients may be able to resolve derived prefixes of the original prefix.

Spec: 4.3.6 IDENTITY: HS_PUBKEY

An element of type HS_PUBKEY stores a public key. The element can be used as an administrative identity, for referring to in HS_ADMIN or HS_VLIST elements for authorization, or for identifying the administrative identity in DO-IRP authentication. A reference to the element for use as an administrative identity is as a pair of the identifier and the index of the element within the identifier record; in this document this is often written with a colon as :.

The of the element is a binary encoding of the public key which for key types considered in this specification is as follows. First, there is a UTF8-string that describes the key type; then, a two- byte option field reserved for future use; and finally, a key-type-dependent number of length- prefixed byte-arrays that contains the public key itself.

Spec: 4.3.7 IDENTITY: HS_SECKEY

An element of type HS_SECKEY is used to store a secret key. The element can be used as an administrative identity, for referring to in HS_ADMIN or HS_VLIST elements for authorization, or for identifying the administrative identity in DO-IRP authentication.

The of the element is the secret key. In order to protect the secret key, the of the element should be set to forbid PUBLIC_READ. This is the only common usage of any other than PUBLIC_READ, ADMIN_READ, and ADMIN_WRITE.

Use of public keys is recommended over use of secret keys for DO-IRP authentication.

Spec: 4.3.8 VALUE LIST: HS_VLIST

HS_VLIST allows referencing a list of elements in other identifiers, and allows the referenced elements to be updated without requiring an update of the referring identifier record. An HS_VLIST element is one whose is HS_VLIST and whose consists of a 4-byte unsigned integer followed by a list of references to other elements. The integer specifies the number of references in the list. The references may refer to elements under the same identifier or elements from other identifiers. Each reference is encoded as an UTF8-string followed by a 4-byte unsigned integer that identifies the referenced identifier and its index.

HS_VLIST elements may be used to define administrator groups for identifiers. Each administrator (as defined in 4.3.1) in the HS_VLIST includes is a member of the administrator group. Each element reference is defined in terms of an : pair. An administrator group may also contain other administrator groups as its members. This allows administrator groups to be defined in a hierarchical fashion. Care must be taken, however, to avoid a cyclic definition of administrators or administrator groups. Multiple levels of administrator groups should be avoided due to their lack of efficiency, but will not be signaled as an error. Client software should be prepared to detect any potential cyclic definition of administrators that refer to non-existent elements and treat them as errors.

Spec: 4.3.9 ALIASES: HS_ALIAS

It is possible that the set of elements (i.e., type-value pairs) of a digital object may be included in other digital objects and thus multiple identifiers could be associated with the same information represented in digital form, thus creating, in effect, multiple different digital objects all with the same information represented in digital form. DO-IRP does not specify a specific mechanism for identifier records to reference all such alternatives, but various DO-IRP implementations and their users should use the pre-defined HS_ALIAS type in such cases.

An HS_ALIAS element is one whose field is HS_ALIAS and whose field contains a reference to another identifier. An identifier whose record contains an HS_ALIAS element is an alias to the identifier referenced in the HS_ALIAS element. An alias record should not have any additional elements other than HS_ALIAS or HS_ADMIN (for administration) elements. This is necessary to prevent any inconsistency between an identifier and its aliases.

During an identifier resolution, a client may get back an HS_ALIAS element. This indicates that the identifier in question is an alias identifier. The client may then retry the query against the identifier specified in the HS_ALIAS element until final results are obtained.

The use of HS_ALIAS introduces a number of special considerations. For example, multiple levels of aliases should be avoided for the sake of efficiency, but are not signaled as an error. Alias loops and aliases that point to non-existent identifiers should be caught and error conditions passed back to the user.

Spec: 6.2.2.1

The stands for operation code, which is a four-byte unsigned integer that specifies the intended operation.

A detailed description of each of these s can be found in section 7 of this document. In general, clients use the to tell the server what kind of operation they want to accomplish. Response from the server must maintain the same as the original request and use the to indicate the result.

Spec: 6.2.2.2

The is a 4-byte unsigned integer that is given by a server to indicate the result of any service request.

Detailed descriptions of these s can be found in section 7 of this document. In general, any request from a client must have its set to 0. The response message from the server must have a non-zero to indicate the result. For example, a response message from a server with set to RC_SUCCESS indicates that the server has successfully fulfilled the client’s request.