GNU IDN Library - Libidn

 [image of the Head of a GNU]


Table of Contents


Introduction

GNU Libidn is an implementation of the Stringprep, Punycode and IDNA specifications defined by the IETF Internationalized Domain Names (IDN) working group, used for internationalized domain names. The C library is available under the GNU Lesser General Public License.

The library contains a generic Stringprep implementation that does Unicode 3.2 NFKC normalization, mapping and prohibitation of characters, and bidirectional character handling. Profiles for iSCSI, Kerberos 5, Nameprep, SASL and XMPP are included. Punycode and ASCII Compatible Encoding (ACE) via IDNA are supported.

The Stringprep API consists of two main functions, one for converting data from the system's native representation into UTF-8, and one function to perform the Stringprep processing. Adding a new Stringprep profile for your application within the API is straightforward. The Punycode API consists of one encoding function and one decoding function. The IDNA API consists of the ToASCII and ToUnicode functions, as well as an high-level interface for converting entire domain names to and from the ACE encoded form.

The library is used by, e.g., GNU SASL and Shishi to process user names and passwords. Libidn can be built into GNU Libc to enable a new system-wide getaddrinfo() flag for IDN processing.

Libidn is developed for the GNU/Linux system, but runs on over 20 Unix platforms (including Solaris, IRIX, AIX, and Tru64) and Windows. Libidn is written in C and (parts of) the API is accessible from C, C++, Emacs Lisp, Python and Java. A native Java and C# port is also provided, licensed under the GNU General Public License.

For more information:

News

Note that new releases are only mentioned here if they introduce a major feature or is significant in some other way. Read the help-libidn mailing list if you seek more frequent announcements.

Information on what is new in the library itself is found in the NEWS file (live CVS version).

Try it

A web interface to libidn is available online. Try libidn before you buy it.

A simple IDN web server is also available.

Documentation

Refer to the Libidn Manual web page for links to the manual in all formats; however, quick links to the most popular formats:

You may also be interested in a preliminary document with Nameprep and IDNA test vectors.

Downloading

The releases are distributed from ftp://alpha.gnu.org/pub/gnu/libidn/ and http://josefsson.org/libidn/releases/.

All official releases are signed with an OpenPGP key with fingerprint 0xB565716F.

Support

A mailing list where users of Libidn may help each other exists, and you can reach it by sending e-mail to help-libidn@gnu.org. Archives of the mailing list discussions, and an interface to manage subscriptions, is available through the World Wide Web at http://lists.gnu.org/mailman/listinfo/help-libidn.

If you are interested in paid support for Libidn, or sponsor the development, please contact me. If you provide paid services for Libidn, and would like to be mentioned here, also contact me.

If you find Libidn useful, please consider making a donation. No amount is too small!

Development

Libidn is developed in CVS on a private machine. At irregular intervals, it is synchronized against a publicly available machine (just press enter at the password prompt):

$ cvs -d :pserver:anoncvs@yxa.extundo.com:/home/cvs/public-cvs login
Logging in to :pserver:anoncvs@yxa.extundo.com:2401/home/cvs/public-cvs
CVS password:
$ cvs -d :pserver:anoncvs@yxa.extundo.com:/home/cvs/public-cvs co libidn

See the file README-alpha on how to bootstrap and build the package from CVS.

The online CVS repository is available, and there is also some CVS statistics.

A log of recent CVS activity is also available. If you prefer a mailing list, notifications of each CVS change is also sent to libidn-commit@gnu.org.

If you have trouble using CVS, you may download a daily snapshot. The snapshots are prepared similar to regular releases, i.e., you simply build them using ./configure && make.

Before each release, the package is built on many platforms. The latest results from the autobuilder is available.

Bugs

Report all problems to bug-libidn@gnu.org, but please read the manual on how to report bugs first.

Related implementations

The following is a list of links to other free IDN, or otherwise related, implementations. The list is not conclusive, suggestions appreciated.

Projects using GNU Libidn include:

Let us know about more projects that use GNU Libidn!

How to use it?

Read data from user, convert it to UTF-8 and then pass it to stringprep(). Example code below (it is included in the distribution as example.c). To simplify compiling, use libtool and pkg-config. More information and more examples are included in the manual.

See also the other example*.c files in the source distribution on how to use other features of the library (punycode, IDNA).

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/*
 * Compiling using libtool and pkg-config is recommended:
 *
 * $ libtool cc -o example example.c `pkg-config --cflags --libs libstringprep`
 * $ ./example
 * Input string encoded as `ISO-8859-1': 
 * Before locale2utf8 (length 2): aa 0a
 * Before stringprep (length 3): c2 aa 0a
 * After stringprep (length 2): 61 0a
 * $
 *
 */

int main(int argc, char *argv[])
{
  char buf[BUFSIZ];
  char *p;
  int rc, i;

  printf("Input string encoded as `%s': ",
	 stringprep_locale_charset ());
  fflush(stdout);
  fgets(buf, BUFSIZ, stdin);

  printf("Before locale2utf8 (length %d): ", strlen(buf));
  for (i=0; i < strlen(buf); i++)
    printf("%02x ", buf[i] & 0xFF);
  printf("\n");

  p = stringprep_locale_to_utf8 (buf);
  if (p)
    {
      strcpy(buf, p);
      free(p);
    }
  else
    printf("Could not convert string to UTF-8, continuing anyway...\n");

  printf("Before stringprep (length %d): ", strlen(buf));
  for (i=0; i < strlen(buf); i++)
    printf("%02x ", buf[i] & 0xFF);
  printf("\n");

  rc = stringprep(buf, BUFSIZ, 0, stringprep_nameprep);
  if (rc != STRINGPREP_OK)
    printf("Stringprep failed with rc %d...\n", rc);
  else
    {
      printf("After stringprep (length %d): ", strlen(buf));
      for (i=0; i < strlen(buf); i++)
        printf("%02x ", buf[i] & 0xFF);
      printf("\n");
    }

  return 0;
}


Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to webmasters@gnu.org, send other questions to gnu@gnu.org.

Copyright © 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Updated: $Date: 2006/11/24 06:04:14 $ $Author: ramprasadb $