281 lines
5.9 KiB
Groff
281 lines
5.9 KiB
Groff
.TH IPSEC_TTODATA 3 "16 August 2003"
|
|
.SH NAME
|
|
ipsec ttodata, datatot \- convert binary data bytes from and to text formats
|
|
.SH SYNOPSIS
|
|
.B "#include <freeswan.h>"
|
|
.sp
|
|
.B "const char *ttodata(const char *src, size_t srclen,"
|
|
.ti +1c
|
|
.B "int base, char *dst, size_t dstlen, size_t *lenp);"
|
|
.br
|
|
.B "const char *ttodatav(const char *src, size_t srclen,"
|
|
.ti +1c
|
|
.B "int base, char *dst, size_t dstlen, size_t *lenp,"
|
|
.ti +1c
|
|
.B "char *errp, size_t errlen, int flags);"
|
|
.br
|
|
.B "size_t datatot(const char *src, size_t srclen,"
|
|
.ti +1c
|
|
.B "int format, char *dst, size_t dstlen);"
|
|
.SH DESCRIPTION
|
|
.IR Ttodata ,
|
|
.IR ttodatav ,
|
|
and
|
|
.I datatot
|
|
convert arbitrary binary data (e.g. encryption or authentication keys)
|
|
from and to more-or-less human-readable text formats.
|
|
.PP
|
|
Currently supported formats are hexadecimal, base64, and characters.
|
|
.PP
|
|
A hexadecimal text value begins with a
|
|
.B 0x
|
|
(or
|
|
.BR 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
|
|
.B _
|
|
(underscore)
|
|
between consecutive groups is ignored, permitting punctuation to improve
|
|
readability; doing this every eight digits seems about right.
|
|
.PP
|
|
A base64 text value begins with a
|
|
.B 0s
|
|
(or
|
|
.BR 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
|
|
.B flags
|
|
has the
|
|
.B TTODATAV_IGNORESPACE
|
|
bit on, blanks are ignore (after the prefix).
|
|
Note that the last one or two digits of a base64 group can be
|
|
.B =
|
|
to indicate that fewer than three binary bytes are encoded.
|
|
.PP
|
|
A character text value begins with a
|
|
.B 0t
|
|
(or
|
|
.BR 0T )
|
|
prefix
|
|
and continues with text characters, each being the value of one binary byte.
|
|
.PP
|
|
All these functions basically copy data from
|
|
.I src
|
|
(whose size is specified by
|
|
.IR srclen )
|
|
to
|
|
.I dst
|
|
(whose size is specified by
|
|
.IR dstlen ),
|
|
doing the conversion en route.
|
|
If the result will not fit in
|
|
.IR dst ,
|
|
it is truncated;
|
|
under no circumstances are more than
|
|
.I dstlen
|
|
bytes of result written to
|
|
.IR dst .
|
|
.I Dstlen
|
|
can be zero, in which case
|
|
.I dst
|
|
need not be valid and no result bytes are written at all.
|
|
.PP
|
|
The
|
|
.I base
|
|
parameter of
|
|
.I ttodata
|
|
and
|
|
.I ttodatav
|
|
specifies what format the input is in;
|
|
normally it should be
|
|
.B 0
|
|
to signify that this gets figured out from the prefix.
|
|
Values of
|
|
.BR 16 ,
|
|
.BR 64 ,
|
|
and
|
|
.BR 256
|
|
respectively signify hexadecimal, base64, and character-text formats
|
|
without prefixes.
|
|
.PP
|
|
The
|
|
.I format
|
|
parameter of
|
|
.IR datatot ,
|
|
a single character used as a type code,
|
|
specifies which text format is wanted.
|
|
The value
|
|
.B 0
|
|
(not ASCII
|
|
.BR '0' ,
|
|
but a zero value) specifies a reasonable default.
|
|
Other currently-supported values are:
|
|
.RS 2
|
|
.TP 4
|
|
.B 'x'
|
|
continuous lower-case hexadecimal with a
|
|
.B 0x
|
|
prefix
|
|
.TP
|
|
.B 'h'
|
|
lower-case hexadecimal with a
|
|
.B 0x
|
|
prefix and a
|
|
.B _
|
|
every eight digits
|
|
.TP
|
|
.B ':'
|
|
lower-case hexadecimal with no prefix and a
|
|
.B :
|
|
(colon) every two digits
|
|
.TP
|
|
.B 16
|
|
lower-case hexadecimal with no prefix or
|
|
.B _
|
|
.TP
|
|
.B 's'
|
|
continuous base64 with a
|
|
.B 0s
|
|
prefix
|
|
.TP
|
|
.B 64
|
|
continuous base64 with no prefix
|
|
.RE
|
|
.PP
|
|
The default format is currently
|
|
.BR 'h' .
|
|
.PP
|
|
.I Ttodata
|
|
returns NULL for success and
|
|
a pointer to a string-literal error message for failure;
|
|
see DIAGNOSTICS.
|
|
On success,
|
|
if and only if
|
|
.I lenp
|
|
is non-NULL,
|
|
.B *lenp
|
|
is set to the number of bytes required to contain the full untruncated result.
|
|
It is the caller's responsibility to check this against
|
|
.I dstlen
|
|
to determine whether he has obtained a complete result.
|
|
The
|
|
.B *lenp
|
|
value is correct even if
|
|
.I dstlen
|
|
is zero, which offers a way to determine how much space would be needed
|
|
before having to allocate any.
|
|
.PP
|
|
.I Ttodatav
|
|
is just like
|
|
.I ttodata
|
|
except that in certain cases,
|
|
if
|
|
.I errp
|
|
is non-NULL,
|
|
the buffer pointed to by
|
|
.I errp
|
|
(whose length is given by
|
|
.IR errlen )
|
|
is used to hold a more detailed error message.
|
|
The return value is NULL for success,
|
|
and is either
|
|
.I errp
|
|
or a pointer to a string literal for failure.
|
|
If the size of the error-message buffer is
|
|
inadequate for the desired message,
|
|
.I ttodatav
|
|
will fall back on returning a pointer to a literal string instead.
|
|
The
|
|
.I freeswan.h
|
|
header file defines a constant
|
|
.B TTODATAV_BUF
|
|
which is the size of a buffer large enough for worst-case results.
|
|
.PP
|
|
The normal return value of
|
|
.IR datatot
|
|
is the number of bytes required
|
|
to contain the full untruncated result.
|
|
It is the caller's responsibility to check this against
|
|
.I dstlen
|
|
to determine whether he has obtained a complete result.
|
|
The return value is correct even if
|
|
.I dstlen
|
|
is zero, which offers a way to determine how much space would be needed
|
|
before having to allocate any.
|
|
A return value of
|
|
.B 0
|
|
signals a fatal error of some kind
|
|
(see DIAGNOSTICS).
|
|
.PP
|
|
A zero value for
|
|
.I srclen
|
|
in
|
|
.I ttodata
|
|
(but not
|
|
.IR datatot !)
|
|
is synonymous with
|
|
.BR strlen(src) .
|
|
A non-zero
|
|
.I srclen
|
|
in
|
|
.I ttodata
|
|
must not include the terminating NUL.
|
|
.PP
|
|
Unless
|
|
.I dstlen
|
|
is zero,
|
|
the result supplied by
|
|
.I datatot
|
|
is always NUL-terminated,
|
|
and its needed-size return value includes space for the terminating NUL.
|
|
.PP
|
|
Several obsolete variants of these functions
|
|
.RI ( atodata ,
|
|
.IR datatoa ,
|
|
.IR atobytes ,
|
|
and
|
|
.IR bytestoa )
|
|
are temporarily also supported.
|
|
.SH SEE ALSO
|
|
sprintf(3), ipsec_atoaddr(3)
|
|
.SH DIAGNOSTICS
|
|
Fatal errors in
|
|
.I ttodata
|
|
and
|
|
.I 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.
|
|
.PP
|
|
Fatal errors in
|
|
.I datatot
|
|
are:
|
|
unknown format code;
|
|
zero-length input.
|
|
.SH HISTORY
|
|
Written for the FreeS/WAN project by Henry Spencer.
|
|
.SH BUGS
|
|
.I Datatot
|
|
should have a format code to produce character-text output.
|
|
.PP
|
|
The
|
|
.B 0s
|
|
and
|
|
.B 0t
|
|
prefixes are the author's inventions and are not a standard
|
|
of any kind.
|
|
They have been chosen to avoid collisions with existing practice
|
|
(some C implementations use
|
|
.B 0b
|
|
for binary)
|
|
and possible confusion with unprefixed hexadecimal.
|