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.
2.2.1.3. <SessionId>
The <SessionId> is a four-byte unsigned integer that identifies a
communication session between the client and server.
Session and its <SessionId> 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 <SessionId> 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 <SessionId> set to zero. The server must assign a unique
non-zero <SessionId> 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 <SessionId> for
messages exchanged under an established session. A message whose
<SessionId> 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
<SessionId>. 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. <RequestId>
Each request from a client is identified by a <RequestId>, a 4-byte
unsigned integer set by the client. Each <RequestId> must be unique
from all other outstanding requests from the same client. The
<RequestId> allows the client to keep track of its requests, and any
response from the server must include the correct <RequestId>.
2.2.1.5. <SequenceNumber>
Messages under the Handle protocol may be truncated during their
transmission (e.g., under UDP). The <SequenceNumber> 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 <SequenceNumber>. The
<SequenceNumber> 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 <SequenceNumber> to zero.
2.2.1.6. <MessageLen>
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 <RequestId>.
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. <OpCode>
The <OpCode> stands for operation code, which is a four-byte unsigned
integer that specifies the intended operation. The following table
lists the <OpCode>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.
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 <OpCode>s can be found in
section 3 of this document. In general, clients use the <OpCode> to
tell the server what kind of handle operation they want to
accomplish. Response from the server must maintain the same <OpCode>
as the original request and use the <ResponseCode> to indicate the
result.
2.2.2.2. <ResponseCode>
The <ResponseCode> is a 4-byte unsigned integer that is given by a
server to indicate the result of any service request. The list of
<ResponseCode>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.
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
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 <ResponseCode>s can be found in
section 3 of this document. In general, any request from a client
must have its <ResponseCode> set to 0. The response message from the
server must have a non-zero <ResponseCode> to indicate the result.
For example, a response message from a server with <ResponseCode> set
to RC_SUCCESS indicates that the server has successfully fulfilled
the client’s request.
2.2.2.3. <OpFlag>
The <OpFlag> 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 <OpFlag> 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.
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 <ResponseCode> 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.
All other bits in the <OpFlag> field are reserved and must be set to
zero.
In general, servers must honor the <OpFlag> specified in the request.
If a requested option cannot be met, the server should return an
error message with the proper <ResponseCode> as defined in the
previous section.
2.2.2.4. <SiteInfoSerialNumber>
The <SiteInfoSerialNumber> is a two-byte unsigned integer. The
<SiteInfoSerialNumber> in a request refers to the <SerialNumber> of
the HS_SITE value used by the client (to access the server). Servers
can check the <SiteInfoSerialNumber> 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 <SiteInforSerialNumber> 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 <ResponseCode> set to
RC_EXPIRED_SITE_INFO.
2.2.2.5. <RecursionCount>
The <RecursionCount> 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 <RecursionCount> set
to 0. If the server has to send a recursive request on behalf of the
client, it must increment the <RecursionCount> by 1. Any response
from the server must maintain the same <RecursionCount> 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 <RecursionCount> reaches a certain value.
2.2.2.6. <ExpirationTime>
The <ExpirationTime> 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.
2.2.2.7. <BodyLength>
The <BodyLength> is a 4-byte unsigned integer that specifies the
number of octets in the Message Body. The <BodyLength> 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 <BodyLength> in
the Message Header. The Message Body may be empty. The exact format
of the Message Body depends on the <OpCode> and the <ResponseCode> in
the Message Header. Details of the Message Body under each <OpCode>
and <ResponseCode> are described in section 3 of this document.
For any response message, if the Message Header has its RD bit (in
<OpFlag>) set to 1, the Message Body must begin with the message
digest of the original request. The message digest is defined as
follows:
<RequestDigest> ::= <DigestAlgorithmIdentifier>
<MessageDigest>
where
<DigestAlgorithmIdentifier>
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.
<MessageDigest>
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
<SequenceNumber> in the Message Envelope.
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: <Handle, Index>