Internet Draft Sam X. Sun Document: draft-sun-handle-system-protocol-03.txt Sean Reilly Expires: April 2003 Larry Lannom Jason Petrone CNRI October 2002 Handle System Protocol (ver 2.1) Specification Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract This document describes the protocol used for client software to access the Handle System for both handle resolution and administration. The protocol specifies the procedure for a client software to locate the responsible handle server of any given handle. It also defines the messages exchanged between the client and server for any handle operation. Table of Contents 1. Overview....................................................2 2. Protocol Elements...........................................4 2.1 Conventions.................................................4 2.1.1 Data Transmission Order...................................4 2.1.2 Transport Layer...........................................5 2.1.3 Character Case............................................5 2.1.4 Standard String Type: UTF8-String.........................6 2.2 Common Elements.............................................6 Sun Expires - April 2003 [Page 1] Internet-Draft Handle System Protocol (v2.1) October 2002 2.2.1 Message Envelope..........................................7 2.2.2 Message Header...........................................10 2.2.3 Message Body.............................................15 2.2.4 Message Credential.......................................16 2.3 Message Transmission.......................................19 3. Handle System Protocol Operations..........................20 3.1 Client Bootstrapping.......................................20 3.1.1 Global Handle Registry and its Service Information.......20 3.1.2 Locating the Handle System Service Component.............20 3.1.3 Selecting the Responsible Server.........................21 3.2 Query Operation............................................21 3.2.1 Query Request............................................21 3.2.2 Successful Query Response................................23 3.2.3 Unsuccessful Query Response..............................23 3.3 Error Response from Server.................................24 3.4 Service Referral...........................................25 3.5 Client Authentication......................................26 3.5.1 Challenge from Server to Client..........................27 3.5.2 Challenge-Response from Client to Server.................27 3.5.3 Challenge-Response Verification-Request..................29 3.5.4 Challenge-Response Verification-Response.................30 3.6 Handle Administration......................................31 3.6.1 Add Handle Value(s)......................................31 3.6.2 Remove Handle Value(s)...................................32 3.6.3 Modify Handle Value(s)...................................33 3.6.4 Create Handle............................................34 3.6.5 Delete Handle............................................35 3.7 Naming Authority (NA) Administration.......................36 3.7.1 List Handle(s) under a Naming Authority..................36 3.7.2 List Sub-Naming Authorities under a Naming Authority.....37 3.8 Session and Session Management.............................38 3.8.1 Session Setup Request....................................39 3.8.2 Session Setup Response...................................41 3.8.3 Session Key Exchange.....................................43 3.8.4 Session Termination......................................43 4. Implementation Guidelines..................................44 4.1 Server Implementation......................................44 4.2 Client Implementation......................................44 5. Security Considerations....................................45 References and Bibliography.....................................45 Author's Addresses..............................................46 1. Overview The handle system defines a client server protocol in which client software submits requests via a network to handle servers. Each request describes the operation to be performed on the server. The server will process the request and return a message indicating the result of the operation. This document specifies the protocol for Sun Expires - April 2003 [Page 2] Internet-Draft Handle System Protocol (v2.1) October 2002 client software to access a handle server for handle resolution and administration. It does not include the description of the protocol used to manage handle servers. A discussion of the management protocol is out of the scope of this document and will be made available in a separate document. The document assumes that readers are familiar with the basic concepts of the Handle System as introduced in the "Handle System Overview" [1], as well as the data model and service definition given in the "Handle System Namespace and Service Definition" [2]. The Handle System consists of a set of service components as defined in [2]. From the client's point of view, the Handle System is a distributed database for handles. Different handles under the Handle System may be maintained by different handle servers at different network locations. The handle system protocol specifies the procedure for a client to locate the responsible handle server of any given handle. It also defines the messages exchanged between the client and server for any handle operation. Some key aspects of the handle system protocol include: . The handle system protocol supports both handle resolution and administration. The protocol follows the data and service model defined in [2]. . A client may authenticate any server response based on the server's digital signature. . A server may authenticate its client as handle administrator via the handle system authentication protocol. The handle system authentication protocol is a challenge-response protocol that supports both public-key and secret-key based authentication. . A session may be established between the client and server so that authentication information and network resources (e.g., TCP connection) may be shared among multiple operations. A session key can be established to achieve service integrity and data confidentiality. . The protocol can be extended to support new operations. Controls can be used to extend the existing operations. The protocol is defined to allow future backward compatibility. . Distributed service architecture. Support service referral among different service components. Sun Expires - April 2003 [Page 3] Internet-Draft Handle System Protocol (v2.1) October 2002 . Handles and their data types are based on the ISO-10646 (Unicode 2.0) character set. UTF-8 [3] is the mandated encoding under the handle system protocol. The handle system protocol (version 2.1) specified in this document has changed significantly from its earlier versions. These changes are necessary due to changes made in the handle system data model and the service model. Servers that implement this protocol may continue to support earlier versions of the protocol by checking the protocol version specified in the Message Envelope (see section 2.2.1). 2. Protocol Elements 2.1 Conventions The following conventions are followed by the handle system protocol to ensure interoperability among different implementations. 2.1.1 Data Transmission Order The order of transmission of data packets follows the network byte order (also called the Big-Endian [11]). That is, when a data-gram consists of a group of octets, the order of transmission of those octets follows their natural order from left to right and from top to bottom, as they are read in English. For example, in the following diagram, the octets are transmitted in the order they are numbered. 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 .-------------------------------. | 1 | 2 | |-------------------------------| | 3 | 4 | |-------------------------------| | 5 | 6 | '-------------------------------' If an octet represents a numeric quantity, the left most bit is the most significant bit. For example, the following diagram represents the value 170 (decimal). 0 1 2 3 4 5 6 7 .---------------. |1 0 1 0 1 0 1 0| '---------------' Sun Expires - April 2003 [Page 4] Internet-Draft Handle System Protocol (v2.1) October 2002 Similarly, whenever a multi-octet field represents a numeric quantity, the left most bit is the most significant bit and the most significant octet of the whole field is transmitted first. 2.1.2 Transport Layer The handle system protocol is designed so that messages may be transmitted either as separate data-grams over UDP or as a continuous byte stream via a TCP connection. The recommended port number for both UDP and TCP is 2641. UDP usage Messages carried by UDP are restricted to 512 bytes (not including the IP or UDP header). Longer messages must be fragmented into UDP packets where each packet carries a proper sequence number in the Message Envelope (see Section 2.2.1). The optimum retransmission policy will vary depending on the network or server performance. But the following are recommended: . The client should try other servers or service interfaces before repeating a request to the same server address. . The retransmission interval should be based on prior statistics if possible. Overly aggressive retransmission should be avoided to prevent slowdown of the community at large. The recommended retransmission interval is 2-5 seconds. TCP Usage Messages under the handle system protocol can be mapped directly into a TCP byte-stream. However, the size of each message is limited by the range of a 4-byte unsigned integer. Longer messages may be fragmented into multiple messages before the transmission and reassembled at the receiving end. Several connection management policies are recommended: . The server should support multiple connections and should not block other activities waiting for TCP data. . By default, the server should close the connection after completing the request. However, if the request asks to keep the connection open, the server should assume that the client will initiate connection closing. 2.1.3 Character Case Sun Expires - April 2003 [Page 5] Internet-Draft Handle System Protocol (v2.1) October 2002 Handles are character strings based on the ISO-10646 character set and must be encoded in UTF-8. By default, handle characters are treated as case-sensitive under the handle system protocol. A handle service, however, may be implemented in such a way that ASCII characters are processed case-insensitively. For example, the Global Handle Registry (GHR) provides a handle service where ASCII characters are processed in a case-insensitive manner. This suggests that ASCII characters in any naming authority are case- insensitive. When handles are created under a case-insensitive handle server, their original case should be preserved. To avoid any confusion, the server should avoid creating any handle whose character string matches that of an existing handle, ignoring the case difference. For example, if the handle "X/Y" was already created, the server should refuse any request to create the handle "x/y" or any of its case variations. 2.1.4 Standard String Type: UTF8-String Handles are transmitted as UTF8-Strings under the handle system protocol. Throughout this document, UTF8-String stands for the data type that consists of a 4-byte unsigned integer followed by a character string in UTF-8 encoding. The leading integer specifies the number of octets of the character string. 2.2 Common Elements Each message exchanged under the handle system protocol consists of four sections (see Fig. 2.2). Some of these sections (e.g., the Message Body) may be empty depending on the protocol operation. The Message Envelope must always be present. It has a fixed size of 20 octets. The Message Envelope does not carry any application layer information and is primarily used to help deliver the message. Content in the Message Envelope is not protected by the digital signature in the Message Credential. The Message Header must always be present as well. It has a fixed size of 24 octets and holds the common data fields of all messages exchanged between client and server. These include the operation code, the response code, and the control options for each protocol operation. Content in the Message Header is protected by the digital signature in the Message Credential. The Message Body contains data specific to each protocol operation. Its format varies according to the operation code and the response code in the Message Header. The Message Body may be empty. Content Sun Expires - April 2003 [Page 6] Internet-Draft Handle System Protocol (v2.1) October 2002 in the Message Body is protected by the digital signature in the Message Credential. The Message Credential provides a mechanism for transport security for any message exchanged between the client and server. A non- empty Message Credential may contain the digital signature from the originator of the message or the one-way Message Authentication Code (MAC) based on a pre-established session key. The Message Credential may be used to authenticate the message between the client and server. It can also be used to check the message integrity after its transmission. .----------------------. | | ; Message wrapper for proper message | Message Envelope | ; delivery. Not protected by the | | ; digital signature in the Message | | ; Credential. |----------------------| | | ; Common data fields for all handle | Message Header | ; operations. | | |----------------------| | | ; Specific data fields for each | Message Body | ; request/response. | | |----------------------| | | ; Contains digital signature or | Message Credential | ; message authentication code (MAC) | | ; upon Message Header and Message '----------------------' ; Body. Fig 2.2: Message format under the handle system protocol 2.2.1 Message Envelope Each message begins with a Message Envelope under the handle system protocol. If a message has to be truncated before its transmission, each truncated portion must also begin with a Message Envelope. The Message Envelope allows the reassembly of the message at the receiving end. It has a fixed size of 20 octets and consists of seven fields: Sun Expires - April 2003 [Page 7] Internet-Draft Handle System Protocol (v2.1) October 2002 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 .---------------------------------------------------------------. | MajorVersion | MinorVersion | MessageFlag | |---------------------------------------------------------------| | SessionId | |---------------------------------------------------------------| | RequestId | |---------------------------------------------------------------| | SequenceNumber | |---------------------------------------------------------------| | MessageLength | '---------------------------------------------------------------' 2.2.1.1 and The and are used to identify the version of the handle system protocol. Each of them is defined as a one-byte unsigned integer. This specification defines the protocol version whose is 2 and is 1. and are designed to allow future backward compatibility. A difference in indicates major variation in the protocol format and the party with the lower will have to upgrade its software to ensure precise communication. An increment in is made when additional capabilities are added to the protocol without any major change to the message format. 2.2.1.2 The consists of two-octets defined as follows: 1 1 1 1 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 .---------------------------------------------------------------. |CP |EC |TC | Reserved | '---------------------------------------------------------------' Bit 0 is the CP (ComPressed) flag that indicates whether the message (excluding the Message Envelope) is compressed. If the CP bit is set (to 1), the message is compressed. Otherwise, the message is not compressed. The handle system protocol uses the same compression method as used by the FTP protocol[8]. Bit 1 is the EC (EnCrypted) flag that indicates whether the message (excluding the Message Envelope) is encrypted. The EC bit should only be set under an established session where a session key is in Sun Expires - April 2003 [Page 8] Internet-Draft Handle System Protocol (v2.1) October 2002 place. If the EC bit is set (to 1), the message is encrypted using the session key. Otherwise the message is not encrypted. Bit 2 is the TC (TrunCated) flag that indicates whether this is a truncated message. Message truncation happens mostly when transmitting a large message over the UDP protocol. Details of message truncation (or fragmentation) will be discussed in section 2.3. Bits 3 to 15 are currently reserved and must be set to zero. 2.2.1.3 The is a four-byte unsigned integer that identifies a communication session between the client and server. Session and its are assigned by a server either upon a explicit request from a client or when multiple message exchanges are expected to fulfill the client's request. For example, the server will assign a unique in its response if it has to authenticate the client. A client may explicitly ask the server to setup a session as a virtually private communication channel like SSL [4]. Requests from clients without an established session must have their set to zero. The server must assign a unique non-zero for each new session. It is also responsible to terminate those sessions that are not in use after some period of time. Both clients and servers must maintain the same for messages exchanged under an established session. A message whose is zero indicates that no session has been established. The session and its state information may be shared among multiple handle operations. They may also be shared over multiple TCP connections as well. Once a session is established, both client and server must maintain their state information according to the . The state information may include the stage of the conversation, the other party's authentication information, and the session key that was established for message encryption or authentication. Details of these are discussed in section 3.8. 2.2.1.4 Each request from any client is identified by a , a 4- byte unsigned integer set by the client. Each request must have a unique among all outstanding requests from the same client. The allows the client to keep track of its requests. Any response from the server must maintain the same according to the request. Sun Expires - April 2003 [Page 9] Internet-Draft Handle System Protocol (v2.1) October 2002 2.2.1.5 Messages under the handle system protocol may be truncated during their transmission (e.g. under UDP). The is a 4- byte unsigned integer used as a counter to keep track of each truncated portion of the original message. Message recipient can reassemble the original message based on the . The must start with 0 for each message. Each truncated messages must set its TC flag in the Message Envelope. Messages that are not truncated must set their to zero. 2.2.1.6 A 4-byte unsigned integer that specifies the total number of octets of any message, excluding those in the Message Envelope. The length of any single message exchanged under the handle system protocol is limited by the range of a 4-byte unsigned integer. Longer data can be transmitted as multiple messages with a common . 2.2.2 Message Header The Message Header contains the common data elements among any protocol operation. It has a fixed size of 24 octets and consists of eight fields. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 .---------------------------------------------------------------. | OpCode | |---------------------------------------------------------------| | ResponseCode | |---------------------------------------------------------------| | OpFlag | |---------------------------------------------------------------| | SiteInfoSerialNumber | RecursionCount| | |---------------------------------------------------------------| | ExpirationTime | |---------------------------------------------------------------| | BodyLength | '---------------------------------------------------------------' Every message that is not truncated must have a Message Header. If a message has to be truncated for its transmission, the Message Header must appear in the first truncated portion of the message. This is different from the Message Envelope, which appears in each truncated portion of the message. 2.2.2.1 Sun Expires - April 2003 [Page 10] Internet-Draft Handle System Protocol (v2.1) October 2002 The stands for operation code, which is a four-byte unsigned integer that specifies the intended operation. The following table lists the s that MUST be supported by all implementations in order to conform to the base protocol specification. Each operation code is given a symbolic name that is used throughout this document for easy reference. Op_Code Symbolic Name Remark --------- ------------- ------ 0 OC_RESERVED Reserved 1 OC_RESOLUTION Handle query 2 OC_GET_SITEINFO Get HS_SITE values 100 OC_CREATE_HANDLE Create new handle 101 OC_DELETE_HANDLE Delete existing handle 102 OC_ADD_VALUE Add handle value(s) 103 OC_REMOVE_VALUE Remove handle value(s) 104 OC_MODIFY_VALUE Modify handle value(s) 105 OC_LIST_HANDLE List handles 106 OC_LIST_NA List sub-naming authorities 200 OC_CHALLENGE_RESPONSE Response to challenge 201 OC_VERIFY_RESPONSE Verify challenge response 300 : { Reserved for handle server administration } 399 400 OC_SESSION_SETUP Session setup request 401 OC_SESSION_TERMINATE Session termination request 402 OC_SESSION_EXCHANGEKEY Session key exchange A detailed description of each of these s can be found in section 3 of this document. In general, clients use the to tell the server what kind of handle operation they want to accomplish. Response from the server must maintain the same as the original request and use the to indicate the result. 2.2.2.2. The is a 4-byte unsigned integer that is given by a server to indicate the result of any service request. The list of s used in the handle system protocol is defined in the following table. Each response code is given a symbolic name that is used throughout this document for easy reference. Sun Expires - April 2003 [Page 11] Internet-Draft Handle System Protocol (v2.1) October 2002 Res. Code Symbolic Name Remark --------- ------------- ------ 0 RC_RESERVED Reserved for request 1 RC_SUCCESS Success response 2 RC_ERROR General error 3 RC_SERVER_BUSY Server too busy to respond 4 RC_PROTOCOL_ERROR Corrupted or unrecognizable message 5 RC_OPERATION_DENIED Unsupported operation 6 RC_RECUR_LIMIT_EXCEEDED Too many recursions for the request 100 RC_HANDLE_NOT_FOUND Handle not found 101 RC_HANDLE_ALREADY_EXIST Handle already exists 102 RC_INVALID_HANDLE Encoding (or syntax) error 200 RC_VALUE_NOT_FOUND Value not found 201 RC_VALUE_ALREADY_EXIST Value already exists 202 RC_VALUE_INVALID Invalid handle value 300 RC_EXPIRED_SITE_INFO SITE_INFO out of date 301 RC_SERVER_NOT_RESP Server not responsible 302 RC_SERVICE_REFERRAL Server referral 400 RC_NOT_AUTHORIZED Not authorized/permitted 401 RC_ACCESS_DENIED No access to data 402 RC_AUTHEN_NEEDED Authentication required 403 RC_AUTHEN_FAILED Failed to authenticate 404 RC_INVALID_CREDENTIAL Invalid credential 405 RC_AUTHEN_TIMEOUT Authentication timed out 406 RC_UNABLE_TO_AUTHEN Unable to authenticate 500 RC_SESSION_TIMEOUT Session expired 501 RC_SESSION_FAILED Unable to establish session 502 RC_NO_SESSION_KEY No session yet available 503 RC_SESSION_NO_SUPPORT Session not supported 900 RC_TRYING Request under processing 901 RC_FORWARDED Request forwarded to another server 902 RC_QUEUED Request queued for later processing Response codes under 10000 are reserved for system use. Any message with a response code under 10000 but not listed above should be treated as an unknown error. Response codes above 10000 are user defined and can be used for application specific purposes. Sun Expires - April 2003 [Page 12] Internet-Draft Handle System Protocol (v2.1) October 2002 Detailed descriptions of these s can be found in section 3 of this document. In general, any request from client must have its set to 0. The response message from the server must have a non-zero to indicate the result. For example, a response message from a server with set to RC_SUCCESS indicates that the server has successfully fulfilled the client's request. 2.2.2.3. The is a 32-bit bit-mask that defines various control options for protocol operation. The following figure shows the location of each option flag in the field. 1 1 1 1 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 .---------------------------------------------------------------. |AT |CT |ENC|REC|CA |CN |KC |PO |RD | Reserved | |---------------------------------------------------------------| | Reserved | '---------------------------------------------------------------' AT - AuThoritative bit. A request with the AT bit set (to 1) indicates that the request should be directed to the primary service site (instead of any mirroring sites). A response message with the AT bit set (to 1) indicates that the message is returned from a primary server (within the primary service site). CT - CerTified bit. A request with the CT bit set (to 1) asks the server to sign its response with its digital signature. A response with the CT bit set (to 1) indicates that the message is signed. ENC - ENCryption bit. A request with the ENC bit set (to 1) requires the server to encrypt its response using the pre-established session key. REC - RECursive bit. A request with the REC bit set (to 1) asks the server to forward the query on behalf of the client if the request has to be processed by another handle server. The server may honor the request by forwarding the request to the appropriate handle server and passing on any result back to the client. The server may also deny any such request by sending a response with set to RC_SERVER_NOT_RESP. CA - Cache Authentication. A request with the CA bit set (to 1) asks the caching server (if any) to authenticate any server response (e.g. verifying the server's signature) Sun Expires - April 2003 [Page 13] Internet-Draft Handle System Protocol (v2.1) October 2002 on behalf of the client. A response with the CA bit set (to 1) indicates that the response has been authenticated by the caching server. CN - ContiNuous bit. A message with the CN bit set (to 1) tells the message recipient that more messages that are part of the same request (or response) will follow. This happens if a request (or response) has data that is too large to fit into any single message and has to be fragmented into multiple messages. KC - Keep Connection bit. A message with the KC bit set requires the message recipient to keep the TCP connection open (after the response is sent back). This allows the same TCP connection to be used for multiple handle operations. PO - Public Only bit. Used by query operations only. A query request with the PO bit set (to 1) indicates that the client is only asking for handle values that have the PUB_READ permission. A request with PO bit set to zero asks for all the handle values regardless of their read permission. If any of the handle values requires ADMIN_READ permission, the server must authenticate the client as the handle administrator. RD - Request-Digest bit. A request with the RD bit set (to 1) asks the server to include in its response the message digest of the request. A response message with the RD bit set (to 1) indicates that the first field in the Message Body contains the message digest of the original request. The message digest can be used to check the integrity of the server response. Details of these are discussed later in this document. All other bits in the field are reserved and must be set to zero. In general, servers must honor the specified in the request. If a requested option cannot be met, the server should return an error message with the proper as defined in the previous section. 2.2.2.4. The is a two-byte unsigned integer. The in a request refers to the of the HS_SITE value used by the client (to access the server). Sun Expires - April 2003 [Page 14] Internet-Draft Handle System Protocol (v2.1) October 2002 Servers can check the in the request to find out if the client has the up-to-date service information. When possible, the server should fulfill a client's request even if the service information used by the client is out-of-date. However, the response message should specify the latest version of service information in the field. Clients with out- of-date service information can update the service information from the Global Handle Registry. If the server can not fulfill a client's request due to expired service information, it should reject the request and return an error message with set to RC_EXPIRED_SITE_INFO. 2.2.2.5. The is a one-byte unsigned integer that specifies the number of service recursions. Service recursion happens if the server has to forward client's request to another server. Any request directly from client must have its set to 0. If the server has to send a recursive request on behalf of the client, it must increment the by 1. Any response from the server must maintain the same as the one in the request. To prevent infinite loop of service recursion, the server should be configurable to stop sending any recursive request when the reaches a certain value. 2.2.2.6. The is a 4-byte unsigned integer that specifies the time when the message should be considered expired, relative to January 1st, 1970 GMT, in seconds. It is set to zero if no expiration is expected. 2.2.2.7. The is a 4-byte unsigned integer that specifies the number of octets in the Message Body. The does not count the octets in the Message Header or those in the Message Credential. 2.2.3 Message Body The Message Body always follows the Message Header. The number of octets in the Message Body can be found from the in the Message Header. The Message Body may be empty. The exact format of the Message Body depends on the and the in the Message Header. Details of the Message Body under each and are described in section 3 of this document. Sun Expires - April 2003 [Page 15] Internet-Draft Handle System Protocol (v2.1) October 2002 For any response message, if the Message Header has its RD bit (in ) set to 1, the Message Body must begin with the message digest of the original request. The message digest is defined as follows: ::= where An octet that identifies the algorithm used to generate the message digest. If the octet is set to 1, the digest is generated using the MD5 [9] algorithm. If the octet is set to 2, SHA-1 [10] algorithm is used. The message digest itself. It is calculated upon the Message Header and the Message Body of the original request. The length of the field is fixed according to the digest algorithm. For MD5 algorithm, the length is 16 octets. For SHA-1, the length is 20 octets. The Message Body may be truncated into multiple portions during its transmission (e.g. over UDP). Recipient of such message may reassemble the Message Body from each portion based on the in the Message Envelop. 2.2.4 Message Credential The Message Credential is primarily used to carry any digital signature signed by the message issuer. It may also carry the Message Authentication Code (MAC) if a session key has been established. The Message Credential is used to protect contents in the Message Header and the Message Body from being tampered during the transmission. The format of the Message Credential is designed to be semantically compatible with PKCS#7 [5]. Each Message Credential consists of the following fields: Sun Expires - April 2003 [Page 16] Internet-Draft Handle System Protocol (v2.1) October 2002 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 .---------------------------------------------------------------. | CredentialLength | |---------------------------------------------------------------| | Version | Reserved | Options | |---------------------------------------------------------------| | | Signer: | |---------------------------------------------------------------| | Type (UTF8-String) | |---------------------------------------------------------------| | | SignedInfo: : 4-byte unsigned integer | DigestAlgorithm: | SignedData: | '---------------------------------------------------------------' where A 4-byte unsigned integer that specifies the number of octets in the Message Credential. It must be set to zero if the message has no Message Credential. An octet that identifies the version number of the Message Credential. The version number specified in this document is zero. An octet that must be set to zero. Two octets reserved for various cryptography options. ::= A reference to a handle value in terms of the and the of the handle value. The handle value may contain the public key that can be used to validate the digital signature. A UTF8-String that specifies the content type in the field (described below). This document identifies three content Sun Expires - April 2003 [Page 17] Internet-Draft Handle System Protocol (v2.1) October 2002 types: HS_SIGNED for public key signature, HS_DIGEST for message digest, and HS_MAC for Message Authentication Code (MAC). ::= where A 4-byte unsigned integer that specifies the number of octets in the field. A UTF8-String that refers to the digest algorithm used to generate the digital signature. For example, the value "SHA- 1" indicates that SHA-1 algorithm is used to generate the message digest for the signature. ::= where A 4-byte unsigned integer that specifies the number of octets in the . Contains the digital signature or the MAC over the Message Header and Message Body. The syntax and semantics of the signature depends on the field and the public key referenced in the field. For example, if the field is "HS_SIGNED" and the public key referred to by the field is a DSA [6] public key, the signature will be the X.509 [7] (using ASN.1 encoding) representation of the parameter R and S used by DSA. The Message Credential may contain the message authentication code (MAC) generated using a pre-established session key. In this case, the field must set its to a zero-length UTF8- String and its to the specified in the Message Envelope. The field must contain the MAC in its field. The MAC is the result of the one-way hash over the concatenation of the session key, the , the , and the session key again. The Message Credential in a response message may contain the digital signature signed by the server. The server's public key can be found in the service information used by the client to send the Sun Expires - April 2003 [Page 18] Internet-Draft Handle System Protocol (v2.1) October 2002 request to the server. In this case, the client should ignore any reference in the field and use the public key in the service information to verify the signature. The Message Credential provides a mechanism for safe transmission of any message between the client and server. Any message whose Message Header and Message Body complies with its Message Credential suggests that the message indeed comes from its originator. It also assures that the message has not been tampered with during its transmission. 2.3 Message Transmission A large message may be truncated into multiple packets during its transmission. For example, to fit the size limit of UDP packet, the message issuer must truncate any large message into multiple UDP packets before its transmission. The message recipient must reassemble the message from these truncated packets before further processing. Message truncation must be carried out over the entire message except the Message Envelope. A new Message Envelope has to be inserted in front of each truncated packet before its transmission. For example, a large message that consists of .--------------------------------------------------------. | Message Envelope | Message Header, Body, Credential | '--------------------------------------------------------' may be truncated into: .--------------------------------------------. | Message Envelope 1 | Truncated_Packet 1 | '--------------------------------------------' .--------------------------------------------. | Message Envelope 2 | Truncated_Packet 2 | '--------------------------------------------' ...... .--------------------------------------------. | Message Envelope N | Truncated Packet N | '--------------------------------------------' where the "Truncated_packet 1", "Truncated_packet 2", ..., and "Truncated_packet N" are the results from truncating the Message Header, the Message Body and the Message Credential. Each "Message Envelope i" (inserted before each truncation) must set its TC flag to 1 and maintain the proper sequence count (in the ). Each "Message Envelope i" must also set its to reflect the size of the packet. The recipient of Sun Expires - April 2003 [Page 19] Internet-Draft Handle System Protocol (v2.1) October 2002 these truncated packets can reassemble the message by concatenating these packets based on their . 3. Handle System Protocol Operations This section describes the details of each protocol operation in terms of messages exchanged between the client and server. It also defines the format of the Message Body according to each and in the Message Header. 3.1 Client Bootstrapping 3.1.1 Global Handle Registry and its Service Information The service information for the Global Handle Registry (GHR) allows clients to contact the GHR to find out the responsible service components for their handles. The service information is a set of HS_SITE values assigned to the root handle "0.NA/0.NA" and is also called the root service information. The root service information may be distributed along with the client software, or be downloaded from the handle system website at http://www.handle.net. Changes to the root service information are identified by the in the HS_SITE values. A server at GHR can find out if the root service information used by the client is outdated by checking the in the client's request. The client should update the root service information if the of the response message is RC_EXPIRED_SITE_INFO. Clients may obtain the most up-to-date root service information from the root handle. The GHR must sign the root service information using the public key specified in the outdated service information (identified in the client's request) so that the client can validate the signature. 3.1.2 Locating the Handle System Service Component Each handle under the Handle System is managed by a unique handle system service component. For any given handle, the responsible service component (and its service information) can be found from its naming authority handle managed by the GHR. For example, to find the responsible LHS for the handle "1000/abc", client software can query the GHR for the HS_SITE (or HS_SERV) values assigned to the naming authority handle "0.NA/1000". The set of HS_SITE values is the service information of the LHS that manages every handle under the naming authority "1000". If no HS_SITE values are found, the client can check if there is any HS_SERV value assigned to the naming authority handle. From the HS_SERV value, the client can find the service handle that maintains the service information for the LHS. Recall that service Sun Expires - April 2003 [Page 20] Internet-Draft Handle System Protocol (v2.1) October 2002 handles are handles under the naming authority "0.SERV". They are used to manage the service information shared by different naming authorities. 3.1.3 Selecting the Responsible Server Each handle system service component is defined in terms of a set of HS_SITE values. Each of these HS_SITE values defines a service site within the service component. A service site may consist of a group of handle servers. For any given handle, the responsible handle server within the service component can be found following this procedure: 1. Select a preferred service site. Each service site is defined in terms of an HS_SITE value. The HS_SITE value may contain a or other attributes (under the ) to help the selection. Clients must select the primary service site for any administrative operations. 2. Locate the responsible server within the service site. This can be done as follows: Convert every ASCII character in the handle to its upper case. Calculate the MD5 hash of the converted handle string according to the given in the HS_SITE value. Take the last 4 bytes of the hash result as an signed integer. Modulo the absolute value of the integer by the given in the HS_SITE value. The result is the sequence number of the listed in the HS_SITE value. For example, if the result of the modulation is 2, the third listed in the should be selected. The defines the responsible handle server for the given handle. 3.2 Query Operation A query operation consists of client sending a query request to the responsible handle server and the server returning the query result to the client. Query request are used to retrieve handle values assigned to any given handle. 3.2.1 Query Request The Message Header of any query request must set its to OC_RESOLUTION (defined in section 2.2.2.1) and to 0. The Message Body for any query request is defined as follows: Sun Expires - April 2003 [Page 21] Internet-Draft Handle System Protocol (v2.1) October 2002 ::= where A UTF8-String (as defined in section 2.1.4) that specifies the handle to be resolved. 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. 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. The list may be empty if the first integer is 0, in which case the server must return all handle values regardless of their data type. If a query request does not specify any index or data type and the PO flag (in the Message Header) is set, the server will return all the handle values that have the PUBLIC_READ permission. Clients can also send queries without the PO flag set. In this case, the server will return all the handle values with PUBLIC_READ permission and all the handle values with ADMIN_READ permission. If the query requests a specific handle value via the value index and the value does not have PUBLIC_READ permission, the server should accept the request (and authenticate the client) even if the request has its PO flag set. If a query consists of a non-empty but an empty , the server should only return those handle values whose indexes are listed in the . Likewise, if a query consists of non-empty but an empty , the server should only return those handle values whose data types are listed in the . When both and fields are non-empty, the server should return those handle values whose indexes are listed Sun Expires - April 2003 [Page 22] Internet-Draft Handle System Protocol (v2.1) October 2002 in the and those handle values whose data types are listed in the . 3.2.2 Successful Query Response The Message Header of any query response must set its to OC_RESOLUTION. Successful query response must set its to RC_SUCCESS. The message body of the successful query response is defined as follows: ::= [] where Optional field as defined in section 2.2.3. A UTF8-String that specifies the handle queried by the client. A 4-byte unsigned integer followed by a list of handle values. The integer specifies the number of handle values in the list. The encoding of each handle value follows the specification given in [2] (see section 3.1). The integer is set to zero if there is no handle value that satisfies the query. 3.2.3 Unsuccessful Query Response If a server can not fulfill a client's request, it must return an error message to reveal the error. 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 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 in query. It is possible that the queried handle exists but is managed by another handle server (under some other handle service). When this happens, Sun Expires - April 2003 [Page 23] Internet-Draft Handle System Protocol (v2.1) October 2002 the server should either send a service referral (see section 3.4) or simply return an error message with set to RC_SERVER_NOT_RESP. The server may return an error message with set to RC_SERVER_BUSY if the server is too busy to process the request. Like RC_HANDLE_NOT_FOUND, a 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 the ADMIN_READ permission but no PUBLIC_READ permission. Details of client authentication is 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 (in the message header) as the one in the original request. Each error condition is identified by a unique as defined in section 2.2.2.2 of this document. The Message Body of an error message may be empty. Otherwise it consists of the following data fields (unless otherwise specified): ::= [] [ ] where Optional field as defined in section 2.2.3. A UTF8-String that explains the error. 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. For Sun Expires - April 2003 [Page 24] Internet-Draft Handle System Protocol (v2.1) October 2002 example, if a server is asked to add three handle values of of index 1, 2, and 3. If handle values with index 1 and 2 already exists, the server could return an error message with set to RC_VALUE_ALREADY_EXIST and add the index 1 and 2 to the . Note that the server is not obliged to return a 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 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 as the one in the original request and set its to RC_SERVICE_REFERRAL. The Message Body of any service referral is defined as follows: ::= [ ] [ ] where Optional field as defined in section 2.2.3. 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 this refers to). If the is set to "0.NA/0.NA", it is referring the client to the GHR. An optional field that must be empty if the 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 usual query responses that may consist of handle values of any data type, a service referral can only have zero or more Sun Expires - April 2003 [Page 25] Internet-Draft Handle System Protocol (v2.1) October 2002 HS_SITE values in its . The may contain an empty UTF8-String if the HS_SITE values in the 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 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 privilege. This includes adding, removing, or modifying handles or handle values. Client authentication consists of multiple messages exchanged between the client and server. Messages exchanged during the authentication are correlated via a unique assigned by the server. The authentication starts with a response message from the server that contains a challenge to the client. The client must respond 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 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 privilege, the server will process the request and send back the result. If the administrator does not have sufficient privilege, the server will return an error message with set to RC_NOT_AUTHORIZED. The following sections will provide details of each message exchanged during the authentication process. Sun Expires - April 2003 [Page 26] Internet-Draft Handle System Protocol (v2.1) October 2002 3.5.1 Challenge from Server to Client The Message Header of the CHALLENGE must keep the same as the original request and set the to RC_AUTH_NEEDED. The server must assign a non-zero unique in the Message Envelope to keep track of the authentication. It must also set the RD flag of the (see section 2.2.2.3) in the Message Header, regardless whether the original request had the RD bit set or not. The Message Body of the server's CHALLENGE is defined as follows: ::= where Message Digest of the request message, as defined in section 2.2.3. 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. 3.5.2 Challenge-Response from Client to Server The Message Header of the CHALLENGE_RESPONSE must set its to OC_CHALLENGE_RESPONSE and its to 0. It must also keep the same (in the Message Envelope) as specified in the challenge from the server. The Message Body of the CHALLENGE_RESPONSE request is defines as follows: ::= where A UTF8-String that identifies the type of authentication key used by the client. For example, the field is set to "HS_SECKEY" when the client choose to use a secret key for its authentication. The field is set to "HS_PUBKEY" if a public key is used instead. Sun Expires - April 2003 [Page 27] Internet-Draft Handle System Protocol (v2.1) October 2002 A UTF8-String that identifies the handle that holds the public or secret key of the handle administrator. A 4-byte unsigned integer that specifies the index of the handle value (of the ) that holds the public or secret key of the administrator. Contains either the Message Authentication Code (MAC) or the digital signature over the challenge from the server. If the is "HS_SECKEY", the consists of an octet followed by the MAC. The octet identifies the message digest algorithm used to generate the MAC, as described in section 2.2.3. The MAC is the hash result over the concatenation of the secret key of the administrator, the server's challenge, and the secret key again. For example, if the first octet is set to 1, the MAC is generated by MD5_Hash( + + ) where the is the administrator's secret key referenced by the and . The is the Message Body portion of the server's challenge. If the is "HS_PUBKEY", the contains the digital signature over the Message Body portion of the server's challenge. 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 and 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 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 field may refer to a handle value of type HS_VLIST. A 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. Sun Expires - April 2003 [Page 28] Internet-Draft Handle System Protocol (v2.1) October 2002 For handles with multiple HS_ADMIN values, the server will have to check each of those with sufficient privilege to see if its field matches the and . If no match is found but there are administrator groups defined, the server must check if the and belongs to any of the administrator groups that have sufficient privilege. 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 and is not referenced by any of the HS_ADMIN values or the administrator group that has sufficient privilege, the server will return an error message with set to RC_NOT_AUTHORIZED. Otherwise, the server will continue to authenticate the client as follows: If the is "HS_PUBKEY", the server will retrieve the administrator's public key based on the and . The public key can be used to verify the against the server's . If the matches the , the server will continue to process the original request and return the result. Otherwise, the server will return an error message with set to RC_AUTHENTICATION_FAILED. If the 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 . The verification request and its response are defined in the following sections. The verification server will verify the against the on behalf of the handle server. 3.5.3 Challenge-Response Verification-Request The message header of the VERIFICATION_REQUEST must set its to OC_VERIFY_CHALLENGE and the to 0. The message body of the Verification-Request is defined as follows: ::= where Sun Expires - April 2003 [Page 29] Internet-Draft Handle System Protocol (v2.1) October 2002 A UTF8-String that refers to the handle that holds the secret key of the administrator. A 4-byte unsigned integer that is the index of the handle value that holds the secret key of the administrator. The message body of the server's challenge, as described in section 3.5.1. The from the client in response to the server's , 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 matches the in the Verification-Request. The Message Header of the Verification-Response must set its to RC_SUCCESS whether the matches the or not. The RD flag in the field should also be set (to 1) since the will be mandatory in the Message Body. The Message Body of the Verification-Response is defined as follows: ::= where Contains the message digest of the Verification-Request. An octet that is set to 1 if the matches the . Otherwise it must be set to 0. Sun Expires - April 2003 [Page 30] Internet-Draft Handle System Protocol (v2.1) October 2002 The verification server may return an error with set to RC_AUTHEN_FAILED if it can not perform the verification (e.g. the does not exist, or the and refers 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 administrations 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 to OC_ADD_VALUE. The Message Body of the ADD_VALUE request is encoded as follows: ::= where A UTF8-String that specifies the handle. 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 to the . If successful, the server will return a RC_SUCCESS message to the client. Each ADD_VALUE request must be carried out as a transaction. If adding any value in the raises an error, the entire operation must be rolled back. For any failed ADD_VALUE request, none of the values in the should be added to the . The server must also send a response to the client that explains the error. For example, if a value in the has Sun Expires - April 2003 [Page 31] Internet-Draft Handle System Protocol (v2.1) October 2002 the same index as the one of an existing handle value, the server will return an error message that has the set to RC_VALUE_ALREADY_EXISTS. ADD_VALUE requests can also be used to add handle administrators. This happens if the in the ADD_VALUE request contains any HS_ADMIN values. The server must authenticate the client as the administrator with 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 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 to OC_REMOVE_VALUE. The Message Body of any REMOVE_VALUE request is encoded as follows: ::= where A UTF8-String that specifies the handle whose value(s) needs to be removed. 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 . 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 from the . If successful, the server will return a RC_SUCCESS message to the client. Each REMOVE_VALUE request must be carried out as a transaction. If removing any value specified in the raises an error, the entire operation must be rolled back. For any failed REMOVE_VALUE request, none of values referenced in the Sun Expires - April 2003 [Page 32] Internet-Draft Handle System Protocol (v2.1) October 2002 should be removed from the . 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 a 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 refer to a HS_ADMIN value. Servers must authenticate the client as the administrator with 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 to OC_MODIFY_VALUE. The Message Body of any MODIFY_VALUE request is defined as follows: ::= where A UTF8-String that specifies the handle whose value(s) needs to be modified. 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 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 the administrator with MODIFY_VALUE privilege. Upon successful authentication, the server will proceed to replace those handle values listed in the , provided each handle value has the PUB_WRITE or ADMIN_WRITE permission. If successful, the server must notify the client with a RC_SUCCESS message. Each MODIFY_VALUE request must be carried out as a transaction. If replacing any value listed in the raises an error, the entire operation must be rolled back. For any failed MODIFY_VALUE Sun Expires - April 2003 [Page 33] Internet-Draft Handle System Protocol (v2.1) October 2002 request, none of values in the should be replaced. The server must also return a response to the client that explains the error. For example, if a MODIFY_VALUE request asks to remove a handle value that has neither PUB_WRITE nor ADMIN_WRITE permission, the server must return an error message with the 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 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 and the value to be replaced are HS_ADMIN values. Servers must authenticate the client as the administrator with MODIFY_ADMIN privilege before fulfilling such request. It is an error to replace a non HS_ADMIN value with a HS_ADMIN value. In this case, the server will return an error message with 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 to OC_CREATE_HANDLE. The Message Body of any CREATE_HANDLE request is defined as follows: ::= where A UTF8-String that specifies the handle. A 4-byte unsigned integer followed by a list of handle values. The integer indicates the number of handle values in the list. The 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 Sun Expires - April 2003 [Page 34] Internet-Draft Handle System Protocol (v2.1) October 2002 the client as the administrator of the handle. Upon successful authentication, the server will proceed to create the new handle and add each value in the to the new . If successful, the server will return a 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 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 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 to OC_DELETE_HANDLE. The Message Body of any DELETE_HANDLE request is defined as follows: ::= where 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 value assigned to the handle. If successful, the server will return a 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 failed, the entire operation Sun Expires - April 2003 [Page 35] Internet-Draft Handle System Protocol (v2.1) October 2002 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 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 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 at 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 authority may be created or deleted by the administrator of the root handle "0.NA/0.NA". Non-root level naming authority 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 system 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 Sun Expires - April 2003 [Page 36] Internet-Draft Handle System Protocol (v2.1) October 2002 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 to OC_LIST_HANDLE. The Message Body of any LIST_HANDLE request is defined as follows: ::= where 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 any 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 successful LIST_HANDLE response (from each handle server) is defined as follows: ::= where Number of handles (managed by the handle server) under the naming authority. 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 whether to support such request or not. The server will return a RC_OPERATION_DENIED message if LIST_HANDLE is not supported. The server that receives a LIST_HANDLE request should authenticate the client as the 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 to OC_LIST_NA. The Message Body of any LIST_NA request is defined as follows: ::= Sun Expires - April 2003 [Page 37] Internet-Draft Handle System Protocol (v2.1) October 2002 where 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: ::= where Number of handles (managed by the handle server) under the naming authority. 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 which manages all the naming authority handles. The LIST_NA request may potentially slow down the overall system performance, especially the GHS. Server (or service sites) under the GHR has the option whether to support such request or not. The server will return a RC_OPERATION_DENIED message if LIST_NA is not supported. The server that receives a LIST_HANDLE request should authenticate the client as the 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 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. Sun Expires - April 2003 [Page 38] Internet-Draft Handle System Protocol (v2.1) October 2002 Sessions may be established as the result of an explicit OC_SESSION_SETUP request from a client. A server may also setup a session automatically when multiple message exchanges are expected to fulfill a request. For example, the server will establish a session automatically 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, the information obtained from client authentication, as well as any communication options. Servers and clients are responsible to keep the state information in sync until the session is terminated. A session may be terminated with a OC_SESSION_TERMINATE request from the client. Servers may also terminate a session that has been idle for some significant amount of time. 3.8.1 Session Setup Request Clients may establish a session with a handle server with a SESSION_SETUP request. 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 set to OC_SESSION_SETUP and to 0. The Message Body of any SESSION_SETUP request is defined as follows: ::= where 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 , the , and the . Each of these attributes is defined as follows: ::= where Sun Expires - April 2003 [Page 39] Internet-Draft Handle System Protocol (v2.1) October 2002 A UTF-8 string constant "HS_SESSION_IDENTITY". An 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. ::= where A UTF-8 string constant "HS_SESSION_KEY_EXCHANGE". One of the these tuples: , , or . Each of these tuples is defined as follows: ::= where A UTF-8 string constant "CLIENT_CIPHER". A public key provided by the client and used by the server to encrypt the session key. ::= where A UTF-8 string constant "HDL_CIPHER". A UTF-8 String followed by a 4-byte unsigned integer. The and refers to a handle value used for session key exchange. The handle value must contain the public key of the client. The public Sun Expires - April 2003 [Page 40] Internet-Draft Handle System Protocol (v2.1) October 2002 key will be used by the server to encrypt the session key before sending it to the client. ::= where 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 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. ::= where A UTF-8 string constant "HS_SESSION_TIMEOUT". A 4-byte unsigned integer that specifies the desired duration of the session in terms of number of seconds. Note that it should be treated as an error if the same session attribute is listed multiple times in the field. When this happens, the server should return an error message with set to RC_PROTOCOL_ERROR. A SESSION_SETUP_REQUEST can be used to change session attributes of any established session. This happens if the 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 appropriate MAC in its Message Credential. 3.8.2 Session Setup Response The Message Header of the SESSION_SETUP response must set its to OC_SESSION_SETUP. The of the SESSION_SETUP response varies according to the SESSION_SETUP Sun Expires - April 2003 [Page 41] Internet-Draft Handle System Protocol (v2.1) October 2002 request. It must be set to RC_SUCCESS if the SESSION_SETUP request is successful and no The Message Body of the SESSION_SETUP response is empty unless the request is asking for . In this case, the Message Body of the SESSION_SETUP response may contain the encrypted session key from the server, or the server' public key to be used for session key exchange. The exact format depends on the content of the in the SESSION_SETUP request. If or 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: ::= where Message digest of the SESSION_SETUP request as specified in section 2.2.3. Session key 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 if the in the SESSION_SETUP request provides the public key from the client. If 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 to RC_SESSION_EXCHANGEKEY. The Message Body of the SESSION_SETUP response must include the server's public key and is defined as follows: ::= where Message digest of the SESSION_SETUP request as specified in Sun Expires - April 2003 [Page 42] Internet-Draft Handle System Protocol (v2.1) October 2002 section 2.2.3. Public key from the server to be used for session key exchange. It is encoded in the same format as the record in the HS_SITE value (see section 3.2.2 in [2]). 3.8.3 Session Key Exchange If the of a SESSION_SETUP response is RC_SESSION_EXCHANGEKEY, the client is responsible to generate the session key and send 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 to OC_SESSION_EXCHANGEKEY and its to 0. The Message Body of the SESSION_EXCHANGEKEY request is defined as follows: ::= [ ] where 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. 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 set to OC_SESSION_TERMINATE and its to 0. The message body of any SESSION_TERMINATE request must be empty. Server must send a SESSION_TERMINATE response to the client after the session gets terminated. The server should only terminate the session after it has finished processing all the requests (under the session) that have been submitted before the Session Termination request. The message header of the SESSION_TERMINATE response must set its to OC_SESSION_TERMINATE. Successful SESSION_TERMINATE response must have its set to RC_SUCCESS, and a empty message body. Sun Expires - April 2003 [Page 43] Internet-Draft Handle System Protocol (v2.1) October 2002 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 include 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. 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 don't. Client implementations should Sun Expires - April 2003 [Page 44] Internet-Draft Handle System Protocol (v2.1) October 2002 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] and 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]. For efficiency reason, the handle system protocol includes a simple challenge-response authentication protocol for basic client authentication. Handle servers are free to provide additional authentication mechanism (e.g. SASL) as needed. Details of this will be discussed in a separate document. Message integrity under handle system protocol is achieved via 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) at the GHR. References and Bibliography [1] S. Sun, L. Lannom, "Handle System Overview", IETF draft, work in progress [2] S. Sun, S. Reilly, L. Lannom, "Handle System Namespace and Service Definition", IETF draft, work in progress [3] F. Yergeau, "UTF-8, A Transform Format for Unicode and ISO10646", RFC2044, October 1996 [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/ [6] U.S. Federal Information Processing Standard: Digital Signature Standard. [7] ITU/ISO Recommendation X.509 - Information technology - Open System Interconnection - The directory: Autherntication framework. November, 1993 [8] R. Braden, "FTP DATA COMPRESSION", RFC468, March 8, 1973 Sun Expires - April 2003 [Page 45] Internet-Draft Handle System Protocol (v2.1) October 2002 [9] R. Rivest, "The MD5 Message-Digest Algorithm", RFC1321, 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. Author's 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 Sun Expires - April 2003 [Page 46]