2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
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:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
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
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.
41 void *xmalloc(size_t len
);
44 * free() wrapper, meant to release blocks allocated with xmalloc().
46 void xfree(void *buf
);
49 * Duplicate a character string into a newly allocated block.
51 char *xstrdup(const void *src
);
54 * Allocate a new block with the provided length, filled with a copy
55 * of exactly that many bytes starting at address 'src'.
57 void *xblobdup(const void *src
, size_t len
);
60 * Duplicate a public key, into newly allocated blocks. The returned
61 * key must be later on released with xfreepkey().
63 br_x509_pkey
*xpkeydup(const br_x509_pkey
*pk
);
66 * Release a public key that was allocated with xpkeydup(). If pk is NULL,
67 * this function does nothing.
69 void xfreepkey(br_x509_pkey
*pk
);
72 * Macros for growable arrays.
76 * Make a structure type for a vector of 'type'.
78 #define VECTOR(type) struct { \
84 * Constant initialiser for a vector.
86 #define VEC_INIT { 0, 0, 0 }
91 #define VEC_CLEAR(vec) do { \
99 * Clear a vector, first calling the provided function on each vector
102 #define VEC_CLEAREXT(vec, fun) do { \
104 for (vec_tmp = 0; vec_tmp < (vec).ptr; vec_tmp ++) { \
105 (fun)(&(vec).buf[vec_tmp]); \
111 * Add a value at the end of a vector.
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); \
120 * Add several values at the end of a vector.
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; \
132 * Access a vector element by index. This is a lvalue, and can be modified.
134 #define VEC_ELT(vec, idx) ((vec).buf[idx])
137 * Get current vector length.
139 #define VEC_LEN(vec) ((vec).ptr)
142 * Copy all vector elements into a newly allocated block.
144 #define VEC_TOARRAY(vec) xblobdup((vec).buf, sizeof *((vec).buf) * (vec).ptr)
147 * Internal function used to handle memory allocations for vectors.
149 void *vector_expand(void *buf
,
150 size_t esize
, size_t *ptr
, size_t *len
, size_t extra
);
153 * Type for a vector of bytes.
155 typedef VECTOR(unsigned char) bvector
;
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
164 int eqstr(const char *s1
, const char *s2
);
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.
170 size_t parse_size(const char *s
);
173 * Structure for a known protocol version.
182 * Known protocol versions. Last element has a NULL name.
184 extern const protocol_version protocol_versions
[];
187 * Parse a version name. If the name is not recognized, then an error
188 * message is printed, and 0 is returned.
190 unsigned parse_version(const char *name
, size_t len
);
193 * Type for a known hash function.
197 const br_hash_class
*hclass
;
202 * Known hash functions. Last element has a NULL name.
204 extern const hash_function hash_functions
[];
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.
212 unsigned parse_hash_functions(const char *arg
);
215 * Type for a known cipher suite.
225 * Known cipher suites. Last element has a NULL name.
227 extern const cipher_suite cipher_suites
[];
230 * Flags for cipher suite requirements.
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_3DESCBC 0x0040 /* suite needs 3DES/CBC encryption */
239 #define REQ_RSAKEYX 0x0080 /* suite uses RSA key exchange */
240 #define REQ_ECDHE_RSA 0x0100 /* suite uses ECDHE_RSA key exchange */
241 #define REQ_ECDHE_ECDSA 0x0200 /* suite uses ECDHE_ECDSA key exchange */
242 #define REQ_ECDH 0x0400 /* suite uses static ECDH key exchange */
245 * Parse a list of cipher suite names. The names are comma-separated. If
246 * one of the name is not recognised, or the list is empty, then an
247 * appropriate error message is printed, and NULL is returned.
248 * The returned array is allocated with xmalloc() and must be released
249 * by the caller. That array is terminated with a dummy entry whose 'name'
250 * field is NULL. The number of entries (not counting the dummy entry)
251 * is also written into '*num'.
253 cipher_suite
*parse_suites(const char *arg
, size_t *num
);
256 * Get the name of a cipher suite. Returned value is NULL if the suite is
259 const char *get_suite_name(unsigned suite
);
262 * Get the name of a cipher suite. The name is written in the provided
263 * buffer; if the suite is not recognised, then the name is
264 * "unknown (0x****)" where "****" is the hexadecimal value of the suite.
265 * If the name does not fit in the provided buffer, then dst[0] is set
266 * to 0 (unless len is 0, in which case nothing is written), and -1 is
267 * returned. Otherwise, the name is written in dst[] (with a terminating
268 * 0), and this function returns 0.
270 int get_suite_name_ext(unsigned suite
, char *dst
, size_t len
);
273 * Print out all known names (for protocol versions, cipher suites...).
275 void list_names(void);
278 * Get the symbolic name for an elliptic curve (by ID).
280 const char *ec_curve_name(int curve
);
283 * Read a file completely. The returned block is allocated with xmalloc()
284 * and must be released by the caller.
285 * If the file cannot be found or read completely, or is empty, then an
286 * appropriate error message is written, and NULL is returned.
288 unsigned char *read_file(const char *fname
, size_t *len
);
291 * Write a file completely. This returns 0 on success, -1 on error. On
292 * error, an appropriate error message is printed.
294 int write_file(const char *fname
, const void *data
, size_t len
);
297 * This function returns non-zero if the provided buffer "looks like"
298 * a DER-encoded ASN.1 object (criteria: it has the tag for a SEQUENCE
299 * with a definite length that matches the total object length).
301 int looks_like_DER(const unsigned char *buf
, size_t len
);
304 * Type for a named blob (the 'name' is a normalised PEM header name).
313 * Release the contents of a named blob (buffer and name).
315 void free_pem_object_contents(pem_object
*po
);
318 * Decode a buffer as a PEM file, and return all objects. On error, NULL
319 * is returned and an error message is printed. Absence of any object
322 * The returned array is terminated by a dummy object whose 'name' is
323 * NULL. The number of objects (not counting the dummy terminator) is
326 pem_object
*decode_pem(const void *src
, size_t len
, size_t *num
);
329 * Get the certificate(s) from a file. This accepts both a single
330 * DER-encoded certificate, and a text file that contains
331 * PEM-encoded certificates (and possibly other objects, which are
334 * On decoding error, or if the file turns out to contain no certificate
335 * at all, then an error message is printed and NULL is returned.
337 * The returned array, and all referenced buffers, are allocated with
338 * xmalloc() and must be released by the caller. The returned array
339 * ends with a dummy entry whose 'data' field is NULL.
340 * The number of decoded certificates (not counting the dummy entry)
341 * is written into '*num'.
343 br_x509_certificate
*read_certificates(const char *fname
, size_t *num
);
346 * Interpret a certificate as a trust anchor. The trust anchor is
347 * newly allocated with xmalloc() and the caller must release it.
348 * On decoding error, an error message is printed, and this function
351 br_x509_trust_anchor
*certificate_to_trust_anchor(br_x509_certificate
*xc
);
354 * Type for a vector of trust anchors.
356 typedef VECTOR(br_x509_trust_anchor
) anchor_list
;
359 * Release contents for a trust anchor (assuming they were dynamically
360 * allocated with xmalloc()). The structure itself is NOT released.
362 void free_ta_contents(br_x509_trust_anchor
*ta
);
365 * Decode certificates from a file and interpret them as trust anchors.
366 * The trust anchors are added to the provided list. The number of found
367 * anchors is returned; on error, 0 is returned (finding no anchor at
368 * all is considered an error). An appropriate error message is displayed.
370 size_t read_trust_anchors(anchor_list
*dst
, const char *fname
);
373 * Special "no anchor" X.509 validator that wraps around another X.509
374 * validator and turns "not trusted" error codes into success. This is
375 * by definition insecure, but convenient for debug purposes.
378 const br_x509_class
*vtable
;
379 const br_x509_class
**inner
;
380 } x509_noanchor_context
;
381 extern const br_x509_class x509_noanchor_vtable
;
384 * Initialise a "no anchor" X.509 validator.
386 void x509_noanchor_init(x509_noanchor_context
*xwc
,
387 const br_x509_class
**inner
);
390 * Aggregate type for a private key.
393 int key_type
; /* BR_KEYTYPE_RSA or BR_KEYTYPE_EC */
395 br_rsa_private_key rsa
;
396 br_ec_private_key ec
;
401 * Decode a private key from a file. On error, this prints an error
402 * message and returns NULL.
404 private_key
*read_private_key(const char *fname
);
407 * Free a private key.
409 void free_private_key(private_key
*sk
);
412 * Find the symbolic name and the description for an error. If 'err' is
413 * recognised then the error symbolic name is returned; if 'comment' is
414 * not NULL then '*comment' is then set to a descriptive human-readable
415 * message. If the error code 'err' is not recognised, then '*comment' is
416 * untouched and this function returns NULL.
418 const char *find_error_name(int err
, const char **comment
);
421 * Run a SSL engine, with a socket connected to the peer, and using
422 * stdin/stdout to exchange application data.
425 * 0 SSL connection closed successfully
426 * x > 0 SSL error "x"
427 * -1 early socket close
428 * -2 stdout was closed, or something failed badly
430 int run_ssl_engine(br_ssl_engine_context
*eng
, int fd
, unsigned flags
);
432 #define RUN_ENGINE_VERBOSE 0x0001 /* enable verbose messages */
433 #define RUN_ENGINE_TRACE 0x0002 /* hex dump of records */
436 * Do the "client" command. Returned value is 0 on success, -1 on failure.
437 * Command-line arguments start _after_ the command name.
439 int do_client(int argc
, char *argv
[]);
442 * Do the "server" command. Returned value is 0 on success, -1 on failure.
443 * Command-line arguments start _after_ the command name.
445 int do_server(int argc
, char *argv
[]);
448 * Do the "verify" command. Returned value is 0 on success, -1 on failure.
449 * Command-line arguments start _after_ the command name.
451 int do_verify(int argc
, char *argv
[]);
454 * Do the "skey" command. Returned value is 0 on success, -1 on failure.
455 * Command-line arguments start _after_ the command name.
457 int do_skey(int argc
, char *argv
[]);
460 * Do the "ta" command. Returned value is 0 on success, -1 on failure.
461 * Command-line arguments start _after_ the command name.
463 int do_ta(int argc
, char *argv
[]);
466 * Do the "chain" command. Returned value is 0 on success, -1 on failure.
467 * Command-line arguments start _after_ the command name.
469 int do_chain(int argc
, char *argv
[]);