mdn.conf(5)

NAME
mdn.conf - configuration file for internationalized domain name handling

SYNOPSIS
@sysconfdir@/mdn.conf

DESCRIPTION
mdn.conf is a configuration file for mDNkit, which is a toolkit for handling internationalized/multilingualized domain names.

To use internationalized domain names in DNS or other protocols, they must be converted to an appropriate format before further processing. In mDNkit, this conversion process is comprised of the following tasks.

1.  Convert the given domain name in application's local codeset to Unicode, and vice versa.

2.  Map certain characters in the name to period character so that they are treated as the domain name delimiter (delimiter mapping).

3.  Map certain characters in the name to other characters or chracter sequences, according to a mapping rule determined by its top level domain (TLD).

4.  Perform NAMEPREP, which is a starndard name preparation process for internationalized domain names. This process is composed of the tree steps called mapping, normalization and prohibited character checking.

5.  Convert the nameprepped name to IDN encoding, which is the standard encoding for internationalized domain names (also known as ASCII-compatible encoding, ACE), and vice versa.

mdn.conf specifies the parameters for these tasks, such as:

    -   the encoding of internationalized domain names (IDN encoding).

    -   NAMEPREP schemes.

    -   the alternative encoding which is used in case the domain name in the IDN encoding cannot be convertible to the local encoding.

SYNTAX
mdn.conf is a simple text file, and each line in the file (other than comment lines, which begin with ``#'', and empty lines) forms an entry of the following format:

    keyword value..
."

IDN-ENCODING ENTRY
IDN encoding entry specifies the encoding name (codeset name) which is used as the encoding of multilingualized domain names by resolvers and DNS servers.

The syntax of this entry is:

    idn-encoding encoding

encoding is the encoding name to be used, and any of the following names can be specified.

    •   ``RACE''

    •   ``BRACE''

    •   ``LACE''

    •   ``DUDE''

    •   ``UTF-6''

    •   ``AltDUDE''

    •   ``AMC-ACE-M''

    •   ``AMC-ACE-O''

    •   ``AMC-ACE-R''

    •   ``UTF-8''

    •   Codeset names which iconv_open() library function accepts. Please consult iconv() documentation for the available codesets.

    •   Any alias names for the above, defined by the alias file. (See section ``ENCODING-ALIAS-FILE ENTRY'')

The standard encoding is being discussed by IETF IDN working group.

NAMEPREP ENTRY
Nameprep entry specifies the version of NAMEPREP, which is a specification of ``canonicalization'' process of multilingual domain name before it is converted to the IDN encoding. It is also being discussed by IETF IDN working group.

The syntax of this entry is:

    nameprep version

version is the version name of NAMEPREP specification, and currently the following versions can be specified.

    •   ``nameprep-02''
        This version refers to Internet Draft ``draft-ietf-idn-nameprep-02.txt''.

    •   ``nameprep-03''
        This version refers to Internet Draft ``draft-ietf-idn-nameprep-03.txt''.

The NAMEPREP process consists of the following 3 subprocesses.

1.  mapping, which maps certain characters in a name to other characters, possibly none.

2.  normalization, which replaces character variants in a name to a unique one.

3.  prohibited/unassigned character checking, which detects invalid characters in a name.

This entry is a shorthand for specifying all of them at once. Actually,

    nameprep version

has the same effect of specifying following 4 entries.

    nameprep-map version
    nameprep-normalize version
    nameprep-prohibit version
    nameprep-unassigned version

If both this entry and more-specific entries above are specified, more-specific ones take precedence.

NAMEPREP-MAP ENTRY
Mapping entry specifies the mapping scheme of NAMEPREP process. The syntax of this entry is:

    nameprep-map scheme [scheme..]

scheme specifies the mapping scheme, and currently available schemes are:

    nameprep-02
        Specify mapping defined by NAMEPREP-02 draft.

    nameprep-03
        Specify mapping defined by NAMEPREP-03 draft.

    filemap:pathname
        Specify mapping defined by the file pathname. See ``MAPFILE FORMAT'' for the format of this file.

More than one scheme can be specified. If multiple schemes are specified, they are applied in turn.

NAMEPREP-NORMALIZE ENTRY
Normalization entry specifies the normalization schemes which should be applied to the domain names before sending them to name servers. The syntax of this entry is:

    nameprep-normalize scheme [scheme..]

scheme is the normalization scheme, and following shows the currently available schemes:

    nameprep-02
        Synonim for unicode-form-kc.

    nameprep-03
        Synonim for unicode-form-kc.

    ascii-lowercase
        Convert ASCII uppercase letters to lowercase.

    ascii-uppercase
        Convert ASCII lowercase letters to uppercase.

    unicode-lowercase
        Convert Unicode uppercase letters to lowercase, based on ``Unicode Technical Report #21: Case Mappings''. Note that only locale-independent conversion is supported.

    unicode-uppercase
        Convert Unicode lowercase letters to uppercase, based on ``Unicode Technical Report #21: Case Mappings''. Note that only locale-independent conversion is supported.

    unicode-foldcase
        Perform Unicode case-folding for case-less string matching, which is also defined by ``Unicode Technical Report #21: Case Mappings''.

    unicode-form-c
        Perform Unicode normalization called ``Unicode Normalization Form C''.

    unicode-form-kc
        Perform Unicode normalization called ``Unicode Normalization Form KC''.

More than one schemes can be specified. If multiple schemes are specified, they are applied in turn.

NAMEPREP-PROHIBIT ENTRY
Prohibit entry specifies the prohibited characters in the NAMEPREP process. The syntax of this entry is:

    nameprep-prohibit set [set..]

set specifies the set of prohibited characters. Currently following sets can be specified.

    nameprep-02
        Specify set of prohibited characters defined by NAMEPREP-02 draft.

    nameprep-03
        Specify set of prohibited characters defined by NAMEPREP-03 draft.

    fileset:pathname
        Specify set of prohibited characters defined by the file pathname. See ``SETFILE FORMAT '' for the format of this file.

When more than one sets are specified, a character is considered prohibited if it belongs to any of those sets.

NAMEPREP-UNASSIGNED ENTRY
Unassigned entry specifies the unassigned codepoints in the NAMEPREP process. The syntax of this entry is:

    nameprep-unassigned set [set..]

set specifies the set of unassigned characters. Currently following sets can be specified.

    nameprep-02
        Specify set of unassigned characters defined by NAMEPREP-02 draft.

    nameprep-03
        Specify set of unassigned characters defined by NAMEPREP-03 draft.

    fileset:pathname
        Specify set of unassigned characters defined by the file pathname. See ``SETFILE FORMAT '' for the format of this file.

When more than one sets are specified, a character is considered unassigned if it belongs to any one of those sets.

ALTERNATE-ENCODING ENTRY
mDNkit provides local codeset coversion feature, and in domain name decoding process, multilingual domain names are converted to the local codeset the application is using. However, it is possible that the conversion fails because some characters in the domain names have no mapping to the local codeset. This occurs, for example, when a Japanese application using Japanese codeset receives a DNS reply containing Chinese characters which are not included in the Japanese character set.

Alternative encoding entry specifies the codeset name to be used instead of the local codeset in case the above problem happens.

The syntax of this entry is:

    alternate-encoding encoding

encoding is the name of the codeset. It must be an ASCII-compatible encoding (ACE) such as ``RACE''.

ENCODING-ALIAS-FILE ENTRY
Encoding alias entry specifies the file containing codeset name aliases. The aliases can be used just as the real names.

The syntax of this entry is:

    encoding-alias-file pathname

pathname specifies the path name of the alias file. The alias file is a simple text file, consisting of lines of the form:

    alias-name name

alias-name is the alias name to be defined, and name is the real name or another alias name.

LOCAL-MAP ENTRY
This entry specifies localized mapping phase before NAMEPREP takes place. Different mapping rules can be specified for each TLD (top-level domain). For example, you can have one mapping for ``.tw'' domain, and another for ``.jp'' domain.

The syntax of this entry is:

    local-map tld scheme [scheme..]

tld specifies the TLD to which the mapping rule is to be applied, and scheme specifies the mapping scheme. Available schemes are same as nameprep-map entry. See ``NAMEPREP-MAP ENTRY'' for details.

There are two special tlds for specifying the mapping rule for local domain names (domain names without any dots in them), and the default mapping rule. If tld is ``-'', it matches domain names which do not contain any dots. If tld is ``.'', it matches any domain names which don't match to any other mapping rules specified by ``local-map'' entries.

DELIMITER-MAP ENTRY
This entry specifies characters to be regarded as the domain name delimiter, which is period (``.'').

The syntax of this entry is:

    delimiter-map codepoint [codepoint..]

codepoint specifies the Unicode codepoint value (in hexadecimal format) for the character to be regarded as a delimiter.

MAPFILE FORMAT
A mapfile defines a set of character mapping rules. It can define unconditional one-character to N-character-sequence (N can be 0, 1 or more) mappings.

A mapfile is a simple text file, and each line specifies a single mapping. Each line is of the form:

    src-codepoint; mapped-codepoint-seq;

src-codepoint indicates source character of the mapping, and must be a Unicode codepoint value in hexadecimal string. mapped-codepoint-seq is a sequence of characters which is the outcome of the mapping, and must be a (possibly empty) list of Unicode codepoint values in hexadecimal string, separated by spaces.

Lines which begin with ``#'' are treated as comments and ignored.

A sample mapfile is shown below.

    # map "A" to "a"
    0041; 0061;
    # map "#" to nothing
    0023; ;
    # map "@" to "at"
    0040; 0061 0074;

SETFILE FORMAT
A setfile defines a set of characters, and is used for specifying prohibited/unasssigned characters. The set is specified by enumerating either individual character codepoints or ranges of character codepoints.

A setfile is also a simple text file, and each line specifies a single character codepoint, or a range of codepoints as follows:

    codepoint
    codepoint-start-codepoint-end

codepoint, codepoint-start and codepoint-end are Unicode codepoint values in hexadecimal format.

Lines which begin with ``#'' are treated as comments and ignored.

A sample setfile is shown below.

    # Prohibit tilde
    007E
    # Prohibit control characters
    0000-001F
    007F-000F
    # Prohibit all the Unicode characters beyond BMP
    10000-10FFFF

LOCAL CODESET
mdn.conf does not have an entry to specify the local codeset, since it is determined from the application's current locale information. So each application can use different local codeset.

Although mDNkit tries hard to find out the local codeset, sometimes it fails. For example, there are applications which use non-ASCII codeset but work in C locale. In this case, you can specify the application's local codeset by an environment variable ``MDN_LOCAL_CODESET''. Just set the codeset name (or its alias name) to the variable, and mDNkit will use the codeset as the local one, regardless of the locale setting.

SAMPLE CONFIGURATION
The following shows a sample configuration file.

    #
    # a sample configuration.
    #
    # Use RACE as the IDN encoding.
    idn-encoding RACE
    # Use draft-ietf-idn-nameprep-03.txt as NAMEPREP.
    nameprep nameprep-03
    # Use BRACE as the alternative encoding.
    alternate-encoding BRACE
    # Regard U+3002 (IDEOGRAPHIC FULL STOP) and U+FF0E
    # (FULLWIDTH FULL STOP) as the domain component delimiter
    # as well as ``.''.
    delimiter-map U+3002 U+FF0E
    # Perform Japanese-specific mapping for .jp domain.
    # assuming /usr/local/lib/mdnkit/jp-map contains the mapping.
    local-map .jp filemap:/usr/local/lib/mdnkit/jp-map

FILES
@sysconfdir@/mdn.conf
@sysconfdir@/mdn.conf.sample - sample configuration with comments

SEE ALSO
iconv(3), mdnsproxy(8)