Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3652

Handle System Protocol (ver 2.1) Specification

Pages: 53
Informational
Part 2 of 2 – Pages 24 to 53
First   Prev   None

Top   ToC   RFC3652 - Page 24   prevText

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.
Top   ToC   RFC3652 - Page 25
   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.
Top   ToC   RFC3652 - Page 26

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.
Top   ToC   RFC3652 - Page 27
   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.
Top   ToC   RFC3652 - Page 28
   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.

            <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
Top   ToC   RFC3652 - Page 29
   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.
Top   ToC   RFC3652 - Page 30
   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.
Top   ToC   RFC3652 - Page 31
            <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
Top   ToC   RFC3652 - Page 32
            <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.
Top   ToC   RFC3652 - Page 33

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.
Top   ToC   RFC3652 - Page 34
   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.
Top   ToC   RFC3652 - Page 35
            <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.
Top   ToC   RFC3652 - Page 36
            <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.
Top   ToC   RFC3652 - Page 37
            <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.
Top   ToC   RFC3652 - Page 38
   The Message Body of any CREATE_HANDLE request is defined as follows:

      <Message Body of CREATE_HANDLE Response> ::= <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 <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".
Top   ToC   RFC3652 - Page 39

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".
Top   ToC   RFC3652 - Page 40

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:
Top   ToC   RFC3652 - Page 41
      <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:
Top   ToC   RFC3652 - Page 42
      <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
Top   ToC   RFC3652 - Page 43
   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.
Top   ToC   RFC3652 - Page 44
               <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
Top   ToC   RFC3652 - Page 45
                        <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
Top   ToC   RFC3652 - Page 46
   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.
Top   ToC   RFC3652 - Page 47
   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

          <RequestDigest>
          Message digest of the SESSION_SETUP request as specified in
          section 2.2.3.

          <Public Key for Session Key Exchange>
          Public key from the server to be used for session key
          exchange.  It is encoded in the same format as the <PublicKey>
          record in the HS_SITE value (see section 3.2.2 in [2]).

3.8.3. Session Key Exchange

If the <ResponseCode> of a SESSION_SETUP response is RC_SESSION_EXCHANGEKEY, the client is responsible for generating the session key and sending it to the server. In this case, the client can generate a session key, encrypt it with the public key provided by the server in the SESSION_SETUP response, and send the encrypted session key to the server in a SESSION_EXCHANGEKEY request. The Message Header of the SESSION_EXCHANGEKEY request must set its <OpCode> to OC_SESSION_EXCHANGEKEY and its <ResponseCode> to 0. The Message Body of the SESSION_EXCHANGEKEY request is defined as follows: <Message Body of OC_SESSION_EXCHANGEKEY> ::= <Encrypted Session Key> [ <EncryptionAlgorithm> ] where <EncryptedSessionKey> Session key encrypted using the public key provided in the SESSION_SETUP response. The session key is a randomly generated octet string by the client.
Top   ToC   RFC3652 - Page 48
          <EncryptionAlgorithm>
          (optional) UTF-8 string that identifies the encryption
          algorithm used by the session key.

   During the session key exchange, the server receiving the exchange
   key or session key has the responsibility of ensuring that the key
   meets the security requirements defined in its local policy.  If the
   server considers the key being volunable, it must return an error
   message to the client with <ResponseCode> set to
   RC_SESSION_KEY_INVALID.

3.8.4. Session Termination

Clients can terminate a session with a SESSION_TERMINATE request. The Message Header of a SESSION_TERMINATE request must have its <OpCode> set to OC_SESSION_TERMINATE and its <ResponseCode> to 0. The message body of any SESSION_TERMINATE request must be empty. The server must send a SESSION_TERMINATE response to the client after the session is terminated. The server should only terminate the session after it has finished processing all the requests (under the session) that were submitted before the Session Termination request. The message header of the SESSION_TERMINATE response must set its <OpCode> to OC_SESSION_TERMINATE. A successful SESSION_TERMINATE response must have its <ResponseCode> set to RC_SUCCESS, and an empty message body.

4. Implementation Guidelines

4.1. Server Implementation

The optimal structure for any handle server will depend on the host operating system. This section only addresses those implementation considerations that are common to most handle servers. A good server implementation should allow easy configuration or fine-tuning. A suggested list of configurable items includes the server's network interface(s) (e.g., IP address, port number, etc.), the number of concurrent processes/threads allowed, time-out intervals for any TCP connection and/or authentication process, re- try policy under UDP connection, policies on whether to support recursive service, case-sensitivity for ASCII characters, and different levels of transaction logging, etc.
Top   ToC   RFC3652 - Page 49
   All handle server implementations must support all the handle data
   types as defined in the "Handle System Namespace and Service
   Definition" [2].  They should also be able to store handle values of
   any application defined data type.

   A handle server must support multiple concurrent activities, whether
   they are implemented as separate processes or threads in the host's
   operating system, or multiplexed inside a single name server program.
   A handle server should not block the service of UDP requests while it
   waits for TCP data or other query activities.  Similarly, a handle
   server should not attempt to provide recursive service without
   processing such requests in parallel, though it may choose to
   serialize requests from a single client, or to regard identical
   requests from the same client as duplicates.

4.2. Client Implementation

Clients should be prepared to receive handle values of any data type. Clients may choose to implement a callback interface to allow new modules or plug-ins to be added to support any application-defined data types. Clients that follow service referrals or handle aliases must avoid falling into an infinite loop. They should not repeatedly contact the same server for the same request with the same target entry. A client may choose to use a counter that is incremented each time it follows a service referral or handle alias. There should be a configurable upper limit to the counter to control the levels of service referrals or handle aliases followed by the client. Clients that provide some caching can expect much better performance than those that do not. Client implementations should always consider caching the service information associated with a naming authority. This will reduce the number of roundtrips for subsequent handle requests under the same naming authority.

5. Security Considerations

The overall Handle System security considerations are discussed in "Handle System Overview" [1]; that discussion applies equally to this document. Security considerations regarding the Handle System data model and service model are discussed in "Handle System Namespace and Service Definition" [2].
Top   ToC   RFC3652 - Page 50
   For efficiency, the Handle protocol includes a simple challenge-
   response authentication protocol for basic client authentication.
   Handle servers are free to provide additional authentication
   mechanisms (e.g., SASL) as needed.  Details of this will be discussed
   in a separate document.

   Data integrity under the Handle protocol is achieved via the server's
   digital signature.  Care must be taken to protect the server's
   private key from any impersonation attack.  Any change to the
   server's public key pair must be registered (in terms of service
   information) with the GHR.

6. Acknowledgements

This work is derived from the earlier versions of the Handle System implementation. The overall digital object architecture, including the Handle System, was described in a paper by Robert Kahn and Robert Wilensky [22] 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. Design ideas are based on those discussed within the Handle System development team, including David Ely, Charles Orth, Allison Yu, Sean Reilly, Jane Euler, Catherine Rey, Stephanie Nguyen, Jason Petrone, and Helen She. Their contributions to this work are gratefully acknowledged. The authors also thank Russ Housley (housley@vigilsec.com), Ted Hardie (hardie@qualcomm.com), and Mark Baugher (mbaugher@cisco.com) for their extensive review and comments, as well as recommendations received from other members of the IETF/IRTF community.

7. Informative References

[1] Sun, S. and L. Lannom, "Handle System Overview", RFC 3650, November 2003. [2] Sun, S., Reilly, S. and L. Lannom, "Handle System Namespace and Service Definition", RFC 3651, November 2003. [3] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998. [4] A. Freier, P. Karlton, P. Kocher "The SSL Protocol Version 3.0" [5] RSA Laboratories, "Public-Key Cryptography Standard PKCS#7" http://www.rsasecurity.com/rsalabs/pkcs/
Top   ToC   RFC3652 - Page 51
   [6]  U.S. Federal Information Processing Standard: Digital Signature
        Standard.

   [7]  Housley, R., "Cryptographic Message Syntax (CMS) Algorithms",
        RFC 3370, August 2002.

   [8]  Braden, R., "FTP Data Compression", RFC 468, March 1973.

   [9]  Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April
        1992.

   [10] NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995.

   [11] D. Cohen, "On Holy Wars and a Plea for Peace", Internet
        Experiment, Note IEN 137, 1 April 1980.

   [12] Balakrishnan, H. and S. Seshan, "The Congestion Manager", RFC
        3124, June 2001.

   [13] R. Kahn, R. Wilensky, "A Framework for Distributed Digital
        Object Services, May 1995, http://www.cnri.reston.va.us/k-w.html

   [14] Polk, W., Housley, R. and L. Bassham, "Algorithms and
        Identifiers for the Internet X.509 Public Key Infrastructure
        Certificate and Certificate Revocation List (CRL) Profile", RFC
        3279, April 2002.

   [15] Housley, R., Polk, W., Ford, W. and D. Solo, "Internet X.509
        Public Key Infrastructure Certificate and Certificate Revocation
        List (CRL) Profile", RFC 3280, April 2002.

   [16] M. Bellare and P. Rogaway. The Exact Security of Digital
        Signatures - How to Sign with RSA and Rabin. In Advances in
        Cryptology-Eurocrypt '96, pp.399-416, Springer-Verlag, 1996.

   [17] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing
        for Message Authentication", RFC 2104, February 1997.

   [18] R. Kahn, R. Wilensky, "A Framework for Distributed Digital
        Object Services", May 1995, http://www.cnri.reston.va.us/k-w.html
Top   ToC   RFC3652 - Page 52

8. Authors' Addresses

Sam X. Sun Corporation for National Research Initiatives (CNRI) 1895 Preston White Dr., Suite 100 Reston, VA 20191 Phone: 703-262-5316 EMail: ssun@cnri.reston.va.us Sean Reilly Corporation for National Research Initiatives (CNRI) 1895 Preston White Dr., Suite 100 Reston, VA 20191 Phone: 703-620-8990 EMail: sreilly@cnri.reston.va.us Larry Lannom Corporation for National Research Initiatives (CNRI) 1895 Preston White Dr., Suite 100 Reston, VA 20191 Phone: 703-262-5307 EMail: llannom@cnri.reston.va.us Jason Petrone Corporation for National Research Initiatives (CNRI) 1895 Preston White Dr., Suite 100 Reston, VA 20191 Phone: 703-262-5340 EMail: jpetrone@cnri.reston.va.us
Top   ToC   RFC3652 - Page 53

9. Full Copyright Statement

Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.