[Ietf-not43] XML-RPC for an information service?
Stephane Bortzmeyer
bortzmeyer@nic.fr
Fri, 26 Jul 2002 11:53:10 +0200
--x+6KMIRAuhnl3hBn
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
On Wed, Jul 24, 2002 at 07:54:58AM -0700,
Ted Hardie <Ted.Hardie@nominum.com> wrote
a message of 51 lines which said:
> whether you are interested in writing a draft describing a CRISP
> service using XML-RPC.
Ask and thou shall receive. The draft is here, I'll provide a sample
implementation soon (anyone has one for IRIS, BTW?).
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).
--x+6KMIRAuhnl3hBn
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="draft-bortzmeyer-irpi.txt"
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]
--x+6KMIRAuhnl3hBn--