Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

b64_decode(3C)

Name

b64_encode, b64_decode, b32_encode, b32_decode - encode and decode a string in base64 or base32

Synopsis

#include <string.h>

ssize_t b64_encode(char restrict *outbuf, size_t outbufsz,
     const void restrict *inbuf, size_t inbufsz,
     const char *alphabet, uint64_t flags);

ssize_t b64_decode(void *outbuf, size_t outbufsz,
     const char *inbuf, const char *alphabet, uint64_t flags);

ssize_t b32_encode(char restrict *outbuf, size_t outbufsz,
     const void restrict *inbuf, size_t inbufsz,
     const char *alphabet, uint64_t flags);

ssize_t b32_decode(void *outbuf, size_t outbufsz,
     const char *inbuf, const char *alphabet, uint64_t flags);

const char *BASE64_URL_ALPHABET;
const char *BASE32_HEX_ALPHABET;

Description

These functions convert sequences of bytes to and from single-byte character strings using the Base64 and Base32 encoding schemes defined in RFC 4648. By default, the characters used in the strings are a subset of the US-ASCII printable character set.

b64_encode(), b32_encode()

The argument inbuf points to an array of bytes, the argument outbuf points to a string which is an array of characters with a terminating null character, and inbufsz and outbufsz are their sizes, respectively. The argument flags is currently unused and is set to 0.

The alphabet argument allows the caller to supply a customized encoding alphabet string. This is comprised of the encoding characters, followed by the pad character, followed by a null terminator. Passing NULL for this argument allows the standard character set to be used. For b64_encode() function, this string is exactly 65 characters long, for b32_encode() function, it is 33 characters long, excluding the terminator. The alternate encoding alphabets, base64 "URL and filename safe" and base32 "extended hex" described in RFC 4648 are available as the constant strings BASE64_URL_ALPHABET and BASE32_HEX_ALPHABET.

These functions encode the contents of inbuf in base64 or base32, and copy the result into outbuf as a null-terminated string. The functions do not write more than the outbufsz bytes. To avoid an error condition, the size of the array pointed to by outbuf must be large enough to contain the encoding of the string pointed to by inbuf along with a terminating null character.

b64_decode(), b32_decode()

The argument inbuf points to a string, which is an array of characters terminated by a null character. The argument outbuf points to an array of bytes, and outbufsz is the size of outbuf. The argument flags is currently unused and is set to 0.

The alphabet argument functions exactly as for b64_encode or b32encode.

These functions decode the contents of inbuf from base64 or base32 and write the output to outbuf as an array of bytes. Newline characters and whitespace are allowed in the input data and are ignored, but any other characters that are not part of the base64 alphabet will result in an error condition. Both functions will not write more than outbufsz bytes. To avoid an error condition, the size of the array pointed to by outbuf must be large enough to contain the decoding of the string pointed to by inbuf.

Return Values

Upon successful completion, the functions return the number of bytes written. The functions return -1 in an error condition. If outbuf is a null pointer and outbufsz is 0, then instead of returning the number of bytes written, an estimate of the number of bytes required to hold the output string or data is returned. This estimate is guaranteed to be at least as large as the size of the actual output.

Errors

The b64_encode() and b32_encode() functions will fail if:

EOVERFLOW

outbuf is not large enough to hold the output string

EINVAL

an invalid custom alphabet string is supplied

The b64_decode() and b32_decode() functions will fail if:

EOVERFLOW

outbuf is not large enough to hold the output data

EBADMSG

illegal character(s) in the input string

EINVAL

an invalid custom alphabet string is supplied

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
Standard
None

See Also

uuencode(1C), ascii(7)

Josefsson, S. RFC 4648: The Base16, Base32, and Base64 Data Encodings. October 2006. https://tools.ietf.org/html/rfc4648

History

The b64_encode(), b64_decode(), b32_encode(), and b32_decode() functions were added to Oracle Solaris in the 11.4.0 release.