Handle System Protocol

Description Glossary RFCs Publications Obsolete RFCs


Protocol suite: TCP/IP.
Protocol type: Application layer protocol.
Ports:2641 (TCP, UDP).
MIME subtype:
Working groups:
Links: www.handle.net

The Handle System is a general purpose global name service that allows secured name resolution and administration over networks such as the Internet. This system manages handles, which are unique names for digital objects and other Internet resources.

RFC 3650:

The Handle System was originally conceived and developed at CNRI as part of an overall digital object architecture. The first public implementation was created at CNRI in the fall of 1994 in an effort led by David Ely. The overall digital object architecture, including the Handle System, was later described in a paper by Robert Kahn and Robert Wilensky in 1995. Development continued at CNRI as part of the Computer Science Technical Reports (CSTR) project, funded by the Defense Advanced Projects Agency (DARPA) under Grant Number MDA-972-92-J-1029 and MDA-972-99-1-0018. One aspect of this early digital library project, which was also a major factor in the evolution of the Networked Computer Science Technical Reference Library (NCSTRL) and related activities, was to develop a framework for the underlying infrastructure of digital libraries.

Early adopters of the Handle System included the Library of Congress, the Defense Technical Information Center (DTIC), and the International DOI Foundation (IDF). Feedback from these organizations as well as NCSTRL, other digital library projects, and related IETF efforts as mentioned above, have all contributed to the evolution of the Handle System.

Messages carried by UDP are restricted to 512 bytes not including the IP or UDP headers. Longer messages must be fragmented into UDP packets where each packet carries a proper sequence number.

MAC header IP header TCP | UDP header Message envelope Message header Data :::

Message envelope:

0001020304050607 0809101112131415 1617181920212223 2425262728293031
Major version Minor version Message flag
Session Id
Request Id
Sequence number
Message length

Major version. 8 bits.
Major version number of this protocol.

Minor version. 8 bits.
Minor version number of this protocol.

Message flag. 16 bits.

0001020304050607 0809101112131415

CP, compressed. 1 bit.
If set, the message is compressed.

EC, encrypted. 1 bit.
If set, the message is encrypted.

TC, truncated. 1 bit.
If set, this is a trunctated message.

Session Id. 32 bits, unsigned.
Identifies a communication session between the client and server. This field is assigned by the server, either upon an explicit request from the client or when multiple message exchanges are expected to fulfill the client's request. The client may explicitly ask the server to set up a session as a virtually private communication channel like SSL. Requests from clients without an established session must have the field set to zero. The server must assign a unique non zero value 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 Session Id for messages exchanged under an established session.

Request Id. 32 bits, unsigned.
Each request from the client is identified by this field set by the client. Each Request Id must be unique from all other outstanding requests from the same client. This field allows the client to keep track of its requests and any response from the server must have a matching value

Sequence number. 32 bits.
This field is 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 this field. The Sequence number is initialized to 0 for each message. Each truncated message must set its TC flag in the Message envelope. Messages that are not truncated must set this field to zero.

Message length. 32 bits, unsigned. 0 .. 0xFFFF.
Specifies the total number of bytes of any message, excluding those in the Message Envelope. A message can be transmitted as multiple messages with a common Request Id.

Message header:

0001020304050607 0809101112131415 1617181920212223 2425262728293031
Response code
Site info serial number Recursion count  
Expiration time
Body length
Message body :::
Message credential :::

Opcode. 32 bits, unsigned.
Operation code.

1OC_RESOLUTION.Handle query.
100OC_CREATE_HANDLE.Create new handle.
101OC_DELETE_HANDLE.Delete existing handle.
102OC_ADD_VALUE.Add handle value(s).
103OC_REMOVE_VALUE.Remove handle value(s).
104OC_MODIFY_VALUE.Modify handle value(s).
105OC_LIST_HANDLE.List handles.
106OC_LIST_NA.List sub-naming authorities.
200OC_CHALLENGE_RESPONSE.Response to challenge.
201OC_VERIFY_RESPONSE.Verify challenge response.
 Reserved for handle server administration.
400OC_SESSION_SETUP.Session setup request.
401OC_SESSION_TERMINATE.Session termination request.
402OC_SESSION_EXCHANGEKEY.Session key exchange.

Response code. 32 bits.
Used to indicate the result of a service request.

2RC_ERROR.General error.
3RC_SERVER_BUSY.Server too busy to respond.
4RC_PROTOCOL_ERROR.Corrupted or unrecognizable message.
5RC_OPERATION_DENIED.Unsupported operation.
6RC_RECUR_LIMIT_EXCEEDED.Too many recursions for the request.
100RC_HANDLE_NOT_FOUND.Handle not found.
101RC_HANDLE_ALREADY_EXIST.Handle already exists.
102RC_INVALID_HANDLE.Encoding or syntax error.
200RC_VALUE_NOT_FOUND.Value not found.
201RC_VALUE_ALREADY_EXIST.Value already exists.
202RC_VALUE_INVALID.Invalid handle value.
301RC_SERVER_NOT_RESP.Server not responsible.
302RC_SERVICE_REFERRAL.Server referral.
303RC_NA_DELEGATE.Naming authority delegation takes place.
400RC_NOT_AUTHORIZED.Not authorized/permitted.
401RC_ACCESS_DENIED.No access to data.
402RC_AUTHEN_NEEDED.Authentication required.
403RC_AUTHEN_FAILED.Failed to authenticate.
404RC_INVALID_CREDENTIAL.Invalid credential.
405RC_AUTHEN_TIMEOUT.Authentication timed out.
406RC_UNABLE_TO_AUTHEN.Unable to authenticate.
500RC_SESSION_TIMEOUT.Session expired.
501RC_SESSION_FAILED.Unable to establish session.
502RC_NO_SESSION_KEY.No session yet available.
503RC_SESSION_NO_SUPPORT.Session not supported.
504RC_SESSION_KEY_INVALID.Invalid session key.
900RC_TRYING.Request under processing.
901RC_FORWARDED.Request forwarded to another server.
902RC_QUEUED.Request queued for later processing.

Opflag. 32 bits.
In general, servers must honor this field in the request. If a requested option cannot be met, the server should return an error message with the proper response code.

0001020304050607 0809101112131415 1617181920212223 2425262728293031

AT, Authoritative. 1 bit.
A request message with this bit set indicates that the request should be directed to the primary service site instead of any mirroring sites. A response message with this bit set indicates that the message is returned from a primary server (within the primary service site).

CT, Certified. 1 bit.
A request with this bit set asks the server to sign its response with its digital signature. A response with this bit set indicates that the message is signed. The server must sign its response if the request has this bit set. 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. 1 bit.
A request with this bit set requires the server to encrypt its response using the pre-established session key.

REC, Recursive. 1 bit.
A request with this bit set 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 the Response code set to RC_SERVER_NOT_RESP.

CA, Cache Authentication. 1 bit.
A request with this bit set 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 this bit set indicates that the response has been authenticated by the caching server.

CN, Continuous. 1 bit.
A message with this bit set 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. 1 bit.
A message with this 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. 1 bit.
Used by query operations only. A query request with this bit set indicates that the client is only asking for handle values that have the PUB_READ permission. A request with this bit cleared 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. 1 bit.
A request with this bit set asks the server to include in its response the message digest of the request. A response message with this bit set 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.

Site info serial number. 16 bits.
When used in a request this field refers to the Serial Number of the HS_SITE value used by the client (to access the server). Servers can check the this field 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 this 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 the Response code set to RC_EXPIRED_SITE_INFO.

Recursion count. 8 bits.
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 this field cleared. If the server has to send a recursive request on behalf of the client, it must increment this field by 1. Any response from the server must maintain the same value 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 count reaches a certain value.

Expiration time. 32 bits, unsigned.
Specifies the time when the message should be considered expired, relative to January 1st, 1970 GMT, in seconds. It is cleared if no expiration is expected.

Body length. 32 bits.
Specifies the number of bytes in the Message body. It does not count the bytes in the Message header or those in the Message credential.

Message body. Variable length.

Message credential. Variable length.

0001020304050607 0809101112131415 1617181920212223 2425262728293031
Credential length
Version 0 Crypto options
Signer :::
Type ::
Signed info ::

Credential length. 32 bits.
Specifies the number of bytes in the Message credential. It must be cleared if the message has no Message credential.

Version. 8 bits.
Identifies the version number of the Message credential.

Crypto options. 16 bits.

Signer. Variable length.

Type. Variable length.

Signed info. Variable length.



[RFC 3650] Handle System Overview.

[RFC 3651] Handle System Namespace and Service Definition.

[RFC 3652] Handle System Protocol (ver 2.1) Specification.


Obsolete RFCs:

Description Glossary RFCs Publications Obsolete RFCs