unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

IPSEC_TTODATA(3)           Library Functions Manual           IPSEC_TTODATA(3)



NAME
       ipsec  ttodata,  datatot  -  convert binary data bytes from and to text
       formats

SYNOPSIS
       #include <&lt;freeswan.h>&gt;

       const char *ttodata(const char *src, size_t srclen,
           int base, char *dst, size_t dstlen, size_t *lenp);
       const char *ttodatav(const char *src, size_t srclen,
           int base, char *dst, size_t dstlen, size_t *lenp,
           char *errp, size_t errlen, int flags);
       size_t datatot(const char *src, size_t srclen,
           int format, char *dst, size_t dstlen);

DESCRIPTION
       Ttodata, ttodatav, and datatot  convert  arbitrary  binary  data  (e.g.
       encryption or authentication keys) from and to more-or-less human-read-
       able text formats.

       Currently supported formats are hexadecimal, base64, and characters.

       A hexadecimal text value begins with a 0x (or 0X) prefix and  continues
       with two-digit groups of hexadecimal digits (0-9, and a-f or A-F), each
       group encoding the value of one binary byte, high-order digit first.  A
       single _ (underscore) between consecutive groups is ignored, permitting
       punctuation to improve readability; doing this every eight digits seems
       about right.

       A  base64 text value begins with a 0s (or 0S) prefix and continues with
       four-digit groups of base64 digits (A-Z, a-z,  0-9,  +,  and  /),  each
       group  encoding the value of three binary bytes as described in section
       6.8 of RFC 2045.  If flags has the TTODATAV_IGNORESPACE bit on,  blanks
       are ignore (after the prefix).  Note that the last one or two digits of
       a base64 group can be = to indicate that fewer than three binary  bytes
       are encoded.

       A  character  text  value begins with a 0t (or 0T) prefix and continues
       with text characters, each being the value of one binary byte.

       All these functions basically copy data from src (whose size is  speci-
       fied  by  srclen) to dst (whose size is specified by dstlen), doing the
       conversion en route.  If the result will not fit in dst,  it  is  trun-
       cated;  under  no  circumstances  are  more than dstlen bytes of result
       written to dst.  Dstlen can be zero, in which  case  dst  need  not  be
       valid and no result bytes are written at all.

       The  base  parameter  of ttodata and ttodatav specifies what format the
       input is in; normally it should be 0 to signify that this gets  figured
       out  from  the  prefix.  Values of 16, 64, and 256 respectively signify
       hexadecimal, base64, and character-text formats without prefixes.

       The format parameter of datatot, a single  character  used  as  a  type
       code,  specifies  which  text format is wanted.  The value 0 (not ASCII
       '0', but a zero value) specifies  a  reasonable  default.   Other  cur-
       rently-supported values are:

         'x' continuous lower-case hexadecimal with a 0x prefix

         'h' lower-case  hexadecimal with a 0x prefix and a _ every eight dig-
             its

         ':' lower-case hexadecimal with no prefix and a : (colon)  every  two
             digits

         16  lower-case hexadecimal with no prefix or _

         's' continuous base64 with a 0s prefix

         64  continuous base64 with no prefix

       The default format is currently 'h'.

       Ttodata  returns  NULL  for  success  and a pointer to a string-literal
       error message for failure; see DIAGNOSTICS.  On success, if and only if
       lenp  is non-NULL, *lenp is set to the number of bytes required to con-
       tain the full untruncated result.  It is the caller's responsibility to
       check  this  against dstlen to determine whether he has obtained a com-
       plete result.  The *lenp value is correct even if dstlen is zero, which
       offers  a way to determine how much space would be needed before having
       to allocate any.

       Ttodatav is just like ttodata except that in certain cases, if errp  is
       non-NULL,  the  buffer  pointed  to  by  errp (whose length is given by
       errlen) is used to hold a more  detailed  error  message.   The  return
       value  is NULL for success, and is either errp or a pointer to a string
       literal for failure.  If the size of the error-message buffer is inade-
       quate  for  the desired message, ttodatav will fall back on returning a
       pointer to a  literal  string  instead.   The  freeswan.h  header  file
       defines  a  constant  TTODATAV_BUF  which is the size of a buffer large
       enough for worst-case results.

       The normal return value of datatot is the number of bytes  required  to
       contain the full untruncated result.  It is the caller's responsibility
       to check this against dstlen to determine whether  he  has  obtained  a
       complete  result.   The return value is correct even if dstlen is zero,
       which offers a way to determine how much space would be  needed  before
       having  to  allocate any.  A return value of 0 signals a fatal error of
       some kind (see DIAGNOSTICS).

       A zero value for srclen in ttodata (but not  datatot!)   is  synonymous
       with  strlen(src).   A  non-zero srclen in ttodata must not include the
       terminating NUL.

       Unless dstlen is zero, the result supplied by datatot  is  always  NUL-
       terminated,  and  its  needed-size  return value includes space for the
       terminating NUL.

       Several obsolete variants of these functions  (atodata,  datatoa,  ato-
       bytes, and bytestoa) are temporarily also supported.

SEE ALSO
       sprintf(3), ipsec_atoaddr(3)

DIAGNOSTICS
       Fatal  errors  in  ttodata  and ttodatav are: unknown characters in the
       input; unknown or missing prefix; unknown base; incomplete digit group;
       non-zero  padding  in a base64 less-than-three-bytes digit group; zero-
       length input.

       Fatal errors in datatot are: unknown format code; zero-length input.

HISTORY
       Written for the FreeS/WAN project by Henry Spencer.

BUGS
       Datatot should have a format code to produce character-text output.

       The 0s and 0t prefixes are the author's inventions and are not a  stan-
       dard  of  any  kind.   They  have  been chosen to avoid collisions with
       existing practice (some C implementations use 0b for binary) and possi-
       ble confusion with unprefixed hexadecimal.



                                16 August 2003                IPSEC_TTODATA(3)