1 /* $NetBSD: base32.h,v 1.5 2014/12/10 04:38:00 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2008, 2014 Internet Systems Consortium, Inc. ("ISC") 5 * 6 * Permission to use, copy, modify, and/or distribute this software for any 7 * purpose with or without fee is hereby granted, provided that the above 8 * copyright notice and this permission notice appear in all copies. 9 * 10 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 11 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 12 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 13 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 14 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 15 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 16 * PERFORMANCE OF THIS SOFTWARE. 17 */ 18 19 #ifndef ISC_BASE32_H 20 #define ISC_BASE32_H 1 21 22 /*! \file */ 23 24 /* 25 * Routines for manipulating base 32 and base 32 hex encoded data. 26 * Based on RFC 4648. 27 * 28 * Base 32 hex preserves the sort order of data when it is encoded / 29 * decoded. 30 * 31 * Base 32 hex "np" is base 32 hex but no padding is produced or accepted. 32 */ 33 34 #include <isc/lang.h> 35 #include <isc/types.h> 36 37 ISC_LANG_BEGINDECLS 38 39 /*** 40 *** Functions 41 ***/ 42 43 isc_result_t 44 isc_base32_totext(isc_region_t *source, int wordlength, 45 const char *wordbreak, isc_buffer_t *target); 46 isc_result_t 47 isc_base32hex_totext(isc_region_t *source, int wordlength, 48 const char *wordbreak, isc_buffer_t *target); 49 isc_result_t 50 isc_base32hexnp_totext(isc_region_t *source, int wordlength, 51 const char *wordbreak, isc_buffer_t *target); 52 /*!< 53 * \brief Convert data into base32 encoded text. 54 * 55 * Notes: 56 *\li The base32 encoded text in 'target' will be divided into 57 * words of at most 'wordlength' characters, separated by 58 * the 'wordbreak' string. No parentheses will surround 59 * the text. 60 * 61 * Requires: 62 *\li 'source' is a region containing binary data 63 *\li 'target' is a text buffer containing available space 64 *\li 'wordbreak' points to a null-terminated string of 65 * zero or more whitespace characters 66 * 67 * Ensures: 68 *\li target will contain the base32 encoded version of the data 69 * in source. The 'used' pointer in target will be advanced as 70 * necessary. 71 */ 72 73 isc_result_t 74 isc_base32_decodestring(const char *cstr, isc_buffer_t *target); 75 isc_result_t 76 isc_base32hex_decodestring(const char *cstr, isc_buffer_t *target); 77 isc_result_t 78 isc_base32hexnp_decodestring(const char *cstr, isc_buffer_t *target); 79 /*!< 80 * \brief Decode a null-terminated string in base32, base32hex, or 81 * base32hex non-padded. 82 * 83 * Requires: 84 *\li 'cstr' is non-null. 85 *\li 'target' is a valid buffer. 86 * 87 * Returns: 88 *\li #ISC_R_SUCCESS -- the entire decoded representation of 'cstring' 89 * fit in 'target'. 90 *\li #ISC_R_BADBASE32 -- 'cstr' is not a valid base32 encoding. 91 * 92 * Other error returns are any possible error code from: 93 *\li isc_lex_create(), 94 *\li isc_lex_openbuffer(), 95 *\li isc_base32_tobuffer(). 96 */ 97 98 isc_result_t 99 isc_base32_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); 100 isc_result_t 101 isc_base32hex_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); 102 isc_result_t 103 isc_base32hexnp_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); 104 /*!< 105 * \brief Convert text encoded in base32, base32hex, or base32hex 106 * non-padded from a lexer context into data. 107 * 108 * Requires: 109 *\li 'lex' is a valid lexer context 110 *\li 'target' is a buffer containing binary data 111 *\li 'length' is an integer 112 * 113 * Ensures: 114 *\li target will contain the data represented by the base32 encoded 115 * string parsed by the lexer. No more than length bytes will be read, 116 * if length is positive. The 'used' pointer in target will be 117 * advanced as necessary. 118 */ 119 120 isc_result_t 121 isc_base32_decoderegion(isc_region_t *source, isc_buffer_t *target); 122 isc_result_t 123 isc_base32hex_decoderegion(isc_region_t *source, isc_buffer_t *target); 124 isc_result_t 125 isc_base32hexnp_decoderegion(isc_region_t *source, isc_buffer_t *target); 126 /*!< 127 * \brief Decode a packed (no white space permitted) region in 128 * base32, base32hex or base32hex non-padded. 129 * 130 * Requires: 131 *\li 'source' is a valid region. 132 *\li 'target' is a valid buffer. 133 * 134 * Returns: 135 *\li #ISC_R_SUCCESS -- the entire decoded representation of 'cstring' 136 * fit in 'target'. 137 *\li #ISC_R_BADBASE32 -- 'source' is not a valid base32 encoding. 138 */ 139 140 ISC_LANG_ENDDECLS 141 142 #endif /* ISC_BASE32_H */ 143