base32.h 4.35 KB
Newer Older
1
/*
2
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3
 *
4 5 6
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 8 9
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
10 11 12 13 14 15 16 17 18 19 20 21 22
 */

#ifndef ISC_BASE32_H
#define ISC_BASE32_H 1

/*! \file */

/*
 * Routines for manipulating base 32 and base 32 hex encoded data.
 * Based on RFC 4648.
 *
 * Base 32 hex preserves the sort order of data when it is encoded /
 * decoded.
23 24
 *
 * Base 32 hex "np" is base 32 hex but no padding is produced or accepted.
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
 */

#include <isc/lang.h>
#include <isc/types.h>

ISC_LANG_BEGINDECLS

/***
 *** Functions
 ***/

isc_result_t
isc_base32_totext(isc_region_t *source, int wordlength,
		  const char *wordbreak, isc_buffer_t *target);
isc_result_t
isc_base32hex_totext(isc_region_t *source, int wordlength,
		     const char *wordbreak, isc_buffer_t *target);
42 43 44
isc_result_t
isc_base32hexnp_totext(isc_region_t *source, int wordlength,
		       const char *wordbreak, isc_buffer_t *target);
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
/*!<
 * \brief Convert data into base32 encoded text.
 *
 * Notes:
 *\li	The base32 encoded text in 'target' will be divided into
 *	words of at most 'wordlength' characters, separated by
 * 	the 'wordbreak' string.  No parentheses will surround
 *	the text.
 *
 * Requires:
 *\li	'source' is a region containing binary data
 *\li	'target' is a text buffer containing available space
 *\li	'wordbreak' points to a null-terminated string of
 *		zero or more whitespace characters
 *
 * Ensures:
 *\li	target will contain the base32 encoded version of the data
 *	in source.  The 'used' pointer in target will be advanced as
 *	necessary.
 */

isc_result_t
isc_base32_decodestring(const char *cstr, isc_buffer_t *target);
isc_result_t
isc_base32hex_decodestring(const char *cstr, isc_buffer_t *target);
70 71
isc_result_t
isc_base32hexnp_decodestring(const char *cstr, isc_buffer_t *target);
72
/*!<
73 74
 * \brief Decode a null-terminated string in base32, base32hex, or
 * base32hex non-padded.
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
 *
 * Requires:
 *\li	'cstr' is non-null.
 *\li	'target' is a valid buffer.
 *
 * Returns:
 *\li	#ISC_R_SUCCESS	-- the entire decoded representation of 'cstring'
 *			   fit in 'target'.
 *\li	#ISC_R_BADBASE32 -- 'cstr' is not a valid base32 encoding.
 *
 * 	Other error returns are any possible error code from:
 *\li		isc_lex_create(),
 *\li		isc_lex_openbuffer(),
 *\li		isc_base32_tobuffer().
 */

isc_result_t
isc_base32_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length);
isc_result_t
isc_base32hex_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length);
95 96
isc_result_t
isc_base32hexnp_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length);
97
/*!<
98
 * \brief Convert text encoded in base32, base32hex, or base32hex
99 100 101 102 103 104 105 106 107 108
 * non-padded from a lexer context into `target`. If 'length' is
 * non-negative, it is the expected number of encoded octets to convert.
 *
 * If 'length' is -1 then 0 or more encoded octets are expected.
 * If 'length' is -2 then 1 or more encoded octets are expected.
 *
 * Returns:
 *\li	#ISC_R_BADBASE32 -- invalid base32 encoding.
 *\li	#ISC_R_UNEXPECTEDEND: the text does not contain the expected
 *			      number of encoded octets.
109 110
 *
 * Requires:
111
 *\li	'lexer' is a valid lexer context
112
 *\li	'target' is a buffer containing binary data
113
 *\li	'length' is -2, -1, or non-negative
114 115 116
 *
 * Ensures:
 *\li	target will contain the data represented by the base32 encoded
117 118 119
 *	string parsed by the lexer.  No more than `length` octets will
 *	be read, if `length` is non-negative.  The 'used' pointer in
 *	'target' will be advanced as necessary.
120 121 122 123 124 125
 */

isc_result_t
isc_base32_decoderegion(isc_region_t *source, isc_buffer_t *target);
isc_result_t
isc_base32hex_decoderegion(isc_region_t *source, isc_buffer_t *target);
126 127
isc_result_t
isc_base32hexnp_decoderegion(isc_region_t *source, isc_buffer_t *target);
128
/*!<
129 130
 * \brief Decode a packed (no white space permitted) region in
 * base32, base32hex or base32hex non-padded.
131 132 133 134 135 136 137 138 139 140 141 142 143 144
 *
 * Requires:
 *\li   'source' is a valid region.
 *\li   'target' is a valid buffer.
 *
 * Returns:
 *\li   #ISC_R_SUCCESS  -- the entire decoded representation of 'cstring'
 *                         fit in 'target'.
 *\li   #ISC_R_BADBASE32 -- 'source' is not a valid base32 encoding.
 */

ISC_LANG_ENDDECLS

#endif /* ISC_BASE32_H */