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 <ValueList> should at least include one
HS_ADMIN value that defines the handle administrator.
Only naming authority administrators with the CREATE_HANDLE privilege
are allowed to create new handles under the naming authority. The
server that receives a CREATE_HANDLE request must authenticate the
client as the administrator of the corresponding naming authority
handle and make certain that the administrator is authorized to
create handles under the naming authority. This is different from
the ADD_VALUE request where the server authenticates the client as an
administrator of the handle. Upon successful authentication, the
server will proceed to create the new handle and add each value in
the <ValueList> to the new <Handle>. If successful, the server will
return an RC_SUCCESS message to the client.
Each CREATE_HANDLE request must be carried out as a transaction. If
any part of the CREATE_HANDLE process fails, the entire operation can
be rolled back. For example, if the server fails to add values in
the <ValueList> to the new handle, it must return an error message
without creating the new handle. Any CREATE_HANDLE request that asks
to create a handle that already exists will be treated as an error.
In this case, the server will return an error message with the
<ResponseCode> set to RC_HANDLE_ALREADY_EXIST.
CREATE_HANDLE requests can also be used to create naming authorities.
Naming authorities are created as naming authority handles at the
GHR. Before creating a new naming authority handle, the server must
authenticate the client as the administrator of the parent naming
authority. Only administrators with the CREATE_NA privilege are
allowed to create any sub-naming authority. Root level naming
authorities may be created by the administrator of the root handle
"0.NA/0.NA".
3.6.5. Delete Handle
Clients delete existing handles by sending DELETE_HANDLE requests to
the responsible handle server. The Message Header of the
DELETE_HANDLE request must set its <OpCode> to OC_DELETE_HANDLE.
The Message Body of any DELETE_HANDLE request is defined as follows:
<Message Body of DELETE_HANDLE Request> ::= <Handle>
where
<Handle>
A UTF8-String that specifies the handle.
The server that receives the DELETE_HANDLE request must first
authenticate the client as the administrator with the DELETE_HANDLE
privilege. Upon successful authentication, the server will proceed
to delete the handle along with any handle values assigned to the
handle. If successful, the server will return an RC_SUCCESS message
to the client.
Each DELETE_HANDLE request must be carried out as a transaction. If
any part of the DELETE_HANDLE process fails, the entire operation
must be rolled back. For example, if the server fails to remove any
handle values assigned to the handle (before deleting the handle), it
must return an error message without deleting the handle. This may
happen if the handle contains a value that has neither PUB_WRITE nor
ADMIN_WRITE permission. In this case, the server will return an
error message with the <ResponseCode> set to RC_PERMISSION_DENIED. A
DELETE_HANDLE request that asks to delete a non-existing handle will
also be treated as an error. The server will return an error message
with the <ResponseCode> set to RC_HANDLE_NOT_EXIST.
DELETE_HANDLE requests can also be used to delete naming authorities.
This is achieved by deleting the corresponding naming authority
handle on the GHR. Before deleting a naming authority handle, the
server must authenticate the client as the administrator of the
naming authority handle. Only administrators with the DELETE_NA
privilege are allowed to delete the naming authority. Root level
naming authorities may be deleted by the administrator of the root
handle "0.NA/0.NA".
3.7. Naming Authority (NA) Administration
The Handle System manages naming authorities via naming authority
handles. Naming authority handles are managed by the GHR. Clients
can change the service information of any naming authority by
changing the HS_SITE values assigned to the corresponding naming
authority handle. Creating or deleting naming authorities is done by
creating or deleting the corresponding naming authority handles.
Root level naming authorities may be created or deleted by the
administrator of the root handle "0.NA/0.NA". Non-root-level naming
authorities may be created by the administrator of its parent naming
authority.
For example, the administrator of the naming authority handle
"0.NA/10" may create the naming authority "10.1000" by sending a
CREATE_HANDLE request to the GHR to create the naming authority
handle "0.NA/10.1000". Before fulfilling the request, the server at
the GHR must authenticate the client as the administrator of the
parent naming authority, that is, the administrator of the naming
authority handle "0.NA/10". The server must also make sure that the
administrator has the NA_CREATE privilege.
The Handle protocol also allows clients to list handles or sub-naming
authorities under a naming authority. Details of these operations
are described in the following sections.
3.7.1. List Handle(s) under a Naming Authority
Clients send LIST_HANDLE requests to handle servers to get a list of
handles under a naming authority. The Message Header of the
LIST_HANDLE request must set its <OpCode> to OC_LIST_HANDLE.
The Message Body of any LIST_HANDLE request is defined as follows:
<Message Body of LIST_HANDLE Request> ::= <NA_Handle>
where
<NA_Handle>
A UTF8-String that specifies the naming authority handle.
To obtain a complete list of the handles, the request must be sent to
every handle server listed in one of the service sites of the
responsible handle service. Each server within the service site will
return its own list of handles under the naming authority. The
Message Body of a successful LIST_HANDLE response (from each handle
server) is defined as follows:
<Message Body of LIST_HANDLE Response> ::= <Num_Handles>
<HandleList>
where
<Num_Handles>
Number of handles (managed by the handle server) under the
naming authority.
<HandleList>
A list of UTF8-Strings, each of which identify a handle
under the naming authority.
The LIST_HANDLE request may potentially slow down the overall system
performance. A handle service (or its service site) has the option
of whether or not to support such request. The server will return an
RC_OPERATION_DENIED message if LIST_HANDLE is not supported. The
server that receives a LIST_HANDLE request should authenticate the
client as a naming authority administrator with the LIST_HANDLE
privilege before fulfilling the request.
3.7.2. List Sub-Naming Authorities under a Naming Authority
Clients send LIST_NA requests to handle servers to get a list of
sub-naming authorities under a naming authority. The Message Header
of the LIST_NA request must set its <OpCode> to OC_LIST_NA.
The Message Body of any LIST_NA request is defined as follows:
<Message Body of LIST_HANDLE Request> ::= <NA_Handle>
where
<NA_Handle>
A UTF8-String that specifies the naming authority handle.
To obtain a complete list of the sub-naming authorities, the request
must be sent to every handle server listed in any one of the service
sites of the GHR. Each server within the service site will return
its own list of sub-naming authority handles under the given naming
authority. The Message Body of a successful LIST_NA response (from
each handle server) is defined as follows:
<Message Body of LIST_HANDLE Response> ::= <Num_Handles>
<HandleList>
where
<Num_Handles>
Number of handles (managed by the handle server) under the
naming authority.
<HandleList>
A list of UTF8-Strings, each of which identifies a sub-
naming authority user-specified naming authority.
LIST_NA requests must be sent to servers under the GHR that manages
all the naming authority handles. The LIST_NA request may
potentially slow down the overall system performance, especially the
GHS. A server (or service sites) under the GHR has the option of
whether or not to support such requests. The server will return an
RC_OPERATION_DENIED message if LIST_NA is not supported. The server
that receives a LIST_HANDLE request should authenticate the client as
a naming authority administrator with the LIST_NA privilege before
fulfilling the request.
3.8. Session and Session Management
Sessions are used to allow sharing of authentication information or
network resources among multiple protocol operations. For example, a
naming authority administrator may authenticate itself once through
the session setup, and then register multiple handles under the
session.
A client may ask the server to establish a session key and use it for
subsequent requests. A session key is a secret key that is shared by
the client and server. It can be used to authenticate or encrypt any
message exchanged under the session. A session is encrypted if every
message exchanged within the session is encrypted using the session
key.
Sessions may be established as the result of an explicit
OC_SESSION_SETUP request from a client. A server may also
automatically setup a session when multiple message exchanges are
expected to fulfill a request. For example, the server will
automatically establish a session if it receives a CREATE_HANDLE
request that requires client authentication.
Every session is identified by a non-zero Session ID that appears in
the Message Header. Servers are responsible for generating a unique
Session ID for each outstanding session. Each session may have a set
of state information associated with it. The state information may
include the session key and the information obtained from client
authentication, as well as any communication options. Servers and
clients are responsible for keeping the state information in sync
until the session is terminated.
A session may be terminated with an OC_SESSION_TERMINATE request from
the client. Servers may also terminate a session that has been idle
for a significant amount of time.
3.8.1. Session Setup Request
Clients establish a session with a handle server with a SESSION_SETUP
request. A SESSION_SETUP request can also be used to update any
state information associated to an existing session. The Message
Header of the SESSION_SETUP request must have its <OpCode> set to
OC_SESSION_SETUP and <ResponseCode> to 0.
The Message Body of any SESSION_SETUP request is defined as follows:
<SESSION_SETUP Request Message Body> ::= <SessionAttributes>
where
<SessionAttributes>
A 4-byte unsigned integer followed by a list of session
attributes. The integer indicates the number of session
attributes in the list. Possible session attributes include
the <HS_SESSION_IDENTITY>, the <HS_SESSION_TIMEOUT>, and the
<HS_SESSION_KEY_EXCHANGE>. Each of these attributes is
defined as follows:
<HS_SESSION_IDENTITY> ::= <Key>
<Handle>
<ValueIndex>
where
<Key>
A UTF-8 string constant "HS_SESSION_IDENTITY".
<Handle>
<ValueIndex>
A UTF-8 string followed by a 4-byte unsigned
integer that specifies the handle and the handle
value used for client authentication. It must
refer to a handle value that contains the public
key of the client. The public key is used by
the server to authenticate the client.
<HS_SESSION_KEY_EXCHANGE> ::= <Key>
<KeyExchangeData>
where
<Key>
A UTF-8 string constant "HS_SESSION_KEY_EXCHANGE".
<KeyExchangeData>
One of the these tuples: <ClientCipher
<ClientCipher KeyExchange>,
<HdlCipher KeyExchange>, or
<ServerCipher KeyExchange>.
Each of these tuples is defined as follows:
<ClientCipher KeyExchange> ::= <Key>
<PubKey>
where
<Key>
A UTF-8 string constant "CLIENT_CIPHER".
<PubKey>
A public key provided by the client and used
by the server to encrypt the session key.
<HdlCipher KeyExchange> ::= <Key>
<ExchangeKeyHdl>
<ExchangeKeyIndex>
where
<Key>
A UTF-8 string constant "HDL_CIPHER".
<ExchangeKeyHdl>
<ExchangeKeyIndex>
A UTF-8 string followed by a 4-byte unsigned
integer. The <ExchangeKeyHdl> and
<ExchangeKeyIndex> refers to a handle value
used for session key exchange. The handle
value must contain the public key of the
client. The public key will be used by the
server to encrypt the session key before
sending it to the client.
<ServerCipher KeyExchange> ::= <Key>
where
<Key>
A UTF-8 string constant "SERVER_CIPHER". This
tells the server that the client will be
responsible for generating the session key. The
server will have to provide its public key in
the response message and set the <ResponseCode>
to RC_SESSION_EXCHANGEKEY. The client can use
the server’s public key to encrypt the session
key and send it to the server via a subsequent
SESSION_EXCHANGEKEY request.
<DiffieHellman KeyExchange> ::= <Key>
<DHParams>
where
<Key>
A UTF-8 string constant "DIFFIE_HELLMAN"
<DHParams>
The values used as input in the Diffie-
Hellman algorithm. It consists of three big
integers of variable length. Each big
integer is encoded in terms of a 4-byte
unsigned integer followed by an octet string.
The octet string contains the big integer
itself. The 4-byte unsigned integer
specifies the number of octets of the octet
string.
<HS_SESSION_TIMEOUT> ::= <Key>
<TimeOut>
where
<Key>
A UTF-8 string constant "HS_SESSION_TIMEOUT".
<TimeOut>
A 4-byte unsigned integer that specifies the desired
duration of the session in seconds.
Note that it should be treated as an error if the same session
attribute is listed multiple times in the <SessionAttribute> field.
When this happens, the server should return an error message with
<ResponseCode> set to RC_PROTOCOL_ERROR.
A SESSION_SETUP_REQUEST can be used to change session attributes of
any established session. This happens if the <SessionId> is non-zero
and matches one of the established sessions. Care must be taken by
the server to prevent any unauthorized request from changing the
session attributes. For example, an encrypted session may only be
changed into an unencrypted session by a SESSION_SETUP_REQUEST with
an appropriate MAC in its Message Credential.
3.8.2. Session Setup Response
The Message Header of the SESSION_SETUP response must set its
<OpCode> to OC_SESSION_SETUP. The <ResponseCode> of the
SESSION_SETUP response varies according to the SESSION_SETUP request.
It must be set to RC_SUCCESS if the SESSION_SETUP request is
successful and the server does not expect a session key to be
returned by the client.
The Message Body of the SESSION_SETUP response is empty unless the
request is asking for <HS_SESSION_KEY_EXCHANGE>. In this case, the
Message Body of the SESSION_SETUP response may contain the encrypted
session key from the server, or the server’s public key, to be used
for session key exchange. The exact format depends on the content of
the <HS_SESSION_KEY_EXCHANGE> in the SESSION_SETUP request. If
<ClientCipher KeyExchange> or <HdlCipher KeyExchange> is given in the
SESSION_SETUP request, the Message Body of the SESSION_SETUP response
will contain the encrypted session key from the server and is defined
as follows:
<Message Body of SESSION_SETUP Response>
::= <RequestDigest>
<EncryptedSessionKey>
[ <EncryptionAlgorithm> ]
where
<RequestDigest>
Message digest of the SESSION_SETUP request is as specified in
section 2.2.3.
<EncryptedSessionKey>
Session key is encrypted using the public key provided in the
SESSION_SETUP request. The session key is a randomly
generated octet string from the server. The server will only
return the <EncryptedSessionKey> if the <KeyExchangeData> in
the SESSION_SETUP request provides the public key from the
client.
<EncryptionAlgorithm>
(optional) UTF-8 string that identifies the encryption
algorithm used by the session key.
If <ServerCipher KeyExchange> is given in the SESSION_SETUP request,
the server must provide its public key in the SESSION_SETUP response.
The public key can be used by the client in a subsequent
SESSION_EXCHANGEKEY request (defined below) for session key exchange.
In this case, the Message Header of the SESSION_SETUP response must
set its <ResponseCode> to RC_SESSION_EXCHANGEKEY. The Message Body
of the SESSION_SETUP response must include the server’s public key
and is defined as follows:
<Message Body of SESSION_SETUP response>
::= <RequestDigest>
<Public Key for Session Key Exchange>
where