--- name: "libmdnlite" section: "3" platform: "linux" package: "libmdnkit-dev" version: "2.4-4" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/libmdnlite" --- # libmdnlite(3) Mulitilingual Domain Name Handling Libraries ## NAME libmdn, libmdnlite - Mulitilingual Domain Name Handling Libraries ## SYNOPSIS ``` #include mdn_result_t mdn_nameinit(void) mdn_result_t mdn_encodename(int actions, const char *from, char *to, size_t tolen) mdn_result_t mdn_decodename(int actions, const char *from, char *to, size_t tolen) mdn_result_t mdn_enable(int on_off) char * mdn_result_tostring(mdn_result_t result) ``` ## OVERVIEW The **libmdn** and **libmdnlite** libraries support various manipulations of multilingual domain names, including: - \- encoding convesion - \- name preparation They are designed according to IDNA framework where each application must do necessary preparations for the multilingual domain names before passing them to the resolver. To help applications do the preparation, the libraries provide easy-to-use, high-level interface for the work. Both libraries provide almost the same API. The difference between them is that **libmdn** internally uses *iconv* function to provide encoding conversion from UTF-8 to the local encoding (such as iso-8859-1, usually determined by the current locale), and vise versa. **libmdnlite** is lightweight version of libmdn. It assumes local encoding is UTF-8 so that it never uses *iconv*. This manual describes only a small subset of the API that the libraries provide, most important functions for application programmers. For other API, please refer to the mDNkit's specification document (which is not yet available) or the header files typically found under \`/usr/local/include/mdn/' on your system. ## DESCRIPTION The **mdn\_nameinit** function initializes the whole library, and reads the default configuration file **mdn.conf**, which includes configuration parameters for multilingual domain name preparation. If **mdn\_nameinit** is called more than once, the library initialization will take place only at the first call while the configuration file will be (re)read at every call. If there are no errors, **mdn\_nameinit** returns **mdn\_success**. Otherwise, the returned value indicates the cause of the error. See the section \`\`RETURN VALUES'' below for the error codes. Usually you don't have to call this function explicitly because it is implicitly called when **mdn\_encodename** or **mdn\_decodename** is first called without prior calling of **mdn\_nameinit**. **mdn\_encodename** function performs name preparation and encoding conversion on the multilingual domain name specified by *from*, and stores the result to *to*, whose length is specified by *tolen*. *actions* is a bitwise-OR of the following macros, specifying which subprocesses in the encoding process are to be employed. ``` MDN_LOCALCONV Local encoding <-> UTF-8 conversion MDN_DELIMMAP Delimiter mapping MDN_LOCALMAP Local mapping MDN_NAMEPREP NAMEPREP (inculding unassigned codepoint check) MDN_IDNCONV UTF-8 <-> ACE conversion ``` Details of this encoding process can be found in the section \`\`NAME ENCODING''. For ordinary application, also the **MDN\_ENCODE\_APP** macro is provided for the convenience. It is eqivalent to ``` MDN_LOCALCONV|MDN_DELIMMAP|MDN_LOCALMAP|MDN_NAMEPREP|MDN_IDNCONV ``` in libmdn, and eqivalent to ``` MDN_DELIMMAP|MDN_LOCALMAP|MDN_NAMEPREP|MDN_IDNCONV ``` in libmdnlite. **mdn\_decodename** function performs the reverse of **mdn\_encodename**. It converts the multilingual domain name given by *from*, which is represented in a special encoding called ACE, to the application's local codeset and stores into *to*, whose length is specified by *tolen*. *actions* specifies which subprocesses in decoding process take place, as in **mdn\_encodename**, except that only `MDN_IDNCONV`, `MDN_NAMEPREP` and `MDN_LOCALCONV` are allowed. Details of this decoding process can be found in the section \`\`NAME DECODING''. For ordinary application, also the **MDN\_DECODE\_APP** macro is provided for the convenience. It is eqivalent to ``` MDN_IDNCONV|MDN_NAMEPREP|MDN_LOCALCONV ``` in libmdn, and eqivalent to ``` MDN_IDNCONV|MDN_NAMEPREP ``` in libmdnlite. All of the functions above return error code of type **mdn\_result\_t**. All codes other than **mdn\_success** indicates some kind of failure. **mdn\_result\_tostring** function takes an error code *result* and returns a pointer to the corresponding message string. ## NAME ENCODING Name encoding is a process that transforms the specified multilingual domain name to a certain string suitable for name resolution. The name encoding process consists of the following steps. - (1) Encoding Conversion (local codeset to UCS) Convert the encoding of the given domain name to Unicode/ISO10646 UTF-8 format string.\ This step is performed if *actions* given to **mdn\_encodename** contains **MDN\_LOCALCONV** or equals to **MDN\_ENCODE\_APP**. Note that libmdnlite doesn't support this step.\ The source encoding must be one of the two encodings below: - \- The application's local encoding (codeset). - \- ACE specified by the configuration file. The latter is suppored because name decoding process may produce ACE strings when its attempt to convert to the local encoding fails. See the section \`\`NAME DECODING'' for details. - (2) Local mapping Apply any locale/language-specific mapping. This process is further divided into two subprocesses: - (2-1) Delimiter mapping Map certain characters to the domain name delimiter (U+002E). This step is performed if *actions* given to **mdn\_encodename** contains **MDN\_DELIMMAP** or equals to **MDN\_ENCODE\_APP**. - (2-2) Local mapping based on TLD Apply character mapping whose rule is determined by the TLD of the name.\ This step is performed if *actions* given to **mdn\_encodename** contains **MDN\_LOCALMAP** or equals to **MDN\_ENCODE\_APP**. - (3) NAMEPREP Perform name preparation (NAMEPREP), which is a standard process for name canonicalizaion of multilingual domain names. **mdn\_encodename** performs mapping, normalization, prohibited character check and unassigned codepoint check in that order, as NAMEPREP mentions.\ This process includes checking of characters which are not allowed in multilingual domain names. This step is performed if *actions* given to **mdn\_encodename** contains **MDN\_NAMEPREP** or equals to **MDN\_ENCODE\_APP**. - (4) Encoding conversion (UCS to ACE) Convert the NAMEPREPed name to a special encoding designed for representing multilingual domain names.\ The encoding is also known as ACE (ASCII Compatible Encoding) since a string in the encoding is just like a traditional ASCII domain name consisting of only letters, numbers and hyphens. This step is performed if *actions* given to **mdn\_encodename** contains **MDN\_IDNCONV** or equals to **MDN\_ENCODE\_APP**. There are many configuration parameters for this process, such as the ACE or the local mapping rules. These parameters are read from the default mDNkit's configuration file, **mdn.conf**. See [mdn.conf(5)](/mdn.conf/5.md) for details. ## NAME DECODING Name decoding is a reverse process of the name encoding. It transforms the specified multilingual domain name in a special encoding suitable for name resolution to the normal name string in the application's current codeset. However, name encoding and name decoding are not symmetric. Name decoding doesn't perform local mapping. Both name encoding and decoding do NAMEPREP, but decoding does it to verfiy a name, while encoding does it to normalize a name. The name decoding process consists of the following steps. - (1) Encoding conversion (ACE to UCS) Convert the encoding of the given domain name from a special one designed for representing multilingual domain names (ACE) to Unicode/ISO10646 UTF-8. This step is performed if *actions* given to **mdn\_decodename** contains **MDN\_IDNCONV** or equals to **MDN\_DECODE\_APP**. - (2) NAMEPREP check Perform name preparation (NAMEPREP) as also done in name encoding, and compare the result of NAMEPREP and the given UCS name. If the NAMEPREP is failed or the names are different, the given name is considered as invalid domain name. It contains a character which is never seen in a NAMEPREPed domain name. This step is performed if *actions* given to **mdn\_decodename** contains **MDN\_NAMEPREP** or equals to **MDN\_DECODE\_APP**. - (3) Encoding conversion (UCS to local codeset) Convert the encoding of the name from UTF-8 to the application's local codeset.\ The local codeset is determined by the application's locale. However, it is possible that the conversion to the application's local codeset fails because the name includes some characters which don't have mappings to the local codeset. In this case, libmdn tries instead to convert to ACE specified by the configuration file. \ This step is performed if *actions* given to **mdn\_decodename** contains **MDN\_LOCALCONV** or equals to **MDN\_DECODE\_APP**. Note that libmdnlite doesn't support this step. The configuration parameters for this process, are also read from the configuration file **mdn.conf**. ## MDN\_DISABLE If the **MDN\_DISABLE** environ variable is defined at run-time, the libraries disable mulitilingual domain name support, by default. In this case, **mdn\_encodename** and **mdn\_decodename** don't encode/decode an input name, but instead they simply ouput a copy of the input name as the result of encoding/decoding. If your application should always enable mulitilingual domain name support regardless of definition of **MDN\_DISABLE**, call ``` mdn_enable(1) ``` before performing encoding/decoding. ## RETURN VALUES Most of the API functions return values of type **mdn\_result\_t** in order to indicate the status of the call. The following is a complete list of the status codes. Note that some of them are never returned by the functions described in this manual. - **mdn\_success** Not an error. The call succeeded. - **mdn\_notfound** Specified information does not exist. - **mdn\_invalid\_encoding** The encoding of the specified string is invalid. - **mdn\_invalid\_syntax** There is a syntax error in the configuration file. - **mdn\_invalid\_name** The specified name is not valid. - **mdn\_invalid\_message** The specified DNS message is not valid. - **mdn\_invalid\_action** The specified action contains invalid flags. - **mdn\_invalid\_codepoint** The specified Unicode code point value is not valid. - **mdn\_buffer\_overflow** The specified buffer is too small to hold the result. - **mdn\_noentry** The specified key does not exist in the hash table. - **mdn\_nomemory** Memory allocation using malloc failed. - **mdn\_nofile** The specified file could not be opened. - **mdn\_nomapping** Some characters do not have the mapping to the target character set. - **mdn\_context\_required** Context information is required. - **mdn\_prohibited** The specified string contains some prohibited characters. - **mdn\_failure** Generic error which is not covered by the above codes. ## EXAMPLES To get the address of a multilingual domain name in the application's local codeset, use **mdn\_encodename** to convert the name to the format suitable for passing to resolver functions. ``` mdn_result_t r; char ace_name[256]; struct hostent *hp; ... r = mdn_encodename(MDN_ENCODE_APP, name, ace_name, sizeof(ace_name)); if (r != mdn_success) { fprintf(stderr, "mdn_encodename failed: %s\n", mdn_result_tostring(r)); exit(1); } hp = gethostbyname(ace_name); ... ``` To decode the multilingual domain name returned from a resolver function, use **mdn\_decodename**. ``` mdn_result_t r; char local_name[256]; struct hostent *hp; ... hp = gethostbyname(name); r = mdn_decodename(MDN_DECODE_APP, hp->h_name, local_name, sizeof(local_name)); if (r != mdn_success) { fprintf(stderr, "mdn_decodename failed: %s\n", mdn_result_tostring(r)); exit(1); } printf("name: %s\n", local_name); ... ``` ## COMPATIBILITY **mdn\_encodename** and **mdn\_decodename** in mDNkit version 2.x prior to 2.4 provide the **MDN\_UNASCHECK** process macro for unassigned codepoint check. However, beginning with mDNkit version 2.4, the **MDN\_NAMEPREP** process macro also performs the unassigned check. To perform NAMEPREP without the unassigned check on mDNkit 2.4 or later, specify the actions: ``` MDN_NAMEPREP^MDN_UNASCHECK ``` instead of **MDN\_NAMEPREP**. ## FILES */etc/mdn.conf* ## SEE ALSO [mdn.conf(5)](/mdn.conf/5.md)