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