1ZARMOUR(3) CZMQ Manual ZARMOUR(3)
2
6 zarmour - Class for armoured text encoding and decoding
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 #define ZARMOUR_MODE_BASE64_STD 0 // Standard base 64
12 #define ZARMOUR_MODE_BASE64_URL 1 // URL and filename friendly base 64
13 #define ZARMOUR_MODE_BASE32_STD 2 // Standard base 32
14 #define ZARMOUR_MODE_BASE32_HEX 3 // Extended hex base 32
15 #define ZARMOUR_MODE_BASE16 4 // Standard base 16
16 #define ZARMOUR_MODE_Z85 5 // Z85 from ZeroMQ RFC 32
17 // Create a new zarmour
19 CZMQ_EXPORT zarmour_t *
20 zarmour_new (void);
21 // Destroy the zarmour
23 CZMQ_EXPORT void
24 zarmour_destroy (zarmour_t **self_p);
25 // Encode a stream of bytes into an armoured string. Returns the armoured
27 // string, or NULL if there was insufficient memory available to allocate
28 // a new string.
29 // Caller owns return value and must destroy it when done.
30 CZMQ_EXPORT char *
31 zarmour_encode (zarmour_t *self, const byte *data, size_t size);
32 // Decode an armoured string into a chunk. The decoded output is
34 // null-terminated, so it may be treated as a string, if that's what
35 // it was prior to encoding.
36 // Caller owns return value and must destroy it when done.
37 CZMQ_EXPORT zchunk_t *
38 zarmour_decode (zarmour_t *self, const char *data);
39 // Get the mode property.
41 CZMQ_EXPORT int
42 zarmour_mode (zarmour_t *self);
43 // Get printable string for mode.
45 CZMQ_EXPORT const char *
46 zarmour_mode_str (zarmour_t *self);
47 // Set the mode property.
49 CZMQ_EXPORT void
50 zarmour_set_mode (zarmour_t *self, int mode);
51 // Return true if padding is turned on.
53 CZMQ_EXPORT bool
54 zarmour_pad (zarmour_t *self);
55 // Turn padding on or off. Default is on.
57 CZMQ_EXPORT void
58 zarmour_set_pad (zarmour_t *self, bool pad);
59 // Get the padding character.
61 CZMQ_EXPORT char
62 zarmour_pad_char (zarmour_t *self);
63 // Set the padding character.
65 CZMQ_EXPORT void
66 zarmour_set_pad_char (zarmour_t *self, char pad_char);
67 // Return if splitting output into lines is turned on. Default is off.
69 CZMQ_EXPORT bool
70 zarmour_line_breaks (zarmour_t *self);
71 // Turn splitting output into lines on or off.
73 CZMQ_EXPORT void
74 zarmour_set_line_breaks (zarmour_t *self, bool line_breaks);
75 // Get the line length used for splitting lines.
77 CZMQ_EXPORT size_t
78 zarmour_line_length (zarmour_t *self);
79 // Set the line length used for splitting lines.
81 CZMQ_EXPORT void
82 zarmour_set_line_length (zarmour_t *self, size_t line_length);
83 // Print properties of object
85 CZMQ_EXPORT void
86 zarmour_print (zarmour_t *self);
87 // Self test of this class.
89 CZMQ_EXPORT void
90 zarmour_test (bool verbose);
91 Please add '@interface' section in './../src/zarmour.c'.
93
95 zarmour - armoured text encoding and decoding
96 The zarmour class implements encoding and decoding of armoured text
98 data. The following codecs are implemented: * RFC 4648
99 (http://www.ietf.org/rfc/rfc4648.txt) - base64 - base64url - base32 -
100 base32hex - base16 * Z85 (http://rfc.zeromq.org/spec:32) All RFC4648
101 base64 and base32 variants support padding the output. The pad
102 character is configurable. Default is padding on, with character =.
103 Additionally, in some cases (e.g. MIME), splitting the output into
104 lines of a specific length is required. This feature is also supported,
105 though turned off by default. The z85 mode does neither padding nor
106 line breaks; it is merely a wrapping of the corresponding libzmq
107 methods. Encoding will assert if input length is not divisible by 4 and
108 decoding will assert if input length is not divisible by 5.
109
111 From zarmour_test method.
112 zarmour_t *self = zarmour_new ();
114 assert (self);
115 int mode = zarmour_mode (self);
117 assert (mode == ZARMOUR_MODE_BASE64_STD);
118 zarmour_set_mode (self, ZARMOUR_MODE_BASE64_URL);
120 mode = zarmour_mode (self);
121 assert (mode == ZARMOUR_MODE_BASE64_URL);
122 assert (zarmour_pad (self));
124 zarmour_set_pad (self, false);
125 assert (!zarmour_pad (self));
126 assert (zarmour_pad_char (self) == '=');
128 zarmour_set_pad_char (self, '!');
129 assert (zarmour_pad_char (self) == '!');
130 zarmour_set_pad_char (self, '=');
131 assert (zarmour_pad_char (self) == '=');
132 assert (!zarmour_line_breaks (self));
134 zarmour_set_line_breaks (self, true);
135 assert (zarmour_line_breaks (self));
136 assert (zarmour_line_length (self) == 72);
138 zarmour_set_line_length (self, 64);
139 assert (zarmour_line_length (self) == 64);
140 // Test against test vectors from RFC4648.
142 zarmour_set_mode (self, ZARMOUR_MODE_BASE64_STD);
143 if (verbose)
144 zarmour_print (self);
145 s_armour_test (self, "", "", verbose);
147 s_armour_test (self, "f", "Zg", verbose);
148 s_armour_test (self, "fo", "Zm8", verbose);
149 s_armour_test (self, "foo", "Zm9v", verbose);
150 s_armour_test (self, "foob", "Zm9vYg", verbose);
151 s_armour_test (self, "fooba", "Zm9vYmE", verbose);
152 s_armour_test (self, "foobar", "Zm9vYmFy", verbose);
153 zarmour_set_pad (self, true);
154 if (verbose)
155 zarmour_print (self);
156 s_armour_test (self, "", "", verbose);
158 s_armour_test (self, "f", "Zg==", verbose);
159 s_armour_test (self, "fo", "Zm8=", verbose);
160 s_armour_test (self, "foo", "Zm9v", verbose);
161 s_armour_test (self, "foob", "Zm9vYg==", verbose);
162 s_armour_test (self, "fooba", "Zm9vYmE=", verbose);
163 s_armour_test (self, "foobar", "Zm9vYmFy", verbose);
164 zarmour_set_pad (self, false);
166 zarmour_set_mode (self, ZARMOUR_MODE_BASE64_URL);
167 if (verbose)
168 zarmour_print (self);
169 s_armour_test (self, "", "", verbose);
171 s_armour_test (self, "f", "Zg", verbose);
172 s_armour_test (self, "fo", "Zm8", verbose);
173 s_armour_test (self, "foo", "Zm9v", verbose);
174 s_armour_test (self, "foob", "Zm9vYg", verbose);
175 s_armour_test (self, "fooba", "Zm9vYmE", verbose);
176 s_armour_test (self, "foobar", "Zm9vYmFy", verbose);
177 zarmour_set_pad (self, true);
178 if (verbose)
179 zarmour_print (self);
180 s_armour_test (self, "", "", verbose);
182 s_armour_test (self, "f", "Zg==", verbose);
183 s_armour_test (self, "fo", "Zm8=", verbose);
184 s_armour_test (self, "foo", "Zm9v", verbose);
185 s_armour_test (self, "foob", "Zm9vYg==", verbose);
186 s_armour_test (self, "fooba", "Zm9vYmE=", verbose);
187 s_armour_test (self, "foobar", "Zm9vYmFy", verbose);
188 zarmour_set_pad (self, false);
190 zarmour_set_mode (self, ZARMOUR_MODE_BASE32_STD);
191 if (verbose)
192 zarmour_print (self);
193 s_armour_test (self, "", "", verbose);
195 s_armour_test (self, "f", "MY", verbose);
196 s_armour_test (self, "fo", "MZXQ", verbose);
197 s_armour_test (self, "foo", "MZXW6", verbose);
198 s_armour_test (self, "foob", "MZXW6YQ", verbose);
199 s_armour_test (self, "fooba", "MZXW6YTB", verbose);
200 s_armour_test (self, "foobar", "MZXW6YTBOI", verbose);
201 s_armour_decode (self, "my", "f", verbose);
202 s_armour_decode (self, "mzxq", "fo", verbose);
203 s_armour_decode (self, "mzxw6", "foo", verbose);
204 s_armour_decode (self, "mzxw6yq", "foob", verbose);
205 s_armour_decode (self, "mzxw6ytb", "fooba", verbose);
206 s_armour_decode (self, "mzxw6ytboi", "foobar", verbose);
207 zarmour_set_pad (self, true);
208 if (verbose)
209 zarmour_print (self);
210 s_armour_test (self, "", "", verbose);
212 s_armour_test (self, "f", "MY======", verbose);
213 s_armour_test (self, "fo", "MZXQ====", verbose);
214 s_armour_test (self, "foo", "MZXW6===", verbose);
215 s_armour_test (self, "foob", "MZXW6YQ=", verbose);
216 s_armour_test (self, "fooba", "MZXW6YTB", verbose);
217 s_armour_test (self, "foobar", "MZXW6YTBOI======", verbose);
218 s_armour_decode (self, "my======", "f", verbose);
219 s_armour_decode (self, "mzxq====", "fo", verbose);
220 s_armour_decode (self, "mzxw6===", "foo", verbose);
221 s_armour_decode (self, "mzxw6yq=", "foob", verbose);
222 s_armour_decode (self, "mzxw6ytb", "fooba", verbose);
223 s_armour_decode (self, "mzxw6ytboi======", "foobar", verbose);
224 zarmour_set_pad (self, false);
226 zarmour_set_mode (self, ZARMOUR_MODE_BASE32_HEX);
227 if (verbose)
228 zarmour_print (self);
229 s_armour_test (self, "", "", verbose);
231 s_armour_test (self, "f", "CO", verbose);
232 s_armour_test (self, "fo", "CPNG", verbose);
233 s_armour_test (self, "foo", "CPNMU", verbose);
234 s_armour_test (self, "foob", "CPNMUOG", verbose);
235 s_armour_test (self, "fooba", "CPNMUOJ1", verbose);
236 s_armour_test (self, "foobar", "CPNMUOJ1E8", verbose);
237 s_armour_decode (self, "co", "f", verbose);
238 s_armour_decode (self, "cpng", "fo", verbose);
239 s_armour_decode (self, "cpnmu", "foo", verbose);
240 s_armour_decode (self, "cpnmuog", "foob", verbose);
241 s_armour_decode (self, "cpnmuoj1", "fooba", verbose);
242 s_armour_decode (self, "cpnmuoj1e8", "foobar", verbose);
243 zarmour_set_pad (self, true);
244 if (verbose)
245 zarmour_print (self);
246 s_armour_test (self, "", "", verbose);
248 s_armour_test (self, "f", "CO======", verbose);
249 s_armour_test (self, "fo", "CPNG====", verbose);
250 s_armour_test (self, "foo", "CPNMU===", verbose);
251 s_armour_test (self, "foob", "CPNMUOG=", verbose);
252 s_armour_test (self, "fooba", "CPNMUOJ1", verbose);
253 s_armour_test (self, "foobar", "CPNMUOJ1E8======", verbose);
254 s_armour_decode (self, "co======", "f", verbose);
255 s_armour_decode (self, "cpng====", "fo", verbose);
256 s_armour_decode (self, "cpnmu===", "foo", verbose);
257 s_armour_decode (self, "cpnmuog=", "foob", verbose);
258 s_armour_decode (self, "cpnmuoj1", "fooba", verbose);
259 s_armour_decode (self, "cpnmuoj1e8======", "foobar", verbose);
260 zarmour_set_pad (self, true);
261 zarmour_set_mode (self, ZARMOUR_MODE_BASE16);
263 if (verbose)
264 zarmour_print (self);
265 s_armour_test (self, "", "", verbose);
267 s_armour_test (self, "f", "66", verbose);
268 s_armour_test (self, "fo", "666F", verbose);
269 s_armour_test (self, "foo", "666F6F", verbose);
270 s_armour_test (self, "foob", "666F6F62", verbose);
271 s_armour_test (self, "fooba", "666F6F6261", verbose);
272 s_armour_test (self, "foobar", "666F6F626172", verbose);
273 s_armour_decode (self, "666f", "fo", verbose);
274 s_armour_decode (self, "666f6f", "foo", verbose);
275 s_armour_decode (self, "666f6f62", "foob", verbose);
276 s_armour_decode (self, "666f6f6261", "fooba", verbose);
277 s_armour_decode (self, "666f6f626172", "foobar", verbose);
278 #ifdef _INCLUDE_Z85
280 // Z85 test is homemade; using 0, 4 and 8 bytes, with precalculated
281 // test vectors created with a libzmq test.
282 // ----------------------------------------------------------------
283 // Make a fake curve key from hex (base16) string, making sure
285 // there are no null bytes inside, so we can use our test utility
286 zarmour_set_mode (self, ZARMOUR_MODE_BASE16);
287 zarmour_set_line_breaks (self, false);
288 zchunk_t *chunk = zarmour_decode (self,
290 "4E6F87E2FB6EB22A1EF5E257B75D79124949565F0B8B36A878A4F03111C96E0B");
291 assert (chunk);
292 zarmour_set_mode (self, ZARMOUR_MODE_Z85); // Z85 mode does not support padding or line breaks
294 zarmour_set_pad (self, false); // so these two are superfluous;
295 zarmour_set_line_breaks (self, false); // just for consistency
296 if (verbose)
297 zarmour_print (self);
298 s_armour_test (self, "", "", verbose);
300 s_armour_test (self, "foob", "w]zP%", verbose);
301 s_armour_test (self, "foobar!!", "w]zP%vr9Im", verbose);
302 s_armour_test (self, (char *) zchunk_data (chunk),
303 "ph+{E}!&X?9}!I]W{sm(nL8@&3Yu{wC+<*-5Y[[#", verbose);
304 zchunk_destroy (&chunk);
305 #endif
306 // Armouring longer byte array to test line breaks
308 zarmour_set_pad (self, true);
309 zarmour_set_line_breaks (self, true);
310 byte test_data [256];
311 int index;
312 for (index = 0; index < 256; index++)
313 test_data [index] = index;
314 zarmour_set_mode (self, ZARMOUR_MODE_BASE64_STD);
316 s_armour_test_long (self, test_data, 256, verbose);
317 zarmour_set_mode (self, ZARMOUR_MODE_BASE64_URL);
318 s_armour_test_long (self, test_data, 256, verbose);
319 zarmour_set_mode (self, ZARMOUR_MODE_BASE32_STD);
320 s_armour_test_long (self, test_data, 256, verbose);
321 zarmour_set_mode (self, ZARMOUR_MODE_BASE32_HEX);
322 s_armour_test_long (self, test_data, 256, verbose);
323 zarmour_set_mode (self, ZARMOUR_MODE_BASE16);
324 s_armour_test_long (self, test_data, 256, verbose);
325 #ifdef _INCLUDE_Z85
326 zarmour_set_mode (self, ZARMOUR_MODE_Z85);
327 s_armour_test_long (self, test_data, 256, verbose);
328 #endif
329 zarmour_destroy (&self);
331 #if defined (__WINDOWS__)
333 zsys_shutdown();
334 #endif
335
338 The czmq manual was written by the authors in the AUTHORS file.
339
341 Main web site:
342 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
344
346 Copyright (c) the Contributors as noted in the AUTHORS file. This file
347 is part of CZMQ, the high-level C binding for 0MQ:
348 http://czmq.zeromq.org. This Source Code Form is subject to the terms
349 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
350 distributed with this file, You can obtain one at
351 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
352 distribution.
353
355 1. zeromq-dev@lists.zeromq.org
356 mailto:zeromq-dev@lists.zeromq.org
357CZMQ 4.2.1 07/19/2023 ZARMOUR(3)