idnits 2.17.1 draft-hoffman-rescap-protocol-01.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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 1005 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. ** There are 43 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 68 has weird spacing: '...s. This confo...' == Line 825 has weird spacing: '...request x000...' == Line 826 has weird spacing: '...request x000...' == Line 827 has weird spacing: '...request x000...' == Line 828 has weird spacing: '...request x000...' == (23 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 1, 1999) is 9088 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) -- Possible downref: Normative reference to a draft: ref. 'RESCAP-REQUIRE' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHA-1' -- No information found for draft-ietf-svrloc-protocol-v2-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SLP' -- No information found for draft-ietf-dnsind-rfc2052bis-xx - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SRV' ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2279 (ref. 'UTF8') (Obsoleted by RFC 3629) Summary: 9 errors (**), 0 flaws (~~), 9 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft Paul Hoffman 2 draft-hoffman-rescap-protocol-01.txt Internet Mail Consortium 3 June 1, 1999 4 Expires in six months 6 The rescap Resolution Protocol 8 Status of this memo 10 This document is an Internet-Draft and is in full conformance with all 11 provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering Task 14 Force (IETF), its areas, and its working groups. Note that other 15 groups may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference material 20 or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Abstract 30 The rescap protocol is a general client-server resolution protocol that 31 translates resource identifiers to a list of attributes. For instance, 32 a rescap client can ask a rescap server for the attributes of a 33 particular mail user. rescap is very light-weight and acts only as a 34 resolution protocol, not a directory service. 36 1. Introduction 38 When an Internet client is accessing a resource, it is often valuable 39 for the client to know the attributes of the resource before contacting 40 the resource. For example, a mail user might want to know whether 41 another mail user is able to natively display TIFF files before 42 creating a message with a TIFF file in it. The rescap protocol is a 43 simple, extensible client-server protocol that allows a client to 44 easily find the correct rescap server for a particular resource and 45 find the attributes for that resource. 47 This document specifies: 48 - How to find the rescap server for a particular resource 49 - The recap protocol 50 - The format for rescap requests and responses 51 - Required rescap items that must be supported 52 - Registration of the "rescap" scheme name for URLs 54 The protocol in this document attempts to meet all the requirements 55 described in the rescap requirements document [RESCAP-REQUIRE]. 56 It should be noted that rescap is explicitly not to be used as 57 a service-discovery protocol; users that want such a capability 58 should use the Service Location Protocol [SLP]. 60 This document and others relating to the rescap protocol are being 61 discussed on the rescap@cs.utk.edu mailing list. To subscribe, send a 62 message to rescap-request@cs.utk.edu. An archive of the mailing list is 63 available at . 65 1.1 Terminology 67 Throughout this draft, the terms MUST, MUST NOT, SHOULD, and SHOULD NOT 68 are used in capital letters. This conforms to the definitions in 69 [MUSTSHOULD]. [MUSTSHOULD] defines the use of these key words to help 70 make the intent of standards track documents as clear as possible. The 71 same key words are used in this document to help implementors achieve 72 interoperability. 74 Hexadecimal values are indicated as "xNN" or "xNNNN". For example, 75 xA0B1 corresponds to the octet xA0 followed by the octet xB1. 77 2. Finding a rescap Server 79 A rescap client that wants to find the attributes for a particular 80 Internet resource needs to find the rescap server for that resource. 81 The client MUST look up the A record associated with the rescap server 82 for the host name in the resource. When SRV records (described in 83 [SRV]) become widely deployed, the client MAY instead use the SRV 84 protocol to locate the rescap server. 86 To find the A record of the rescap server, the client prepends two 87 special domain names to the host name in the resource. The first name 88 prepended (just to the left of the host name) is "_rescap."; the second 89 name prepended (just to the left of "_rescap." is an underscore followed 90 by the URL scheme name. 92 For example, to find the rescap server that is authoritative for the 93 URI "mailto:someone@example.com", the rescap client would resolve the A 94 record of the name "_mailto._rescap.example.com" and use that value as 95 the location of the rescap server. 97 2.1 Optional use of SRV Records 99 SRV records MAY be used for locating rescap servers. The request sent 100 to the DNS server is somewhat different than is specified in [SRV] 101 because the rescap client must indicate the type of resource that will 102 be resolved by the rescap server. The resource name is given as the URI 103 scheme name, and it appears in the left-most part of the DNS name to be 104 resolved. The URI scheme name has an underscore character (_) prepended 105 to it, just as the service and prototype names do. 107 As described in section 3 of this specification, the rescap protocol 108 runs over both the UDP and TCP protocols, and all compliant servers 109 must run the rescap service on both protocols on the same host. It is 110 inefficient to force the rescap client to look up SRV records for both 111 protocols, and doubling the number of SRV records for the rescap 112 protocol can have an adverse effect on the domain name system. Thus, 113 rescap clients MUST only resolve rescap SRV records for the UDP 114 protocol, and MUST assume that the same host that was resolved for the 115 UDP protocol will support rescap over the TCP protocol as well. rescap 116 clients MUST NOT attempt to resolve rescap SRV records for the TCP 117 protocol. 119 For example, to use SRV records to find the rescap server that is 120 authoritative for the URI "mailto:someone@example.com", the rescap 121 client would resolve the SRV record for the name 122 "_mailto._rescap._udp.example.com". 124 3. Protocol 126 The rescap protocol uses a single request-response model. That is, a 127 rescap client connects to the rescap server, sends a single request, 128 and waits for the response. The server sends a single response and 129 closes the connection. 131 The requirement that the rescap protocol be light-weight and fast leads 132 to the conclusion that it should run on UDP instead of TCP because UDP 133 takes less system and network resources for short exchanges. However, 134 UDP has many problems, including that long datagrams may get split up 135 or lost. Thus, to make rescap reliable, rescap servers run on both UDP 136 and TCP. 138 A rescap server MUST run the same service on both the UDP and TCP 139 protocols, and MUST use the same port number for both services. The 140 port number 283 has been reserved by IANA for rescap, and a rescap 141 server SHOULD run on that port number. However, because the client is 142 allowed to find the port number using SRV records, the rescap server 143 can run on any UDP and TCP port. 145 A rescap client SHOULD make its initial request to the rescap server 146 using UDP. However, if the rescap client expects that the response from 147 the server to be longer than 512 octets (such as if it is asking for an 148 attribute whose value is always longer than 512 octets), the client MAY 149 choose to make the initial connection using TCP. 151 If a client sends a UDP request to the server named in an SRV record 152 but does not receive a response, the client SHOULD send the same 153 request using TCP. If a client sends a UDP request to a server and 154 receives an incomplete response, the client MUST send the same 155 request using TCP. This is due to the fact that a later part of 156 a response might modify or negate the meaning of an earlier part 157 of a response. 159 4. Request and Response Format 161 Rescap requests and responses have a simple format. The format is 162 optimized for simple processing in small clients. It is also optimized 163 for size so that it is more likely that requests and responses can fit 164 in single UDP datagrams. 166 The basic unit of a rescap request or response is the item. An item 167 consists of exactly three parts: 168 - a two-octet tag 169 - a two-octet length 170 - content whose length and structure are defined by the tag 171 Each of the three parts of an are in network byte order, as is the 172 entire item. 174 The tag values are given in this document and in other documents that 175 profile rescap for various resource types. The length is the length of 176 the content of the item, measured in octets. Some tags define 177 fixed-length content, while other tags define variable-length content. 179 A program parsing a request or response can easily skip over items 180 whose tags it doesn't recognize by reading the tag, reading the length, 181 and skipping over the number of octets given in the length to get to 182 the beginning of the next item. 184 There are three types of items: request-type items, response-type 185 items, and data-type items. The type of the item is given in each 186 item's specification. 188 4.1 Long content 190 The most significant bit of the two-octet length part of an item is a 191 continuation marker. If the continuation marker is "1", the item has 192 been split into two or more fragments. The item following an item whose 193 continuation marker is "1" MUST have the same tag value as the 194 preceding item. The first fragment that has a continuation marker of 195 "0" is the last fragment in the item. When reconstructing a fragmented 196 item, the content of all fragments are appended in the same sequence 197 that they appeared in the data steam. 199 A consequence of this design is that any item whose length is greater 200 than x7FFF MUST be split into at least two packets. Any item MAY be 201 split into fragments. A process interpreting a stream of rescap items 202 MUST be able to correctly handle long content. That is, if an item has 203 a continuation marker of "1" in the length part, the process MUST read 204 the next item, check that the tag matches that of the preceding item, 205 and append the content of the second item to that of the first item, 206 until the process comes to an item with the continuation marker set to 207 "0". It is an error if the process comes to an item with a different 208 tag value than the preceding item if that preceding item had a 209 continuation marker of "1". 211 Design note: the method of using a two-octet length and checking for 212 the special value for the continuation marker was chosen instead of 213 using a four-octet length in order to keep the size of the rescap 214 response shorter, and therefore make it more likely that a response 215 would fit in a single UDP datagram. The vast majority of items will 216 probably have lengths less than x7FFF. The continuation marker allows a 217 program to marshal fewer than x7FFF octets if it has memory 218 constraints. The cost of having to check for the special case of a 219 continuation marker seems to be worth the tradeoff of making every item 220 two octets longer. 222 5. Basic requests and responses 224 The items in this section are included in a rescap client's request to 225 a rescap server and in the server's response to the client. A rescap 226 request is always a FullRequest item; that item contains other 227 request-type items. A rescap response is always a FullResponse item; 228 that item contains other response-type items. 230 5.1 Basic request types 232 Clients MUST be able to emit the FullRequest and BaseURI types, and 233 SHOULD be able to emit ItemsToReturn. Clients MAY implement the 234 PrivUseRequest types. Servers MUST be able to interpret the 235 FullRequest, BaseURI, and ItemsToReturn types, although servers do not 236 have to comply with the request in ItemsToReturn. For instance, a 237 server may not want to return certain items due to lack of 238 authorization or due to the response becoming too long. 240 5.1.1 FullRequest 242 The FullRequest item (tag x0001) is used to encapsulate the other 243 request-type items. A rescap client's request to the server MUST be a 244 single FullRequest item (unless the content of the FullRequest is 245 longer than xFFFF octets, as described in section 4.1). The structure 246 of the item is a sequence of one or more request-type items. A 247 FullRequest item MUST NOT be included in a FullRequest item, and a 248 FullRequest item MUST contain only request-type items. Note that some 249 items contain other items; the prohibition against response-type and 250 data-type items is only for items directly encapsulated in the 251 FullRequest item, not items that are encapsulated in lower-level items. 253 A FullRequest item MUST contain exactly one instance of a BaseURI item, 254 and MAY contain zero or one instances of each of the other request-type 255 items. 257 5.1.2 BaseURI 259 The BaseURI item (tag x0002) specifies the Internet resource for which 260 the rescap client wants information. The structure of the item is a URI 261 string as defined in [URI] for a single resource. Every FullRequest 262 MUST include exactly one BaseURI item. 264 5.1.3 ItemsToReturn 266 The ItemsToReturn item (tag x0003) lists the response-type items that 267 the client would like the server to return. It is a request, not a 268 demand; the server is allowed to return any response-type item it 269 chooses. The client can use this item to specify that it only is 270 interested in a limited number of response-type items, and that the 271 server should not waste its time or bandwidth returning any items not 272 listed in the ItemsToReturn item. The structure of the item is a 273 sequence of tag values, each of which is two octets long. 275 If the ItemsToReturn item is not included in a request, the server may 276 return whatever information it pleases about the resource named in the 277 BaseURI item. If the ItemsToReturn item is included and its length is 278 zero, the client wants the server to return all the information it has 279 about the resource named in the BaseURI item. If the ItemsToReturn item 280 is included and its length is greater than zero, the client wants the 281 server to return only response-type items of the type listed in the 282 ItemsToReturn item. 284 Note that it is not an error for the client to list items in the 285 ItemsToReturn item that cannot be returned to by the server. 287 5.1.4 PrivUseRequest00 through PrivUseRequest255 289 The PrivUseRequest00 through PrivUseRequest255 items (tags xFE00 290 through xFEFF) are reserved for private use as request-type items and 291 will never be assigned by IANA. These tags may be used by protocol 292 developers to test protocols that they are developing, such as during 293 the process of preparing Internet Drafts that contain registration for 294 future request-type items. The structure of the items is undefined. 296 5.2 Basic response types 298 Servers MUST implement the FullResponse and Status types, and SHOULD 299 implement the Referral type. Servers SHOULD implement the TTLOfInfo, 300 ExpirationOfInfo, and DateOfChange types. Servers MAY implement the 301 PrivUseResponse types. 303 Clients MUST be able to interpret the FullResponse, Status, and 304 Referral types; clients SHOULD be able to process Referrals by fetching 305 the information from the referred-to host. A rescap client SHOULD NOT 306 attempt to make any use of the user response-type items that it does 307 not fully understand. 309 Note: clients MUST parse TTLOfInfo, ExpirationOfInfo, and DateOfChange 310 items even if the clients do not know how to check the expiration or 311 modification of information (such as a client that does not know when 312 the information will be delivered to the user or a client that does not 313 know the current time). These items encapsulate other response items 314 that the client may want to deliver to the user regardless of the 315 expiration status. Clients that cannot check the expiration or 316 creation information MUST treat the enclosed response-type data as if 317 it appeared outside of the time-specific types, and in the case of 318 TTLOfInfo and ExpirationOfInfo, SHOULD indicate to the user that the 319 server put an expiration on the information and that the expiration was 320 not checked. 322 5.2.1 FullResponse 324 The FullResponse item (tag x000C) is used to encapsulate the other 325 response-type items. A rescap server's Response to a client MUST be a 326 single FullResponse item (unless the content of the FullResponse is 327 longer than xFFFF octets, as described in section 4.1). The structure 328 of the item is a sequence of one or more response-type items. A 329 FullResponse item MUST NOT be included in a FullResponse item, and a 330 FullResponse item MUST contain only Response-type items. Note that some 331 items contain other items; the prohibition against request-type and 332 data-type items is only for items directly encapsulated in the 333 FullResponse item, not items that are encapsulated in lower-level 334 items. 336 A FullResponse item MUST contain one or more instance of a Status item, 337 and MAY contain zero or more instances of each of other 338 response-type items. Note that some response-type items further 339 restrict the number of times those items can appear in a FullResponse 340 item. 342 5.2.2 Status 344 The Status item (tag x000D) gives status information to the client 345 about its request. The structure of the status tag is a sequence of a 346 one-octet main status code, a one-octet secondary status code, and an 347 optional string that is a sequence of characters from the ISO/IEC 348 10646-1 character set encoded with the UTF-8 transformation format 349 defined in [UTF8]. A FullResponse MUST have at least one Status item 350 and MAY have more than one Status item. A rescap server SHOULD include 351 only as many Status items as necessary for a client to process the 352 response. 354 The optional string may be used to transmit status information, but it 355 is optional. In fact, a rescap server that is trying to keep its 356 responses as short as possible SHOULD NOT include a string at all. 358 The rescap client MAY choose to display the string to the client. 359 However, because there is no way to know the languages understood by 360 the user, the string may be of little or no use to them. 362 Note: If a client sent a request over UDP and receives a Status 363 item of x0201, the client SHOULD sent the same request over TCP. 365 The values for the main status code (the first octet of the Status 366 item) are based loosely on those in SMTP. They are: 367 x00 - positive completion 368 x01 - transient negative completion 369 x02 - permanent negative completion 371 A rescap client MAY use just the main status code to decide how to 372 display any results of the request to the user who made the request. 374 The complete list of status codes is: 376 x0000 The request was fully processable 377 x0001 Successful authorization through AuthInTheClear 378 x0002 Successful authorization through AuthDigest 379 x0003 Successful authorization through AuthPublicKey 380 x0004 Successful authorization through AuthIP 381 x0005 No valid KeyID items in the the SigningPrefs 382 x0006 No valid KeyID items in the SignedRequest 383 x0007 The content of the SignedRequest didn't validate against the 384 signature 386 x0100 Too busy; try again whenever you feel like it 387 x0101 Too busy; try again later than 10 seconds from now 388 x0102 Too busy; try again later than 60 seconds from now 389 x0103 Too busy; the Referral item in the response leads to another 390 rescap server authoritative for this resource 392 x0200 The body of the request was longer than what was indicated in the 393 length 394 x0201 The body of the request was shorter than what was indicated in 395 the length 396 x0202 The request included items not of request-type 397 x0203 The request included more than one BaseURI item 398 x0204 This server is not authoritative for the resource named in the 399 BaseURI item and no referral is available 400 x0205 This server is not authoritative for the resource named in the 401 BaseURI item; the URI in the Referral item leads you to a server 402 that this server believes is authoritative 403 x0206 No valid KeyID items in EncryptingPrefs 405 5.2.3 Referral 407 The Referral item (tag x000E) tells the client that another rescap 408 server has authoritative information for the requested resource. If 409 some information may be available from several sources, an 410 "authoritative" source is one whose response should be regarded as 411 superseding all others in the event of any discrepancy. The structure 412 of the Referral item is a URI string as defined in [URI] for a single 413 resource. The scheme in the URI MUST be "rescap". If a FullResponse 414 item contains a Referral item or a Referral item enclosed in a 415 SignedResponse or an EncryptedResponse item, there MUST NOT be any 416 other items in the FullResponse item other than Status items. 418 5.2.4 TTLOfInfo 420 The TTLOfInfo item (tag x0017) specifies how long the server assures 421 that the information enclosed in the item will be valid. The TTLOfInfo 422 item has the structure of a four-octet integer followed by one or more 423 response-type items. The four-octet integer represents the number of 424 seconds before the server no longer assures that the listed items are 425 valid. 427 If a rescap client does not support expiration of items, it MUST treat 428 the items in a TTLOfInfo item as if they appeared outside of a 429 TTLOfInfo item. This allows a server to respond with TTLOfInfo without 430 knowing whether or not the client handles the expiration time listed in 431 the item. 433 5.2.5 ExpirationOfInfo 435 The ExpirationOfInfo item (tag x0018) specifies the final time in the 436 future that the server assures that the information enclosed in the 437 item will be valid. The ExpirationOfInfo item has the structure of a 438 14-octet integer followed by one or more response-type items. The 439 14-octet integer represents the date at Greenwich Mean Time as a string 440 of ASCII characters in YYYYMMDDHHMMSS format after which the server no 441 longer assures that the listed items are valid. 443 If a rescap client does not support expiration of items, it MUST treat 444 the items in a ExpirationOfInfo item as if they appeared outside of a 445 ExpirationOfInfo item. This allows a server to respond with 446 ExpirationOfInfo without knowing whether or not the client handles the 447 expiration time listed in the item. 449 5.2.6 DateOfChange 451 The DateOfChange item (tag x001C) specifies the time that the server 452 last changed the value of the attribute (or, if it has never been 453 changed, first created the value). The DateOfChange item has the 454 structure of a 14-octet integer followed by one or more response-type 455 items. The 14-octet integer represents the date at Greenwich Mean Time 456 as a string of ASCII characters in YYYYMMDDHHMMSS format. 458 If a rescap client does not support showing modification times of 459 items, it MUST treat the items in a DateOfChange item as if they 460 appeared outside of a DateOfChange item. This allows a server to 461 respond with DateOfChange without knowing whether or not the client 462 handles the display of modification time listed in the item. 464 5.2.7 PrivUseResponse00 through PrivUseResponse255 466 The PrivUseResponse00 through PrivUseResponse255 items (tags xFF00 467 through xFFFF) are reserved for private use as response-type items and 468 will never be assigned by IANA. These tags may be used by protocol 469 developers to test protocols that they are developing, such as during 470 the process of preparing Internet Drafts that contain registration for 471 future response-type items. The structure of the items is undefined. 473 6. Security-related requests and responses 475 The security-related requests and responses are optional for both 476 clients and servers. 478 Note: clients SHOULD be able to parse SignedResponse items even if the 479 client does not know how to verify signatures. These items contain 480 other response items that the client MAY want to deliver to the user 481 regardless of the signature status. 483 6.1 Security-related request types 485 6.1.1 AuthInfo 487 The AuthInfo item (tag x0004) holds authorization items that can be 488 used by the server to choose to give the client more or less 489 information in the response. The AuthInfo item MUST contain a list of 490 one or more request-type items that relate to authorization. The 491 acceptable items that may be contained in the AuthInfo item are 492 AuthInTheClear, AuthDigest, AuthPublicKey, and AuthIP. If more than one 493 item is in the AuthInfo item, the server MAY use any of the items to 494 determine authorization to the information about the resource named in 495 the BaseURI item. 497 If one or more of the authorizations succeeds, the server SHOULD 498 include a Status item indicating which type of authorization succeeded. 499 If none of the given authorizations succeeds, the server MAY still 500 include information items in the response. 502 6.1.1.1 AuthInTheClear 504 The AuthInTheClear item (tag x0005) holds a sequence of binary octets. 505 The format of the sequence is determined by private agreement between 506 the client and the server. This type of authorization is inherently 507 insecure because an eavesdropper can see the sequence and use it get 508 authorization on a later request. 510 6.1.1.2 AuthDigest 512 The AuthDigest item (tag x0006) holds a hashed password. TBD: This will 513 probably be done with something similar to the Digest mechanism in 514 draft-ietf-http-authentication-03.txt. However, for this to work, the 515 server must give the client a nonce before the client creates the 516 AuthDigest item; otherwise, the mechanism suffers from a simple replay 517 attack. 519 6.1.1.3 AuthPublicKey 521 The AuthPublicKey item (tag x0007) holds a password that has been 522 encrypted with the client's private key. TBD: This will probably be 523 done using a DSS signature with no PKI specified. However, for this to 524 work, the server must give the client a nonce before the client creates 525 the AuthDigest item; otherwise, the mechanism suffers from a simple 526 replay attack. 528 6.1.1.4 AuthIP 530 The AuthIP item (tag x0008) is a zero-length item that indicates that 531 the client requests that it gain some authorization simply based on the 532 IP address of the client, which the server will determine by examining 533 the IP address of the connection. 535 6.1.2 SigningPrefs 537 The SigningPrefs item (tag x0009) tells the server how the client 538 prefers the server to sign the items in the response. The SigningPrefs 539 item contains a sequence of one or more items; it SHOULD contain a Nonce 540 item, and MAY contain one or more KeyID items. The Nonce item is a 541 nonce that the server SHOULD use if the server returns signed items, and 542 the KeyID items are the key identifiers with which the client would 543 prefer the server to sign. The KeyID items are in decreasing order of 544 preference. 546 If the FullRequest item includes a SigningPrefs item, the server SHOULD 547 encapsulate as many items as possible in one or more SignedResponse 548 items. If the FullRequest item does not include a SigningPrefs item, 549 the server MAY still include SignedResponse items in the response. If 550 the FullRequest item includes a SigningPrefs item that does not contain 551 any KeyID items that correspond to keys currently usable by the server, 552 the server SHOULD still return information in the response. 554 If the SigningPrefs item does not include a Nonce item, the server's 555 SignedResponse item will not contain a NonceReply item. Note that the 556 server may chose not to include the NonceReply item if it has 557 pre-signed the objects it is returning. If the SignedResponse item does 558 not contain a NonceReply item, the server's response is still signed, 559 but the reply can be replayed by an attacker at a later time. 561 6.1.3 EncryptingPrefs 563 The EncryptingPrefs item (tag x000A) tells the server the encrypting 564 key with which the client would like the response-type items other than 565 Status items encrypted. The structure of the item is a sequence of one 566 or more KeyID items, in decreasing order of preference. If an 567 EncryptingPrefs item is included in the request, the server MUST NOT 568 include anything other than one or more Status items and one or more 569 EncryptedResponse items in the FullResponse item. That is, because the 570 client requested an encrypted response, the server MUST NOT include 571 anything other than a Status item in the FullResponse that is not 572 encrypted. 574 6.1.4 SignedRequest 576 The SignedRequest item (tag x000B) gives a digital signature for the 577 other items in the FullRequest. The structure is a single KeyID item 578 followed by a single SignatureValue item. The signature is computed 579 over the contents of the FullRequest item, excluding the entire 580 SignedRequest item. 582 If the server is able to process a SignedRequest item, it MUST first 583 verify that the KeyID in the SignedRequest is a valid signing key known 584 to be associated with a client. It MUST then use the signature 585 algorithm associated with the KeyID to check the integrity of the 586 content of the SignedRequest. If the integrity check fails, the server 587 SHOULD indicate the failure in the Status item returned in the 588 response, and MAY choose to not include some or all other items in the 589 response. 591 If the server is not able to process a SignedRequest item, it SHOULD 592 indicate this fact in the Status item in the response. However, other 593 than the status indication, such a server SHOULD treat the FullRequest 594 item as if it did not contain a SignedRequest item. 596 6.2 Security-related response types 598 6.2.1 SignedResponse 600 The SignedResponse item (tag x000F) encloses other response-type items 601 and gives a digital signature for all the items in the SignedResponse 602 item other than the signing control items. The structure of the 603 SignedResponse item is one SignatureControlInfo item followed by one or 604 more response-type items. The digital signature in the 605 SignatureControlInfo is computed over the items other than the 606 SignatureControlInfo item. If the FullRequest item contained a 607 SigningPrefs item, the SignedResponse SHOULD contain a NonceReply item. 609 If the client can process the signature in the SignedResponse item, it 610 MUST first verify that the KeyID in the SignedResponse is a valid 611 signing key known to be associated with the server or with the resource 612 provider. It MUST then use the signature algorithm associated with the 613 KeyID to check the integrity of the content of the SignedResponse. If 614 the integrity check fails, the client software SHOULD indicate the 615 failure to the user, and MAY choose to reject the values given in the 616 SignedResponse. 618 Note that all rescap clients MUST be able to process SignedResponse 619 items even if they cannot process the signatures. If a client cannot 620 process signatures, it MUST treat the items enclosed in the 621 SignedResponse as if they were outside a SignedResponse but inside the 622 FullResponse item. Requiring clients to handle SignedResponse items in 623 this fashion allows a server to create pre-signed items and groups of 624 items and serve them without first checking if the client can handle a 625 particular signature algorithm. However, a server SHOULD still check 626 the SigningPrefs item of the FullRequest item to assure that it is 627 returning signatures that the client can use. 629 6.2.1.1 SignatureControlInfo 631 The SignatureControlInfo item (tag x0010) gives the key and digital 632 signature used to sign the items in the SignedResponse item. The 633 structure of the SignatureControlInfo item is an optional single KeyID 634 item followed by the value of the digital signature. The algorithm used 635 to calculate the digital signature depends on the KeyID. See the 636 DefaultKeyID item for information about handling SignatureControlInfo 637 items that have no KeyID item. 639 6.2.1.2 DefaultKeyID 641 The DefaultKeyID item (tag x0011) contains the KeyID that is used by 642 default in every SignatureControlInfo item that does not contain a 643 KeyID item. The structure of the DefaultKeyID item is a single KeyID 644 item. A DefaultKeyID item MUST only appear at the top level of a 645 FullResponse item or the top level of an EncryptedResponse item; in 646 either case, it MUST only appear zero or one time. A DefaultKeyID item 647 MUST NOT appear at any level of a SignedResponse item, a TTLOfInfo 648 item, or an ExpirationOfInfo item. 650 6.2.1.3 NonceReply 652 The NonceReply item (tag x0012) contains a single item, the Nonce item 653 that was specified in the SigningPrefs item in the request. 655 6.2.2 EncryptedResponse 657 The EncryptedResponse item (tag x0013) carries information that has 658 been encrypted with the client's encryption key. The structure of the 659 EncryptedResponse item is a sequence of one EncryptionControlInfo item 660 and one EncryptedBlob item. The EncryptedBlob item contains the 661 encryption of one or more response-type items. 663 If a FullResponse item contains an EncryptedResponse item, the 664 FullResponse MUST only contain EncryptedResponse items and Status 665 items. A FullResponse item MAY contain more than one EncryptedResponse 666 item, although doing so is of limited value and causes greater 667 processing overhead for the client. 669 The server MUST ONLY prepare an EncryptedResponse item using a KeyID 670 that is associated with a known client. Otherwise, an attacker can 671 cause the server to think that it is sending protected information on 672 the Internet when in fact it can be decrypted by the attacker. 674 6.2.2.1 EncryptionControlInfo 676 The EncryptionControlInfo item (tag x0014) contains the encrypted 677 session key used for encrypting the EncryptedBlob item. The structure 678 of the EncryptionControlInfo is a sequence of the KeyID item of the key 679 that was used to create the key encryption key, and the 680 KeyEncryptionKey item that holds the key encryption key. 682 6.2.2.2 EncryptedBlob 684 The EncryptedBlob item (tag x0015) contains binary data that has been 685 encrypted. When decrypted, the contents of the EncryptedBlob item MUST 686 be a sequence of response-type items. 688 6.2.2.3 KeyEncryptionKey 690 The KeyEncryptionKey item (tag x0016) contains binary data that is a 691 key encryption key. The structure of the key encryption key is 692 determined by the algorithm used, which is specified in the KeyID item. 694 7. Data-type items 696 7.1 Nonce 698 The Nonce item (tag x0019) contains a random or pseudo-random list of 699 octets. The length of the Nonce item is determined by the process using 700 the nonce, but MUST NOT be less than eight octets. 702 7.2 KeyID 704 The KeyID item (tag x001A) holds an identifier for an encrypting or 705 signing key. The contents of the KeyID item is always an 8-octet 706 identifier. The identifier is derived by first concatenating an 707 algorithm identifier to the end of the key, then taking the SHA-1 708 [SHA-1] hash of the result, then taking the first eight octets of the 709 hash. 711 7.3 SignatureValue 713 The SignatureValue item (tag x001B) holds the value of the signature. 714 The contents of the SignatureValue item is a binary value whose length 715 is determined by the signature algorithm used. 717 8. Security Algorithms 719 TBD. The spec will require the use of DSA for signatures, 720 Diffie-Hellman for encryption key exchange, and TripleDES for 721 encryption. It will suggest also implementing RSA for both signatures 722 and encryption key exchange. It may or may not suggest support for 723 shared-secret keys for encryption key exchange. 725 9. Security Considerations 727 The current draft doesn't specify how the security algorithms will be 728 used, and thus doesn't give enough detail to analyze the security 729 considerations of the specification. 731 A server may choose to allow authorization through a variety of 732 mechanisms, some of which have better security properties than others. 733 Specifically, the AuthInTheClear mechanism passes authorization in the 734 clear; this allows an attacker to copy the authorization information 735 and impersonate the client in the future. 737 All public keys in this specification are trusted based on private 738 agreement. The client and server can use out-of-band mechanisms to 739 agree to public key management, but none of the mechanisms are 740 described here. A successful attack on the out-of-band mechanism could 741 allow the attacker to impersonate the client or the server, or could 742 allow the attacker to read encrypted responses. 744 10. References 746 [MUSTSHOULD] "Key words for use in RFCs to Indicate Requirement 747 Levels", RFC 2119. 749 [RESCAP-REQUIRE] "ResCap Requirements", draft-beck-rescap-req. 751 [SHA-1] "Secure Hash Standard", NIST FIPS publication 180-1, 752 April 1995. 754 [SLP] "Service Location Protocol", RFC 2165. NOTE: RFC 2165 is 755 being updated by draft-ietf-svrloc-protocol-v2-xx.txt. 757 [SRV] "A DNS RR for specifying the location of services (DNS SRV)", RFC 758 2052. NOTE: RFC 2052 is being updated by 759 draft-ietf-dnsind-rfc2052bis-xx.txt. The examples in this document are 760 based on the Internet Draft, not on RFC 2052. 762 [URI] "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396. 764 [UTF8] "UTF-8, a transformation format of ISO 10646", RFC 2279. 766 A. IANA Considerations 768 A.1 Item registry 770 IANA will maintain a registry of all rescap items. The registry will be 771 populated by the items in this specification and any other RFC. The 772 RFCs must give sufficient detail so that interoperability between 773 independent implementations is possible. The registry will contain the 774 name of the item, the tag value, the type, and the RFC which defines 775 the item. Each name in the registry must be unique, and each tag value 776 must also be unique. The types in the registry are "request-type", 777 "response-type", and "data-type". IANA should also list the RFC in 778 which the items are defined so that protocol designers know where to 779 find the document defining the items. 781 Each RFC that defines rescap items must include an application of the 782 form: 784 To: iana@iana.org 785 From: 786 Subject: Registration of rescap items 788 The following are the rescap items defined in this document. 790 Item Type Tag 792 A.2 Status value registry 794 IANA will maintain a registry of all rescap status values. The registry 795 will be populated by the status values in this specification and any 796 other RFC. The RFCs must give sufficient detail so that 797 interoperability between independent implementations is possible. The 798 registry will contain the value of the status value, a brief 799 description of the meaning of the value, and the RFC which defines the 800 value. Each value in the registry must be unique. IANA should also list 801 the RFC in which the status values are defined so that protocol 802 designers know where to find the document defining the status values. 804 Each RFC that defines rescap status values must include an application 805 of the form: 807 To: iana@iana.org 808 From: 809 Subject: Registration of rescap status values 811 The following are the rescap status values defined in this document. 813 Value Meaning 815 B. Registration of rescap Types, Status Values, and URL Scheme 817 B.1 Registration of rescap Types 819 To: iana@iana.org 820 From: Paul Hoffman 821 Subject: Registration of rescap items 822 The following are the rescap items defined in this document. 824 Item Type Tag 825 FullRequest request x0001 826 BaseURI request x0002 827 ItemsToReturn request x0003 828 AuthInfo request x0004 829 AuthInTheClear request x0005 830 AuthDigest request x0006 831 AuthPublicKey request x0007 832 AuthIP request x0008 833 SigningPrefs request x0009 834 EncryptingPrefs request x000A 835 SignedRequest request x000B 836 FullResponse response x000C 837 Status response x000D 838 Referral response x000E 839 SignedResponse response x000F 840 SignatureControlInfo response x0010 841 DefaultKeyID response x0011 842 NonceReply response x0012 843 EncryptedResponse response x0013 844 EncryptionControlInfo response x0014 845 EncryptedBlob response x0015 846 KeyEncryptionKey response x0016 847 TTLOfInfo response x0017 848 ExpirationOfInfo response x0018 849 Nonce data x0019 850 KeyID data x001A 851 SignatureValue data x001B 852 DateOfChange response x001C 853 PrivUseRequest00 through 854 PrivUseRequest255 request xFE00-xFEFF 855 PrivUseResponse00 through 856 PrivUseResponse255 response xFF00-xFFFF 858 B.2 Registration of rescap Status Values 860 To: iana@iana.org 861 From: Paul Hoffman 862 Subject: Registration of rescap status values 864 The following are the rescap status values defined in this document. 866 Value Meaning 867 x0000 The request was fully processable 868 x0001 Successful authorization through AuthInTheClear 869 x0002 Successful authorization through AuthDigest 870 x0003 Successful authorization through AuthPublicKey 871 x0004 Successful authorization through AuthIP 872 x0005 No valid KeyID items in the the SigningPrefs 873 x0006 No valid KeyID items in the SignedRequest 874 x0007 The content of the SignedRequest didn't validate against the 875 signature 877 x0100 Too busy; try again whenever you feel like it 878 x0101 Too busy; try again later than 10 seconds from now 879 x0102 Too busy; try again later than 60 seconds from now 880 x0103 Too busy; the Referral item in the response leads to another 881 rescap server authoritative for this resource 883 x0200 The body of the request was longer than what was indicated in the 884 length 885 x0201 The body of the request was shorter than what was indicated in 886 the length 887 x0202 The request included items not of request-type 888 x0203 The request included more than one BaseURI item 889 x0204 This server is not authoritative for the resource named in the 890 BaseURI item and no referral is available 891 x0205 This server is not authoritative for the resource named in the 892 BaseURI item; the URI in the Referral item leads you to a server 893 that this server believes is authoritative 894 x0206 No valid KeyID items in EncryptingPrefs 896 B.3 Registration for rescap URL Scheme 898 URL scheme name: rescap 900 URL scheme syntax: ://? 901 is the string "rescap". is exactly as 902 defined in RFC 2396. is the Base64 encoding of 903 a rescap request 905 For example, to indicate a query to the rescap server on the host 906 "an.example.com" at the default port of 283, the URL would be 907 rescap:an.example.com/SK398cske002CcksleEEx 909 For example, to indicate a query to the rescap server on the host 910 at 10.20.30.40 at port 1234, the URL would be 911 rescap:10.20.30.40:1234/SK398cske002CcksleEEx 913 Character encoding considerations: None. All three parts are expressed 914 in US-ASCII. 916 Intended usage: To identify queries rescap servers. The resolution of a 917 rescap URL will normally cause a query to be sent to the named 918 server. The resolver would decode the Base64 of the third part of 919 the URL and send it to the specified port (or the default port of 920 283 if no port is specified in the URL) using the TCP protocol. 922 Applications and/or protocols which use this URL scheme name: 923 This document describes the rescap protocol. 925 Interoperability considerations: None known. 927 Security considerations: Same as in this document. 929 Relevant publications: This document. 931 Person & email address to contact for further information: 932 Paul Hoffman 934 Author/Change controller: 935 Paul Hoffman 937 C. Acknowledgments 939 Graham Klyne provided all the suggestions for changes to the first draft. 941 D. Changes Between Versions of This Document 943 D.1 Changes from -00 to -01 945 Changed the title of the document. Also slightly reworded the abstract. 947 3: Second paragraph, added "for short exchanges". Last paragraph, 948 changed the "MAY choose to not go to TCP" to "MUST get a TCP response" 949 because some extensions to rescap may have later parts of a response 950 modifying earlier parts. 952 4: Added the bit about network byte order for each part of an item. 954 4.1: Changed the entire "long content" design. 956 5.: Added the last sentence about the rationale for not returning 957 requested items. 959 5.2: Changed the last sentence in the second paragraph to get rid of 960 "display". 962 5.2.3: Added the defintion of authoritative. 964 6.1.1.4: Changed "empty" to "zero-length". 966 6.2.1: Added " or with the resource provider" in the second paragraph. 968 7.2: Added the reference to SHA-1. 970 10: Added [SHA-1]. 972 B: Renumbered the section. 974 B.3: Changed "" to "". More importantly, changed 975 the scheme from "rescap:host.example.com/" to 976 "rescap://host.example.com?". 978 E. Author Contact Information 980 Paul Hoffman 981 Internet Mail Consortium 982 127 Segre Place 983 Santa Cruz, CA 95060 USA 984 phoffman@imc.org