[Ietf-not43] XML-RPC for an information service?
Ted Hardie
Ted.Hardie@nominum.com
Fri, 26 Jul 2002 14:03:06 -0700
On Fri, Jul 26, 2002 at 11:53:10AM +0200, Stephane Bortzmeyer wrote:
> Ask and thou shall receive. The draft is here, I'll provide a sample
> implementation soon (anyone has one for IRIS, BTW?).
Thanks for putting together a draft; I'll review it in detail as
soon as I can, as, I am sure, will other members of the list.
> Feel free to comments, flame, suggest, etc. But do remember that my
> draft does not follow exactly the same ideas as IRIS: IRIS is more
> open, IRPI is less flexible, in order to be ready faster.
>
> > Now is the time to put forward other proposals, and a draft specifying
> > how those proposals meet the requirements would be great.
>
> Nice idea, but the requirments specify both things to be done at the
> protocol level and things to be done only at the implementation level
> (such as rate-limiting functions).
>
Hmm. If it does suggest something at the implementation level it's a
doc bug. The draft is meant to describe how the *service* should work
and that includes both on-the-wire and off the wire details.
Implementation details (like "use this Java package" or "use XML
namepsaces" or even "avoid buffer overuns") don't belong there.
If you see things in there that reach into implementation, please
note them to the list, so we can disucss removing them.
thanks,
Ted Hardie
>
>
>
>
>
> Network Working Group S. Bortzmeyer
> Internet-Draft AFNIC
> Expires: January 24, 2003 July 26, 2002
>
>
> Internet Registry Procedural Interface
> draft-bortzmeyer-irpi
>
> Status of this Memo
>
> This document is an Internet-Draft and is in full conformance with
> all provisions of Section 10 of RFC2026.
>
> Internet-Drafts are working documents of the Internet Engineering
> Task Force (IETF), its areas, and its working groups. Note that
> other groups may also distribute working documents as Internet-
> Drafts.
>
> Internet-Drafts are draft documents valid for a maximum of six months
> and may be updated, replaced, or obsoleted by other documents at any
> time. It is inappropriate to use Internet-Drafts as reference
> material or to cite them other than as "work in progress."
>
> The list of current Internet-Drafts can be accessed at http://
> www.ietf.org/ietf/1id-abstracts.txt.
>
> The list of Internet-Draft Shadow Directories can be accessed at
> http://www.ietf.org/shadow.html.
>
> This Internet-Draft will expire on January 24, 2003.
>
> Copyright Notice
>
> Copyright (C) The Internet Society (2002). All Rights Reserved.
>
> Abstract
>
> DRAFT OF DRAFT - DO NOT USE YET
>
> This document describes a procedural interface to query the database
> of an Internet Registry, for instance the various contacts for a
> domain.
>
> It is specified as an API for the XML-RPC protocol.
>
> It is intended to be simple and easy to implement. It is not a full
> solution to a complicated problem, but a way to get rid of whois more
> rapidly.
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 1]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> 1. Introduction
>
> The specification outlined in this document is based on the
> functional requirements described in the Internet Registry Directory
> requirments [5].
>
> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
> document are to be interpreted as described in RFC2119 [9].
>
> 1.1 General view
>
> IRPI is specified as an Application Programming Interface of XML-RPC
> [1]. XML-RPC is a way to call remote procedures, here we assume that
> the RPC callee will be on a Registry machine and that the caller
> wants to access information in the Registry.
>
> XML-RPC provides a way to marshall parameters, send them over HTTP ,
> retrieve the results and unmarshall them. The results can be
> structured. They can also be a fault, i.e. an exception. The rest
> of this document will assume familiarity with XML-RPC.
>
> 1.2 Transport
>
> XML-RPC specifies only one transport, HTTP. But it should be
> straightforward to make IRPI run over other non-standard transports
> like Jabber [8].
>
> 1.3 Objects
>
> IRPI has a fixed set of objects, unlike, for instance, IRIS [6].
> This is to make it simpler and easier to implement fast. A general-
> purpose Internet directory is out of scope.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 2]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> 2. The API
>
> 2.1 General rules for the server
>
> The server MUST implement the introspection API [7].
>
> The server MUST reacts gracefully (sending a fault) to calls of
> unknown methods.
>
> The server MUST accepts XML-RPC structs with unknown members (in
> order to extend the protocol in the future) and SHOULD ignore them.
> It MUST accepts XML-RPC arrays with more elements than expected and
> SHOULD ignore them.
>
> 2.2 General rules for the client
>
> The client SHOULD use the introspection API [7] before trying
> methods.
>
> The client MUST accepts XML-RPC structs with unknown members (in
> order to extend the protocol in the future) and SHOULD ignore them.
> It MUST accepts XML-RPC arrays with more elements than expected and
> SHOULD ignore them.
>
> 2.3 Credentials
>
> Credentials are always transmitted as XML-RPC structs. If they are
> empty (no members), it means the client has no credential to present.
> If they are non-empty, credentials always have the member "name" (a
> string) and they also have the possible members (at least one must be
> present):
>
> password: a plain password
>
> signature: TODO. Sign what, a concatenation of the parameters,
> and how, X509 or OpenPGP?
>
> If non-empty credentials are presented, they MUST be checked.
>
> TODO: describe how the server may use the underlying authentication
> (X509 client certificate if https). The server may also use other
> underlying information (such as the client's IP address) before
> deciding to send data or not.
>
> When the reply includes several named members, the server MAY choose
> to omit some for privacy reasons, depending on the client. The
> client MUST reacts gracefully to such missing members. TODO: a way
> for the client to discover if the information exists? Not sure it
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 3]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> would not help the stalker.
>
> 2.4 Exceptions
>
> Every procedure may return faults (raise exceptions). XML-RPC [1]
> does not define standard faults so we specify these (as faultCode and
> explanation, you may choose a different faultString):
>
> TODO: should we specify the fault for an nonexisting method?
>
> 400: Badly formed request
>
> 403: Access forbidden
>
> 404: No such object
>
>
> 2.5 Mandatory procedures
>
> All the mandatory procedures are prefixed by 'registry.'. Adding new
> procedures whould be done with the prefix 'registry-local.', in order
> to avoid name clashes.
>
> queryDomain (name <string>, credentials <struct>) returns
> <struct>. The struct has the following members (remember that
> some may be missing, either for privacy reasons or because this
> information has no meaning for a given registry):
>
> name <string>
>
> status <string> TODO: define statuses, using the enumerated
> values of EPP domain mapping [3]?
>
> registered <dateTime.iso8601>
>
> modified <dateTime.iso8601>
>
> expires <dateTime.iso8601>
>
> holder <string> TODO: name it registrant because EPP and IRIS
> call it that way?
>
> technical_c <string>
>
> administrative_c <string>
>
> billing_c <string>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 4]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> comments <string>
>
> TODO: maintainer like in RIPE-NCC registry?
>
> nameservers <array> This array is made of two-members structs,
> each struct has two strings, "name" and "address" (the second
> may be missing if the registry does not keep that information
> for a given nameserver).
>
> queryContact (handle <string>, credentials <struct>) returns
> <struct>. The returned struct has the following members (remember
> that some may be missing, either for privacy reasons or because
> this information has is not kept by a given registry):
>
> handle <string>
>
> registered <dateTime.iso8601>
>
> modified <dateTime.iso8601>
>
> status <string> TODO: define statuses, using the enumerated
> values of EPP contact mapping [4]?
>
> address <struct> This struct is made of:
>
> street <string> TODO: several strings?
>
> city <string>
>
> country <string>
>
> email <string>
>
> phone <string>
>
> fax <string>
>
> zipcode <string>
>
> TODO: maintainer like in RIPE-NCC registry?
>
> queryHost (info <struct>, credentials <struct>) returns <struct>.
> The input struct has one member, either "name" when you indicate
> the name of the host or "ipaddress" when you indicate its address.
> The returned struct has the following members:
>
> name <string>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 5]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> ipaddress <string>, may be missing if the registry does not
> keep it. TODO: and if several addresses?
>
>
> 2.6 Optional procedures
>
> All the optional procedures are prefixed by 'registry.'. Adding new
> procedures whould be done with the prefix 'registry-local.', in order
> to avoid name clashes.
>
> queryObject, query an obect without specifying the type. TODO:
> describe the API
>
> queryIPaddress, query an IP address, for a RIR or an IRR, although
> it is outside of the scope of our requirments [5].
>
> search, fuzzy search, with regexps or things like that. TODO:
> very dangerous for privacy.
>
>
> 2.7 Extending the API
>
> You can extend the above API in several ways:
>
> A registry can add new procedures, prefixed by 'registry-local.'.
>
> A registry can add new fields to structs passed or returned.
> These fields SHOULD be prefixed by 'x-'.
>
> Other extensions (such as adding parameters to procedures) are
> prohibited.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 6]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> 3. Internationalization Considerations
>
> Contact information, such as names and addresses may be stored in
> Unicode and sent back in whatever encoding the caller or the callee
> chose. The general rules of XML apply: UTF-8 and UTF-16 encoding
> MUST be supported by the parties. Other encodings SHOULD NOT be used
> unless there is a serious reason to believe they are supported by the
> other party (XML-RPC does not allow encoding negociation).
>
> IDN domain names MUST be in ACE encoded form. It is up to the client
> to translate.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 7]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> 4. Security considerations
>
> There are many privacy and authentication considerations at various
> places of that document. Apart from authentication, IRPI completely
> resides on the layers below for its security against passive
> eavesdropping or session replay. The security model in XML-RPC
> defers all the security to the transport layer. So you should use
> HTTPS and not HTTP is security is a concern. See also the
> requirments [5] for a general discussion of security of an Internet
> Registry Directory.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 8]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> References
>
> [1] UserLand Software, "The XML-RPC protocol", November 2001,
> <http://www.xml-rpc.com/>.
>
> [2] AdamsNames, "AdamsNames XMLRPC API", April 2001, <http://
> www.adamsnames.tc/api/xmlrpc.html>.
>
> [3] Hollenbeck, S., "Extensible Provisioning Protocol Domain
> Mapping", draft-ietf-provreg-epp-domain-04 (work in progress),
> January 2002.
>
> [4] Hollenbeck, S., "Extensible Provisioning Protocol Contact
> Mapping", draft-ietf-provreg-epp-contact-04 (work in progress),
> January 2002.
>
> [5] Newton, A., "Internet Registry Directory Requirements", draft-
> newton-ir-dir-requirments-00 (work in progress), June 2002.
>
> [6] Newton, A., "Internet Registry Information Service", draft-
> newton-iris-00 (work in progress), February 2002.
>
> [7] Dumbill, Edd., "XML-RPC introspection API", Unknown Unknown,
> <http://xmlrpc.usefulinc.com/doc/reserved.html>.
>
> [8] Adams, DJ., "Jabber RPC", September 2001, <http://
> www.pipetree.com/jabber/jrpc/>.
>
> [9] Bradner, S., "Key words for use in RFCs to Indicate Requirement
> Levels", RFC 2119, March 1997.
>
>
> Author's Address
>
> Stephane Bortzmeyer
> AFNIC
> Immeuble International
> Saint-Quentin en Yvelines cedex 78181
> France
>
> Phone: +33 1 39 30 83 46
> EMail: bortzmeyer@nic.fr
>
>
>
>
>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 9]
>
> Internet-Draft Internet Registry Procedural Interface July 2002
>
>
> Full Copyright Statement
>
> Copyright (C) The Internet Society (2002). All Rights Reserved.
>
> This document and translations of it may be copied and furnished to
> others, and derivative works that comment on or otherwise explain it
> or assist in its implementation may be prepared, copied, published
> and distributed, in whole or in part, without restriction of any
> kind, provided that the above copyright notice and this paragraph are
> included on all such copies and derivative works. However, this
> document itself may not be modified in any way, such as by removing
> the copyright notice or references to the Internet Society or other
> Internet organizations, except as needed for the purpose of
> developing Internet standards in which case the procedures for
> copyrights defined in the Internet Standards process must be
> followed, or as required to translate it into languages other than
> English.
>
> The limited permissions granted above are perpetual and will not be
> revoked by the Internet Society or its successors or assigns.
>
> This document and the information contained herein is provided on an
> "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
> TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
> BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
> HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
> MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
>
> Acknowledgement
>
> Funding for the RFC Editor function is currently provided by the
> Internet Society.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> Bortzmeyer Expires January 24, 2003 [Page 10]
>