
				mDNkit
		-- multilingual domain name toolkit --
			    version 2.2.3
	       Japan Network Information Center (JPNIC)


Table of contents of this file:

  1. Overview
  2. Directory structure of this distribution
  3. Applying patches
  4. Supported systems
  5. Contact information

See the file INSTALL for compilation and installation instructions.
See the file NEWS for a list of major changes in the current release.


1. Overview

mDNkit is a toolkit for handling multilingualized/internationalized 
domain names.  To handle such names, the following features are required:

    + Encoding conversion
	Multilingualized domain names have to be converted from
	the encoding application uses (local encoding) to
	the encoding used for name resolution (IDN encoding), and
	vice versa.  Since domain names in IDN encoding just look
	like good old ASCII domain names, the encoding is also known
	as ASCII-compatible encoding (ACE).

    + NAMEPREP
	Name preparation of domain names before converting to
	IDN encoding.  Basically this is a normalization process
	of the domain names.

These conversion/nameprep processes to domain names have to be
performed before they are sent to DNS servers.  And since the
processed domain names (in IDN encoding) consist of only legal ASCII
characters, no changes are required to DNS servers.
	
mDNkit provides several ways for adding these features.

This kit consists of following components.

    + library for handling multilingual domain names (libmdn)
	This is a library implementing encoding conversion and
	nameprep.  The library provides easy-to-use API for these
	features, so it should be easy to add capability of handling
	multilingual domain name to your applications using this
	library.
	This library is also used for implementing various commands in
	this toolkit (such as mdnsproxy and mdnconv).

    + DNS proxy server (mdnsproxy)
	This works as a fake DNS server for the clients.  It receives
	DNS request containing domain names in the client's local
	encoding (e.g. Shift_JIS), translates them into the encoding
	on DNS protocol (e.g. UTF-8 or RACE), and forwards to the real
	DNS server.  Also the response from the server is converted
	back to the client's local encoding and returned.  See
	``2. using mdnsproxy'' below.

    + a command dynamically adds MDN feature to unix applications (runmdn)
	This command enables normal applications to handle
	multilingual domain names by dynamically attaching special
	library to them.  See ``3. using runmdn'' below.

    + a patch for BIND-9 that adds MDN capability
	This patch adds MDN capability to BIND9.  It adds encoding
	conversion and nameprep features to `dig', `host' and
	`nslookup'.  With the patch, those commands become capable of
	multilingual domain names.

    + mDN wrapper for Windows applications
        On windows, name resolving request is passed to WINSOCK DLL. So,
        replacing WINSOCK DLL with multi-lingual domain name version 
        makes legacy windows applications compatible with mDN.  This is
	wrapper DLL for WINSOCK's name resolving functions. See
	``4. using mDN wrapper'' below.

    + a codeset converter for named.conf/zone master files (mdnconv)
	This is a codeset (encoding) converter specially designed for
	converting named.conf and zone master files from your local
	encoding (e.g. EUC-JP) to the encoding which internationalized
	DNS servers employ (e.g. RACE).

    + a patch that makes BIND-8 8-bit through
	This is needed in order for named and resolver to handle
	non-ascii domain names encoded in local encoding or UTF-8.
	The patch is rudimentary; it makes almost any byte sequence
	legal as a domain name (which is what 8-bit through is for).

    + a patch for making Squid cache server 8-bit through
	This is a simple patch that disables Squid's validity check
	for host name part in URLs.  Without this patch, Squid rejects
	URLs containing multilingual domain name (correctly).


This kit provides several ways to handle multilingual domain names
using above components.

 ** 1. using API
    This is the preferred way to handle multilingual domain names,
    applications are required to explicitly call the name conversion
    API mDNkit provides.

				  domain name
   +-----------+-------+--------+   in ACE
   |           |       |        |  encoding  +------------+
   |  client   |  mdn  |system's|----------->| DNS server |
   |application|library|resolver|<-----------|            |
   |           |       |        |            +------------+
   +-----------+-------+--------+ 

 ** 2. using mdnsproxy
    In case the application cannot be modified to use the above API,
    you can still be able to use multilingual domain names using
    mdnsproxy, provided that the application uses 8bit-through
    resolver.

		  domain name      encoding      domain name
		   in local     conversion and     in ACE
   +------------+  encoding        nameprep       endoding
   |   client   |             +----------------+             +----------+
   |application |------------>|   mdnsproxy    |------------>|DNS server|
   |    with    |<------------|                |<------------|          |
   |8bit through|             +----------------+             +----------+
   |  resolver  |
   +------------+

 ** 3. using runmdn
    Or if the client application dynamically links resolver API (such as
    gethostbyname) and the OS supports certain features, you can use
    runmdn.  By replacing the resolver API with a version which performs
    encoding conversion and nameprep, runmdn enables normal applications
    to resolve multilingual domain names.

		   encoding      domain name
		conversion and     in ACE
		   nameprep       encoding
   +-----------+-------------+                 +----------+
   |   client  | dynamically |---------------->|DNS server|
   |application|  attached   |<----------------|          |
   |           |   library   |                 +----------+
   +-----------+-------------+

 ** 4. using mDN wrapper
    By wrapping WINSOCK DLL, mDN Wrapper enables Windows applications
    to resolve multilingual domain names.

                domain name    nameprep           domain name
                 in local     and encoding          in ACE
   +-----------+ encoding      conversion          encoding
   |  legacy   |             +---------+---------+           +----------+
   |  windows  |------------>|   mDN   | orignal |---------->|DNS server|
   |  network  |<------------| wrapper | winsock |<----------|          |
   |application|             +---------+---------+           +----------+
   +-----------+


2. Directory structure of this distribution

Below is a directory structure of this distribution with some 
important files and their brief description.

    +README		this file
    +README.ja		.. in Japanese
    +INSTALL		compilation and installation instructions.
    +INSTALL.ja		.. in Japanese
    +DISTFILES		list of files in this distribution
    +NEWS		what's new in this version
    +ChangeLog		list of changes
    +Makefile.in	toplevel makefile template
    +configure		a `configure' script
    +include/
    |	+config.h.in	template header file for configuration
    |	+mdn/		header files for mdn library
    +lib/		source directory for mdn library
    +mdnsproxy/		source directory for DNS proxy server
    +patch/		various patch files
    |	+bind8/		bind-8 patch directory
    |	+bind9/		bind-9 patch directory
    |   +libiconv/	libiconv patch directory
    |	+squid/		squid patch directory
    +tools/		source directory for tools
    |	+mdnconv/	source directory for codeset converter
    |   +runmdn/	source directory for runmdn command
    +util/		utilities
    +wsock/		source directory for mDN wrapper


3. Applying patches

This distribution also contains patches for BIND 9.1.3, BIND 8.2.3 and
Squid 2.4.STABLE1.  The top of these patch files describe how to apply
the patch and (re)install.

Note that on Solaris, "patch" command that comes with the system
sometimes doesn't work correctly.  You may want to install the GNU
version of the command (http://www.gnu.org/software/patch/) and use
it.


4. Supported systems

We've had successful builds on the following systems:

    -------------------------------------------------------------------
    OS                      iconv library      configure options
    ===================================================================
    FreeBSD 4.4-RELEASE     GNU libiconv       --with-libiconv
    for Intel               1.6.1
    -------------------------------------------------------------------
    FreeBSD 3.5.1-RELEASE   GNU libiconv       --with-libiconv
    for Intel               1.7
    -------------------------------------------------------------------
    NetBSD 1.5.2            GNU libiconv       --with-libiconv
    for Intel               1.7
    -------------------------------------------------------------------
    Red Hat Linux 7.1       standard library   none
    for Intel               (glibc)
    -------------------------------------------------------------------
    Red Hat Linux 7.0       standard library   none
    for Intel               (glibc)
    -------------------------------------------------------------------
    Debian/GNU Linux 2.2r3  standard library   none
    for Intel               (glibc)
    -------------------------------------------------------------------
    Solaris 2.6             standard library   none
    for Sparc               (libc)
    -------------------------------------------------------------------
    Windows2000             GNU libiconv       --with-libiconv
    (cygwin-1.3.2) *1       1.7
    -------------------------------------------------------------------

    *1: Only mdnconv can work on that system.

The latest information about supported/unsupported systems will be
found at the mDNkit FAQ page linked from:

	http://www.nic.ad.jp/jp/research/idn/


5. Contact information

Please see

	http://www.nic.ad.jp/jp/research/idn/

for the latest news about this kit.
Bug reports and comments on this kit should be sent to

	mdnkit-bugs@nic.ad.jp
and
	idn-cmt@nic.ad.jp

respectively.


; $Id: README,v 1.1 2002/01/02 02:46:21 marka Exp $
