idnits 2.17.1 draft-sun-handle-system-protocol-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) == There are 13 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 495: '...e s that MUST be supported by ...' Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 2003) is 7614 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '18' on line 2332 looks like a reference -- Missing reference section? '1' on line 2281 looks like a reference -- Missing reference section? '2' on line 2284 looks like a reference -- Missing reference section? '3' on line 2287 looks like a reference -- Missing reference section? '11' on line 2308 looks like a reference -- Missing reference section? '12' on line 2311 looks like a reference -- Missing reference section? '8' on line 2301 looks like a reference -- Missing reference section? '4' on line 2290 looks like a reference -- Missing reference section? '9' on line 2303 looks like a reference -- Missing reference section? '10' on line 2306 looks like a reference -- Missing reference section? '5' on line 2292 looks like a reference -- Missing reference section? '16' on line 2325 looks like a reference -- Missing reference section? '6' on line 2295 looks like a reference -- Missing reference section? '7' on line 2298 looks like a reference -- Missing reference section? '14' on line 2317 looks like a reference -- Missing reference section? '15' on line 2321 looks like a reference -- Missing reference section? '17' on line 2329 looks like a reference -- Missing reference section? '13' on line 2314 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 20 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft Sam X. Sun 3 Document: draft-sun-handle-system-protocol-05.txt Sean Reilly 4 Expires: December 2003 Larry Lannom 5 Jason Petrone 6 CNRI 7 June 2003 9 Handle System Protocol (ver 2.1) Specification 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other 23 documents at any time. It is inappropriate to use Internet-Drafts 24 as reference material or to cite them other than as "work in 25 progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 Abstract 34 The Handle System is a general-purpose global name service that 35 allows secured name resolution and administration over the public 36 Internet. This document describes the protocol used for client 37 software to access the Handle System for both handle resolution and 38 administration. The protocol specifies the procedure for a client 39 software to locate the responsible handle server of any given 40 handle. It also defines the messages exchanged between the client 41 and server for any handle operation. 43 Table of Contents 45 1. Overview...................................................2 46 2. Protocol Elements..........................................4 47 2.1 Conventions................................................4 48 2.1.1 Data Transmission Order...................................4 49 2.1.2 Transport Layer...........................................5 50 2.1.3 Character Case............................................6 51 2.1.4 Standard String Type: UTF8-String.........................6 52 2.2 Common Elements............................................6 53 2.2.1 Message Envelope..........................................7 54 2.2.2 Message Header...........................................10 55 2.2.3 Message Body.............................................16 56 2.2.4 Message Credential.......................................16 57 2.3 Message Transmission......................................19 58 3. Handle Protocol Operations................................20 59 3.1 Client Bootstrapping......................................20 60 3.1.1 Global Handle Registry and its Service Information.......20 61 3.1.2 Locating the Handle System Service Component.............21 62 3.1.3 Selecting the Responsible Server.........................21 63 3.2 Query Operation...........................................22 64 3.2.1 Query Request............................................22 65 3.2.2 Successful Query Response................................24 66 3.2.3 Unsuccessful Query Response..............................24 67 3.3 Error Response from Server................................25 68 3.4 Service Referral..........................................26 69 3.5 Client Authentication.....................................27 70 3.5.1 Challenge from Server to Client..........................28 71 3.5.2 Challenge-Response from Client to Server.................28 72 3.5.3 Challenge-Response Verification-Request..................31 73 3.5.4 Challenge-Response Verification-Response.................32 74 3.6 Handle Administration.....................................32 75 3.6.1 Add Handle Value(s)......................................33 76 3.6.2 Remove Handle Value(s)...................................33 77 3.6.3 Modify Handle Value(s)...................................34 78 3.6.4 Create Handle............................................36 79 3.6.5 Delete Handle............................................37 80 3.7 Naming Authority (NA) Administration......................38 81 3.7.1 List Handle(s) under a Naming Authority..................38 82 3.7.2 List Sub-Naming Authorities under a Naming Authority.....39 83 3.8 Session and Session Management............................40 84 3.8.1 Session Setup Request....................................41 85 3.8.2 Session Setup Response...................................43 86 3.8.3 Session Key Exchange.....................................45 87 3.8.4 Session Termination......................................46 88 4. Implementation Guidelines.................................46 89 4.1 Server Implementation.....................................46 90 4.2 Client Implementation.....................................47 91 5. Security Considerations...................................47 92 References and Bibliography.....................................47 93 Author's Addresses..............................................49 95 1. Overview 97 The Handle System provides a general-purpose, secured global name 98 service for the Internet. It was originally conceived and described 99 in a paper by Robert Kahn and Robert Wilensky [18] in 1995. The 100 Handle System defines a client server protocol in which client 101 software submits requests via a network to handle servers. Each 102 request describes the operation to be performed on the server. The 103 server will process the request and return a message indicating the 104 result of the operation. This document specifies the protocol for 105 client software to access a handle server for handle resolution and 106 administration. It does not include the description of the protocol 107 used to manage handle servers. A discussion of the management 108 protocol is out of the scope of this document and will be made 109 available in a separate document. The document assumes that readers 110 are familiar with the basic concepts of the Handle System as 111 introduced in the "Handle System Overview" [1], as well as the data 112 model and service definition given in the "Handle System Namespace 113 and Service Definition" [2]. 115 The Handle System consists of a set of service components as 116 defined in [2]. From the client's point of view, the Handle System 117 is a distributed database for handles. Different handles under the 118 Handle System may be maintained by different handle servers at 119 different network locations. The handle protocol specifies the 120 procedure for a client to locate the responsible handle server of 121 any given handle. It also defines the messages exchanged between 122 the client and server for any handle operation. 124 Some key aspects of the handle protocol include: 126 o The handle protocol supports both handle resolution and 127 administration. The protocol follows the data and service 128 model defined in [2]. 130 o A client may authenticate any server response based on the 131 server's digital signature. 133 o A server may authenticate its client as handle administrator 134 via the handle authentication protocol. The handle 135 authentication protocol is a challenge-response protocol that 136 supports both public-key and secret-key based authentication. 138 o A session may be established between the client and server so 139 that authentication information and network resources (e.g., 140 TCP connection) may be shared among multiple operations. A 141 session key can be established to achieve data integrity and 142 confidentiality. 144 o The protocol can be extended to support new operations. 145 Controls can be used to extend the existing operations. The 146 protocol is defined to allow future backward compatibility. 148 o Distributed service architecture. Support service referral 149 among different service components. 151 o Handles and their data types are based on the ISO-10646 152 (Unicode 2.0) character set. UTF-8 [3] is the mandated 153 encoding under the handle protocol. 155 The handle protocol (version 2.1) specified in this document has 156 changed significantly from its earlier versions. These changes are 157 necessary due to changes made in the Handle System data model and 158 the service model. Servers that implement this protocol may 159 continue to support earlier versions of the protocol by checking 160 the protocol version specified in the Message Envelope (see section 161 2.2.1). 163 2. Protocol Elements 165 2.1 Conventions 167 The following conventions are followed by the handle protocol to 168 ensure interoperability among different implementations. 170 2.1.1 Data Transmission Order 172 The order of transmission of data packets follows the network byte 173 order (also called the Big-Endian [11]). That is, when a data-gram 174 consists of a group of octets, the order of transmission of those 175 octets follows their natural order from left to right and from top 176 to bottom, as they are read in English. For example, in the 177 following diagram, the octets are transmitted in the order they are 178 numbered. 180 0 1 181 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 182 .-------------------------------. 183 | 1 | 2 | 184 |-------------------------------| 185 | 3 | 4 | 186 |-------------------------------| 187 | 5 | 6 | 188 '-------------------------------' 190 If an octet represents a numeric quantity, the left most bit is the 191 most significant bit. For example, the following diagram represents 192 the value 170 (decimal). 194 0 1 2 3 4 5 6 7 195 .---------------. 196 |1 0 1 0 1 0 1 0| 197 '---------------' 199 Similarly, whenever a multi-octet field represents a numeric 200 quantity, the left most bit is the most significant bit and the 201 most significant octet of the whole field is transmitted first. 203 2.1.2 Transport Layer 205 The handle protocol is designed so that messages may be transmitted 206 either as separate data-grams over UDP or as a continuous byte 207 stream via a TCP connection. The recommended port number for both 208 UDP and TCP is 2641. 210 UDP Usage 212 Messages carried by UDP are restricted to 512 bytes (not including 213 the IP or UDP header). Longer messages must be fragmented into UDP 214 packets where each packet carries a proper sequence number in the 215 Message Envelope (see Section 2.2.1). 217 The optimum retransmission policy will vary depending on the 218 network or server performance, but the following are recommended: 220 o The client should try other servers or service interfaces 221 before repeating a request to the same server address. 223 o The retransmission interval should be based on prior 224 statistics if possible. Overly aggressive retransmission 225 should be avoided to prevent network congestion. The 226 recommended retransmission interval is 2-5 seconds. 228 o When transmitting large amounts of data, TCP-friendly 229 congestion control, such as an interface to the Congestion 230 Manager [12], should be implemented whenever possible to avoid 231 unfair consumption of the bandwidth against TCP-based 232 applications. Details of the congestion control will be 233 discussed in a separate document. 235 TCP Usage 237 Messages under the handle protocol can be mapped directly into a 238 TCP byte-stream. However, the size of each message is limited by 239 the range of a 4-byte unsigned integer. Longer messages may be 240 fragmented into multiple messages before the transmission and 241 reassembled at the receiving end. 243 Several connection management policies are recommended: 245 o The server should support multiple connections and should not 246 block other activities waiting for TCP data. 248 o By default, the server should close the connection after 249 completing the request. However, if the request asks to keep 250 the connection open, the server should assume that the client 251 will initiate connection closing. 253 2.1.3 Character Case 255 Handles are character strings based on the ISO-10646 character set 256 and must be encoded in UTF-8. By default, handle characters are 257 treated as case-sensitive under the handle protocol. A handle 258 service, however, may be implemented in such a way that ASCII 259 characters are processed case-insensitively. For example, the 260 Global Handle Registry (GHR) provides a handle service where ASCII 261 characters are processed in a case-insensitive manner. This 262 suggests that ASCII characters in any naming authority are case- 263 insensitive. 265 When handles are created under a case-insensitive handle server, 266 their original case should be preserved. To avoid any confusion, 267 the server should avoid creating any handle whose character string 268 matches that of an existing handle, ignoring the case difference. 269 For example, if the handle "X/Y" was already created, the server 270 should refuse any request to create the handle "x/y" or any of its 271 case variations. 273 2.1.4 Standard String Type: UTF8-String 275 Handles are transmitted as UTF8-Strings under the handle protocol. 276 Throughout this document, UTF8-String stands for the data type that 277 consists of a 4-byte unsigned integer followed by a character 278 string in UTF-8 encoding. The leading integer specifies the number 279 of octets of the character string. 281 2.2 Common Elements 283 Each message exchanged under the system protocol consists of four 284 sections (see Fig. 2.2). Some of these sections (e.g., the Message 285 Body) may be empty depending on the protocol operation. 287 The Message Envelope must always be present. It has a fixed size of 288 20 octets. The Message Envelope does not carry any application 289 layer information and is primarily used to help deliver the 290 message. Content in the Message Envelope is not protected by the 291 digital signature in the Message Credential. 293 The Message Header must always be present as well. It has a fixed 294 size of 24 octets and holds the common data fields of all messages 295 exchanged between client and server. These include the operation 296 code, the response code, and the control options for each protocol 297 operation. Content in the Message Header is protected by the 298 digital signature in the Message Credential. 300 The Message Body contains data specific to each protocol operation. 301 Its format varies according to the operation code and the response 302 code in the Message Header. The Message Body may be empty. Content 303 in the Message Body is protected by the digital signature in the 304 Message Credential. 306 The Message Credential provides a mechanism for transport security 307 for any message exchanged between the client and server. A non- 308 empty Message Credential may contain the digital signature from the 309 originator of the message or the one-way Message Authentication 310 Code (MAC) based on a pre-established session key. The Message 311 Credential may be used to authenticate the message between the 312 client and server. It can also be used to check data integrity 313 after its transmission. 315 .----------------------. 316 | | ; Message wrapper for proper message 317 | Message Envelope | ; delivery. Not protected by the 318 | | ; digital signature in the Message 319 | | ; Credential. 320 |----------------------| 321 | | ; Common data fields for all handle 322 | Message Header | ; operations. 323 | | 324 |----------------------| 325 | | ; Specific data fields for each 326 | Message Body | ; request/response. 327 | | 328 |----------------------| 329 | | ; Contains digital signature or 330 | Message Credential | ; message authentication code (MAC) 331 | | ; upon Message Header and Message 332 '----------------------' ; Body. 334 Fig 2.2: Message format under the handle protocol 336 2.2.1 Message Envelope 338 Each message begins with a Message Envelope under the handle 339 protocol. If a message has to be truncated before its transmission, 340 each truncated portion must also begin with a Message Envelope. 342 The Message Envelope allows the reassembly of the message at the 343 receiving end. It has a fixed size of 20 octets and consists of 344 seven fields: 346 0 1 2 3 347 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 348 .---------------------------------------------------------------. 349 | MajorVersion | MinorVersion | MessageFlag | 350 |---------------------------------------------------------------| 351 | SessionId | 352 |---------------------------------------------------------------| 353 | RequestId | 354 |---------------------------------------------------------------| 355 | SequenceNumber | 356 |---------------------------------------------------------------| 357 | MessageLength | 358 '---------------------------------------------------------------' 360 2.2.1.1 and 362 The and are used to identify the 363 version of the handle protocol. Each of them is defined as a one- 364 byte unsigned integer. This specification defines the protocol 365 version whose is 2 and is 1. 367 and are designed to allow future 368 backward compatibility. A difference in indicates 369 major variation in the protocol format and the party with the lower 370 will have to upgrade its software to ensure precise 371 communication. An increment in is made when 372 additional capabilities are added to the protocol without any major 373 change to the message format. 375 2.2.1.2 377 The consists of two octets defined as follows: 379 1 1 1 1 1 1 380 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 381 .---------------------------------------------------------------. 382 |CP |EC |TC | Reserved | 383 '---------------------------------------------------------------' 385 Bit 0 is the CP (ComPressed) flag that indicates whether the 386 message (excluding the Message Envelope) is compressed. If the CP 387 bit is set (to 1), the message is compressed. Otherwise, the 388 message is not compressed. The handle protocol uses the same 389 compression method as used by the FTP protocol[8]. 391 Bit 1 is the EC (EnCrypted) flag that indicates whether the message 392 (excluding the Message Envelope) is encrypted. The EC bit should 393 only be set under an established session where a session key is in 394 place. If the EC bit is set (to 1), the message is encrypted using 395 the session key. Otherwise the message is not encrypted. 397 Bit 2 is the TC (TrunCated) flag that indicates whether this is a 398 truncated message. Message truncation happens most often when 399 transmitting a large message over the UDP protocol. Details of 400 message truncation (or fragmentation) will be discussed in section 401 2.3. 403 Bits 3 to 15 are currently reserved and must be set to zero. 405 2.2.1.3 407 The is a four-byte unsigned integer that identifies a 408 communication session between the client and server. 410 Session and its are assigned by a server either upon an 411 explicit request from a client or when multiple message exchanges 412 are expected to fulfill the client's request. For example, the 413 server will assign a unique in its response if it has 414 to authenticate the client. A client may explicitly ask the server 415 to set up a session as a virtually private communication channel 416 like SSL [4]. Requests from clients without an established session 417 must have their set to zero. The server must assign a 418 unique non-zero for each new session. It is also 419 responsible for terminating those sessions that are not in use 420 after some period of time. 422 Both clients and servers must maintain the same for 423 messages exchanged under an established session. A message whose 424 is zero indicates that no session has been established. 426 The session and its state information may be shared among multiple 427 handle operations. They may also be shared over multiple TCP 428 connections as well. Once a session is established, both client and 429 server must maintain their state information according to the 430 . The state information may include the stage of the 431 conversation, the other party's authentication information, and the 432 session key that was established for message encryption or 433 authentication. Details of these are discussed in section 3.8. 435 2.2.1.4 437 Each request from a client is identified by a , a 4-byte 438 unsigned integer set by the client. Each must be unique 439 from all other outstanding requests from the same client. The 440 allows the client to keep track of its requests, and 441 any response from the server must include the correct . 443 2.2.1.5 445 Messages under the handle protocol may be truncated during their 446 transmission (e.g. under UDP). The is a 4-byte 447 unsigned integer used as a counter to keep track of each truncated 448 portion of the original message. The message recipient can 449 reassemble the original message based on the . The 450 must start with 0 for each message. Each truncated 451 message must set its TC flag in the Message Envelope. Messages that 452 are not truncated must set their to zero. 454 2.2.1.6 456 A 4-byte unsigned integer that specifies the total number of octets 457 of any message, excluding those in the Message Envelope. The length 458 of any single message exchanged under the handle protocol is 459 limited by the range of a 4-byte unsigned integer. Longer data can 460 be transmitted as multiple messages with a common . 462 2.2.2 Message Header 464 The Message Header contains the common data elements among any 465 protocol operation. It has a fixed size of 24 octets and consists 466 of eight fields. 468 0 1 2 3 469 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 470 .---------------------------------------------------------------. 471 | OpCode | 472 |---------------------------------------------------------------| 473 | ResponseCode | 474 |---------------------------------------------------------------| 475 | OpFlag | 476 |---------------------------------------------------------------| 477 | SiteInfoSerialNumber | RecursionCount| | 478 |---------------------------------------------------------------| 479 | ExpirationTime | 480 |---------------------------------------------------------------| 481 | BodyLength | 482 '---------------------------------------------------------------' 484 Every message that is not truncated must have a Message Header. If 485 a message has to be truncated for its transmission, the Message 486 Header must appear in the first truncated portion of the message. 488 This is different from the Message Envelope, which appears in each 489 truncated portion of the message. 491 2.2.2.1 493 The stands for operation code, which is a four-byte 494 unsigned integer that specifies the intended operation. The 495 following table lists the s that MUST be supported by all 496 implementations in order to conform to the base protocol 497 specification. Each operation code is given a symbolic name that is 498 used throughout this document for easy reference. 500 Op_Code Symbolic Name Remark 501 --------- ------------- ------ 503 0 OC_RESERVED Reserved 504 1 OC_RESOLUTION Handle query 505 2 OC_GET_SITEINFO Get HS_SITE values 507 100 OC_CREATE_HANDLE Create new handle 508 101 OC_DELETE_HANDLE Delete existing handle 509 102 OC_ADD_VALUE Add handle value(s) 510 103 OC_REMOVE_VALUE Remove handle value(s) 511 104 OC_MODIFY_VALUE Modify handle value(s) 512 105 OC_LIST_HANDLE List handles 513 106 OC_LIST_NA List sub-naming authorities 515 200 OC_CHALLENGE_RESPONSE Response to challenge 516 201 OC_VERIFY_RESPONSE Verify challenge response 518 300 519 : { Reserved for handle server administration } 520 399 522 400 OC_SESSION_SETUP Session setup request 523 401 OC_SESSION_TERMINATE Session termination request 524 402 OC_SESSION_EXCHANGEKEY Session key exchange 526 A detailed description of each of these s can be found in 527 section 3 of this document. In general, clients use the to 528 tell the server what kind of handle operation they want to 529 accomplish. Response from the server must maintain the same 530 as the original request and use the to 531 indicate the result. 533 2.2.2.2. 535 The is a 4-byte unsigned integer that is given by a 536 server to indicate the result of any service request. The list of 537 s used in the handle protocol is defined in the 538 following table. Each response code is given a symbolic name that 539 is used throughout this document for easy reference. 541 Res. Code Symbolic Name Remark 542 --------- ------------- ------ 544 0 RC_RESERVED Reserved for request 545 1 RC_SUCCESS Success response 546 2 RC_ERROR General error 547 3 RC_SERVER_BUSY Server too busy to respond 548 4 RC_PROTOCOL_ERROR Corrupted or 549 unrecognizable message 550 5 RC_OPERATION_DENIED Unsupported operation 551 6 RC_RECUR_LIMIT_EXCEEDED Too many recursions for 552 the request 554 100 RC_HANDLE_NOT_FOUND Handle not found 555 101 RC_HANDLE_ALREADY_EXIST Handle already exists 556 102 RC_INVALID_HANDLE Encoding (or syntax) error 558 200 RC_VALUE_NOT_FOUND Value not found 559 201 RC_VALUE_ALREADY_EXIST Value already exists 560 202 RC_VALUE_INVALID Invalid handle value 562 300 RC_EXPIRED_SITE_INFO SITE_INFO out of date 563 301 RC_SERVER_NOT_RESP Server not responsible 564 302 RC_SERVICE_REFERRAL Server referral 565 303 RC_NA_DELEGATE Naming authority delegation 566 takes place. 568 400 RC_NOT_AUTHORIZED Not authorized/permitted 569 401 RC_ACCESS_DENIED No access to data 570 402 RC_AUTHEN_NEEDED Authentication required 571 403 RC_AUTHEN_FAILED Failed to authenticate 572 404 RC_INVALID_CREDENTIAL Invalid credential 573 405 RC_AUTHEN_TIMEOUT Authentication timed out 574 406 RC_UNABLE_TO_AUTHEN Unable to authenticate 576 500 RC_SESSION_TIMEOUT Session expired 577 501 RC_SESSION_FAILED Unable to establish session 578 502 RC_NO_SESSION_KEY No session yet available 579 503 RC_SESSION_NO_SUPPORT Session not supported 580 504 RC_SESSION_KEY_INVALID Invalid session key 582 900 RC_TRYING Request under processing 583 901 RC_FORWARDED Request forwarded to 584 another server 586 902 RC_QUEUED Request queued for later 587 processing 589 Response codes under 10000 are reserved for system use. Any message 590 with a response code under 10000 but not listed above should be 591 treated as an unknown error. Response codes above 10000 are user 592 defined and can be used for application specific purposes. 594 Detailed descriptions of these s can be found in 595 section 3 of this document. In general, any request from client 596 must have its set to 0. The response message from 597 the server must have a non-zero to indicate the 598 result. For example, a response message from a server with 599 set to RC_SUCCESS indicates that the server has 600 successfully fulfilled the client's request. 602 2.2.2.3. 604 The is a 32-bit bit-mask that defines various control 605 options for protocol operation. The following figure shows the 606 location of each option flag in the field. 608 1 1 1 1 1 1 609 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 610 .---------------------------------------------------------------. 611 |AT |CT |ENC|REC|CA |CN |KC |PO |RD | Reserved | 612 |---------------------------------------------------------------| 613 | Reserved | 614 '---------------------------------------------------------------' 616 AT - AuThoritative bit. A request with the AT bit set (to 1) 617 indicates that the request should be directed to the 618 primary service site (instead of any mirroring sites). A 619 response message with the AT bit set (to 1) indicates 620 that the message is returned from a primary server 621 (within the primary service site). 623 CT - CerTified bit. A request with the CT bit set (to 1) asks 624 the server to sign its response with its digital 625 signature. A response with the CT bit set (to 1) 626 indicates that the message is signed. The server must 627 sign its response if the request has its CT bit set (to 628 1). If the server fails to provide valid signature in 629 its response, the client should discard the response and 630 treat the request as failed. 632 ENC - ENCryption bit. A request with the ENC bit set (to 1) 633 requires the server to encrypt its response using the 634 pre-established session key. 636 REC - RECursive bit. A request with the REC bit set (to 1) 637 asks the server to forward the query on behalf of the 638 client if the request has to be processed by another 639 handle server. The server may honor the request by 640 forwarding the request to the appropriate handle server 641 and passing on any result back to the client. The server 642 may also deny any such request by sending a response 643 with set to RC_SERVER_NOT_RESP. 645 CA - Cache Authentication. A request with the CA bit set (to 646 1) asks the caching server (if any) to authenticate any 647 server response (e.g., verifying the server's signature) 648 on behalf of the client. A response with the CA bit set 649 (to 1) indicates that the response has been 650 authenticated by the caching server. 652 CN - ContiNuous bit. A message with the CN bit set (to 1) 653 tells the message recipient that more messages that are 654 part of the same request (or response) will follow. This 655 happens if a request (or response) has data that is too 656 large to fit into any single message and has to be 657 fragmented into multiple messages. 659 KC - Keep Connection bit. A message with the KC bit set 660 requires the message recipient to keep the TCP 661 connection open (after the response is sent back). This 662 allows the same TCP connection to be used for multiple 663 handle operations. 665 PO - Public Only bit. Used by query operations only. A query 666 request with the PO bit set (to 1) indicates that the 667 client is only asking for handle values that have the 668 PUB_READ permission. A request with PO bit set to zero 669 asks for all the handle values regardless of their read 670 permission. If any of the handle values require 671 ADMIN_READ permission, the server must authenticate the 672 client as the handle administrator. 674 RD - Request-Digest bit. A request with the RD bit set (to 1) 675 asks the server to include in its response the message 676 digest of the request. A response message with the RD 677 bit set (to 1) indicates that the first field in the 678 Message Body contains the message digest of the original 679 request. The message digest can be used to check the 680 integrity of the server response. Details of these are 681 discussed later in this document. 683 All other bits in the field are reserved and must be set 684 to zero. 686 In general, servers must honor the specified in the 687 request. If a requested option cannot be met, the server should 688 return an error message with the proper as defined 689 in the previous section. 691 2.2.2.4. 693 The is a two-byte unsigned integer. The 694 in a request refers to the of 695 the HS_SITE value used by the client (to access the server). 696 Servers can check the in the request to find 697 out if the client has up-to-date service information. 699 When possible, the server should fulfill a client's request even if 700 the service information used by the client is out-of-date. However, 701 the response message should specify the latest version of service 702 information in the field. Clients with out- 703 of-date service information can update the service information from 704 the Global Handle Registry. If the server cannot fulfill a client's 705 request due to expired service information, it should reject the 706 request and return an error message with set to 707 RC_EXPIRED_SITE_INFO. 709 2.2.2.5. 711 The is a one-byte unsigned integer that specifies 712 the number of service recursions. Service recursion happens if the 713 server has to forward the client's request to another server. Any 714 request directly from the client must have its set 715 to 0. If the server has to send a recursive request on behalf of 716 the client, it must increment the by 1. Any 717 response from the server must maintain the same as 718 the one in the request. To prevent an infinite loop of service 719 recursion, the server should be configurable to stop sending a 720 recursive request when the reaches a certain 721 value. 723 2.2.2.6. 725 The is a 4-byte unsigned integer that specifies 726 the time when the message should be considered expired, relative to 727 January 1st, 1970 GMT, in seconds. It is set to zero if no 728 expiration is expected. 730 2.2.2.7. 731 The is a 4-byte unsigned integer that specifies the 732 number of octets in the Message Body. The does not 733 count the octets in the Message Header or those in the Message 734 Credential. 736 2.2.3 Message Body 738 The Message Body always follows the Message Header. The number of 739 octets in the Message Body can be determined from the 740 in the Message Header. The Message Body may be empty. The exact 741 format of the Message Body depends on the and the 742 in the Message Header. Details of the Message Body 743 under each and are described in section 3 744 of this document. 746 For any response message, if the Message Header has its RD bit (in 747 ) set to 1, the Message Body must begin with the message 748 digest of the original request. The message digest is defined as 749 follows: 751 ::= 752 754 where 756 757 An octet that identifies the algorithm used to generate the 758 message digest. If the octet is set to 1, the digest is 759 generated using the MD5 [9] algorithm. If the octet is set to 760 2, SHA-1 [10] algorithm is used. 762 763 The message digest itself. It is calculated upon the Message 764 Header and the Message Body of the original request. The 765 length of the field is fixed according to the digest 766 algorithm. For MD5 algorithm, the length is 16 octets. For 767 SHA-1, the length is 20 octets. 769 The Message Body may be truncated into multiple portions during its 770 transmission (e.g. over UDP). Recipient of such message may 771 reassemble the Message Body from each portion based on the 772 in the Message Envelop. 774 2.2.4 Message Credential 776 The Message Credential is primarily used to carry any digital 777 signatures signed by the message issuer. It may also carry the 778 Message Authentication Code (MAC) if a session key has been 779 established. The Message Credential is used to protect contents in 780 the Message Header and the Message Body from being tampered with 781 during the transmission. The format of the Message Credential is 782 designed to be semantically compatible with PKCS#7 [5]. Each 783 Message Credential consists of the following fields: 785 0 1 2 3 786 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 787 .---------------------------------------------------------------. 788 | CredentialLength | 789 |---------------------------------------------------------------| 790 | Version | Reserved | Options | 791 |---------------------------------------------------------------| 792 | 793 | Signer: 794 | 795 |---------------------------------------------------------------| 796 | Type (UTF8-String) | 797 |---------------------------------------------------------------| 798 | 799 | SignedInfo: : 4-byte unsigned integer 800 | DigestAlgorithm: 801 | SignedData: 802 | 803 '---------------------------------------------------------------' 805 where 807 808 A 4-byte unsigned integer that specifies the number of octets in 809 the Message Credential. It must be set to zero if the message has 810 no Message Credential. 812 813 An octet that identifies the version number of the Message 814 Credential. The version number specified in this document is 815 zero. 817 818 An octet that must be set to zero. 820 821 Two octets reserved for various cryptography options. 823 ::= 824 825 A reference to a handle value in terms of the and the 826 of the handle value. The handle value may contain the 827 public key, or the X.509 certificate, that can be used to 828 validate the digital signature. 830 831 A UTF8-String that indicates the type of the content in the 832 field (described below). It may contain HS_DIGEST if 833 contains the message digest, or HS_MAC if 834 contains the Message Authentication Code (MAC). The 835 field will specify the signature algorithm identifier if 836 contains a digital signature. For example, with the 837 field set to HS_SIGNED_PSS, the field will 838 contain the digital signature generated using the RSA-PSS 839 algorithm [16]. If the field is set to HS_SIGNED, the 840 field will contain the digital signature generated 841 from a DSA public key pair. 843 ::= 844 845 846 where 848 849 A 4-byte unsigned integer that specifies the number of octets 850 in the field. 852 853 A UTF8-String that refers to the digest algorithm used to 854 generate the digital signature. For example, the value "SHA- 855 1" indicates that SHA-1 algorithm is used to generate the 856 message digest for the signature. 858 ::= 859 860 where 862 863 A 4-byte unsigned integer that specifies the number of 864 octets in the . 866 867 Contains the digital signature or the MAC over the 868 Message Header and Message Body. The syntax and semantics 869 of the signature depend on the field and the 870 public key referenced in the field. For example, 871 if the field is "HS_SIGNED" and the public key 872 referred to by the field is a DSA [6] public 873 key, the signature will be the ASN.1 octet string 874 representation of the parameter R and S as described in 875 [7]. If the field refers to a handle value 876 that contains a X.509 certificate, the signature should 877 be encoded according to RFC3279 and RFC3280 [14, 15]. 879 Message Credential may contain the message authentication code 880 (MAC) generated using a pre-established session key. In this case, 881 the field must set its to a zero-length UTF8- 882 String and its to the specified in the Message 883 Envelope. The field must contain the MAC in its 884 field. The MAC is the result of the one-way hash over 885 the concatenation of the session key, the , the 886 , and the session key again. 888 The Message Credential in a response message may contain the 889 digital signature signed by the server. The server's public key can 890 be found in the service information used by the client to send the 891 request to the server. In this case, the client should ignore any 892 reference in the field and use the public key in the 893 service information to verify the signature. 895 Message Credential can also be used for non-repudiation purpose. 896 This happens if the Message Credential contains server's digital 897 signature. The signature may be used as an evidence to demonstrate 898 that the server has rendered its service in response to client's 899 request. 901 Message Credential provides a mechanism for safe transmission of 902 any message between the client and server. Any message whose 903 Message Header and Message Body complies with its Message 904 Credential suggests that the message indeed comes from its 905 originator. It also assures that the message has not been tampered 906 with during its transmission. 908 2.3 Message Transmission 910 A large message may be truncated into multiple packets during its 911 transmission. For example, to fit the size limit of a UDP packet, 912 the message issuer must truncate any large message into multiple 913 UDP packets before its transmission. The message recipient must 914 reassemble the message from these truncated packets before further 915 processing. Message truncation must be carried out over the entire 916 message except the Message Envelope. A new Message Envelope has to 917 be inserted in front of each truncated packet before its 918 transmission. For example, a large message that consists of 920 .--------------------------------------------------------. 921 | Message Envelope | Message Header, Body, Credential | 922 '--------------------------------------------------------' 924 may be truncated into: 926 .--------------------------------------------. 928 | Message Envelope 1 | Truncated_Packet 1 | 929 '--------------------------------------------' 930 .--------------------------------------------. 931 | Message Envelope 2 | Truncated_Packet 2 | 932 '--------------------------------------------' 934 ...... 936 .--------------------------------------------. 937 | Message Envelope N | Truncated Packet N | 938 '--------------------------------------------' 940 where the "Truncated_packet 1", "Truncated_packet 2", ..., and 941 "Truncated_packet N" result from truncating the Message Header, the 942 Message Body and the Message Credential. Each "Message Envelope i" 943 (inserted before each truncation) must set its TC flag to 1 and 944 maintain the proper sequence count (in the ). Each 945 "Message Envelope i" must also set its to reflect 946 the size of the packet. The recipient of these truncated packets 947 can reassemble the message by concatenating these packets based on 948 their . 950 3. Handle Protocol Operations 952 This section describes the details of each protocol operation in 953 terms of messages exchanged between the client and server. It also 954 defines the format of the Message Body according to each 955 and in the Message Header. 957 3.1 Client Bootstrapping 959 3.1.1 Global Handle Registry and its Service Information 961 The service information for the Global Handle Registry (GHR) allows 962 clients to contact the GHR to find out the responsible service 963 components for their handles. The service information is a set of 964 HS_SITE values assigned to the root handle "0.NA/0.NA" and is also 965 called the root service information. The root service information 966 may be distributed along with the client software, or be downloaded 967 from the Handle System website at http://www.handle.net. 969 Changes to the root service information are identified by the 970 in the HS_SITE values. A server at GHR can find out 971 if the root service information used by the client is outdated by 972 checking the in the client's request. The client 973 should update the root service information if the of 974 the response message is RC_EXPIRED_SITE_INFO. Clients may obtain 975 the most up-to-date root service information from the root handle. 976 The GHR must sign the root service information using the public key 977 specified in the outdated service information (identified in the 978 client's request) so that the client can validate the signature. 980 3.1.2 Locating the Handle System Service Component 982 Each handle under the Handle System is managed by a unique handle 983 service component (e.g. LHS). For any given handle, the responsible 984 service component (and its service information) can be found from 985 its naming authority handle. Before resolving any given handle, the 986 client needs to find the responsible service component by querying 987 the naming authority handle from the GHR. 989 For example, to find the responsible LHS for the handle "1000/abc", 990 client software can query the GHR for the HS_SITE (or HS_SERV) 991 values assigned to the naming authority handle "0.NA/1000". The set 992 of HS_SITE values provides the service information of the LHS that 993 manages every handle under the naming authority "1000". If no 994 HS_SITE values are found, the client can check if there is any 995 HS_SERV value assigned to the naming authority handle. The HS_SERV 996 value provides the service handle that maintains the service 997 information for the LHS. Service handles are used to manage the 998 service information shared by different naming authorities. 1000 It is possible that the naming authority handle requested by the 1001 client does not reside at the GHR. This happens when naming 1002 authority delegation takes place. Naming authority delegation 1003 happens when a naming authority delegates a LHS to manage all its 1004 child naming authorities. In this case, the delegating naming 1005 authority must contain the service information, a set of 1006 HS_NA_DELEGATE values, of the LHS that manages its child naming 1007 authorities. 1009 All top-level naming authority handles must be registered and 1010 managed by the GHR. When a server at the GHR receives a request for 1011 a naming authority that has been delegated to a LHS, it must return 1012 a message with the set to RC_NA_DELEGATE, along with 1013 the HS_NA_DELAGATE values from the nearest ancestor naming 1014 authority. The client can query the LHS described by the 1015 HS_NA_DELAGATE values for the delegated naming authority handle. In 1016 practice, the ancestor naming authority should make itself 1017 available to any handle server within the GHR, by replicating 1018 itself at the time of delegation. This will prevent any cross- 1019 queries among handle servers (within a service site) when the 1020 naming authority in query and the ancestor naming authority doesn't 1021 hash into the same handle server. 1023 3.1.3 Selecting the Responsible Server 1024 Each handle service component is defined in terms of a set of 1025 HS_SITE values. Each of these HS_SITE values defines a service site 1026 within the service component. A service site may consist of a group 1027 of handle servers. For any given handle, the responsible handle 1028 server within the service component can be found following this 1029 procedure: 1031 1. Select a preferred service site. 1033 Each service site is defined in terms of an HS_SITE value. 1034 The HS_SITE value may contain a or other 1035 attributes (under the ) to help the 1036 selection. Clients must select the primary service site 1037 for any administrative operations. 1039 2. Locate the responsible server within the service site. 1041 This can be done as follows: Convert every ASCII character 1042 in the handle to its upper case. Calculate the MD5 hash of 1043 the converted handle string according to the 1044 given in the HS_SITE value. Take the last 4 bytes of the 1045 hash result as a signed integer. Modulo the absolute value 1046 of the integer by the given in the HS_SITE 1047 value. The result is the sequence number of the 1048 listed in the HS_SITE value. For example, 1049 if the result of the modulation is 2, the third 1050 listed in the should be selected. 1051 The defines the responsible handle server 1052 for the given handle. 1054 3.2 Query Operation 1056 A query operation consists of a client sending a query request to 1057 the responsible handle server and the server returning the query 1058 result to the client. Query requests are used to retrieve handle 1059 values assigned to any given handle. 1061 3.2.1 Query Request 1063 The Message Header of any query request must set its to 1064 OC_RESOLUTION (defined in section 2.2.2.1) and to 0. 1066 The Message Body for any query request is defined as follows: 1068 ::= 1069 1070 1072 where 1073 1074 A UTF8-String (as defined in section 2.1.4) that specifies 1075 the handle to be resolved. 1077 1078 A 4-byte unsigned integer followed by an array of 4-byte 1079 unsigned integers. The first integer indicates the number of 1080 integers in the integer array. Each number in the integer 1081 array is a handle value index and refers to a handle value to 1082 be retrieved. The client sets the first integer to zero 1083 (followed by an empty array) to ask for all the handle values 1084 regardless of their index. 1086 1087 A 4-byte unsigned integer followed by a list of UTF8-Strings. 1088 The first integer indicates the number of UTF8-Strings in the 1089 list that follows. Each UTF8-String in the list specifies a 1090 data type. This tells the server to return all handle values 1091 whose data type is listed in the list. If an UTF8-String ends 1092 with the '.' (0x2E) character, the server must return all 1093 handle values whose data type is under the type hierarchy 1094 specified in the UTF8-String. The may contain no 1095 UTF8-String if the first integer is 0. In this case, the 1096 server must return all handle values regardless of their data 1097 type. 1099 If a query request does not specify any index or data type and the 1100 PO flag (in the Message Header) is set, the server will return all 1101 the handle values that have the PUBLIC_READ permission. Clients can 1102 also send queries without the PO flag set. In this case, the server 1103 will return all the handle values with PUBLIC_READ permission and 1104 all the handle values with ADMIN_READ permission. If the query 1105 requests a specific handle value via the value index and the value 1106 does not have PUBLIC_READ permission, the server should accept the 1107 request (and authenticate the client) even if the request has its 1108 PO flag set. 1110 If a query consists of a non-empty but an empty 1111 , the server should only return those handle values whose 1112 indexes are listed in the . Likewise, if a query 1113 consists of non-empty but an empty , the 1114 server should only return those handle values whose data types are 1115 listed in the . 1117 When both and fields are non-empty, the 1118 server should return all handle values whose indexes are listed in 1119 the AND all handle values whose data types are listed 1120 in the . 1122 3.2.2 Successful Query Response 1124 The Message Header of any query response must set its to 1125 OC_RESOLUTION. Successful query response must set its 1126 to RC_SUCCESS. 1128 The message body of the successful query response is defined as 1129 follows: 1131 ::= [] 1132 1133 1135 where 1137 1138 Optional field as defined in section 2.2.3. 1140 1141 A UTF8-String that specifies the handle queried by the 1142 client. 1144 1145 A 4-byte unsigned integer followed by a list of handle 1146 values. The integer specifies the number of handle values in 1147 the list. The encoding of each handle value follows the 1148 specification given in [2] (see section 3.1). The integer is 1149 set to zero if there is no handle value that satisfies the 1150 query. 1152 3.2.3 Unsuccessful Query Response 1154 If a server cannot fulfill a client's request, it must return an 1155 error message. The general format for any error message from the 1156 server is specified in section 3.3 of this document. 1158 For example, a server must return an error message if the queried 1159 handle does not exist in its database. The error message will have 1160 an empty message body and have its set to 1161 RC_HANDLE_NOT_FOUND. 1163 Note that a server should NOT return an RC_HANDLE_NOT_FOUND message 1164 if the server is not responsible for the handle being queried for. 1165 It is possible that the queried handle exists but is managed by 1166 another handle server (under some other handle service). When this 1167 happens, the server should either send a service referral (see 1168 section 3.4) or simply return an error message with 1169 set to RC_SERVER_NOT_RESP. 1171 The server may return an error message with set to 1172 RC_SERVER_BUSY if the server is too busy to process the request. 1173 Like RC_HANDLE_NOT_FOUND, an RC_SERVER_BUSY message also has an 1174 empty message body. 1176 Servers should return an RC_ACCESS_DENIED message if the request 1177 asks for a specific handle value (via the handle value index) that 1178 has neither PUBLIC_READ nor ADMIN_READ permission. 1180 A handle Server may ask its client to authenticate itself as the 1181 handle administrator during the resolution. This happens if any 1182 handle value in query has ADMIN_READ permission, but no PUBLIC_READ 1183 permission. Details of client authentication are described later in 1184 this document. 1186 3.3 Error Response from Server 1188 A handle server will return an error message if it encounters an 1189 error when processing a request. Any error response from the server 1190 must maintain the same (in the message header) as the one 1191 in the original request. Each error condition is identified by a 1192 unique as defined in section 2.2.2.2 of this 1193 document. 1195 The Message Body of an error message may be empty. Otherwise it 1196 consists of the following data fields (unless otherwise specified): 1198 ::= [] 1199 1200 [ ] 1202 where 1204 1205 Optional field as defined in section 2.2.3. 1207 1208 A UTF8-String that explains the error. 1210 1211 An optional field. When not empty, it consists of a 4-byte 1212 unsigned integer followed by a list of handle value indexes. 1213 The first integer indicates the number of indexes in the list. 1214 Each index in the list is a 4-byte unsigned integer that 1215 refers to a handle value that contributed to the error. An 1216 example would be a server that is asked to add three handle 1217 values with indexes 1, 2, and 3, and handle values with 1218 indexes 1 and 2 already exist. In this case the server could 1219 return an error message with set to 1220 RC_VALUE_ALREADY_EXIST and add index 1 and 2 to the 1221 . Note that the server is not obligated to return 1222 the complete list of handle value indexes that may have caused 1223 the error. 1225 3.4 Service Referral 1227 A handle server may receive requests for handles that are managed 1228 by some other handle server or service. When this happens, the 1229 server has the option to either return a referral message that 1230 directs the client to the proper handle service, or simply return 1231 an error message with set to RC_SERVER_NOT_RESP. 1232 Service referral also happens when ownership of handles moves from 1233 one handle service to another. It may also be used by any local 1234 handle service to delegate its service into multiple service layers. 1236 The Message Header of a service referral must maintain the same 1237 as the one in the original request and set its 1238 to RC_SERVICE_REFERRAL. 1240 The Message Body of any service referral is defined as follows: 1242 ::= [ ] 1243 1244 [ ] 1246 where 1248 1249 Optional field as defined in section 2.2.3. 1251 1252 A UTF8-String that identifies the handle (e.g. a service 1253 handle) that maintains the referral information (i.e., the 1254 service information of the handle service this refers to). If 1255 the is set to "0.NA/0.NA", it is referring 1256 the client to the GHR. 1258 1259 An optional field that must be empty if the 1260 is provided. When not empty, it consists of a 4-byte unsigned 1261 integer followed by a list of HS_SITE values. The integer 1262 specifies the number of HS_SITE values in the list. 1264 Unlike regular query responses that may consist of handle values of 1265 any data type, a service referral can only have zero or more 1266 HS_SITE values in its . The may contain 1267 an empty UTF8-String if the HS_SITE values in the are 1268 not maintained by any handle. 1270 Care must be taken by clients to avoid any loops caused by service 1271 referrals. It is also the client's responsibility to authenticate 1272 the service information obtained from the service referral. A 1273 client should always use its own copy of the GHR service 1274 information if the is set to "0.NA/0.NA". 1276 3.5 Client Authentication 1278 Clients are asked to authenticate themselves as handle 1279 administrators when querying for any handle value with ADMIN_READ 1280 but no PUBLIC_READ permission. Client authentication is also 1281 required for any handle administration requests that require 1282 administrator privileges. This includes adding, removing, or 1283 modifying handles or handle values. 1285 Client authentication consists of multiple messages exchanged 1286 between the client and server. Such message include the challenge 1287 from the server to the client to authenticate the client, the 1288 challenge-response from the client in response to the server's 1289 challenge, and the verification request and response message if 1290 secret key authentication takes place. Messages exchanged during 1291 the authentication are correlated via a unique assigned 1292 by the server. For each authentication session, the server needs to 1293 maintain the state information that includes the server's challenge, 1294 the challenge-response from the client, as well as the original 1295 client request. 1297 The authentication starts with a response message from the server 1298 that contains a challenge to the client. The client must respond to 1299 the challenge with a challenge-response message. The server 1300 validates the challenge-response either by verifying the digital 1301 signature inside the challenge-response, or by sending a 1302 verification request to another handle server, herein referred to 1303 as the verification server, that maintains the secret key for the 1304 administrator. The purpose of the challenge and the challenge- 1305 response is to prove to the server that the client possesses the 1306 private key (or the secret key) of the handle administrator. If the 1307 authentication fails, an error response will be sent back with the 1308 set to RC_AUTHEN_FAILED. 1310 Upon successful client authentication, the server must also make 1311 sure that the administrator is authorized for the request. If the 1312 administrator has sufficient privileges, the server will process 1313 the request and send back the result. If the administrator does not 1314 have sufficient privileges, the server will return an error message 1315 with set to RC_NOT_AUTHORIZED. 1317 The following sections provides details of each message exchanged 1318 during the authentication process. 1320 3.5.1 Challenge from Server to Client 1322 The Message Header of the CHALLENGE must keep the same as 1323 the original request and set the to RC_AUTH_NEEDED. 1324 The server must assign a non-zero unique in the Message 1325 Envelope to keep track of the authentication. It must also set the 1326 RD flag of the (see section 2.2.2.3) in the Message Header, 1327 regardless of whether the original request had the RD bit set or 1328 not. 1330 The Message Body of the server's CHALLENGE is defined as follows: 1332 ::= 1333 1334 where 1336 1337 Message Digest of the request message, as defined in section 1338 2.2.3. 1340 1341 A 4-byte unsigned integer followed by a random string 1342 generated by the server via a secure random number generator. 1343 The integer specifies the number of octets in the random 1344 string. The size of the random string should be no less than 1345 20 octets. 1347 Note that the server will not sign the challenge if the client did 1348 not request the server to do so. If the client worries about 1349 whether it is speaking to the right server, it may ask the server 1350 to sign the . If the client requested the server to sign 1351 the but failed to validate the server's signature, the 1352 client should discard the server's response and reissue the request 1353 to the server. 1355 3.5.2 Challenge-Response from Client to Server 1357 The Message Header of the CHALLENGE_RESPONSE must set its 1358 to OC_CHALLENGE_RESPONSE and its to 0. It must also 1359 keep the same (in the Message Envelope) as specified in 1360 the challenge from the server. 1362 The Message Body of the CHALLENGE_RESPONSE request is defines as 1363 follows: 1365 ::= 1366 1367 1368 1370 where 1372 1373 A UTF8-String that identifies the type of authentication key 1374 used by the client. For example, the field is set to 1375 "HS_SECKEY" when the client choose to use a secret key for 1376 its authentication. The field is set to "HS_PUBKEY" if a 1377 public key is used instead. 1379 1380 A UTF8-String that identifies the handle that holds the 1381 public or secret key of the handle administrator. 1383 1384 A 4-byte unsigned integer that specifies the index of the 1385 handle value (of the ) that holds the public or 1386 secret key of the administrator. 1388 1389 Contains either the Message Authentication Code (MAC) or the 1390 digital signature over the challenge from the server. If the 1391 is "HS_SECKEY", the 1392 consists of an octet followed by the MAC. The octet 1393 identifies the algorithm used to generate the MAC. For 1394 example, if the first octet is set to 0x01, the MAC is 1395 generated by 1397 MD5_Hash( + + ) 1399 where the is the administrator's secret key 1400 referenced by the and . The 1401 is the Message Body portion of the 1402 server's challenge. If the first octet in the 1403 is set to 0x02, the MAC is generated 1404 using 1406 SHA-1_Hash( + + ) 1408 A more secure approach is to use HMAC [17] for the 1409 . The HMAC can be generated using the 1410 and . A 1411 with its first octet set to 0x11 indicates that the HMAC 1412 is generated using the MD5 algorithm. Likewise, a 1413 with its first octet set to 0x12 1414 inditates that the HMAC is generated using the SHA-1 1415 algorithm. 1417 If the is "HS_PUBKEY", the 1418 contains the digital signature over the 1419 Message Body portion of the server's challenge. The 1420 signature is generated in two steps: First, a one-way hash 1421 value is computed over the blob that is to be signed. 1422 Second, the hash value is signed using the private key. 1423 The signature consists of a UTF8-String that specifies the 1424 digest algorithm used for the signature, followed by the 1425 signature over the server's challenge. The and 1426 refers to the administrator's public key that can 1427 be used to verify the signature. 1429 Handle administrators are defined in terms of HS_ADMIN values 1430 assigned to the handle. Each HS_ADMIN value defines the set of 1431 privileges granted to the administrator. It also provides the 1432 reference to the authentication key that can be used to 1433 authenticate the administrator. The reference can be made directly 1434 if the field of the HS_ADMIN value refers to the handle 1435 value that holds the authentication key. Indirect reference to the 1436 authentication key can also be made via administrator groups. In 1437 this case, the field may refer to a handle value of type 1438 HS_VLIST. An HS_VLIST value defines an administrator group via a 1439 list of handle value references, each of which refers to the 1440 authentication key of a handle administrator. 1442 For handles with multiple HS_ADMIN values, the server will have to 1443 check each of those with sufficient privileges to see if its 1444 field matches the and . If no 1445 match is found, but there are administrator groups defined, the 1446 server must check if the and belong to any 1447 of the administrator groups that have sufficient privileges. An 1448 administrator group may contain another administrator group as a 1449 member. Servers must be careful to avoid infinite loops when 1450 navigating these groups. 1452 If the and are not referenced by any of the 1453 HS_ADMIN values, or the administrator group that has sufficient 1454 privileges, the server will return an error message with 1455 set to RC_NOT_AUTHORIZED. Otherwise, the server will 1456 continue to authenticate the client as follows: 1458 If the is "HS_PUBKEY", the server will 1459 retrieve the administrator's public key based on the 1460 and . The public key can be used to verify the 1461 against the server's . If the 1462 matches the , the server will 1463 continue to process the original request and return the result. 1464 Otherwise, the server will return an error message with 1465 set to RC_AUTHENTICATION_FAILED. 1467 If the is "HS_SECKEY", the server will have to 1468 send a verification request to the verification server; that is, 1469 the handle server that manages the handle referenced by the 1470 . The verification request and its response are defined 1471 in the following sections. The verification server will verify the 1472 against the on behalf of the handle 1473 server. 1475 3.5.3 Challenge-Response Verification-Request 1477 The message header of the VERIFICATION_REQUEST must set its 1478 to OC_VERIFY_CHALLENGE and the to 0. 1480 The message body of the Verification-Request is defined as follows: 1482 ::= 1483 1484 1485 1487 where 1489 1490 A UTF8-String that refers to the handle that holds the 1491 secret key of the administrator. 1493 1494 A 4-byte unsigned integer that is the index of the handle 1495 value that holds the secret key of the administrator. 1497 1498 The message body of the server's challenge, as described in 1499 section 3.5.1. 1501 1502 The from the client in response to 1503 the server's , as defined in section 3.5.2. 1505 Any Challenge-Response Verification-Request must set its CT bit in 1506 the message header. This is to ensure that the verification server 1507 will sign the Verification-Response as specified in the next 1508 section. 1510 3.5.4 Challenge-Response Verification-Response 1512 The Verification-Response tells the requesting handle server 1513 whether the matches the in the 1514 Verification-Request. 1516 The Message Header of the Verification-Response must set its 1517 to RC_SUCCESS whether or not the 1518 matches the . The RD flag in the field should 1519 also be set (to 1) since the will be mandatory in 1520 the Message Body. 1522 The Message Body of the Verification-Response is defined as 1523 follows: 1525 1526 ::= 1527 1528 where 1530 1531 Contains the message digest of the Verification-Request. 1533 1534 An octet that is set to 1 if the 1535 matches the . Otherwise it must be set to 1536 0. 1538 The verification server may return an error with set 1539 to RC_AUTHEN_FAILED if it cannot perform the verification (e.g., 1540 the does not exist, or the and 1541 refer to an invalid handle value). When this happens, the server 1542 that performs the client authentication should relay the same error 1543 message back to the client. 1545 3.6 Handle Administration 1547 The handle system protocol supports a set of handle administration 1548 functions that include adding, deleting, and modifying handles or 1549 handle values. Before fulfilling any administration request, the 1550 server must authenticate the client as the handle administrator 1551 that is authorized for the administrative operation. Handle 1552 administration can only be carried out by the primary handle 1553 server. 1555 3.6.1 Add Handle Value(s) 1557 Clients add values to existing handles by sending ADD_VALUE 1558 requests to the responsible handle server. The Message Header of 1559 the ADD_VALUE request must set its to OC_ADD_VALUE. 1561 The Message Body of the ADD_VALUE request is encoded as follows: 1563 ::= 1564 1566 where 1568 1569 A UTF8-String that specifies the handle. 1571 1572 A 4-byte unsigned integer followed by a list of handle values. 1573 The integer indicates the number of handle values in the list. 1575 The server that receives the ADD_VALUE request must first 1576 authenticate the client as the administrator with the ADD_VALUE 1577 privilege. Upon successful authentication, the server will proceed 1578 to add each value in the to the . If successful, 1579 the server will return an RC_SUCCESS message to the client. 1581 Each ADD_VALUE request must be carried out as a transaction. If 1582 adding any value in the raises an error, the entire 1583 operation must be rolled back. For any failed ADD_VALUE request, 1584 none of the values in the should be added to the 1585 . The server must also send a response to the client that 1586 explains the error. For example, if a value in the has 1587 the same index as one of the existing handle values, the server 1588 will return an error message that has the set to 1589 RC_VALUE_ALREADY_EXISTS. 1591 ADD_VALUE requests can also be used to add handle administrators. 1592 This happens if the in the ADD_VALUE request contains 1593 any HS_ADMIN values. The server must authenticate the client as an 1594 administrator with the ADD_ADMIN privilege before fulfilling such 1595 requests. 1597 An ADD_VALUE request will result in an error if the requested 1598 handle does not exist. When this happens, the server will return an 1599 error message with set to RC_HANDLE_NOT_EXIST. 1601 3.6.2 Remove Handle Value(s) 1602 Clients remove existing handle values by sending REMOVE_VALUE 1603 requests to the responsible handle server. The Message Header of 1604 the REMOVE_VALUE request must set its to OC_REMOVE_VALUE. 1606 The Message Body of any REMOVE_VALUE request is encoded as follows: 1608 ::= 1609 1611 where 1613 1614 A UTF8-String that specifies the handle whose value(s) needs 1615 to be removed. 1617 1618 A 4-byte unsigned integer followed by a list of handle value 1619 indexes. Each index refers to a handle value to be removed 1620 from the . The integer specifies the number of 1621 indexes in the list. Each index is also encoded as a 4-byte 1622 unsigned integer. 1624 The server that receives the REMOVE_VALUE request must first 1625 authenticate the client as the administrator with the REMOVE VALUE 1626 privilege. Upon successful authentication, the server will proceed 1627 to remove the handle values specified in the from the 1628 . If successful, the server will return an RC_SUCCESS 1629 message to the client. 1631 Each REMOVE_VALUE request must be carried out as a transaction. If 1632 removing any value specified in the raises an error, 1633 the entire operation must be rolled back. For any failed 1634 REMOVE_VALUE request, none of values referenced in the 1635 should be removed from the . The server must also send a 1636 response to the client that explains the error. For example, 1637 attempts to remove any handle value with neither PUB_WRITE nor 1638 ADMIN_WRITE permission will result in an RC_ACCESS_DENIED error. 1639 Note that a REMOVE_VALUE request asking to remove a non-existing 1640 handle value will not be treated as an error. 1642 REMOVE_VALUE requests can also be used to remove handle 1643 administrators. This happens if any of the indexes in the 1644 refer to an HS_ADMIN value. Servers must authenticate 1645 the client as an administrator with the REMOVE_ADMIN privilege 1646 before fulfilling such requests. 1648 3.6.3 Modify Handle Value(s) 1649 Clients can make modifications to an existing handle value by 1650 sending MODIFY_VALUE requests to the responsible handle server. The 1651 Message Header of the MODIFY_VALUE request must set its to 1652 OC_MODIFY_VALUE. 1654 The Message Body of any MODIFY_VALUE request is defined as follows: 1656 ::= 1657 1659 where 1661 1662 A UTF8-String that specifies the handle whose value(s) needs 1663 to be modified. 1665 1666 A 4-byte unsigned integer followed by a list of handle 1667 values. The integer specifies the number of handle values in 1668 the list. Each value in the specifies a handle 1669 value that will replace the existing handle value with 1670 the same index. 1672 The server that receives the MODIFY_VALUE request must first 1673 authenticate the client as an administrator with the MODIFY_VALUE 1674 privilege. Upon successful authentication, the server will proceed 1675 to replace those handle values listed in the , provided 1676 each handle value has PUB_WRITE or ADMIN_WRITE permission. If 1677 successful, the server must notify the client with an RC_SUCCESS 1678 message. 1680 Each MODIFY_VALUE request must be carried out as a transaction. If 1681 replacing any value listed in the raises an error, the 1682 entire operation must be rolled back. For any failed MODIFY_VALUE 1683 request, none of values in the should be replaced. The 1684 server must also return a response to the client that explains the 1685 error. For example, if a MODIFY_VALUE request asks to remove a 1686 handle value that has neither PUB_WRITE nor ADMIN_WRITE permission, 1687 the server must return an error message with the set 1688 to RC_ACCESS_DENIED. Any MODIFY_VALUE request to replace non- 1689 existing handle values is also treated as an error. In this case, 1690 the server will return an error message with set to 1691 RC_VALUE_NOT_FOUND. 1693 MODIFY_VALUE requests can also be used to update handle 1694 administrators. This happens if both the values in the 1695 and the value to be replaced are HS_ADMIN values. Servers must 1696 authenticate the client as an administrator with the MODIFY_ADMIN 1697 privilege before fulfilling such request. It is an error to replace 1698 a non-HS_ADMIN value with an HS_ADMIN value. In this case, the 1699 server will return an error message with set to 1700 RC_VALUE_INVALID. 1702 3.6.4 Create Handle 1704 Clients can create new handles by sending CREATE_HANDLE requests to 1705 the responsible handle server. The Message Header of any 1706 CREATE_HANDLE request must set its to OC_CREATE_HANDLE. 1708 The Message Body of any CREATE_HANDLE request is defined as 1709 follows: 1711 ::= 1712 1714 where 1716 1717 A UTF8-String that specifies the handle. 1719 1720 A 4-byte unsigned integer followed by a list of handle 1721 values. The integer indicates the number of handle values in 1722 the list. The should at least include one 1723 HS_ADMIN value that defines the handle administrator. 1725 Only naming authority administrators with the CREATE_HANDLE 1726 privilege are allowed to create new handles under the naming 1727 authority. The server that receives a CREATE_HANDLE request must 1728 authenticate the client as the administrator of the corresponding 1729 naming authority handle and make certain that the administrator is 1730 authorized to create handles under the naming authority. This is 1731 different from the ADD_VALUE request where the server authenticates 1732 the client as an administrator of the handle. Upon successful 1733 authentication, the server will proceed to create the new handle 1734 and add each value in the to the new . If 1735 successful, the server will return an RC_SUCCESS message to the 1736 client. 1738 Each CREATE_HANDLE request must be carried out as a transaction. If 1739 any part of the CREATE_HANDLE process fails, the entire operation 1740 can be rolled back. For example, if the server fails to add values 1741 in the to the new handle, it must return an error 1742 message without creating the new handle. Any CREATE_HANDLE request 1743 that asks to create a handle that already exists will be treated as 1744 an error. In this case, the server will return an error message 1745 with the set to RC_HANDLE_ALREADY_EXIST. 1747 CREATE_HANDLE requests can also be used to create naming 1748 authorities. Naming authorities are created as naming authority 1749 handles at the GHR. Before creating a new naming authority handle, 1750 the server must authenticate the client as the administrator of the 1751 parent naming authority. Only administrators with the CREATE_NA 1752 privilege are allowed to create any sub-naming authority. Root 1753 level naming authorities may be created by the administrator of the 1754 root handle "0.NA/0.NA". 1756 3.6.5 Delete Handle 1758 Clients delete existing handles by sending DELETE_HANDLE requests 1759 to the responsible handle server. The Message Header of the 1760 DELETE_HANDLE request must set its to OC_DELETE_HANDLE. 1762 The Message Body of any DELETE_HANDLE request is defined as 1763 follows: 1765 ::= 1767 where 1769 1770 A UTF8-String that specifies the handle. 1772 The server that receives the DELETE_HANDLE request must first 1773 authenticate the client as the administrator with the DELETE_HANDLE 1774 privilege. Upon successful authentication, the server will proceed 1775 to delete the handle along with any handle values assigned to the 1776 handle. If successful, the server will return an RC_SUCCESS message 1777 to the client. 1779 Each DELETE_HANDLE request must be carried out as a transaction. If 1780 any part of the DELETE_HANDLE process fails, the entire operation 1781 must be rolled back. For example, if the server fails to remove any 1782 handle values assigned to the handle (before deleting the handle), 1783 it must return an error message without deleting the handle. This 1784 may happen if the handle contains a value that has neither 1785 PUB_WRITE nor ADMIN_WRITE permission. In this case, the server will 1786 return an error message with the set to 1787 RC_PERMISSION_DENIED. A DELETE_HANDLE request that asks to delete a 1788 non-existing handle will also be treated as an error. The server 1789 will return an error message with the set to 1790 RC_HANDLE_NOT_EXIST. 1792 DELETE_HANDLE requests can also be used to delete naming 1793 authorities. This is achieved by deleting the corresponding naming 1794 authority handle on the GHR. Before deleting a naming authority 1795 handle, the server must authenticate the client as the 1796 administrator of the naming authority handle. Only administrators 1797 with the DELETE_NA privilege are allowed to delete the naming 1798 authority. Root level naming authorities may be deleted by the 1799 administrator of the root handle "0.NA/0.NA". 1801 3.7 Naming Authority (NA) Administration 1803 The Handle System manages naming authorities via naming authority 1804 handles. Naming authority handles are managed by the GHR. Clients 1805 can change the service information of any naming authority by 1806 changing the HS_SITE values assigned to the corresponding naming 1807 authority handle. Creating or deleting naming authorities is done 1808 by creating or deleting the corresponding naming authority handles. 1809 Root level naming authorities may be created or deleted by the 1810 administrator of the root handle "0.NA/0.NA". Non-root-level naming 1811 authorities may be created by the administrator of its parent 1812 naming authority. 1814 For example, the administrator of the naming authority handle 1815 "0.NA/10" may create the naming authority "10.1000" by sending a 1816 CREATE_HANDLE request to the GHR to create the naming authority 1817 handle "0.NA/10.1000". Before fulfilling the request, the server at 1818 the GHR must authenticate the client as the administrator of the 1819 parent naming authority, that is, the administrator of the naming 1820 authority handle "0.NA/10". The server must also make sure that the 1821 administrator has the NA_CREATE privilege. 1823 The handle protocol also allows clients to list handles or sub- 1824 naming authorities under a naming authority. Details of these 1825 operations are described in the following sections. 1827 3.7.1 List Handle(s) under a Naming Authority 1829 Clients send LIST_HANDLE requests to handle servers to get a list 1830 of handles under a naming authority. The Message Header of the 1831 LIST_HANDLE request must set its to OC_LIST_HANDLE. 1833 The Message Body of any LIST_HANDLE request is defined as follows: 1835 ::= 1837 where 1839 1840 A UTF8-String that specifies the naming authority handle. 1842 To obtain a complete list of the handles, the request must be sent 1843 to every handle server listed in any one of the service sites of 1844 the responsible handle service. Each server within the service site 1845 will return its own list of handles under the naming authority. The 1846 Message Body of a successful LIST_HANDLE response (from each handle 1847 server) is defined as follows: 1849 ::= 1850 1851 where 1853 1854 Number of handles (managed by the handle server) under the 1855 naming authority. 1857 1858 A list of UTF8-Strings, each of which identify a handle under 1859 the naming authority. 1861 The LIST_HANDLE request may potentially slow down the overall 1862 system performance. A handle service (or its service site) has the 1863 option whether or not to support such request. The server will 1864 return an RC_OPERATION_DENIED message if LIST_HANDLE is not 1865 supported. The server that receives a LIST_HANDLE request should 1866 authenticate the client as a naming authority administrator with 1867 the LIST_HANDLE privilege before fulfilling the request. 1869 3.7.2 List Sub-Naming Authorities under a Naming Authority 1871 Clients send LIST_NA requests to handle servers to get a list of 1872 sub-naming authorities under a naming authority. The Message Header 1873 of the LIST_NA request must set its to OC_LIST_NA. 1875 The Message Body of any LIST_NA request is defined as follows: 1877 ::= 1879 where 1881 1882 A UTF8-String that specifies the naming authority handle. 1884 To obtain a complete list of the sub-naming authorities, the 1885 request must be sent to every handle server listed in any one of 1886 the service sites of the GHR. Each server within the service site 1887 will return its own list of sub-naming authority handles under the 1888 given naming authority. The Message Body of a successful LIST_NA 1889 response (from each handle server) is defined as follows: 1891 ::= 1892 1893 where 1894 1895 Number of handles (managed by the handle server) under the 1896 naming authority. 1898 1899 A list of UTF8-Strings, each of which identifies a sub- 1900 naming authority user-specified naming authority. 1902 LIST_NA requests must be sent to servers under the GHR which 1903 manages all the naming authority handles. The LIST_NA request may 1904 potentially slow down the overall system performance, especially 1905 the GHS. A server (or service sites) under the GHR has the option 1906 whether or not to support such requests. The server will return an 1907 RC_OPERATION_DENIED message if LIST_NA is not supported. The server 1908 that receives a LIST_HANDLE request should authenticate the client 1909 as a naming authority administrator with the LIST_NA privilege 1910 before fulfilling the request. 1912 3.8 Session and Session Management 1914 Sessions are used to allow sharing of authentication information or 1915 network resources among multiple protocol operations. For example, 1916 a naming authority administrator may authenticate itself once 1917 through the session setup, and then register multiple handles under 1918 the session. 1920 A client may ask the server to establish a session key and use it 1921 for subsequent requests. A session key is a secret key that is 1922 shared by the client and server. It can be used to authenticate or 1923 encrypt any message exchanged under the session. A session is 1924 encrypted if every message exchanged within the session is 1925 encrypted using the session key. 1927 Sessions may be established as the result of an explicit 1928 OC_SESSION_SETUP request from a client. A server may also setup a 1929 session automatically when multiple message exchanges are expected 1930 to fulfill a request. For example, the server will establish a 1931 session automatically if it receives a CREATE_HANDLE request that 1932 requires client authentication. 1934 Every session is identified by a non-zero Session ID that appears 1935 in the Message Header. Servers are responsible for generating a 1936 unique Session ID for each outstanding session. Each session may 1937 have a set of state information associated with it. The state 1938 information may include the session key, the information obtained 1939 from client authentication, as well as any communication options. 1940 Servers and clients are responsible for keeping the state 1941 information in sync until the session is terminated. 1943 A session may be terminated with an OC_SESSION_TERMINATE request 1944 from the client. Servers may also terminate a session that has been 1945 idle for a significant amount of time. 1947 3.8.1 Session Setup Request 1949 Clients establish a session with a handle server with a 1950 SESSION_SETUP request. A SESSION_SETUP request can also be used to 1951 update any state information associated to an existing session. The 1952 Message Header of the SESSION_SETUP request must have its 1953 set to OC_SESSION_SETUP and to 0. 1955 The Message Body of any SESSION_SETUP request is defined as 1956 follows: 1958 ::= 1960 where 1962 1963 A 4-byte unsigned integer followed by a list of session 1964 attributes. The integer indicates the number of session 1965 attributes in the list. Possible session attributes include 1966 the , the , and the 1967 . Each of these attributes is 1968 defined as follows: 1970 ::= 1971 1972 1973 where 1975 1976 A UTF-8 string constant "HS_SESSION_IDENTITY". 1978 1979 1980 A UTF-8 string followed by a 4-byte unsigned integer 1981 that specifies the handle and the handle value used for 1982 client authentication. It must refer to a handle value 1983 that contains the public key of the client. The public 1984 key is used by the server to authenticate the client. 1986 ::= 1987 1988 where 1990 1991 A UTF-8 string constant "HS_SESSION_KEY_EXCHANGE". 1993 1994 One of the these tuples: , 1995 , or . 1996 Each of these tuples is defined as follows: 1998 ::= 1999 2000 where 2002 2003 A UTF-8 string constant "CLIENT_CIPHER". 2005 2006 A public key provided by the client and used by 2007 the server to encrypt the session key. 2009 ::= 2010 2011 2012 where 2014 2015 A UTF-8 string constant "HDL_CIPHER". 2017 2018 2019 A UTF-8 string followed by a 4-byte unsigned 2020 integer. The and 2021 refers to a handle value used 2022 for session key exchange. The handle value must 2023 contain the public key of the client. The public 2024 key will be used by the server to encrypt the 2025 session key before sending it to the client. 2027 ::= 2029 where 2031 2032 A UTF-8 string constant "SERVER_CIPHER". This 2033 tells the server that the client will be 2034 responsible for generating the session key. The 2035 server will have to provide its public key in the 2036 response message and set the to 2037 RC_SESSION_EXCHANGEKEY. The client can use the 2038 server's public key to encrypt the session key 2039 and send it to the server via a subsequent 2040 SESSION_EXCHANGEKEY request. 2042 ::= 2043 2044 where 2046 2047 A UTF-8 string constant "DIFFIE_HELLMAN" 2049 2050 The values used as input to the Diffie-Hellman 2051 algorithm. It consists of three big integers of 2052 variable length. Each big integer is encoded in 2053 terms of a 4-byte unsigned integer followed by an 2054 octet string. The octet string contains the big 2055 integer itself. The 4-byte unsigned integer 2056 specifies the number of octets of the octet 2057 string. 2059 ::= 2060 2061 where 2063 2064 A UTF-8 string constant "HS_SESSION_TIMEOUT". 2066 2067 A 4-byte unsigned integer that specifies the desired 2068 duration of the session in number of seconds. 2070 Note that it should be treated as an error if the same session 2071 attribute is listed multiple times in the field. 2072 When this happens, the server should return an error message with 2073 set to RC_PROTOCOL_ERROR. 2075 A SESSION_SETUP_REQUEST can be used to change session attributes of 2076 any established session. This happens if the is non- 2077 zero and matches one of the established sessions. Care must be 2078 taken by the server to prevent any unauthorized request from 2079 changing the session attributes. For example, an encrypted session 2080 may only be changed into an unencrypted session by a 2081 SESSION_SETUP_REQUEST with appropriate MAC in its Message 2082 Credential. 2084 3.8.2 Session Setup Response 2086 The Message Header of the SESSION_SETUP response must set its 2087 to OC_SESSION_SETUP. The of the 2088 SESSION_SETUP response varies according to the SESSION_SETUP 2089 request. It must be set to RC_SUCCESS if the SESSION_SETUP request 2090 is successful and the server does not expect a session key to be 2091 returned by the client. 2093 The Message Body of the SESSION_SETUP response is empty unless the 2094 request is asking for . In this case, the 2095 Message Body of the SESSION_SETUP response may contain the 2096 encrypted session key from the server, or the server' public key, 2097 to be used for session key exchange. The exact format depends on 2098 the content of the in the SESSION_SETUP 2099 request. If or 2100 is given in the SESSION_SETUP request, the Message Body of the 2101 SESSION_SETUP response will contain the encrypted session key from 2102 the server and is defined as follows: 2104 2105 ::= 2106 2107 [ ] 2108 where 2110 2111 Message digest of the SESSION_SETUP request as specified in 2112 section 2.2.3. 2114 2115 Session key encrypted using the public key provided in the 2116 SESSION_SETUP request. The session key is a randomly 2117 generated octet string from the server. The server will only 2118 return the if the in 2119 the SESSION_SETUP request provides the public key from the 2120 client. 2122 2123 (optional) UTF-8 string that identifies the encryption 2124 algorithm used by the session key. 2126 If is given in the SESSION_SETUP 2127 request, the server must provide its public key in the 2128 SESSION_SETUP response. The public key can be used by the client in 2129 a subsequent SESSION_EXCHANGEKEY request (defined below) for 2130 session key exchange. In this case, the Message Header of the 2131 SESSION_SETUP response must set its to 2132 RC_SESSION_EXCHANGEKEY. The Message Body of the SESSION_SETUP 2133 response must include the server's public key and is defined as 2134 follows: 2136 2137 ::= 2138 2140 where 2142 2143 Message digest of the SESSION_SETUP request as specified in 2144 section 2.2.3. 2146 2147 Public key from the server to be used for session key 2148 exchange. It is encoded in the same format as the 2149 record in the HS_SITE value (see section 3.2.2 in [2]). 2151 3.8.3 Session Key Exchange 2153 If the of a SESSION_SETUP response is 2154 RC_SESSION_EXCHANGEKEY, the client is responsible for generating 2155 the session key and sending it to the server. In this case, the 2156 client can generate a session key, encrypt it with the public key 2157 provided by the server in the SESSION_SETUP response, and send the 2158 encrypted session key to the server in a SESSION_EXCHANGEKEY 2159 request. 2161 The Message Header of the SESSION_EXCHANGEKEY request must set its 2162 to OC_SESSION_EXCHANGEKEY and its to 0. The 2163 Message Body of the SESSION_EXCHANGEKEY request is defined as 2164 follows: 2166 2167 ::= 2168 [ ] 2170 where 2172 2173 Session key encrypted using the public key provided in the 2174 SESSION_SETUP response. The session key is a randomly 2175 generated octet string by the client. 2177 2178 (optional) UTF-8 string that identifies the encryption 2179 algorithm used by the session key. 2181 During the session key exchange, the server receiving the exchange 2182 key or session key has the responsibility to make sure that the key 2183 meets the security requirements defined in its local policy. If the 2184 server considers the key being volunable, it must return an error 2185 message to the client with set to 2186 RC_SESSION_KEY_INVALID. 2188 3.8.4 Session Termination 2190 Clients can terminate a session with a SESSION_TERMINATE request. 2191 The Message Header of a SESSION_TERMINATE request must have its 2192 set to OC_SESSION_TERMINATE and its to 0. 2193 The message body of any SESSION_TERMINATE request must be empty. 2195 The server must send a SESSION_TERMINATE response to the client 2196 after the session is terminated. The server should only terminate 2197 the session after it has finished processing all the requests 2198 (under the session) that were submitted before the Session 2199 Termination request. 2201 The message header of the SESSION_TERMINATE response must set its 2202 to OC_SESSION_TERMINATE. A successful SESSION_TERMINATE 2203 response must have its set to RC_SUCCESS, and an 2204 empty message body. 2206 4. Implementation Guidelines 2208 4.1 Server Implementation 2210 The optimal structure for any handle server will depend on the host 2211 operating system. This section only addresses those implementation 2212 considerations that are common to most handle servers. 2214 A good server implementation should allow easy configuration or 2215 fine-tuning. A suggested list of configurable items includes the 2216 server's network interface(s) (e.g., IP address, port number, 2217 etc.), the number of concurrent processes/threads allowed, time-out 2218 intervals for any TCP connection and/or authentication process, re- 2219 try policy under UDP connection, policies on whether to support 2220 recursive service, case-sensitivity for ASCII characters, and 2221 different levels of transaction logging, etc. 2223 All handle server implementations must support all the handle data 2224 types as defined in the "Handle System Namespace and Service 2225 Definition" [2]. They should also be able to store handle values of 2226 any application defined data type. 2228 A handle server must support multiple concurrent activities, 2229 whether they are implemented as separate processes or threads in 2230 the host's operating system, or multiplexed inside a single name 2231 server program. A handle server should not block the service of UDP 2232 requests while it waits for TCP data or other query activities. 2233 Similarly, a handle server should not attempt to provide recursive 2234 service without processing such requests in parallel, though it may 2235 choose to serialize requests from a single client, or to regard 2236 identical requests from the same client as duplicates. 2238 4.2 Client Implementation 2240 Clients should be prepared to receive handle values of any data 2241 type. Clients may choose to implement a callback interface to allow 2242 new modules or plug-ins to be added to support any application- 2243 defined data types. 2245 Clients that follow service referrals or handle aliases must avoid 2246 falling into an infinite loop. They should not repeatedly contact 2247 the same server for the same request with the same target entry. A 2248 client may choose to use a counter that is incremented each time it 2249 follows a service referral or handle alias. There should be a 2250 configurable upper limit to the counter to control the levels of 2251 service referrals or handle aliases followed by the client. 2253 Clients that provide some caching can expect much better 2254 performance than those that don't. Client implementations should 2255 always consider caching the service information associated with a 2256 naming authority. This will reduce the number of roundtrips for 2257 subsequent handle requests under the same naming authority. 2259 5. Security Considerations 2261 The overall Handle System security considerations are discussed in 2262 "Handle System Overview" [1] and that discussion applies equally to 2263 this document. Security considerations regarding the Handle System 2264 data model and service model are discussed in "Handle System 2265 Namespace and Service Definition" [2]. 2267 For efficiency, the handle protocol includes a simple challenge- 2268 response authentication protocol for basic client authentication. 2269 Handle servers are free to provide additional authentication 2270 mechanisms (e.g., SASL) as needed. Details of this will be 2271 discussed in a separate document. 2273 Data integrity under the handle protocol is achieved via the 2274 server's digital signature. Care must be taken to protect the 2275 server's private key from any impersonation attack. Any change to 2276 the server's public key pair must be registered (in terms of 2277 service information) with the GHR. 2279 References and Bibliography 2281 [1] S. Sun, L. Lannom, "Handle System Overview", IETF draft, work 2282 in progress 2284 [2] S. Sun, S. Reilly, L. Lannom, "Handle System Namespace and 2285 Service Definition", IETF draft, work in progress 2287 [3] F. Yergeau, "UTF-8, A Transform Format for Unicode and 2288 ISO10646", RFC2044, October 1996 2290 [4] A. Freier, P. Karlton, P. Kocher "The SSL Protocol Version 3.0" 2292 [5] RSA Laboratories, "Public-Key Cryptography Standard PKCS#7" 2293 http://www.rsasecurity.com/rsalabs/pkcs/ 2295 [6] U.S. Federal Information Processing Standard: Digital Signature 2296 Standard. 2298 [7] R. Housley, "Cryptographic Message Syntax (CMS) Algorithms", 2299 RFC3370, August, 2002 2301 [8] R. Braden, "FTP DATA COMPRESSION", RFC468, March 8, 1973 2303 [9] R. Rivest, "The MD5 Message-Digest Algorithm", RFC1321, April 2304 1992. 2306 [10] NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995. 2308 [11] D. Cohen, "On Holy Wars and a Plea for Peace", Internet 2309 Experiment, Note IEN 137, 1 April 1980. 2311 [12] H. Balakrishnan and S. Seshan. "The Congestion Manager", RFC 2312 3124, June 2001 2314 [13] R. Kahn, R. Wilensky, "A Framework for Distributed Digital 2315 Object Services, May 1995, http://www.cnri.reston.va.us/k-w.html 2317 [14] W. Polk, R. Housley, L. Bassham, "Algorithms and Identifiers 2318 for the Internet X.509 Public Key Infrastructure Certificate and 2319 Certificate Revocation List (CRL) Profile", RFC3279, April, 2002 2321 [15] R. Housley, W. Polk, W. Ford, D. Solo, "Internet X.509 Public 2322 Key Infrastructure Certificate and Certificate Revocation List(CRL) 2323 Profile", RFC3280, April, 2002 2325 [16] M. Bellare and P. Rogaway. The Exact Security of Digital 2326 Signatures - How to Sign with RSA and Rabin. In Advances in 2327 Cryptology-Eurocrypt '96, pp.399-416, Springer-Verlag, 1996. 2329 [17] H. Krawczyk, M. Bellare, R. Canetti, "HMAC: Keyed-Hashing for 2330 Message Authentication", RFC2104, February, 1997 2332 [18] R. Kahn, R. Wilensky, "A Framework for Distributed Digital 2333 Object Services, May 1995, http://www.cnri.reston.va.us/k-w.html 2335 Author's Addresses 2337 Sam X. Sun 2338 Corporation for National Research Initiatives (CNRI) 2339 1895 Preston White Dr. Suite 100 2340 Reston, VA 20191 2341 Phone: 703-262-5316 2342 Email: ssun@cnri.reston.va.us 2344 Sean Reilly 2345 Corporation for National Research Initiatives (CNRI) 2346 1895 Preston White Dr. Suite 100 2347 Reston, VA 20191 2348 Phone: 703-620-8990 2349 Email: sreilly@cnri.reston.va.us 2351 Larry Lannom 2352 Corporation for National Research Initiatives (CNRI) 2353 1895 Preston White Dr. Suite 100 2354 Reston, VA 20191 2355 Phone: 703-262-5307 2356 Email: llannom@cnri.reston.va.us 2358 Jason Petrone 2359 Corporation for National Research Initiatives (CNRI) 2360 1895 Preston White Dr. Suite 100 2361 Reston, VA 20191 2362 Phone: 703-262-5340 2363 Email: jpetrone@cnri.reston.va.us