This library is backwards (API) compatible with the libidn library (https://www.gnu.org/software/libidn/).
Although it is recommended for new software to use the native libidn2
functions (i.e., the ones prefixed with idn2), old software
isn’t always feasible to modify.
As such, libidn2, provides compatibility macros which switch all libidn
functions, to libidn2 functions in a backwards compatible way. To take
advantage of these compatibility functions, it is sufficient to replace
the idna.h header in legacy code, with idn2.h. That
would transform the software from using libidn, i.e., IDNA2003,
to using libidn2 with IDNA2008 non-transitional encoding.
However, it is recommended to switch applications to the IDN2 native APIs. The following table provides a mapping of libidn code snippets to libidn2, for switching to IDNA2008.
| libidn | libidn2 |
|---|---|
rc = idna_to_ascii_8z (buf, &p, IDNA_USE_STD3_ASCII_RULES); if (rc != IDNA_SUCCESS) | rc = idn2_to_ascii_8z (buf, &p, IDN2_USE_STD3_ASCII_RULES); if (rc != IDN2_OK) |
rc = idna_to_ascii_8z (buf, &p, 0 /* any other flags */); if (rc != IDNA_SUCCESS) | /* we recommend to use the default flags (0), so that * the default behavior of libidn2 applies. */ rc = idn2_to_ascii_8z (buf, &p, 0); if (rc != IDN2_OK) |
rc = idna_to_unicode_8z8z (buf, &p, 0 /* any flags */); if (rc != IDNA_SUCCESS) | rc = idn2_to_unicode_8z8z (buf, &p, 0); if (rc != IDN2_OK) |
Note that, although the table only lists the UTF-8 functions, the mapping
is identical for every other one on the family of toUnicode and toAscii.
As the IDNA2003 details differ signicantly to IDNA2008, not all flags used in
the libidn functions map to any specific flags; it is typically safe to use
the suggested libidn2 flags. Exceptionally the libidn flag IDNA_USE_STD3_ASCII_RULES
is mapped to IDN2_USE_STD3_ASCII_RULES.
In several cases where IDNA2008 mappings do not exist whereas IDNA2003 mappings do, software like browsers take a backwards compatible approach. That is convert the domain to IDNA2008 form, and if that fails try the IDNA2003 conversion. The following example demonstrates that approach.
rc = idn2_to_ascii_8z (buf, &p, IDN2_NONTRANSITIONAL); /* IDNA2008 */ if (rc == IDN2_DISALLOWED) rc = idn2_to_ascii_8z (buf, &p, IDN2_TRANSITIONAL); /* IDNA2003 - compatible */
In the special case of software that needs to support both
libraries (e.g., both IDNA2003 and IDNA2008), you must define
IDN2_SKIP_LIBIDN_COMPAT prior to including idn2.h
in order to disable compatibility code which overlaps with libidn
functionality. That would allow software to use both libraries’ functions.
The original libidn library includes functionality for the stringprep
processing in stringprep.h. That functionality was an integral part
of an IDNA2003 implementation, but it does not apply to IDNA2008. Furthermore,
stringprep processing has been replaced by the PRECIS framework (RFC8264).
For the reasons above, libidn2 does not implement stringprep or any other string processing protocols unrelated to IDNA2008. Applications requiring the stringprep processing should continue using the original libidn, and new applications should consider using the PRECIS framework.