- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -0,0 +1,281 @@
|
||||
.TH IPSEC_TTODATA 3 "16 August 2003"
|
||||
.\" RCSID $Id: ttodata.3,v 1.2 2005/07/18 20:13:42 as Exp $
|
||||
.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.
|
||||
Reference in New Issue
Block a user