1 /* $NetBSD: base32.h,v 1.5 2021/02/19 16:42:19 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * This Source Code Form is subject to the terms of the Mozilla Public 7 * License, v. 2.0. If a copy of the MPL was not distributed with this 8 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 9 * 10 * See the COPYRIGHT file distributed with this work for additional 11 * information regarding copyright ownership. 12 */ 13 14 #ifndef ISC_BASE32_H 15 #define ISC_BASE32_H 1 16 17 /*! \file */ 18 19 /* 20 * Routines for manipulating base 32 and base 32 hex encoded data. 21 * Based on RFC 4648. 22 * 23 * Base 32 hex preserves the sort order of data when it is encoded / 24 * decoded. 25 * 26 * Base 32 hex "np" is base 32 hex but no padding is produced or accepted. 27 */ 28 29 #include <isc/lang.h> 30 #include <isc/types.h> 31 32 ISC_LANG_BEGINDECLS 33 34 /*** 35 *** Functions 36 ***/ 37 38 isc_result_t 39 isc_base32_totext(isc_region_t *source, int wordlength, const char *wordbreak, 40 isc_buffer_t *target); 41 isc_result_t 42 isc_base32hex_totext(isc_region_t *source, int wordlength, 43 const char *wordbreak, isc_buffer_t *target); 44 isc_result_t 45 isc_base32hexnp_totext(isc_region_t *source, int wordlength, 46 const char *wordbreak, isc_buffer_t *target); 47 /*!< 48 * \brief Convert data into base32 encoded text. 49 * 50 * Notes: 51 *\li The base32 encoded text in 'target' will be divided into 52 * words of at most 'wordlength' characters, separated by 53 * the 'wordbreak' string. No parentheses will surround 54 * the text. 55 * 56 * Requires: 57 *\li 'source' is a region containing binary data 58 *\li 'target' is a text buffer containing available space 59 *\li 'wordbreak' points to a null-terminated string of 60 * zero or more whitespace characters 61 * 62 * Ensures: 63 *\li target will contain the base32 encoded version of the data 64 * in source. The 'used' pointer in target will be advanced as 65 * necessary. 66 */ 67 68 isc_result_t 69 isc_base32_decodestring(const char *cstr, isc_buffer_t *target); 70 isc_result_t 71 isc_base32hex_decodestring(const char *cstr, isc_buffer_t *target); 72 isc_result_t 73 isc_base32hexnp_decodestring(const char *cstr, isc_buffer_t *target); 74 /*!< 75 * \brief Decode a null-terminated string in base32, base32hex, or 76 * base32hex non-padded. 77 * 78 * Requires: 79 *\li 'cstr' is non-null. 80 *\li 'target' is a valid buffer. 81 * 82 * Returns: 83 *\li #ISC_R_SUCCESS -- the entire decoded representation of 'cstring' 84 * fit in 'target'. 85 *\li #ISC_R_BADBASE32 -- 'cstr' is not a valid base32 encoding. 86 * 87 * Other error returns are any possible error code from: 88 *\li isc_lex_create(), 89 *\li isc_lex_openbuffer(), 90 *\li isc_base32_tobuffer(). 91 */ 92 93 isc_result_t 94 isc_base32_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); 95 isc_result_t 96 isc_base32hex_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); 97 isc_result_t 98 isc_base32hexnp_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); 99 /*!< 100 * \brief Convert text encoded in base32, base32hex, or base32hex 101 * non-padded from a lexer context into `target`. If 'length' is 102 * non-negative, it is the expected number of encoded octets to convert. 103 * 104 * If 'length' is -1 then 0 or more encoded octets are expected. 105 * If 'length' is -2 then 1 or more encoded octets are expected. 106 * 107 * Returns: 108 *\li #ISC_R_BADBASE32 -- invalid base32 encoding. 109 *\li #ISC_R_UNEXPECTEDEND: the text does not contain the expected 110 * number of encoded octets. 111 * 112 * Requires: 113 *\li 'lexer' is a valid lexer context 114 *\li 'target' is a buffer containing binary data 115 *\li 'length' is -2, -1, or non-negative 116 * 117 * Ensures: 118 *\li target will contain the data represented by the base32 encoded 119 * string parsed by the lexer. No more than `length` octets will 120 * be read, if `length` is non-negative. The 'used' pointer in 121 * 'target' will be advanced as necessary. 122 */ 123 124 isc_result_t 125 isc_base32_decoderegion(isc_region_t *source, isc_buffer_t *target); 126 isc_result_t 127 isc_base32hex_decoderegion(isc_region_t *source, isc_buffer_t *target); 128 isc_result_t 129 isc_base32hexnp_decoderegion(isc_region_t *source, isc_buffer_t *target); 130 /*!< 131 * \brief Decode a packed (no white space permitted) region in 132 * base32, base32hex or base32hex non-padded. 133 * 134 * Requires: 135 *\li 'source' is a valid region. 136 *\li 'target' is a valid buffer. 137 * 138 * Returns: 139 *\li #ISC_R_SUCCESS -- the entire decoded representation of 'cstring' 140 * fit in 'target'. 141 *\li #ISC_R_BADBASE32 -- 'source' is not a valid base32 encoding. 142 */ 143 144 ISC_LANG_ENDDECLS 145 146 #endif /* ISC_BASE32_H */ 147