114 lines
2.9 KiB
Groff
114 lines
2.9 KiB
Groff
|
.Dd February 7, 2013
|
||
|
|
.Dt LIBBASE64 3
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm libbase64
|
||
|
|
.Nd OpenBSD's base64 code extracted to a static library
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In base64.h
|
||
|
|
.Ft int
|
||
|
|
.Fo base64_encode
|
||
|
|
.Fa "const uint8_t *src"
|
||
|
|
.Fa "size_t srclen"
|
||
|
|
.Fa "char *dst"
|
||
|
|
.Fa "size_t dstlen"
|
||
|
|
.Fc
|
||
|
|
.Ft int
|
||
|
|
.Fo base64_decode
|
||
|
|
.Fa "const char *src"
|
||
|
|
.Fa "uint8_t *dst"
|
||
|
|
.Fa "size_t dstlen"
|
||
|
|
.Fc
|
||
|
|
.Ft size_t
|
||
|
|
.Fo base64_enclen
|
||
|
|
.Fa "size_t len"
|
||
|
|
.Fc
|
||
|
|
.Ft size_t
|
||
|
|
.Fo base64_declen
|
||
|
|
.Fa "size_t len"
|
||
|
|
.Fc
|
||
|
|
.Ft "const char *"
|
||
|
|
.Fo base64_lib_version
|
||
|
|
.Fa void
|
||
|
|
.Fc
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
.Nm
|
||
|
|
provides functions for base64 encoding and decoding. The
|
||
|
|
.Nm base64_encode
|
||
|
|
function takes arbtitrary binary data and a pre-allocated buffer to
|
||
|
|
store the base64-encoded data in. The expected size of the buffer
|
||
|
|
(sans a NULL byte) can be retrieved with the function
|
||
|
|
.Nm base64_enclen .
|
||
|
|
The destination size should be the value of
|
||
|
|
.Nm base64_enclen(buflen)
|
||
|
|
plus an extra NULL byte.
|
||
|
|
.Nm base64_decode
|
||
|
|
reverses the process; the length to the base64-encoded buffer is not
|
||
|
|
required. The size of the destination buffer should be at least
|
||
|
|
.Nm base64_declen(b64buflen) + 1 .
|
||
|
|
The current version of the library can be retrieved with the
|
||
|
|
.Nm base64_lib_version
|
||
|
|
returns the current version string for the package.
|
||
|
|
.Sh RETURN VALUES
|
||
|
|
.Nm base64_encode
|
||
|
|
and
|
||
|
|
.Nm base64_decode
|
||
|
|
return -1 on error, or the length of the stored data on success.
|
||
|
|
.Nm base64_enclen
|
||
|
|
returns the base64-encoded length of a base64-encoded buffer with a
|
||
|
|
source buffer length of
|
||
|
|
.Nm len ;
|
||
|
|
.Nm base64_decode
|
||
|
|
returns the maximum base64-decoded size of a source buffer of length
|
||
|
|
.Nm len ,
|
||
|
|
possibly two more bytes than actually required. The actual length of
|
||
|
|
the buffer depends on the encoded data.
|
||
|
|
.Nm base64_lib_version
|
||
|
|
returns a pointer to a statically allocated buffer containing the
|
||
|
|
version number. This pointer should not be freed.
|
||
|
|
.Sh EXAMPLES
|
||
|
|
A sample section of code doing base64 encoding might look like:
|
||
|
|
.Bd -literal
|
||
|
|
uint8_t msg[] = "Hello, world.";
|
||
|
|
char *b64 = NULL;
|
||
|
|
size_t b64len;
|
||
|
|
|
||
|
|
b64len = base64_enclen(strlen(msg));
|
||
|
|
b64 = malloc(b64len + 1);
|
||
|
|
if (NULL == b64)
|
||
|
|
return -1;
|
||
|
|
memset(b64, 0x0, b64len);
|
||
|
|
|
||
|
|
if (base64_encode(b64, b64len + 1, msg, strlen(msg)) != -1);
|
||
|
|
do_something(b64, b64len);
|
||
|
|
free(b64);
|
||
|
|
.Ed
|
||
|
|
Decoding is similar:
|
||
|
|
.Bd -literal
|
||
|
|
char msg[] = "SGVsbG8sIHdvcmxk";
|
||
|
|
uint8_t *buf = NULL;
|
||
|
|
size_t buflen;
|
||
|
|
|
||
|
|
buflen = base64_declen(strlen(msg));
|
||
|
|
buf = malloc(buflen + 1);
|
||
|
|
if (NULL == buf)
|
||
|
|
return -1;
|
||
|
|
memset(buf, 0x0, buflen + 1);
|
||
|
|
|
||
|
|
if (base64_decode(msg, buf, buflen) != -1)
|
||
|
|
do_something(buf, buflen);
|
||
|
|
free(buf);
|
||
|
|
.Ed
|
||
|
|
.Sh ERRORS
|
||
|
|
The most common cause for failure will be an incorrectly-sized buffer,
|
||
|
|
or an invalid base64-encoded string.
|
||
|
|
.Sh STANDARDS
|
||
|
|
.Nm
|
||
|
|
conforms to C99 and SUSv4.
|
||
|
|
.Sh AUTHORS
|
||
|
|
.Nm
|
||
|
|
was written by
|
||
|
|
.An Kyle Isom Aq Mt kyle@tyrfingr.is .
|
||
|
|
.Sh BUGS
|
||
|
|
Please report all bugs to the author.
|