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