Added ChaCha20+Poly1305 support (stand-alone, cipher suites).
[BearSSL] / tools / brssl.h
1 /*
2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25 #ifndef BRSSL_H__
26 #define BRSSL_H__
27
28 #include <stdio.h>
29 #include <stdlib.h>
30 #include <string.h>
31 #include <stdint.h>
32
33 #include "bearssl.h"
34
35 /*
36 * malloc() wrapper:
37 * -- If len is 0, then NULL is returned.
38 * -- If len is non-zero, and allocation fails, then an error message is
39 * printed and the process exits with an error code.
40 */
41 void *xmalloc(size_t len);
42
43 /*
44 * free() wrapper, meant to release blocks allocated with xmalloc().
45 */
46 void xfree(void *buf);
47
48 /*
49 * Duplicate a character string into a newly allocated block.
50 */
51 char *xstrdup(const void *src);
52
53 /*
54 * Allocate a new block with the provided length, filled with a copy
55 * of exactly that many bytes starting at address 'src'.
56 */
57 void *xblobdup(const void *src, size_t len);
58
59 /*
60 * Duplicate a public key, into newly allocated blocks. The returned
61 * key must be later on released with xfreepkey().
62 */
63 br_x509_pkey *xpkeydup(const br_x509_pkey *pk);
64
65 /*
66 * Release a public key that was allocated with xpkeydup(). If pk is NULL,
67 * this function does nothing.
68 */
69 void xfreepkey(br_x509_pkey *pk);
70
71 /*
72 * Macros for growable arrays.
73 */
74
75 /*
76 * Make a structure type for a vector of 'type'.
77 */
78 #define VECTOR(type) struct { \
79 type *buf; \
80 size_t ptr, len; \
81 }
82
83 /*
84 * Constant initialiser for a vector.
85 */
86 #define VEC_INIT { 0, 0, 0 }
87
88 /*
89 * Clear a vector.
90 */
91 #define VEC_CLEAR(vec) do { \
92 xfree((vec).buf); \
93 (vec).buf = NULL; \
94 (vec).ptr = 0; \
95 (vec).len = 0; \
96 } while (0)
97
98 /*
99 * Clear a vector, first calling the provided function on each vector
100 * element.
101 */
102 #define VEC_CLEAREXT(vec, fun) do { \
103 size_t vec_tmp; \
104 for (vec_tmp = 0; vec_tmp < (vec).ptr; vec_tmp ++) { \
105 (fun)(&(vec).buf[vec_tmp]); \
106 } \
107 VEC_CLEAR(vec); \
108 } while (0)
109
110 /*
111 * Add a value at the end of a vector.
112 */
113 #define VEC_ADD(vec, x) do { \
114 (vec).buf = vector_expand((vec).buf, sizeof *((vec).buf), \
115 &(vec).ptr, &(vec).len, 1); \
116 (vec).buf[(vec).ptr ++] = (x); \
117 } while (0)
118
119 /*
120 * Add several values at the end of a vector.
121 */
122 #define VEC_ADDMANY(vec, xp, num) do { \
123 size_t vec_num = (num); \
124 (vec).buf = vector_expand((vec).buf, sizeof *((vec).buf), \
125 &(vec).ptr, &(vec).len, vec_num); \
126 memcpy((vec).buf + (vec).ptr, \
127 (xp), vec_num * sizeof *((vec).buf)); \
128 (vec).ptr += vec_num; \
129 } while (0)
130
131 /*
132 * Access a vector element by index. This is a lvalue, and can be modified.
133 */
134 #define VEC_ELT(vec, idx) ((vec).buf[idx])
135
136 /*
137 * Get current vector length.
138 */
139 #define VEC_LEN(vec) ((vec).ptr)
140
141 /*
142 * Copy all vector elements into a newly allocated block.
143 */
144 #define VEC_TOARRAY(vec) xblobdup((vec).buf, sizeof *((vec).buf) * (vec).ptr)
145
146 /*
147 * Internal function used to handle memory allocations for vectors.
148 */
149 void *vector_expand(void *buf,
150 size_t esize, size_t *ptr, size_t *len, size_t extra);
151
152 /*
153 * Type for a vector of bytes.
154 */
155 typedef VECTOR(unsigned char) bvector;
156
157 /*
158 * Compare two strings for equality; returned value is 1 if the strings
159 * are to be considered equal, 0 otherwise. Comparison is case-insensitive
160 * (ASCII letters only) and skips some characters (all whitespace, defined
161 * as ASCII codes 0 to 32 inclusive, and also '-', '_', '.', '/', '+' and
162 * ':').
163 */
164 int eqstr(const char *s1, const char *s2);
165
166 /*
167 * Convert a string to a positive integer (size_t). Returned value is
168 * (size_t)-1 on error. On error, an explicit error message is printed.
169 */
170 size_t parse_size(const char *s);
171
172 /*
173 * Structure for a known protocol version.
174 */
175 typedef struct {
176 const char *name;
177 unsigned version;
178 const char *comment;
179 } protocol_version;
180
181 /*
182 * Known protocol versions. Last element has a NULL name.
183 */
184 extern const protocol_version protocol_versions[];
185
186 /*
187 * Parse a version name. If the name is not recognized, then an error
188 * message is printed, and 0 is returned.
189 */
190 unsigned parse_version(const char *name, size_t len);
191
192 /*
193 * Type for a known hash function.
194 */
195 typedef struct {
196 const char *name;
197 const br_hash_class *hclass;
198 const char *comment;
199 } hash_function;
200
201 /*
202 * Known hash functions. Last element has a NULL name.
203 */
204 extern const hash_function hash_functions[];
205
206 /*
207 * Parse hash function names. This function expects a comma-separated
208 * list of names, and returns a bit mask corresponding to the matched
209 * names. If one of the name does not match, or the list is empty, then
210 * an error message is printed, and 0 is returned.
211 */
212 unsigned parse_hash_functions(const char *arg);
213
214 /*
215 * Type for a known cipher suite.
216 */
217 typedef struct {
218 const char *name;
219 uint16_t suite;
220 unsigned req;
221 const char *comment;
222 } cipher_suite;
223
224 /*
225 * Known cipher suites. Last element has a NULL name.
226 */
227 extern const cipher_suite cipher_suites[];
228
229 /*
230 * Flags for cipher suite requirements.
231 */
232 #define REQ_TLS12 0x0001 /* suite needs TLS 1.2 */
233 #define REQ_SHA1 0x0002 /* suite needs SHA-1 */
234 #define REQ_SHA256 0x0004 /* suite needs SHA-256 */
235 #define REQ_SHA384 0x0008 /* suite needs SHA-384 */
236 #define REQ_AESCBC 0x0010 /* suite needs AES/CBC encryption */
237 #define REQ_AESGCM 0x0020 /* suite needs AES/GCM encryption */
238 #define REQ_CHAPOL 0x0040 /* suite needs ChaCha20+Poly1305 */
239 #define REQ_3DESCBC 0x0080 /* suite needs 3DES/CBC encryption */
240 #define REQ_RSAKEYX 0x0100 /* suite uses RSA key exchange */
241 #define REQ_ECDHE_RSA 0x0200 /* suite uses ECDHE_RSA key exchange */
242 #define REQ_ECDHE_ECDSA 0x0400 /* suite uses ECDHE_ECDSA key exchange */
243 #define REQ_ECDH 0x0800 /* suite uses static ECDH key exchange */
244
245 /*
246 * Parse a list of cipher suite names. The names are comma-separated. If
247 * one of the name is not recognised, or the list is empty, then an
248 * appropriate error message is printed, and NULL is returned.
249 * The returned array is allocated with xmalloc() and must be released
250 * by the caller. That array is terminated with a dummy entry whose 'name'
251 * field is NULL. The number of entries (not counting the dummy entry)
252 * is also written into '*num'.
253 */
254 cipher_suite *parse_suites(const char *arg, size_t *num);
255
256 /*
257 * Get the name of a cipher suite. Returned value is NULL if the suite is
258 * not recognized.
259 */
260 const char *get_suite_name(unsigned suite);
261
262 /*
263 * Get the name of a cipher suite. The name is written in the provided
264 * buffer; if the suite is not recognised, then the name is
265 * "unknown (0x****)" where "****" is the hexadecimal value of the suite.
266 * If the name does not fit in the provided buffer, then dst[0] is set
267 * to 0 (unless len is 0, in which case nothing is written), and -1 is
268 * returned. Otherwise, the name is written in dst[] (with a terminating
269 * 0), and this function returns 0.
270 */
271 int get_suite_name_ext(unsigned suite, char *dst, size_t len);
272
273 /*
274 * Print out all known names (for protocol versions, cipher suites...).
275 */
276 void list_names(void);
277
278 /*
279 * Get the symbolic name for an elliptic curve (by ID).
280 */
281 const char *ec_curve_name(int curve);
282
283 /*
284 * Get the symbolic name for a hash function name (by ID).
285 */
286 const char *hash_function_name(int id);
287
288 /*
289 * Read a file completely. The returned block is allocated with xmalloc()
290 * and must be released by the caller.
291 * If the file cannot be found or read completely, or is empty, then an
292 * appropriate error message is written, and NULL is returned.
293 */
294 unsigned char *read_file(const char *fname, size_t *len);
295
296 /*
297 * Write a file completely. This returns 0 on success, -1 on error. On
298 * error, an appropriate error message is printed.
299 */
300 int write_file(const char *fname, const void *data, size_t len);
301
302 /*
303 * This function returns non-zero if the provided buffer "looks like"
304 * a DER-encoded ASN.1 object (criteria: it has the tag for a SEQUENCE
305 * with a definite length that matches the total object length).
306 */
307 int looks_like_DER(const unsigned char *buf, size_t len);
308
309 /*
310 * Type for a named blob (the 'name' is a normalised PEM header name).
311 */
312 typedef struct {
313 char *name;
314 unsigned char *data;
315 size_t data_len;
316 } pem_object;
317
318 /*
319 * Release the contents of a named blob (buffer and name).
320 */
321 void free_pem_object_contents(pem_object *po);
322
323 /*
324 * Decode a buffer as a PEM file, and return all objects. On error, NULL
325 * is returned and an error message is printed. Absence of any object
326 * is an error.
327 *
328 * The returned array is terminated by a dummy object whose 'name' is
329 * NULL. The number of objects (not counting the dummy terminator) is
330 * written in '*num'.
331 */
332 pem_object *decode_pem(const void *src, size_t len, size_t *num);
333
334 /*
335 * Get the certificate(s) from a file. This accepts both a single
336 * DER-encoded certificate, and a text file that contains
337 * PEM-encoded certificates (and possibly other objects, which are
338 * then ignored).
339 *
340 * On decoding error, or if the file turns out to contain no certificate
341 * at all, then an error message is printed and NULL is returned.
342 *
343 * The returned array, and all referenced buffers, are allocated with
344 * xmalloc() and must be released by the caller. The returned array
345 * ends with a dummy entry whose 'data' field is NULL.
346 * The number of decoded certificates (not counting the dummy entry)
347 * is written into '*num'.
348 */
349 br_x509_certificate *read_certificates(const char *fname, size_t *num);
350
351 /*
352 * Release certificates. This releases all certificate data arrays,
353 * and the whole array as well.
354 */
355 void free_certificates(br_x509_certificate *certs, size_t num);
356
357 /*
358 * Interpret a certificate as a trust anchor. The trust anchor is
359 * newly allocated with xmalloc() and the caller must release it.
360 * On decoding error, an error message is printed, and this function
361 * returns NULL.
362 */
363 br_x509_trust_anchor *certificate_to_trust_anchor(br_x509_certificate *xc);
364
365 /*
366 * Type for a vector of trust anchors.
367 */
368 typedef VECTOR(br_x509_trust_anchor) anchor_list;
369
370 /*
371 * Release contents for a trust anchor (assuming they were dynamically
372 * allocated with xmalloc()). The structure itself is NOT released.
373 */
374 void free_ta_contents(br_x509_trust_anchor *ta);
375
376 /*
377 * Decode certificates from a file and interpret them as trust anchors.
378 * The trust anchors are added to the provided list. The number of found
379 * anchors is returned; on error, 0 is returned (finding no anchor at
380 * all is considered an error). An appropriate error message is displayed.
381 */
382 size_t read_trust_anchors(anchor_list *dst, const char *fname);
383
384 /*
385 * Get the "signer key type" for the certificate (key type of the
386 * issuing CA). On error, this prints a message on stderr, and returns 0.
387 */
388 int get_cert_signer_algo(br_x509_certificate *xc);
389
390 /*
391 * Special "no anchor" X.509 validator that wraps around another X.509
392 * validator and turns "not trusted" error codes into success. This is
393 * by definition insecure, but convenient for debug purposes.
394 */
395 typedef struct {
396 const br_x509_class *vtable;
397 const br_x509_class **inner;
398 } x509_noanchor_context;
399 extern const br_x509_class x509_noanchor_vtable;
400
401 /*
402 * Initialise a "no anchor" X.509 validator.
403 */
404 void x509_noanchor_init(x509_noanchor_context *xwc,
405 const br_x509_class **inner);
406
407 /*
408 * Aggregate type for a private key.
409 */
410 typedef struct {
411 int key_type; /* BR_KEYTYPE_RSA or BR_KEYTYPE_EC */
412 union {
413 br_rsa_private_key rsa;
414 br_ec_private_key ec;
415 } key;
416 } private_key;
417
418 /*
419 * Decode a private key from a file. On error, this prints an error
420 * message and returns NULL.
421 */
422 private_key *read_private_key(const char *fname);
423
424 /*
425 * Free a private key.
426 */
427 void free_private_key(private_key *sk);
428
429 /*
430 * Get the encoded OID for a given hash function (to use with PKCS#1
431 * signatures). If the hash function ID is 0 (for MD5+SHA-1), or if
432 * the ID is not one of the SHA-* functions (SHA-1, SHA-224, SHA-256,
433 * SHA-384, SHA-512), then this function returns NULL.
434 */
435 const unsigned char *get_hash_oid(int id);
436
437 /*
438 * Get a hash implementation by ID. This returns NULL if the hash
439 * implementation is not available.
440 */
441 const br_hash_class *get_hash_impl(int id);
442
443 /*
444 * Find the symbolic name and the description for an error. If 'err' is
445 * recognised then the error symbolic name is returned; if 'comment' is
446 * not NULL then '*comment' is then set to a descriptive human-readable
447 * message. If the error code 'err' is not recognised, then '*comment' is
448 * untouched and this function returns NULL.
449 */
450 const char *find_error_name(int err, const char **comment);
451
452 /*
453 * Run a SSL engine, with a socket connected to the peer, and using
454 * stdin/stdout to exchange application data.
455 *
456 * Returned value:
457 * 0 SSL connection closed successfully
458 * x > 0 SSL error "x"
459 * -1 early socket close
460 * -2 stdout was closed, or something failed badly
461 */
462 int run_ssl_engine(br_ssl_engine_context *eng, int fd, unsigned flags);
463
464 #define RUN_ENGINE_VERBOSE 0x0001 /* enable verbose messages */
465 #define RUN_ENGINE_TRACE 0x0002 /* hex dump of records */
466
467 /*
468 * Do the "client" command. Returned value is 0 on success, -1 on failure.
469 * Command-line arguments start _after_ the command name.
470 */
471 int do_client(int argc, char *argv[]);
472
473 /*
474 * Do the "server" command. Returned value is 0 on success, -1 on failure.
475 * Command-line arguments start _after_ the command name.
476 */
477 int do_server(int argc, char *argv[]);
478
479 /*
480 * Do the "verify" command. Returned value is 0 on success, -1 on failure.
481 * Command-line arguments start _after_ the command name.
482 */
483 int do_verify(int argc, char *argv[]);
484
485 /*
486 * Do the "skey" command. Returned value is 0 on success, -1 on failure.
487 * Command-line arguments start _after_ the command name.
488 */
489 int do_skey(int argc, char *argv[]);
490
491 /*
492 * Do the "ta" command. Returned value is 0 on success, -1 on failure.
493 * Command-line arguments start _after_ the command name.
494 */
495 int do_ta(int argc, char *argv[]);
496
497 /*
498 * Do the "chain" command. Returned value is 0 on success, -1 on failure.
499 * Command-line arguments start _after_ the command name.
500 */
501 int do_chain(int argc, char *argv[]);
502
503 #endif