README

   1 Libstringprep README -- important introductory notes
   2 See the end for copying conditions.
   3
   4 Libstringprep is an implementation of the IETF stringprep
   5 specification, licensed under the LGPL.
   6
   7 Libstringprep is unstable and in its early steps of development.  You
   8 should expect it to not work as well as having security problems.
   9
  10 Currently the API include the following definitions and functions:
  11
  12 Header file: #include <stringprep.h>
  13
  14      Main API header file.
  15
  16 Header file: #include <stringprep_nameprep.h>
  17 Header file: #include <stringprep_kerbero5.h>
  18
  19      Convenience header files for stringprep_nameprep* and
  20      stringprep_kerberos5 macros (see below).
  21
  22 Function: int stringprep (char *in, int maxlen, int flags,
  23                           Stringprep_profile * profile);
  24
  25      Perform stringprep on a zero terminated UTF-8 string.  Since the
  26      stringprep operation can expand the string, maxlen indicate how
  27      large the buffer holding the string is.  See below for valid
  28      flags options.  The profile indicates processing details, see the
  29      profile header files, such as stringprep_generic.h and
  30      stringprep_nameprep.h for two examples.  Your application can
  31      define new profiles, possibly re-using the generic stringprep
  32      tables that always will be part of the library.  Note that you
  33      must convert strings entered in the systems locale into UTF-8
  34      before using this function.
  35
  36 Macro: int stringprep_nameprep(char *in, int maxlen)
  37 Macro: int stringprep_nameprep_no_unassigned(char *in, int maxlen)
  38 Macro: int stringprep_kerberos5(char *in, int maxlen)
  39
  40      Short-hand macros for applying Nameprep with
  41      AllowUnassigned=TRUE, Nameprep with AllowUnassigned=FALSE and
  42      Kerberos 5 stringprep profiles to strings, respectively.
  43
  44 Macro: STRINGPREP_VERSION
  45
  46      CPP definition, a string with version of the stringprep header file.
  47
  48 Function: extern char *stringprep_check_version (char *req_version);
  49
  50      Check that the the version of the library is at minimum the one
  51      given as a string in REQ_VERSION and return the actual version
  52      string of the library; return NULL if the condition is not met.
  53      If `NULL' is passed to this function no check is done and only the
  54      version string is returned.
  55
  56 Type: STRINGPREP_NO_NFKC
  57 Type: STRINGPREP_NO_BIDI
  58 Type: STRINGPREP_NO_UNASSIGNED
  59
  60      Valid options to the FLAGS parameter of stringprep().
  61      STRINGPREP_NO_NFKC disables the NFKC normalization, as well as
  62      selecting the non-NFKC case folding tables. STRINGPREP_NO_BIDI
  63      disables the BIDI step.  STRINGPREP_NO_UNASSIGNED causes
  64      stringprep() abort with an error if string contains unassigned
  65      characters according to profile.  Usually the profile specifies
  66      BIDI and NFKC settings.
  67
  68 The library also contains the following utility functions:
  69
  70 Function: int stringprep_unichar_to_utf8 (long c, char *outbuf);
  71 Function: long stringprep_utf8_to_unichar (const char *p);
  72
  73      Convert between Unicode (UCS4) and UTF-8, one character only.
  74
  75 Function: long *stringprep_utf8_to_ucs4 (const char *str, int  len,
  76                                       int *items_written);
  77 Function: char *stringprep_ucs4_to_utf8 (const long * str, int len,
  78                                       int * items_read, int * items_written);
  79
  80      Convert between Unicode (UCS4) and UTF-8, zero-terminated strings.
  81
  82 Function: char *stringprep_utf8_nfkc_normalize (const char *str, int len);
  83 Function: long *stringprep_ucs4_nfkc_normalize (long *str, int len);
  84
  85      Perform NFKC normalization on strings.
  86
  87 Function: const char *stringprep_locale_charset ();
  88 Function: char *stringprep_convert (const char *str,
  89                                  const char *to_codeset,
  90                                  const char *from_codeset);
  91 Function: char *stringprep_locale_to_utf8 (const char *str);
  92
  93      Convert strings between character sets.
  94
  95 Libstringprep has at some point in time passed the self tests on the
  96 following systems, but no guarantees.
  97
  98   - alphaev67-dec-osf5.0 (Tru64 UNIX C, Tru64 make -- iconv failed!)
  99   - i686-pc-linux-gnu (Debian Sid, iconv ok)
 100   - i686-pc-linux-gnu (RedHat 7.2, iconv ok)
 101   - mips-sgi-irix6.5 (MIPS C compiler, IRIX make, iconv ok)
 102   - rs6000-ibm-aix4.3.2.0 (GCC 2.9-aix43-000718, GNU make, iconv failed!)
 103   - rs6000-ibm-aix4.3.2.0 (IBM C for AIX compiler, AIX make, iconv failed!)
 104   - sparc-sun-solaris2.6 (Sun WorkShop Compiler C 5.0, non-GNU make)
 105   - sparc-sun-solaris2.8 (Sun WorkShop Compiler C 6.0U2, SUN make, iconv ok)
 106   - sparc-sun-solaris2.8 (GCC 3.1, GNU make, iconv ok)
 107   - ... and over 10 other unix systems.
 108
 109 Things left to do below.  If you like to start working on anything,
 110 please let me know so work duplication can be avoided.
 111
 112   - Optimize it, the table searching is slow (but does it matter?).
 113   - Port applications to use libstringprep.
 114   - Include tables for more stringprep profiles.
 115   - Add texi documentation.
 116   - Implement rest of IDN?  Possibly separate project.
 117
 118 Before it becomes a FAQ: This library do not link with GLIB for the
 119 UTF-8 functions for two reasons.  First, GLIB does not provide
 120 versioning of the Unicode tables (and the developers said it will not
 121 be added either) and this package must know the Unicode version used.
 122 Secondly, GLIB requires some things (e.g., threads) that would make
 123 this package less portable.
 124
 125 For more information see <URL:http://josefsson.org/libstringprep/>.
 126
 127 Send all bug reports by electronic mail to bug-libstringprep@josefsson.org.
 128
 129 ----------------------------------------------------------------------
 130 Copyright (C) 2002 Simon Josefsson
 131
 132 Copying and distribution of this file, with or without modification,
 133 are permitted in any medium without royalty provided the copyright
 134 notice and this notice are preserved.