Charles Steinkuehler's LEAF/LRP Website

IPSEC_ATODATA

Section: C Library Functions (3)
Updated: 29 Nov 1999
Index Return to Main Contents

NAME

ipsec atobytes, bytestoa - convert binary data bytes from and to ASCII formats

ipsec atodata, datatoa - convert binary data from and to ASCII formats

SYNOPSIS

#include <freeswan.h>

char *atobytes(const char *src, size_t srclen, char *dst,
size_t dstlen, size_t *lenp);
size_t bytestoa(const char *src, size_t srclen,
int format, char *dst, size_t dstlen);

size_t atodata(const char *src, size_t srclen, char *dst,
size_t dstlen);
size_t datatoa(const char *src, size_t srclen, int format,
char *dst, size_t dstlen);

DESCRIPTION

Atobytes and bytestoa convert arbitrary binary data (e.g. encryption or authentication keys) from and to more-or-less human-readable ASCII formats. Atodata and datatoa are similar but obsolescent.

Currently supported formats are hexadecimal, base64, and characters.

A hexadecimal ASCII 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 ASCII 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. 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 ASCII value begins with a 0t (or 0T) prefix and continues with ASCII characters, each being the value of one binary byte.

All these functions basically copy data from src (whose size is specified 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 truncated; 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 format parameter of bytestoa and datatoa, a single ASCII character used as a type code, specifies which ASCII format is wanted. The value 0 (not ASCII '0', but a zero value) specifies a reasonable default. Other currently-supported values are:

x: continuous lower-case hexadecimal with a 0x prefix
h: lower-case hexadecimal with a 0x prefix and a _ every eight digits

Atobytes 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 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 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.

The normal return value of bytestoa, datatoa, and atodata 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 atobytes or atodata (but not bytestoa or datatoa!) is synonymous with strlen(src). A non-zero srclen in atobytes or atodata must not include the terminating NUL.

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

DIAGNOSTICS

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

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

HISTORY

Written for the FreeS/WAN project by Henry Spencer.

BUGS

Bytestoa really should have format codes to produce base64 or character output.

The 0s and 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 0b for binary) and possible confusion with unprefixed hexadecimal.

The restriction of bytestoa error reports to literal strings (so that callers don't need to worry about freeing them or copying them) does limit the precision of error reporting.

Having two sets of functions is a botch; the author didn't think carefully enough about the need for detailed error reporting when he designed atodata. New code should use atobytes and bytestoa; atodata and datatoa are considered obsolete and will go away soon.

This document was created by man2html, using the manual pages.
Time: 21:22:49 GMT, February 08, 2000

Content-type: text/html