home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / rfc / rfc2169 < prev    next >
Text File  |  1997-06-23  |  18KB  |  508 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                       R. Daniel
  8. Request for Comments: 2169             Los Alamos National Laboratory
  9. Category: Experimental                                      June 1997
  10.  
  11.  
  12.          A Trivial Convention for using HTTP in URN Resolution
  13.  
  14. Status of this Memo
  15. ===================
  16.  
  17.    This memo defines an Experimental Protocol for the Internet
  18.    community.  This memo does not specify an Internet standard of any
  19.    kind.  Discussion and suggestions for improvement are requested.
  20.    Distribution of this memo is unlimited.
  21.  
  22. Abstract:
  23. =========
  24.  
  25.    The Uniform Resource Names Working Group (URN-WG) was formed to
  26.    specify persistent, location-independent names for network accessible
  27.    resources, as well as resolution mechanisms to retrieve the resources
  28.    given such a name. At this time the URN-WG is considering one
  29.    particular resolution mechanism, the NAPTR proposal [1]. That
  30.    proposal specifies how a client may find a "resolver" for a URN. A
  31.    resolver is a database that can provide information about the
  32.    resource identified by a URN, such as the resource's location, a
  33.    bibliographic description, or even the resource itself. The protocol
  34.    used for the client to communicate with the resolver is not specified
  35.    in the NAPTR proposal.  Instead, the NAPTR resource record provides a
  36.    field that indicates the "resolution protocol" and "resolution
  37.    service requests" offered by the resolver.
  38.  
  39.    This document specifies the "THTTP" resolution protocol - a trivial
  40.    convention for encoding resolution service requests and responses as
  41.    HTTP 1.0 or 1.1 requests and responses.  The primary goal of THTTP is
  42.    to be simple to implement so that existing HTTP servers may easily
  43.    add support for URN resolution. We expect that the databases used by
  44.    early resolvers will be useful when more sophisticated resolution
  45.    protocols are developed later.
  46.  
  47. 1.0  Introduction:
  48. ==================
  49.  
  50.    The NAPTR specification[1] defined a new DNS resource record which
  51.    may be used to discover resolvers for Uniform Resource Identifiers.
  52.    That resource record provides the "services" field to specify the
  53.    "resolution protocol" spoken by the resolver, as well as the
  54.    "resolution services" it offers. Resolution protocols mentioned in
  55.  
  56.  
  57.  
  58. Daniel                        Experimental                      [Page 1]
  59.  
  60. RFC 2169                 HTTP in URN Resolution                June 1997
  61.  
  62.  
  63.    that specification are Z3950, THTTP, RCDS, HDL, and RWHOIS. (That
  64.    list is expected to grow over time). The NAPTR specification also
  65.    lists a variety of resolution services, such as N2L (given a URN,
  66.    return a URL); N2R (Given a URN, return the named resource), etc.
  67.  
  68.    This document specifies the "THTTP" (Trivial HTTP) resolution
  69.    protocol.  THTTP is a simple convention for encoding resolution
  70.    service requests and responses as HTTP 1.0 or 1.1 requests and
  71.    responses. The primary goal of THTTP is to have a URN resolution
  72.    protocol that can easily be added to existing HTTP daemons. Other
  73.    resolution protocols are expected to arise over time, so this
  74.    document serves a secondary purpose of illustrating the information
  75.    that needs to be specified for a URN resolution protocol. One of the
  76.    resolution protocols we expect to be developed is an extension of
  77.    HTTP with new methods for the resolution services. Therefore, we use
  78.    "THTTP" as the identifier for this protocol to leave "HTTP" for later
  79.    developments.
  80.  
  81.    The reader is assumed to be familiar with the HTTP/1.0 [2] and 1.1
  82.    [3] specifications. Implementors of this specification should be
  83.    familiar with CGI scripts, or server-specific interfaces, for
  84.    database lookups.
  85.  
  86. 2.0 General Approach:
  87. =====================
  88.  
  89.    The general approach used to encode resolution service requests in
  90.    THTTP is quite simple:
  91.  
  92.        GET /uri-res/<service>?<uri>  HTTP/1.0
  93.  
  94.    For example, if we have the URN "urn:foo:12345-54321" and want a URL,
  95.    we would send the request:
  96.  
  97.        GET /uri-res/N2L?urn:foo:12345-54321 HTTP/1.0
  98.  
  99.    The request could also be encoded as an HTTP 1.1 request. This would
  100.    look like:
  101.  
  102.        GET /uri-res/N2L?urn:foo:12345-54321 HTTP/1.1
  103.        Host: <whatever host we are sending the request to>
  104.  
  105.    Responses from the HTTP server follow standard HTTP practice. Status
  106.    codes, such as 200 (OK) or 404 (Not Found) shall be returned.  The
  107.    normal rules for determining cachability, negotiating formats, etc.
  108.    apply.
  109.  
  110.  
  111.  
  112.  
  113.  
  114. Daniel                        Experimental                      [Page 2]
  115.  
  116. RFC 2169                 HTTP in URN Resolution                June 1997
  117.  
  118.  
  119.    Handling these requests on the server side is easy to implement using
  120.    CGI or other, server-specific, extension mechanisms.  CGI scripts
  121.    will see the incoming URI in the QUERY_STRING environment variable.
  122.    Any %encoded characters in the URN will remain in their %encoded
  123.    state in that string. The script can take the URN, look it up in a
  124.    database, and return the requested information.
  125.  
  126.    One caveat should be kept in mind. The URN syntax document [4]
  127.    discusses the notion of lexical equivalance and requires that
  128.    resolvers return identical results for URNs that are lexically
  129.    equivalent. Implementors of this specification must be careful to
  130.    obey that rule. For example, the two requests below MUST return
  131.    identical results, since the URNs are lexically equivalent.
  132.        GET /uri-res/N2L?urn:cid:foo@huh.com HTTP/1.0
  133.        GET /uri-res/N2L?URN:CID:foo@huh.com HTTP/1.0
  134.  
  135. 3.0 Service-specific details:
  136. =============================
  137.  
  138.    This section goes through the various resolution services established
  139.    in the URN services document [5] and states how to encode each of
  140.    them, how the results should be returned, and any special status
  141.    codes that are likely to arise.
  142.  
  143.    Unless stated otherwise, the THTTP requests are formed according to
  144.    the simple convention above, either for HTTP/1.0 or HTTP/1.1. The
  145.    response is assumed to be an entity with normal headers and body
  146.    unless stated otherwise. (N2L is the only request that need not
  147.    return a body).
  148.  
  149. 3.1  N2L (URN to URL):
  150. ----------------------
  151.  
  152.    The request is encoded as above. The URL MUST be returned in a
  153.    Location:  header for the convienience of the user in the most common
  154.    case of wanting the resource. If the lookup is successful, a 30X
  155.    status line SHOULD be returned. HTTP/1.1 clients should be sent the
  156.    303 status code. HTTP/1.0 clients should be sent the 302 (Moved
  157.    temporarily) status code unless the resolver has particular reasons
  158.    for using 301 (moved permanently) or 304 (not modified) codes.
  159.  
  160.    Note that access controls may be applied to this, or any other,
  161.    resolution service request. Therefore the 401 (unauthorized) and 403
  162.    (forbidden) status codes are legal responses. The server may wish to
  163.    provide a body in the response to explain the reason for refusing
  164.    access, and/or to provide alternate information about the resource,
  165.    such as the price it will cost to obtain the resource's URL.
  166.  
  167.  
  168.  
  169.  
  170. Daniel                        Experimental                      [Page 3]
  171.  
  172. RFC 2169                 HTTP in URN Resolution                June 1997
  173.  
  174.  
  175. 3.2  N2Ls (URN to URLs):
  176. ------------------------
  177.  
  178.    The request is encoded as above. The result is a list of 0 or more
  179.    URLs. The Internet Media Type (aka ContentType) of the result may be
  180.    negotiated using standard HTTP mechanisms if desired. At a minimum
  181.    the resolver should support the text/uri-list media type.  (See
  182.    Appendix A for the definition of this media type). That media type is
  183.    suitable for machine-processing of the list of URLs. Resolvers may
  184.    also return the results as text/html, text/plain, or any other media
  185.    type they deem suitable.
  186.  
  187.    No matter what the particular media type, the result MUST be a list
  188.    of the URLs which may be used to obtain an instance of the resource
  189.    identified by the URN. All URIs shall be encoded according to the URI
  190.    specification [6].
  191.  
  192.    If the client has requested the result be returned as text/html or
  193.    application/html, the result should be a valid HTML docment
  194.    containing the fragment:
  195.    <UL>
  196.    <LI><A HREF="...url 1...">...url 1...</A>
  197.    <LI><A HREF="...url 2...">...url 2...</A>
  198.     etc.
  199.    </UL>
  200.    where the strings ...url n... are replaced by the n'th URL in the
  201.    list.
  202.  
  203. 3.3  N2R (URN to Resource):
  204. ---------------------------
  205.  
  206.    The request is encoded as above. The resource is returned using
  207.    standard HTTP mechanisms. The request may be modified using the
  208.    Accept: header as in normal HTTP to specify that the result be given
  209.    in a preferred Internet Media Type.
  210.  
  211. 3.4  N2Rs (URN to Resources):
  212. -----------------------------
  213.  
  214.    This resolution service returns multiple instances of a resource, for
  215.    example, GIF and JPEG versions of an image. The judgment about the
  216.    resources being "the same" resides with the naming authority that
  217.    issued the URN.
  218.  
  219.    The request is encoded as above. The result shall be a MIME
  220.    multipart/alternative message with the alternative versions of the
  221.    resource in seperate body parts. If there is only one version of the
  222.    resource identified by the URN, it MAY be returned without the
  223.  
  224.  
  225.  
  226. Daniel                        Experimental                      [Page 4]
  227.  
  228. RFC 2169                 HTTP in URN Resolution                June 1997
  229.  
  230.  
  231.    multipart/alternative wrapper. Resolver software SHOULD look at the
  232.    Accept: header, if any, and only return versions of the resource that
  233.    are acceptable according to that header.
  234.  
  235. 3.5  N2C (URN to URC):
  236. ----------------------
  237.  
  238.    URCs (Uniform Resource Characteristics) are descriptions of other
  239.    resources. This request allows us to obtain a description of the
  240.    resource identified by a URN, as opposed to the resource itself.  The
  241.    description might be a bibliographic citation, a digital signature, a
  242.    revision history, etc. This document does not specify the content of
  243.    any response to a URC request. That content is expected to vary from
  244.    one resolver to another.
  245.  
  246.    The format of any response to a N2C request MUST be communicated
  247.    using the ContentType header, as is standard HTTP practice. The
  248.    Accept: header SHOULD be honored.
  249.  
  250. 3.6  N2Ns (URN to URNs):
  251. ------------------------
  252.  
  253.    While URNs are supposed to identify one and only one resource, that
  254.    does not mean that a resource may have one and only one URN. For
  255.    example, consider a resource that has something like "current-
  256.    weather-map" for one URN and "weather-map-for-datetime-x" for another
  257.    URN. The N2Ns service request lets us obtain lists of URNs that are
  258.    believed equivalent at the time of the request. As the weathermap
  259.    example shows, some of the equivalances will be transitory, so the
  260.    standard HTTP mechanisms for communicating cachability MUST be
  261.    honored.
  262.  
  263.    The request is encoded as above. The result is a list of all the
  264.    URNs, known to the resolver, which identify the same resource as the
  265.    input URN. The result shall be encoded as for the N2Ls request above
  266.    (text/uri-list unless specified otherwise by an Accept: header).
  267.  
  268. 3.7  L2Ns (URL to URNs):
  269. ----------------------
  270.  
  271.    The request is encoded as above. The response is a list of any URNs
  272.    known to be assigned to the resource at the given URL. The result
  273.    shall be encoded as for the N2Ls and N2Ns requests.
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282. Daniel                        Experimental                      [Page 5]
  283.  
  284. RFC 2169                 HTTP in URN Resolution                June 1997
  285.  
  286.  
  287. 3.8  L2Ls (URL to URLs):
  288. ------------------------
  289.  
  290.    The request is encoded as described above. The result is a list of
  291.    all the URLs that the resolver knows are associated with the resource
  292.    located by the given URL. This is encoded as for the N2Ls, N2Ns, and
  293.    L2Ns requests.
  294.  
  295. 3.9  L2C (URL to URC):
  296. ----------------------
  297.  
  298.    The request is encoded as above, the response is the same as for the
  299.    N2C request.
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338. Daniel                        Experimental                      [Page 6]
  339.  
  340. RFC 2169                 HTTP in URN Resolution                June 1997
  341.  
  342.  
  343. Appendix A: The text/uri-list Internet Media Type
  344. =================================================
  345. [This appendix will be augmented or replaced by the registration of the
  346. text/uri-list IMT once that registration has been performed].
  347.  
  348.    Several of the resolution service requests, such as N2Ls, N2Ns, L2Ns,
  349.    L2Ls, result in a list of URIs being returned to the client. The
  350.    text/uri-list Internet Media Type is defined to provide a simple
  351.    format for the automatic processing of such lists of URIs.
  352.  
  353.    The format of text/uri-list resources is:
  354.  
  355.    1) Any lines beginning with the '#' character are comment lines
  356.       and are ignored during processing. (Note that '#' is a character
  357.       that may appear in URIs, so it only denotes a comment when it is the
  358.       first character on a line).
  359.    2) The remaining non-comment lines MUST be URIs (URNs or URLs), encoded
  360.       according to the URI specification RFC[6]. Each URI shall appear on
  361.       one and only one line.
  362.    3) As for all text/* formats, lines are terminated with a CR LF pair,
  363.       although clients should be liberal in accepting lines with only
  364.       one of those characters.
  365.  
  366.    In applications where one URI has been mapped to a list of URIs, such
  367.    as in response to the N2Ls request, the first line of the text/uri-
  368.    list response SHOULD be a comment giving the original URI.
  369.  
  370.    An example of such a result for the N2L request is shown below in
  371.    figure 1.
  372.  
  373.         # urn:cid:foo@huh.org
  374.         http://www.huh.org/cid/foo.html
  375.         http://www.huh.org/cid/foo.pdf
  376.         ftp://ftp.foo.org/cid/foo.txt
  377.  
  378.                Figure 1: Example of the text/uri-list format
  379.  
  380. Appendix B:  n2l.pl script
  381. ==========================
  382.  
  383.    This is a simple CGI script for the N2L resolution service. It
  384.    assumes the presence of a DBM database to store the URN to URL
  385.    mappings. This script does not specify standard behavior, it is
  386.    provided merely as a courtesy for implementors. In fact, this script
  387.    does not process incoming Accept: headers, nor does it generate
  388.    status codes. Such behavior should be part of a real script for any
  389.    of the resolution services.
  390.  
  391.  
  392.  
  393.  
  394. Daniel                        Experimental                      [Page 7]
  395.  
  396. RFC 2169                 HTTP in URN Resolution                June 1997
  397.  
  398.  
  399.     #!/bin/perl
  400.     # N2L  - performs urn to url  resolution
  401.  
  402.     $n2l_File = "...filename for DBM database...";
  403.  
  404.  
  405.     $urn = $ENV{'QUERY_STRING'} ;
  406.  
  407.     # Sanity check on the URN. Minimum length of a valid URN is
  408.     # 7 characters - "urn:", a 1-character Namespace ID, ":", and
  409.     # a 1-character namespace-specific string. More elaborate
  410.     # sanity checks should be part of a real resolver script.
  411.     if(length($urn)<7)
  412.     {
  413.         $error=1;
  414.     }
  415.  
  416.     if(!$error)
  417.     {
  418.         # Convert lexically equivalent versions of a URI into
  419.         # a canonical version for DB lookups.
  420.         $urn =~ s/^urn:([^:]*):(.*)$/sprintf("urn:%s:%s", lc $1, $2)/ie;
  421.  
  422.         dbmopen(%lu,$n2l_File,0444);
  423.         if($lu{$urn})
  424.         {
  425.             $url=$lu{$urn};
  426.             print STDOUT "Location: $url\n\n";
  427.         }else{
  428.             $error=2;
  429.         }
  430.         dbmclose(%lu);
  431.     }
  432.  
  433.     if($error)
  434.     {
  435.         print "Content-Type: text/html \n\n";
  436.         print "<html>\n";
  437.         print "<head><title>URN Resolution: N2L</title></head>\n";
  438.         print "<BODY>\n";
  439.         print "<h1>URN to URL resolution failed for the URN:</h1>\n";
  440.         print "<hr><h3>$urn</h3>\n";
  441.         print "</body>\n";
  442.         print "</html>\n";
  443.     }
  444.  
  445.     exit;
  446.  
  447.  
  448.  
  449.  
  450. Daniel                        Experimental                      [Page 8]
  451.  
  452. RFC 2169                 HTTP in URN Resolution                June 1997
  453.  
  454.  
  455. References:
  456. ===========
  457.  
  458.    [1] Daniel, Ron and Michael Mealling, RFC 2168, "Resolution of Uniform
  459.        Resource Identifiers using the Domain Name System", June 1997.
  460.  
  461.    [2] Berners-Lee, T, R. Fielding, H. Frystyk, RFC 1945, "Hypertext
  462.        Transfer Protocol -- HTTP/1.0", T. Berners-Lee, May 1996.
  463.  
  464.    [3] Fielding, R., J. Gettys, J.C. Mogul, H. Frystyk, T. Berners-Lee,
  465.        RFC 2068, "Hypertext Transfer Protocol -- HTTP/1.1", Jan. 1997.
  466.  
  467.    [4] Moats, R., RFC 2141, "URN Syntax", May 1997.
  468.  
  469.    [5] URN-WG. "URN Resolution Services". Work In Progress.
  470.  
  471.    [6] Berners-Lee, T., RFC 1630, "Universal Resource Identifiers in WWW:
  472.        A Unifying Syntax for the Expression of Names and Addresses of
  473.        Objects on the Network as used in the World-Wide Web", June 1994.
  474.  
  475. Security Considerations
  476. =======================
  477.  
  478.    Communications with a resolver may be of a sensitive nature. Some
  479.    resolvers will hold information that should only be released to
  480.    authorized users. The results from resolvers may be the target of
  481.    spoofing, especially once electronic commerce transactions are common
  482.    and there is money to be made by directing users to pirate
  483.    repositories rather than repositories which pay royalties to
  484.    rightsholders. Resolution requests may be of interest to traffic
  485.    analysts. The requests may also be subject to spoofing.
  486.  
  487.    The requests and responses in this draft are amenable to encoding,
  488.    signing, and authentication in the manner of any other HTTP traffic.
  489.  
  490. Author Contact Information:
  491. ===========================
  492.  
  493.    Advanced Computing Lab, MS B287
  494.    Los Alamos National Laboratory
  495.    Los Alamos, NM, USA, 87545
  496.    voice:  +1 505 665 0597
  497.    fax:    +1 505 665 4939
  498.    email:  rdaniel@lanl.gov
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506. Daniel                        Experimental                      [Page 9]
  507.  
  508.