|
|---------------------------------------------------------------|
| Type (UTF8-String) |
|---------------------------------------------------------------|
|
| SignedInfo: <Length> : 4-byte unsigned integer
| DigestAlgorithm: <UTF8-String>
| SignedData: <Length, Signature>
|
’---------------------------------------------------------------’
where
<CredentialLength>
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.
<Version>
An octet that identifies the version number of the Message
Credential. The version number specified in this document is
zero.
<Reserved>
An octet that must be set to zero.
<Options>
Two octets reserved for various cryptography options.
<Signer> ::= <HANDLE>
<INDEX>
A reference to a handle value in terms of the <HANDLE> and the
<INDEX> 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.
<Type>
A UTF8-String that indicates the type of content in the
<SignedInfo> field (described below). It may contain HS_DIGEST if
<SignedInfo> contains the message digest, or HS_MAC if
<SignedInfo> contains the Message Authentication Code (MAC). The
<Type> field will specify the signature algorithm identifier if
<SignedInfo> contains a digital signature. For example, with the
<Type> field set to HS_SIGNED_PSS, the <SignedInfo> field will
contain the digital signature generated using the RSA-PSS
algorithm [16]. If the <Type> field is set to HS_SIGNED, the
<SignedInfo> field will contain the digital signature generated
from a DSA public key pair.
<SignedInfo> ::= <Length>
<DigestAlgorithm>
<SignedData>
where
<Length>
A 4-byte unsigned integer that specifies the number of
octets in the <SignedInfo> field.
<DigestAlgorithm>
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.
<SignedData> ::= <LENGTH>
<SIGNATURE>
where
<LENGTH>
A 4-byte unsigned integer that specifies the number of
octets in the <SIGNATURE>.
<SIGNATURE>
Contains the digital signature or the MAC over the
Message Header and Message Body. The syntax and
semantics of the signature depend on the <Type> field
and the public key referenced in the <Signer> field.
For example, if the <Type> field is "HS_SIGNED" and
the public key referred to by the <Signer> 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 <Signer> 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 <Signer> field must set its <HANDLE> to a zero-length UTF8-String
and its <INDEX> to the <SessionId> specified in the Message Envelope.
The <Signature> field must contain the MAC in its <SIGNATURE> field.
The MAC is the result of the one-way hash over the concatenation of
the session key, the <Message Header>, the <MessageBody>, 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 <Signer> 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
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 <SequenceNumber>). Each
"Message Envelope i" must also set its <MessageLength> to reflect the
size of the packet. The recipient of these truncated packets can
reassemble the message by concatenating these packets based on their
<SequenceNumber>.
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 <OpCode> and
<ResponseCode> 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
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
<SerialNumber> 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 <SerialNumber> in the client’s request. The client
should update the root service information if the <ResponseCode> 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 <ResponseCode> set to RC_NA_DELEGATE, along with the
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 <Description> or other attributes
(under the <AttributeList>) 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 <HashOption> 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 <NumOfServer> given in the HS_SITE value. The result is
the sequence number of the <ServerRecord> listed in the HS_SITE
value. For example, if the result of the modulation is 2, the
third <ServerRecord> listed in the <HS_SITE> should be
selected. The <ServerRecord> 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.
3.2.1. Query Request
The Message Header of any query request must set its <OpCode> to
OC_RESOLUTION (defined in section 2.2.2.1) and <ResponseCode> to 0.
The Message Body for any query request is defined as follows:
<Message Body of Query Request> ::= <Handle>
<IndexList>
<TypeList>
where
<Handle>
A UTF8-String (as defined in section 2.1.4) that specifies
the handle to be resolved.
<IndexList>
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.
<TypeList>
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
<TypeList> 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.
If a query consists of a non-empty <IndexList> but an empty
<TypeList>, the server should only return those handle values whose
indexes are listed in the <IndexList>. Likewise, if a query consists
of a non-empty <TypeList> but an empty <IndexList>, the server should
only return those handle values whose data types are listed in the
<TypeList>.
When both <IndexList> and <TypeList> fields are non-empty, the server
should return all handle values whose indexes are listed in the
<IndexList> AND all handle values whose data types are listed in the
<TypeList>.
3.2.2. Successful Query Response
The Message Header of any query response must set its <OpCode> to
OC_RESOLUTION. A successful query response must set its
<ResponseCode> to RC_SUCCESS.
The message body of the successful query response is defined as
follows:
<Message Body of Successful Query Response> ::= [<RequestDigest>]
<Handle>
<ValueList>
where
<RequestDigest>
Optional field as defined in section 2.2.3.
<Handle>
A UTF8-String that specifies the handle queried by the
client.
<ValueList>
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.
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 <ResponseCode> 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 <ResponseCode> set to
RC_SERVER_NOT_RESP.
The server may return an error message with <ResponseCode> 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 <OpCode> (in the message header) as the one in
the original request. Each error condition is identified by a unique
<ResponseCode> as defined in section 2.2.2.2 of this document.
The Message Body of an error message may be empty. Otherwise it
consists of the following data fields (unless otherwise specified):
<Message Body of Error Response from Server> ::= [<RequestDigest>]
<ErrorMessage>
[ <IndexList> ]
where
<RequestDigest>
Optional field as defined in section 2.2.3.
<ErrorMessage>
A UTF8-String that explains the error.
<IndexList>
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 <REsponseCode>
set to RC_VALUE_ALREADY_EXIST and add index 1 and 2 to the
<IndexList>. 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 <ResponseCode> 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
<OpCode> as the one in the original request and set its
<ResponseCode> to RC_SERVICE_REFERRAL.
The Message Body of any service referral is defined as follows:
<Message Body of Service Referral> ::= [ <RequestDigest> ]
<ReferralHandle>
[ <ValueList> ]
where
<RequestDigest>
Optional field as defined in section 2.2.3.