import base64 (wip)

libbase64/libbase64.3

@@ -0,0 +1,113 @@
+.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.