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