Handle System Protocol (ver 2.1) Specification :: RFC3652
Network Working Group S. Sun
Request for Comments: 3652 S. Reilly
Category: Informational L. Lannom
J. Petrone
CNRI
November 2003
Handle System Protocol (ver 2.1) Specification
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
IESG Note
Several groups within the IETF and IRTF have discussed the Handle
System and its relationship to existing systems of identifiers. The
IESG wishes to point out that these discussions have not resulted in
IETF consensus on the described Handle System, nor on how it might
fit into the IETF architecture for identifiers. Though there has
been discussion of handles as a form of URI, specifically as a URN,
these documents describe an alternate view of how namespaces and
identifiers might work on the Internet and include characterizations
of existing systems which may not match the IETF consensus view.
Abstract
The Handle System is a general-purpose global name service that
allows secured name resolution and administration over the public
Internet. This document describes the protocol used for client
software to access the Handle System for both handle resolution and
administration. The protocol specifies the procedure for a client
software to locate the responsible handle server of any given handle.
It also defines the messages exchanged between the client and server
for any handle operation.
Sun, et al. Informational [Page 1]
RFC 3652 Handle System Protocol (v2.1) November 2003
Table of Contents
1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Protocol Elements. . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Conventions. . . . . . . . . . . . . . . . . . . . . . . 4
2.1.1. Data Transmission Order. . . . . . . . . . . . . 4
2.1.2. Transport Layer. . . . . . . . . . . . . . . . . 5
2.1.3. Character Case . . . . . . . . . . . . . . . . . 6
2.1.4. Standard String Type: UTF8-String. . . . . . . . 7
2.2. Common Elements. . . . . . . . . . . . . . . . . . . . . 7
2.2.1. Message Envelope . . . . . . . . . . . . . . . . 8
2.2.2. Message Header . . . . . . . . . . . . . . . . . 11
2.2.3. Message Body . . . . . . . . . . . . . . . . . . 17
2.2.4. Message Credential . . . . . . . . . . . . . . . 18
2.3. Message Transmission . . . . . . . . . . . . . . . . . . 20
3. Handle Protocol Operations . . . . . . . . . . . . . . . . . . 21
3.1. Client Bootstrapping . . . . . . . . . . . . . . . . . . 21
3.1.1. Global Handle Registry and its Service
Information. . . . . . . . . . . . . . . . . . . 21
3.1.2. Locating the Handle System Service Component . . 22
3.1.3. Selecting the Responsible Server . . . . . . . . 23
3.2. Query Operation. . . . . . . . . . . . . . . . . . . . . 23
3.2.1. Query Request. . . . . . . . . . . . . . . . . . 24
3.2.2. Successful Query Response. . . . . . . . . . . . 25
3.2.3. Unsuccessful Query Response. . . . . . . . . . . 26
3.3. Error Response from Server . . . . . . . . . . . . . . . 26
3.4. Service Referral . . . . . . . . . . . . . . . . . . . . 27
3.5. Client Authentication. . . . . . . . . . . . . . . . . . 28
3.5.1. Challenge from Server to Client. . . . . . . . . 29
3.5.2. Challenge-Response from Client to Server . . . . 30
3.5.3. Challenge-Response Verification-Request. . . . . 33
3.5.4. Challenge-Response Verification-Response . . . . 33
3.6. Handle Administration. . . . . . . . . . . . . . . . . . 34
3.6.1. Add Handle Value(s). . . . . . . . . . . . . . . 34
3.6.2. Remove Handle Value(s) . . . . . . . . . . . . . 35
3.6.3. Modify Handle Value(s) . . . . . . . . . . . . . 36
3.6.4. Create Handle. . . . . . . . . . . . . . . . . . 37
3.6.5. Delete Handle. . . . . . . . . . . . . . . . . . 39
3.7. Naming Authority (NA) Administration . . . . . . . . . . 40
3.7.1. List Handle(s) under a Naming Authority. . . . . 40
3.7.2. List Sub-Naming Authorities under a Naming
Authority. . . . . . . . . . . . . . . . . . . . 41
3.8. Session and Session Management . . . . . . . . . . . . . 42
3.8.1. Session Setup Request. . . . . . . . . . . . . . 43
3.8.2. Session Setup Response . . . . . . . . . . . . . 46
3.8.3. Session Key Exchange . . . . . . . . . . . . . . 47
3.8.4. Session Termination. . . . . . . . . . . . . . . 48
Sun, et al. Informational [Page 2]
RFC 3652 Handle System Protocol (v2.1) November 2003
4. Implementation Guidelines. . . . . . . . . . . . . . . . . . . 48
4.1. Server Implementation. . . . . . . . . . . . . . . . . . 48
4.2. Client Implementation. . . . . . . . . . . . . . . . . . 49
5. Security Considerations. . . . . . . . . . . . . . . . . . . . 49
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 50
7. Informative References . . . . . . . . . . . . . . . . . . . . 50
8. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 52
9. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 53
1. Overview
The Handle System provides a general-purpose, secured global name
service for the Internet. It was originally conceived and described
in a paper by Robert Kahn and Robert Wilensky [18] in 1995. The
Handle System defines a client server protocol in which client
software submits requests via a network to handle servers. Each
request describes the operation to be performed on the server. The
server will process the request and return a message indicating the
result of the operation. This document specifies the protocol for
client software to access a handle server for handle resolution and
administration. It does not include the description of the protocol
used to manage handle servers. A discussion of the management
protocol is out of the scope of this document and will be made
available in a separate document. The document assumes that readers
are familiar with the basic concepts of the Handle System as
introduced in the "Handle System Overview" [1], as well as the data
model and service definition given in the "Handle System Namespace
and Service Definition" [2].
The Handle System consists of a set of service components as defined
in [2]. From the client's point of view, the Handle System is a
distributed database for handles. Different handles under the Handle
System may be maintained by different handle servers at different
network locations. The Handle protocol specifies the procedure for a
client to locate the responsible handle server of any given handle.
It also defines the messages exchanged between the client and server
for any handle operation.
Some key aspects of the Handle protocol include:
o The Handle protocol supports both handle resolution and
administration. The protocol follows the data and service
model defined in [2].
o A client may authenticate any server response based on the
server's digital signature.
Sun, et al. Informational [Page 3]
RFC 3652 Handle System Protocol (v2.1) November 2003
o A server may authenticate its client as handle administrator
via the Handle authentication protocol. The Handle
authentication protocol is a challenge-response protocol that
supports both public-key and secret-key based authentication.
o A session may be established between the client and server so
that authentication information and network resources (e.g.,
TCP connection) may be shared among multiple operations. A
session key can be established to achieve data integrity and
confidentiality.
o The protocol can be extended to support new operations.
Controls can be used to extend the existing operations. The
protocol is defined to allow future backward compatibility.
o Distributed service architecture. Support service referral
among different service components.
o Handles and their data types are based on the ISO-10646
(Unicode 2.0) character set. UTF-8 [3] is the mandated
encoding under the Handle protocol.
The Handle protocol (version 2.1) specified in this document has
changed significantly from its earlier versions. These changes are
necessary due to changes made in the Handle System data model and the
service model. Servers that implement this protocol may continue to
support earlier versions of the protocol by checking the protocol
version specified in the Message Envelope (see section 2.2.1).
2. Protocol Elements
2.1. Conventions
The following conventions are followed by the Handle protocol to
ensure interoperability among different implementations.
2.1.1. Data Transmission Order
The order of transmission of data packets follows the network byte
order (also called the Big-Endian [11]). That is, when a data-gram
consists of a group of octets, the order of transmission of those
octets follows their natural order from left to right and from top to
bottom, as they are read in English. For example, in the following
diagram, the octets are transmitted in the order they are numbered.
Sun, et al. Informational [Page 4]
RFC 3652 Handle System Protocol (v2.1) November 2003
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
.-------------------------------.
| 1 | 2 |
|-------------------------------|
| 3 | 4 |
|-------------------------------|
| 5 | 6 |
'-------------------------------'
If an octet represents a numeric quantity, the left most bit is the
most significant bit. For example, the following diagram represents
the value 170 (decimal).
0 1 2 3 4 5 6 7
.---------------.
|1 0 1 0 1 0 1 0|
'---------------'
Similarly, whenever a multi-octet field represents a numeric
quantity, the left most bit is the most significant bit and the most
significant octet of the whole field is transmitted first.
2.1.2. Transport Layer
The Handle protocol is designed so that messages may be transmitted
either as separate data-grams over UDP or as a continuous byte stream
via a TCP connection. The recommended port number for both UDP and
TCP is 2641.
UDP Usage
Messages carried by UDP are restricted to 512 bytes (not including
the IP or UDP header). Longer messages must be fragmented into
UDP packets where each packet carries a proper sequence number in
the Message Envelope (see Section 2.2.1).
The optimum retransmission policy will vary depending on the
network or server performance, but the following are recommended:
o The client should try other servers or service interfaces
before repeating a request to the same server address.
o The retransmission interval should be based on prior
statistics if possible. Overly aggressive retransmission
should be avoided to prevent network congestion. The
recommended retransmission interval is 2-5 seconds.
Sun, et al. Informational [Page 5]
RFC 3652 Handle System Protocol (v2.1) November 2003
o When transmitting large amounts of data, TCP-friendly
congestion control, such as an interface to the Congestion
Manager [12], should be implemented whenever possible to
avoid unfair consumption of the bandwidth against TCP-based
applications. Details of the congestion control will be
discussed in a separate document.
TCP Usage
Messages under the Handle protocol can be mapped directly into a
TCP byte-stream. However, the size of each message is limited by
the range of a 4-byte unsigned integer. Longer messages may be
fragmented into multiple messages before the transmission and
reassembled at the receiving end.
Several connection management policies are recommended:
o The server should support multiple connections and should
not block other activities waiting for TCP data.
o By default, the server should close the connection after
completing the request. However, if the request asks to
keep the connection open, the server should assume that the
client will initiate connection closing.
2.1.3. Character Case
Handles are character strings based on the ISO-10646 character set
and must be encoded in UTF-8. By default, handle characters are
treated as case-sensitive under the Handle protocol. A handle
service, however, may be implemented in such a way that ASCII
characters are processed case-insensitively. For example, the Global
Handle Registry (GHR) provides a handle service where ASCII
characters are processed in a case-insensitive manner. This suggests
that ASCII characters in any naming authority are case-insensitive.
When handles are created under a case-insensitive handle server,
their original case should be preserved. To avoid any confusion, the
server should avoid creating any handle whose character string
matches that of an existing handle, ignoring the case difference.
For example, if the handle "X/Y" was already created, the server
should refuse any request to create the handle "x/y" or any of its
case variations.
Sun, et al. Informational [Page 6]
RFC 3652 Handle System Protocol (v2.1) November 2003
2.1.4. Standard String Type: UTF8-String
Handles are transmitted as UTF8-Strings under the Handle protocol.
Throughout this document, UTF8-String stands for the data type that
consists of a 4-byte unsigned integer followed by a character string
in UTF-8 encoding. The leading integer specifies the number of
octets of the character string.
2.2. Common Elements
Each message exchanged under the system protocol consists of four
sections (see Fig. 2.2). Some of these sections (e.g., the Message
Body) may be empty depending on the protocol operation.
The Message Envelope must always be present. It has a fixed size of
20 octets. The Message Envelope does not carry any application layer
information and is primarily used to help deliver the message.
Content in the Message Envelope is not protected by the digital
signature in the Message Credential.
The Message Header must always be present as well. It has a fixed
size of 24 octets and holds the common data fields of all messages
exchanged between client and server. These include the operation
code, the response code, and the control options for each protocol
operation. Content in the Message Header is protected by the digital
signature in the Message Credential.
The Message Body contains data specific to each protocol operation.
Its format varies according to the operation code and the response
code in the Message Header. The Message Body may be empty. Content
in the Message Body is protected by the digital signature in the
Message Credential.
The Message Credential provides a mechanism for transport security
for any message exchanged between the client and server. A non-empty
Message Credential may contain the digital signature from the
originator of the message or the one-way Message Authentication Code
(MAC) based on a pre-established session key. The Message Credential
may be used to authenticate the message between the client and
server. It can also be used to check data integrity after its
transmission.
Sun, et al. Informational [Page 7]
RFC 3652 Handle System Protocol (v2.1) November 2003
.----------------------.
| | ; Message wrapper for proper message
| Message Envelope | ; delivery. Not protected by the
| | ; digital signature in the Message
| | ; Credential.
|----------------------|
| | ; Common data fields for all handle
| Message Header | ; operations.
| |
|----------------------|
| | ; Specific data fields for each
| Message Body | ; request/response.
| |
|----------------------|
| | ; Contains digital signature or
| Message Credential | ; message authentication code (MAC)
| | ; upon Message Header and Message
'----------------------' ; Body.
Fig 2.2: Message format under the Handle protocol
2.2.1. Message Envelope
Each message begins with a Message Envelope under the Handle
protocol. If a message has to be truncated before its transmission,
each truncated portion must also begin with a Message Envelope.
The Message Envelope allows the reassembly of the message at the
receiving end. It has a fixed size of 20 octets and consists of
seven 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
.---------------------------------------------------------------.
| MajorVersion | MinorVersion | MessageFlag |
|---------------------------------------------------------------|
| SessionId |
|---------------------------------------------------------------|
| RequestId |
|---------------------------------------------------------------|
| SequenceNumber |
|---------------------------------------------------------------|
| MessageLength |
'---------------------------------------------------------------'
Sun, et al. Informational [Page 8]
RFC 3652 Handle System Protocol (v2.1) November 2003
2.2.1.1. and
The and are used to identify the
version of the Handle protocol. Each of them is defined as a one-
byte unsigned integer. This specification defines the protocol
version whose is 2 and is 1.
and are designed to allow future
backward compatibility. A difference in indicates
major variation in the protocol format and the party with the lower
will have to upgrade its software to ensure precise
communication. An increment in is made when
additional capabilities are added to the protocol without any major
change to the message format.
2.2.1.2.
The consists of two octets defined as follows:
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
.---------------------------------------------------------------.
|CP |EC |TC | Reserved |
'---------------------------------------------------------------'
Bit 0 is the CP (ComPressed) flag that indicates whether the message
(excluding the Message Envelope) is compressed. If the CP bit is set
(to 1), the message is compressed. Otherwise, the message is not
compressed. The Handle protocol uses the same compression method as
used by the FTP protocol[8].
Bit 1 is the EC (EnCrypted) flag that indicates whether the message
(excluding the Message Envelope) is encrypted. The EC bit should
only be set under an established session where a session key is in
place. If the EC bit is set (to 1), the message is encrypted using
the session key. Otherwise the message is not encrypted.
Bit 2 is the TC (TrunCated) flag that indicates whether this is a
truncated message. Message truncation happens most often when
transmitting a large message over the UDP protocol. Details of
message truncation (or fragmentation) will be discussed in section
2.3.
Bits 3 to 15 are currently reserved and must be set to zero.
Sun, et al. Informational [Page 9]
RFC 3652 Handle System Protocol (v2.1) November 2003
2.2.1.3.
The is a four-byte unsigned integer that identifies a
communication session between the client and server.
Session and its are assigned by a server, either upon an
explicit request from a client or when multiple message exchanges are
expected to fulfill the client's request. For example, the server
will assign a unique in its response if it has to
authenticate the client. A client may explicitly ask the server to
set up a session as a virtually private communication channel like
SSL [4]. Requests from clients without an established session must
have their set to zero. The server must assign a unique
non-zero for each new session. It is also responsible
for terminating those sessions that are not in use after some period
of time.
Both clients and servers must maintain the same for
messages exchanged under an established session. A message whose
is zero indicates that no session has been established.
The session and its state information may be shared among multiple
handle operations. They may also be shared over multiple TCP
connections as well. Once a session is established, both client and
server must maintain their state information according to the
. The state information may include the stage of the
conversation, the other party's authentication information, and the
session key that was established for message encryption or
authentication. Details of these are discussed in section 3.8.
2.2.1.4.
Each request from a client is identified by a , a 4-byte
unsigned integer set by the client. Each must be unique
from all other outstanding requests from the same client. The
allows the client to keep track of its requests, and any
response from the server must include the correct .
2.2.1.5.
Messages under the Handle protocol may be truncated during their
transmission (e.g., under UDP). The is a 4-byte
unsigned integer used as a counter to keep track of each truncated
portion of the original message. The message recipient can
reassemble the original message based on the . The
must start with 0 for each message. Each truncated
message must set its TC flag in the Message Envelope. Messages that
are not truncated must set their to zero.
Sun, et al. Informational [Page 10]
RFC 3652 Handle System Protocol (v2.1) November 2003
2.2.1.6.
A 4-byte unsigned integer that specifies the total number of octets
of any message, excluding those in the Message Envelope. The length
of any single message exchanged under the Handle protocol is limited
by the range of a 4-byte unsigned integer. Longer data can be
transmitted as multiple messages with a common .
2.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 | RecursionCount| |
|---------------------------------------------------------------|
| ExpirationTime |
|---------------------------------------------------------------|
| BodyLength |
'---------------------------------------------------------------'
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.
2.2.2.1.
The stands for operation code, which is a four-byte unsigned
integer that specifies the intended operation. The following table
lists the s that MUST be supported by all implementations in
order to conform to the base protocol specification. Each operation
code is given a symbolic name that is used throughout this document
for easy reference.
Sun, et al. Informational [Page 11]
RFC 3652 Handle System Protocol (v2.1) November 2003
Op_Code Symbolic Name Remark
--------- ------------- ------
0 OC_RESERVED Reserved
1 OC_RESOLUTION Handle query
2 OC_GET_SITEINFO Get HS_SITE values
100 OC_CREATE_HANDLE Create new handle
101 OC_DELETE_HANDLE Delete existing handle
102 OC_ADD_VALUE Add handle value(s)
103 OC_REMOVE_VALUE Remove handle value(s)
104 OC_MODIFY_VALUE Modify handle value(s)
105 OC_LIST_HANDLE List handles
106 OC_LIST_NA List sub-naming authorities
200 OC_CHALLENGE_RESPONSE Response to challenge
201 OC_VERIFY_RESPONSE Verify challenge response
300
: { Reserved for handle server administration }
399
400 OC_SESSION_SETUP Session setup request
401 OC_SESSION_TERMINATE Session termination request
402 OC_SESSION_EXCHANGEKEY Session key exchange
A detailed description of each of these s can be found in
section 3 of this document. In general, clients use the to
tell the server what kind of handle operation they want to
accomplish. Response from the server must maintain the same
as the original request and use the to indicate the
result.
2.2.2.2.
The is a 4-byte unsigned integer that is given by a
server to indicate the result of any service request. The list of
s used in the Handle protocol is defined in the
following table. Each response code is given a symbolic name that is
used throughout this document for easy reference.
Sun, et al. Informational [Page 12]
RFC 3652 Handle System Protocol (v2.1) November 2003
Res. Code Symbolic Name Remark
--------- ------------- ------
0 RC_RESERVED Reserved for request
1 RC_SUCCESS Success response
2 RC_ERROR General error
3 RC_SERVER_BUSY Server too busy to respond
4 RC_PROTOCOL_ERROR Corrupted or
unrecognizable message
5 RC_OPERATION_DENIED Unsupported operation
6 RC_RECUR_LIMIT_EXCEEDED Too many recursions for
the request
100 RC_HANDLE_NOT_FOUND Handle not found
101 RC_HANDLE_ALREADY_EXIST Handle already exists
102 RC_INVALID_HANDLE Encoding (or syntax) error
200 RC_VALUE_NOT_FOUND Value not found
201 RC_VALUE_ALREADY_EXIST Value already exists
202 RC_VALUE_INVALID Invalid handle value
300 RC_EXPIRED_SITE_INFO SITE_INFO out of date
301 RC_SERVER_NOT_RESP Server not responsible
302 RC_SERVICE_REFERRAL Server referral
303 RC_NA_DELEGATE Naming authority delegation
takes place.
400 RC_NOT_AUTHORIZED Not authorized/permitted
401 RC_ACCESS_DENIED No access to data
402 RC_AUTHEN_NEEDED Authentication required
403 RC_AUTHEN_FAILED Failed to authenticate
404 RC_INVALID_CREDENTIAL Invalid credential
405 RC_AUTHEN_TIMEOUT Authentication timed out
406 RC_UNABLE_TO_AUTHEN Unable to authenticate
500 RC_SESSION_TIMEOUT Session expired
501 RC_SESSION_FAILED Unable to establish session
502 RC_NO_SESSION_KEY No session yet available
503 RC_SESSION_NO_SUPPORT Session not supported
504 RC_SESSION_KEY_INVALID Invalid session key
900 RC_TRYING Request under processing
901 RC_FORWARDED Request forwarded to
another server
902 RC_QUEUED Request queued for later
processing
Sun, et al. Informational [Page 13]
RFC 3652 Handle System Protocol (v2.1) November 2003
Response codes under 10000 are reserved for system use. Any message
with a response code under 10000 but not listed above should be
treated as an unknown error. Response codes above 10000 are user
defined and can be used for application specific purposes.
Detailed descriptions of these s can be found in
section 3 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.
2.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 | Reserved |
|---------------------------------------------------------------|
| Reserved |
'---------------------------------------------------------------'
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. 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.
Sun, et al. Informational [Page 14]
RFC 3652 Handle System Protocol (v2.1) November 2003
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
handle server. The server may honor the request by
forwarding the request to the appropriate handle 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. A request with the CA bit set (to
1) asks the caching server (if any) to authenticate any
server response (e.g., verifying the server's signature)
on behalf of the client. A response with the CA bit set
(to 1) indicates that the response has been
authenticated by the caching server.
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 too
large to fit into any single message and has to be
fragmented into multiple messages.
KC - Keep Connection bit. A message with the KC bit set
requires the message recipient to keep the TCP
connection open (after the response is sent back). This
allows the same TCP connection to be used for multiple
handle 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 handle values that have the
PUB_READ permission. A request with PO bit set to zero
asks for all the handle values regardless of their read
permission. If any of the handle values require
ADMIN_READ permission, the server must authenticate the
client as the handle 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 later in this document.
Sun, et al. Informational [Page 15]
RFC 3652 Handle System Protocol (v2.1) November 2003
All other bits in the field are reserved and must be set to
zero.
In general, servers must honor the specified in the request.
If a requested option cannot be met, the server should return an
error message with the proper as defined in the
previous section.
2.2.2.4.
The is a two-byte unsigned integer. The
in a request refers to the of
the HS_SITE value 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 from
the Global Handle Registry. 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.
2.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 1. 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.
2.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.
Sun, et al. Informational [Page 16]
RFC 3652 Handle System Protocol (v2.1) November 2003
2.2.2.7.
The is a 4-byte unsigned integer that specifies the
number of octets in the Message Body. The does not
count the octets in the Message Header or those in the Message
Credential.
2.2.3. Message Body
The Message Body always follows the Message Header. The number of
octets in the Message Body can be determined from the in
the Message Header. The Message Body may be empty. The exact format
of the Message Body depends on the and the in
the Message Header. Details of the Message Body under each
and are described in section 3 of this document.
For any response message, if the Message Header has its RD bit (in
) set to 1, the Message Body must begin with the message
digest of the original request. The message digest is defined as
follows:
::=
where
An octet that identifies the algorithm used to generate the
message digest. If the octet is set to 1, the digest is
generated using the MD5 [9] algorithm. If the octet is set
to 2, SHA-1 [10] algorithm is used.
The message digest itself. It is calculated upon the
Message Header and the Message Body of the original request.
The length of the field is fixed according to the digest
algorithm. For MD5 algorithm, the length is 16 octets. For
SHA-1, the length is 20 octets.
The Message Body may be truncated into multiple portions during its
transmission (e.g., over UDP). Recipients of such a message may
reassemble the Message Body from each portion based on the
in the Message Envelope.
Sun, et al. Informational [Page 17]
RFC 3652 Handle System Protocol (v2.1) November 2003
2.2.4. Message Credential
The Message Credential is primarily used to carry any digital
signatures signed by the message issuer. It may also carry the
Message Authentication Code (MAC) if a session key has been
established. The Message Credential is used to protect contents in
the Message Header and the Message Body from being tampered with
during transmission. The format of the Message Credential is
designed to be semantically compatible with PKCS#7 [5]. Each Message
Credential consists of the following 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
.---------------------------------------------------------------.
| CredentialLength |
|---------------------------------------------------------------|
| Version | Reserved | Options |
|---------------------------------------------------------------|
|
| Signer:
|
|---------------------------------------------------------------|
| Type (UTF8-String) |
|---------------------------------------------------------------|
|
| SignedInfo: : 4-byte unsigned integer
| DigestAlgorithm:
| SignedData:
|
'---------------------------------------------------------------'
where
A 4-byte unsigned integer that specifies the number of octets in
the Message Credential. It must be set to zero if the message has
no Message Credential.
An octet that identifies the version number of the Message
Credential. The version number specified in this document is
zero.
An octet that must be set to zero.
Two octets reserved for various cryptography options.
Sun, et al. Informational [Page 18]
RFC 3652 Handle System Protocol (v2.1) November 2003
::=
A reference to a handle value in terms of the and the
of the handle value. The handle value may contain the
public key, or the X.509 certificate, that can be used to
validate the digital signature.
A UTF8-String that indicates the type of content in the
field (described below). It may contain HS_DIGEST if
contains the message digest, or HS_MAC if
contains the Message Authentication Code (MAC). The
field will specify the signature algorithm identifier if
contains a digital signature. For example, with the
field set to HS_SIGNED_PSS, the field will
contain the digital signature generated using the RSA-PSS
algorithm [16]. If the field is set to HS_SIGNED, the
field will contain the digital signature generated
from a DSA public key pair.
::=
where
A 4-byte unsigned integer that specifies the number of
octets in the field.
A UTF8-String that refers to the digest algorithm used to
generate the digital signature. For example, the value
"SHA-1" indicates that the SHA-1 algorithm is used to
generate the message digest for the signature.
::=
where
A 4-byte unsigned integer that specifies the number of
octets in the .
Contains the digital signature or the MAC over the
Message Header and Message Body. The syntax and
semantics of the signature depend on the field
Sun, et al. Informational [Page 19]
RFC 3652 Handle System Protocol (v2.1) November 2003
and the public key referenced in the field.
For example, if the field is "HS_SIGNED" and
the public key referred to by the field is
a DSA [6] public key, the signature will be the
ASN.1 octet string representation of the parameter R
and S as described in [7]. If the field
refers to a handle value that contains a X.509
certificate, the signature should be encoded according
to RFC 3279 and RFC 3280 [14, 15].
The Message Credential may contain the message authentication code
(MAC) generated using a pre-established session key. In this case,
the field must set its to a zero-length UTF8-String
and its to the specified in the Message Envelope.
The field must contain the MAC in its field.
The MAC is the result of the one-way hash over the concatenation of
the session key, the , the , and the
session key again.
The Message Credential in a response message may contain the digital
signature signed by the server. The server's public key can be found
in the service information used by the client to send the request to
the server. In this case, the client should ignore any reference in
the field and use the public key in the service information
to verify the signature.
The Message Credential can also be used for non-repudiation purposes.
This happens if the Message Credential contains a server's digital
signature. The signature may be used as evidence to demonstrate that
the server has rendered its service in response to a client's
request.
The Message Credential provides a mechanism for safe transmission of
any message between the client and server. Any message whose Message
Header and Message Body complies with its Message Credential suggests
that the message indeed comes from its originator and assures that
the message has not been tampered with during its transmission.
2.3. Message Transmission
A large message may be truncated into multiple packets during its
transmission. For example, to fit the size limit of a UDP packet,
the message issuer must truncate any large message into multiple UDP
packets before its transmission. The message recipient must
reassemble the message from these truncated packets before further
processing. Message truncation must be carried out over the entire
Sun, et al. Informational [Page 20]
RFC 3652 Handle System Protocol (v2.1) November 2003
message except the Message Envelope. A new Message Envelope has to
be inserted in front of each truncated packet before its
transmission. For example, a large message that consists of
.--------------------------------------------------------.
| Message Envelope | Message Header, Body, Credential |
'--------------------------------------------------------'
may be truncated into:
.--------------------------------------------.
| Message Envelope 1 | Truncated_Packet 1 |
'--------------------------------------------'
.--------------------------------------------.
| Message Envelope 2 | Truncated_Packet 2 |
'--------------------------------------------'
......
.--------------------------------------------.
| Message Envelope N | Truncated Packet N |
'--------------------------------------------'
where the "Truncated_packet 1", "Truncated_packet 2", ..., and
"Truncated_packet N" result from truncating the Message Header, the
Message Body and the Message Credential. Each "Message Envelope i"
(inserted before each truncation) must set its TC flag to 1 and
maintain the proper sequence count (in the ). Each
"Message Envelope i" must also set its to reflect the
size of the packet. The recipient of these truncated packets can
reassemble the message by concatenating these packets based on their
.
3. Handle Protocol Operations
This section describes the details of each protocol operation in
terms of messages exchanged between the client and server. It also
defines the format of the Message Body according to each and
in the Message Header.
3.1. Client Bootstrapping
3.1.1. Global Handle Registry and its Service Information
The service information for the Global Handle Registry (GHR) allows
clients to contact the GHR to find out the responsible service
components for their handles. The service information is a set of
HS_SITE values assigned to the root handle "0.NA/0.NA" and is also
Sun, et al. Informational [Page 21]
RFC 3652 Handle System Protocol (v2.1) November 2003
called the root service information. The root service information
may be distributed along with the client software, or be downloaded
from the Handle System website at http://www.handle.net.
Changes to the root service information are identified by the
in the HS_SITE values. A server at GHR can find out
if the root service information used by the client is outdated by
checking the in the client's request. The client
should update the root service information if the of
the response message is RC_EXPIRED_SITE_INFO. Clients may obtain the
most up-to-date root service information from the root handle. The
GHR must sign the root service information using the public key
specified in the outdated service information (identified in the
client's request) so that the client can validate the signature.
3.1.2. Locating the Handle System Service Component
Each handle under the Handle System is managed by a unique handle
service component (e.g., LHS). For any given handle, the responsible
service component (and its service information) can be found from its
naming authority handle. Before resolving any given handle, the
client needs to find the responsible service component by querying
the naming authority handle from the GHR.
For example, to find the responsible LHS for the handle "1000/abc",
client software can query the GHR for the HS_SITE (or HS_SERV) values
assigned to the naming authority handle "0.NA/1000". The set of
HS_SITE values provides the service information of the LHS that
manages every handle under the naming authority "1000". If no
HS_SITE values are found, the client can check if there is any
HS_SERV value assigned to the naming authority handle. The HS_SERV
value provides the service handle that maintains the service
information for the LHS. Service handles are used to manage the
service information shared by different naming authorities.
It is possible that the naming authority handle requested by the
client does not reside at the GHR. This happens when naming
authority delegation takes place. Naming authority delegation
happens when a naming authority delegates an LHS to manage all its
child naming authorities. In this case, the delegating naming
authority must contain the service information, a set of
HS_NA_DELEGATE values, of the LHS that manages its child naming
authorities.
All top-level naming authority handles must be registered and managed
by the GHR. When a server at the GHR receives a request for a naming
authority that has been delegated to an LHS, it must return a message
with the set to RC_NA_DELEGATE, along with the
Sun, et al. Informational [Page 22]
RFC 3652 Handle System Protocol (v2.1) November 2003
HS_NA_DELAGATE values from the nearest ancestor naming authority.
The client can query the LHS described by the HS_NA_DELAGATE values
for the delegated naming authority handle. In practice, the ancestor
naming authority should make itself available to any handle server
within the GHR, by replicating itself at the time of delegation.
This will prevent any cross-queries among handle servers (within a
service site) when the naming authority in query and the ancestor
naming authority do not hash into the same handle server.
3.1.3. Selecting the Responsible Server
Each handle service component is defined in terms of a set of HS_SITE
values. Each of these HS_SITE values defines a service site within
the service component. A service site may consist of a group of
handle servers. For any given handle, the responsible handle server
within the service component can be found following this procedure:
1. Select a preferred service site.
Each service site is defined in terms of an HS_SITE value. The
HS_SITE value may contain a or other attributes
(under the ) to help the selection. Clients
must select the primary service site for any administrative
operations.
2. Locate the responsible server within the service site.
This can be done as follows: Convert every ASCII character in
the handle to its upper case. Calculate the MD5 hash of the
converted handle string according to the given in
the HS_SITE value. Take the last 4 bytes of the hash result as
a signed integer. Modulo the absolute value of the integer by
the given in the HS_SITE value. The result is
the sequence number of the listed in the HS_SITE
value. For example, if the result of the modulation is 2, the
third listed in the should be
selected. The defines the responsible handle
server for the given handle.
3.2. Query Operation
A query operation consists of a client sending a query request to the
responsible handle server and the server returning the query result
to the client. Query requests are used to retrieve handle values
assigned to any given handle.
Sun, et al. Informational [Page 23]
RFC 3652 Handle System Protocol (v2.1) November 2003
3.2.1. Query Request
The Message Header of any query request must set its to
OC_RESOLUTION (defined in section 2.2.2.1) and to 0.
The Message Body for any query request is defined as follows:
::=
where
A UTF8-String (as defined in section 2.1.4) that specifies
the handle to be resolved.
A 4-byte unsigned integer followed by an array of 4-byte
unsigned integers. The first integer indicates the number
of integers in the integer array. Each number in the
integer array is a handle value index and refers to a handle
value to be retrieved. The client sets the first integer to
zero (followed by an empty array) to ask for all the handle
values regardless of their index.
A 4-byte unsigned integer followed by a list of UTF8-
Strings. The first integer indicates the number of
UTF8-Strings in the list that follows. Each UTF8-String in
the list specifies a data type. This tells the server to
return all handle values whose data type is listed in the
list. If a UTF8-String ends with the '.' (0x2E) character,
the server must return all handle values whose data type is
under the type hierarchy specified in the UTF8-String. The
may contain no UTF8-String if the first integer
is 0. In this case, the server must return all handle
values regardless of their data type.
If a query request does not specify any index or data type and the PO
flag (in the Message Header) is set, the server will return all the
handle values that have the PUBLIC_READ permission. Clients can also
send queries without the PO flag set. In this case, the server will
return all the handle values with PUBLIC_READ permission and all the
handle values with ADMIN_READ permission. If the query requests a
specific handle value via the value index and the value does not have
PUBLIC_READ permission, the server should accept the request (and
authenticate the client) even if the request has its PO flag set.
Sun, et al. Informational [Page 24]
RFC 3652 Handle System Protocol (v2.1) November 2003
If a query consists of a non-empty but an empty
, the server should only return those handle values whose
indexes are listed in the . Likewise, if a query consists
of a non-empty but an empty , the server should
only return those handle values whose data types are listed in the
.
When both and fields are non-empty, the server
should return all handle values whose indexes are listed in the
AND all handle values whose data types are listed in the
.
3.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 2.2.3.
A UTF8-String that specifies the handle queried by the
client.
A 4-byte unsigned integer followed by a list of handle
values. The integer specifies the number of handle values
in the list. The encoding of each handle value follows the
specification given in [2] (see section 3.1). The integer
is set to zero if there is no handle value that satisfies
the query.
Sun, et al. Informational [Page 25]
RFC 3652 Handle System Protocol (v2.1) November 2003
3.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 3.3 of this document.
For example, a server must return an error message if the queried
handle does not exist in its database. The error message will have
an empty message body and have its set to
RC_HANDLE_NOT_FOUND.
Note that a server should NOT return an RC_HANDLE_NOT_FOUND message
if the server is not responsible for the handle being queried. It is
possible that the queried handle exists but is managed by another
handle server (under some other handle service). When this happens,
the server should either send a service referral (see section 3.4) or
simply return an error message with set to
RC_SERVER_NOT_RESP.
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_HANDLE_NOT_FOUND, an RC_SERVER_BUSY message also has an empty
message body.
Servers should return an RC_ACCESS_DENIED message if the request asks
for a specific handle value (via the handle value index) that has
neither PUBLIC_READ nor ADMIN_READ permission.
A handle Server may ask its client to authenticate itself as the
handle administrator during the resolution. This happens if any
handle value in query has ADMIN_READ permission, but no PUBLIC_READ
permission. Details of client authentication are described later in
this document.
3.3. Error Response from Server
A handle server will return an error message if it encounters an
error when processing a request. Any error response from the server
must maintain the same (in the message header) as the one in
the original request. Each error condition is identified by a unique
as defined in section 2.2.2.2 of this document.
Sun, et al. Informational [Page 26]
RFC 3652 Handle System Protocol (v2.1) November 2003
The Message Body of an error message may be empty. Otherwise it
consists of the following data fields (unless otherwise specified):
::= []
[ ]
where
Optional field as defined in section 2.2.3.
A UTF8-String that explains the error.
An optional field. When not empty, it consists of a 4-byte
unsigned integer followed by a list of handle value indexes.
The first integer indicates the number of indexes in the
list. Each index in the list is a 4-byte unsigned integer
that refers to a handle value that contributed to the error.
An example would be a server that is asked to add three
handle values, with indexes 1, 2, and 3, and handle values
with indexes of 1 and 2 already in existence. In this case,
the server could return an error message with
set to RC_VALUE_ALREADY_EXIST and add index 1 and 2 to the
. Note that the server is not obligated to
return the complete list of handle value indexes that may
have caused the error.
3.4. Service Referral
A handle server may receive requests for handles that are managed by
some other handle server or service. When this happens, the server
has the option to either return a referral message that directs the
client to the proper handle service, or simply return an error
message with set to RC_SERVER_NOT_RESP. Service
referral also happens when ownership of handles moves from one handle
service to another. It may also be used by any local handle service
to delegate its service into multiple service layers.
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.
Sun, et al. Informational [Page 27]
RFC 3652 Handle System Protocol (v2.1) November 2003
The Message Body of any service referral is defined as follows:
::= [ ]
[ ]
where
Optional field as defined in section 2.2.3.
A UTF8-String that identifies the handle (e.g., a service
handle) that maintains the referral information (i.e., the
service information of the handle service in which this
refers). If the is set to "0.NA/0.NA",
it is referring the client to the GHR.
An optional field that must be empty if the
is provided. When not empty, it consists of a 4-byte
unsigned integer, followed by a list of HS_SITE values. The
integer specifies the number of HS_SITE values in the list.
Unlike regular query responses that may consist of handle values of
any data type, a service referral can only have zero or more HS_SITE
values in its . The may contain an empty
UTF8-String if the HS_SITE values in the are not
maintained by any handle.
Care must be taken by clients to avoid any loops caused by service
referrals. It is also the client's responsibility to authenticate
the service information obtained from the service referral. A client
should always use its own copy of the GHR service information if the
is set to "0.NA/0.NA".
3.5. Client Authentication
Clients are asked to authenticate themselves as handle administrators
when querying for any handle value with ADMIN_READ but no PUBLIC_READ
permission. Client authentication is also required for any handle
administration requests that require administrator privileges. This
includes adding, removing, or modifying handles or handle values.
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
Sun, et al. Informational [Page 28]
RFC 3652 Handle System Protocol (v2.1) November 2003
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 handle 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 handle 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_NOT_AUTHORIZED.
The following sections provide details of each message exchanged
during the authentication process.
3.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.
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 2.2.2.3) in the Message Header,
regardless of whether the original request had the RD bit set or not.
Sun, et al. Informational [Page 29]
RFC 3652 Handle System Protocol (v2.1) November 2003
The Message Body of the server's CHALLENGE is defined as follows:
::=
where
Message Digest of the request message, as defined in section
2.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 20 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.
3.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:
::=
where
A UTF8-String that identifies the type of authentication key
used by the client. For example, 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.
Sun, et al. Informational [Page 30]
RFC 3652 Handle System Protocol (v2.1) November 2003
A UTF8-String that identifies the handle that holds the
public or secret key of the handle administrator.
A 4-byte unsigned integer that specifies the index of the
handle value (of the ) that holds the public or
secret key of the administrator.
Contains either the Message Authentication Code (MAC) or the
digital signature over the challenge from the server. If
the is "HS_SECKEY", the
consists of an octet followed by the
MAC. The octet identifies the algorithm used to generate
the MAC. For example, if the first octet is set to 0x01,
the MAC is generated by
MD5_Hash( + + )
where the is the administrator's secret key
referenced by the and . The
is the Message Body portion of the
server's challenge. If the first octet in the
is set to 0x02, the MAC is generated
using
SHA-1_Hash( + + )
A more secure approach is to use HMAC [17] for the
. The HMAC can be generated using the
