<ReferralHandle>
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 <ReferralHandle> is set to "0.NA/0.NA",
it is referring the client to the GHR.
<ValueList>
An optional field that must be empty if the <ReferralHandle>
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 <ValueList>. The <ReferralHandle> may contain an empty
UTF8-String if the HS_SITE values in the <ValueList> 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
<ReferralHandle> 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
the verification request and response message if secret key
authentication takes place. Messages exchanged during the
authentication are correlated via a unique <SessionId> 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
<ResponseCode> 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
<ResponseCode> 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 <OpCode> as
the original request and set the <ResponseCode> to RC_AUTH_NEEDED.
The server must assign a non-zero unique <SessionId> in the Message
Envelope to keep track of the authentication. It must also set the
RD flag of the <OpFlag> (see section 2.2.2.3) in the Message Header,
regardless of whether the original request had the RD bit set or not.
The Message Body of the server’s CHALLENGE is defined as follows:
<Message Body of Server’s Challenge> ::= <RequestDigest>
<Nonce>
where
<RequestDigest>
Message Digest of the request message, as defined in section
2.2.3.
<Nonce>
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
<Challenge>. If the client requested the server to sign the
<Challenge> 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 <OpCode> to
OC_CHALLENGE_RESPONSE and its <ResponseCode> to 0. It must also keep
the same <SessionId> (in the Message Envelope) as specified in the
challenge from the server.
The Message Body of the CHALLENGE_RESPONSE request is defines as
follows:
<Message Body of CHALLENGE_RESPONSE> ::= <AuthenticationType>
<KeyHandle>
<KeyIndex>
<ChallengeResponse>
where
<AuthenticationType>
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.
<KeyHandle>
A UTF8-String that identifies the handle that holds the
public or secret key of the handle administrator.
<KeyIndex>
A 4-byte unsigned integer that specifies the index of the
handle value (of the <KeyHandle>) that holds the public or
secret key of the administrator.
<ChallengeResponse>
Contains either the Message Authentication Code (MAC) or the
digital signature over the challenge from the server. If
the <AuthenticationType> is "HS_SECKEY", the
<ChallengeResponse> 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(<SecretKey> + <ServerChallenge> + <SecretKey>)
where the <SecretKey> is the administrator’s secret key
referenced by the <KeyHandle> and <KeyIndex>. The
<ServerChallenge> is the Message Body portion of the
server’s challenge. If the first octet in the
<ChallengeResponse> is set to 0x02, the MAC is generated
using
SHA-1_Hash(<SecretKey> + <ServerChallenge> + <SecretKey>)
A more secure approach is to use HMAC [17] for the
<ChallengeResponse>. The HMAC can be generated using the
<SecretKey> and <ServerChallenge>. A <ChallengeResponse>
with its first octet set to 0x11 indicates that the HMAC
is generated using the MD5 algorithm. Likewise, a
<ChallengeResponse> with its first octet set to 0x12
indicates that the HMAC is generated using the SHA-1
algorithm.
If the <AuthenticationType> is "HS_PUBKEY", the
<ChallengeResponse> contains the digital signature over the
Message Body portion of the server’s challenge. The
signature is generated in two steps: First, a one-way hash
value is computed over the blob that is to be signed.
Second, the hash value is signed using the private key.
The signature consists of a UTF8-String that specifies the
digest algorithm used for the signature, followed by the
signature over the server’s challenge. The <KeyHandle> and
<KeyIndex> refers to the administrator’s public key that can
be used to verify the signature.
Handle administrators are defined in terms of HS_ADMIN values
assigned to the handle. Each HS_ADMIN value defines the set of
privileges granted to the administrator. It also provides the
reference to the authentication key that can be used to authenticate
the administrator. The reference can be made directly if the
<AdminRef> field of the HS_ADMIN value refers to the handle value
that holds the authentication key. Indirect reference to the
authentication key can also be made via administrator groups. In
this case, the <AdminRef> field may refer to a handle value of type
HS_VLIST. An HS_VLIST value defines an administrator group via a
list of handle value references, each of which refers to the
authentication key of a handle administrator.
For handles with multiple HS_ADMIN values, the server will have to
check each of those with sufficient privileges to see if its
<AdminRef> field matches the <KeyHandle> and <KeyIndex>. If no match
is found, but there are administrator groups defined, the server must
check if the <KeyHandle> and <KeyIndex> belong to any of the
administrator groups that have sufficient privileges. An
administrator group may contain another administrator group as a
member. Servers must be careful to avoid infinite loops when
navigating these groups.
If the <KeyHandle> and <KeyIndex> are not referenced by any of the
HS_ADMIN values, or the administrator group that has sufficient
privileges, the server will return an error message with
<ResponseCode> set to RC_NOT_AUTHORIZED. Otherwise, the server will
continue to authenticate the client as follows:
If the <AuthenticationType> is "HS_PUBKEY", the server will retrieve
the administrator’s public key based on the <KeyHandle> and
<KeyIndex>. The public key can be used to verify the
<ChallengeResponse> against the server’s <Challenge>. If the
<ChallengeResponse> matches the <Challenge>, the server will continue
to process the original request and return the result. Otherwise,
the server will return an error message with <ResponseCode> set to
RC_AUTHENTICATION_FAILED.
If the <AuthenticationType> is "HS_SECKEY", the server will have to
send a verification request to the verification server; that is, the
handle server that manages the handle referenced by the <KeyHandle>.
The verification request and its response are defined in the
following sections. The verification server will verify the
<ChallengeResponse> against the <Challenge> on behalf of the handle
server.
3.5.3. Challenge-Response Verification-Request
The message header of the VERIFICATION_REQUEST must set its <OpCode>
to OC_VERIFY_CHALLENGE and the <ResponseCode> to 0.
The message body of the Verification-Request is defined as follows:
<Message Body of VERIFICATION_REQUEST> ::= <KeyHandle>
<KeyIndex>
<Challenge>
<ChallengeResponse>
where
<KeyHandle>
A UTF8-String that refers to the handle that holds the
secret key of the administrator.
<KeyIndex>
A 4-byte unsigned integer that is the index of the handle
value that holds the secret key of the administrator.
<Challenge>
The message body of the server’s challenge, as described in
section 3.5.1.
<ChallengeResponse>
The <ChallengeResponse> from the client in response to
the server’s <Challenge>, as defined in section 3.5.2.
Any Challenge-Response Verification-Request must set its CT bit in
the message header. This is to ensure that the verification server
will sign the Verification-Response as specified in the next section.
3.5.4. Challenge-Response Verification-Response
The Verification-Response tells the requesting handle server whether
the <ChallengeResponse> matches the <Challenge> in the Verification-
Request.
The Message Header of the Verification-Response must set its
<ResponseCode> to RC_SUCCESS whether or not the <ChallengeResponse>
matches the <Challenge>. The RD flag in the <OpFlag> field should
also be set (to 1) since the <RequestDigist> will be mandatory in the
Message Body.
The Message Body of the Verification-Response is defined as follows:
<Challenge-Response Verification-Response>
::= <RequestDigest>
<VerificationResult>
where
<RequestDigest>
Contains the message digest of the Verification-Request.
<VerificationResult>
An octet that is set to 1 if the <ChallengeResponse>
matches the <Challenge>. Otherwise it must be set to
0.
The verification server may return an error with <ResponseCode> set
to RC_AUTHEN_FAILED if it cannot perform the verification (e.g., the
<KeyHandle> does not exist, or the <KeyHandle> and <KeyIndex> refer
to an invalid handle value). When this happens, the server that
performs the client authentication should relay the same error
message back to the client.
3.6. Handle Administration
The Handle System protocol supports a set of handle administration
functions that include adding, deleting, and modifying handles or
handle values. Before fulfilling any administration request, the
server must authenticate the client as the handle administrator that
is authorized for the administrative operation. Handle
administration can only be carried out by the primary handle server.
3.6.1. Add Handle Value(s)
Clients add values to existing handles by sending ADD_VALUE requests
to the responsible handle server. The Message Header of the
ADD_VALUE request must set its <OpCode> to OC_ADD_VALUE.
The Message Body of the ADD_VALUE request is encoded as follows:
<Message Body of ADD_VALUE Request> ::= <Handle>
<ValueList>
where
<Handle>
A UTF8-String that specifies the handle.
<ValueList>
A 4-byte unsigned integer followed by a list of handle
values. The integer indicates the number of handle values
in the list.
The server that receives the ADD_VALUE request must first
authenticate the client as the administrator with the ADD_VALUE
privilege. Upon successful authentication, the server will proceed
to add each value in the <ValueList> to the <Handle>. If successful,
the server will return an RC_SUCCESS message to the client.
Each ADD_VALUE request must be carried out as a transaction. If
adding any value in the <ValueList> raises an error, the entire
operation must be rolled back. For any failed ADD_VALUE request,
none of the values in the <ValueList> should be added to the
<Handle>. The server must also send a response to the client that
explains the error. For example, if a value in the <ValueList> has
the same index as one of the existing handle values, the server will
return an error message that has the <ResponseCode> set to
RC_VALUE_ALREADY_EXISTS.
ADD_VALUE requests can also be used to add handle administrators.
This happens if the <ValueList> in the ADD_VALUE request contains any
HS_ADMIN values. The server must authenticate the client as an
administrator with the ADD_ADMIN privilege before fulfilling such
requests.
An ADD_VALUE request will result in an error if the requested handle
does not exist. When this happens, the server will return an error
message with <ResponseCode> set to RC_HANDLE_NOT_EXIST.
3.6.2. Remove Handle Value(s)
Clients remove existing handle values by sending REMOVE_VALUE
requests to the responsible handle server. The Message Header of the
REMOVE_VALUE request must set its <OpCode> to OC_REMOVE_VALUE.
The Message Body of any REMOVE_VALUE request is encoded as follows:
<Message Body of REMOVE_VALUE Request> ::= <Handle>
<IndexList>
where
<Handle>
A UTF8-String that specifies the handle whose value(s) needs
to be removed.
<IndexList>
A 4-byte unsigned integer followed by a list of handle value
indexes. Each index refers to a handle value to be removed
from the <Handle>. The integer specifies the number of
indexes in the list. Each index is also encoded as a 4-byte
unsigned integer.
The server that receives the REMOVE_VALUE request must first
authenticate the client as the administrator with the REMOVE VALUE
privilege. Upon successful authentication, the server will proceed
to remove the handle values specified in the <IndexList> from the
<Handle>. If successful, the server will return an RC_SUCCESS
message to the client.
Each REMOVE_VALUE request must be carried out as a transaction. If
removing any value specified in the <IndexList> raises an error, the
entire operation must be rolled back. For any failed REMOVE_VALUE
request, none of values referenced in the <IndexList> should be
removed from the <Handle>. The server must also send a response to
the client that explains the error. For example, attempts to remove
any handle value with neither PUB_WRITE nor ADMIN_WRITE permission
will result in an RC_ACCESS_DENIED error. Note that a REMOVE_VALUE
request asking to remove a non-existing handle value will not be
treated as an error.
REMOVE_VALUE requests can also be used to remove handle
administrators. This happens if any of the indexes in the
<IndexList> refer to an HS_ADMIN value. Servers must authenticate
the client as an administrator with the REMOVE_ADMIN privilege before
fulfilling such requests.
3.6.3. Modify Handle Value(s)
Clients can make modifications to an existing handle value by sending
MODIFY_VALUE requests to the responsible handle server. The Message
Header of the MODIFY_VALUE request must set its <OpCode> to
OC_MODIFY_VALUE.
The Message Body of any MODIFY_VALUE request is defined as follows:
<Message Body of MODIFY_VALUE Response> ::= <Handle>
<ValueList>
where
<Handle>
A UTF8-String that specifies the handle whose value(s) needs
to be modified.
<ValueList>
A 4-byte unsigned integer followed by a list of handle
values. The integer specifies the number of handle values
in the list. Each value in the <ValueList> specifies a
handle value that will replace the existing handle value
with the same index.
The server that receives the MODIFY_VALUE request must first
authenticate the client as an administrator with the MODIFY_VALUE
privilege. Upon successful authentication, the server will proceed
to replace those handle values listed in the <ValueList>, provided
each handle value has PUB_WRITE or ADMIN_WRITE permission. If
successful, the server must notify the client with an RC_SUCCESS
message.
Each MODIFY_VALUE request must be carried out as a transaction. If
replacing any value listed in the <ValueList> raises an error, the
entire operation must be rolled back. For any failed MODIFY_VALUE
request, none of values in the <ValueList> should be replaced. The
server must also return a response to the client that explains the
error. For example, if a MODIFY_VALUE requests to remove a handle
value that has neither PUB_WRITE nor ADMIN_WRITE permission, the
server must return an error message with the <ResponseCode> set to
RC_ACCESS_DENIED. Any MODIFY_VALUE request to replace non- existing
handle values is also treated as an error. In this case, the server
will return an error message with <ResponseCode> set to
RC_VALUE_NOT_FOUND.
MODIFY_VALUE requests can also be used to update handle
administrators. This happens if both the values in the <ValueList>
and the value to be replaced are HS_ADMIN values. Servers must
authenticate the client as an administrator with the MODIFY_ADMIN
privilege before fulfilling such a request. It is an error to
replace a non-HS_ADMIN value with an HS_ADMIN value. In this case,
the server will return an error message with <ResponseCode> set to
RC_VALUE_INVALID.
3.6.4. Create Handle
Clients can create new handles by sending CREATE_HANDLE requests to
the responsible handle server. The Message Header of any
CREATE_HANDLE request must set its <OpCode> to OC_CREATE_HANDLE.
The Message Body of any CREATE_HANDLE request is defined as follows:
<Message Body of CREATE_HANDLE Response> ::= <Handle>
<ValueList>