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 * Get a curve name (by ID). If the curve ID is not known, this returns
218 const char *get_curve_name(int id
);
221 * Get a curve name (by ID). The name is written in the provided buffer
222 * (zero-terminated). If the curve ID is not known, the name is
223 * "unknown (***)" where "***" is the decimal value of the identifier.
224 * If the name does not fit in the provided buffer, then dst[0] is set
225 * to 0 (unless len is 0, in which case nothing is written), and -1 is
226 * returned. Otherwise, the name is written in dst[] (with a terminating
227 * 0), and this function returns 0.
229 int get_curve_name_ext(int id
, char *dst
, size_t len
);
232 * Type for a known cipher suite.
242 * Known cipher suites. Last element has a NULL name.
244 extern const cipher_suite cipher_suites
[];
247 * Flags for cipher suite requirements.
249 #define REQ_TLS12 0x0001 /* suite needs TLS 1.2 */
250 #define REQ_SHA1 0x0002 /* suite needs SHA-1 */
251 #define REQ_SHA256 0x0004 /* suite needs SHA-256 */
252 #define REQ_SHA384 0x0008 /* suite needs SHA-384 */
253 #define REQ_AESCBC 0x0010 /* suite needs AES/CBC encryption */
254 #define REQ_AESGCM 0x0020 /* suite needs AES/GCM encryption */
255 #define REQ_CHAPOL 0x0040 /* suite needs ChaCha20+Poly1305 */
256 #define REQ_3DESCBC 0x0080 /* suite needs 3DES/CBC encryption */
257 #define REQ_RSAKEYX 0x0100 /* suite uses RSA key exchange */
258 #define REQ_ECDHE_RSA 0x0200 /* suite uses ECDHE_RSA key exchange */
259 #define REQ_ECDHE_ECDSA 0x0400 /* suite uses ECDHE_ECDSA key exchange */
260 #define REQ_ECDH 0x0800 /* suite uses static ECDH key exchange */
263 * Parse a list of cipher suite names. The names are comma-separated. If
264 * one of the name is not recognised, or the list is empty, then an
265 * appropriate error message is printed, and NULL is returned.
266 * The returned array is allocated with xmalloc() and must be released
267 * by the caller. That array is terminated with a dummy entry whose 'name'
268 * field is NULL. The number of entries (not counting the dummy entry)
269 * is also written into '*num'.
271 cipher_suite
*parse_suites(const char *arg
, size_t *num
);
274 * Get the name of a cipher suite. Returned value is NULL if the suite is
277 const char *get_suite_name(unsigned suite
);
280 * Get the name of a cipher suite. The name is written in the provided
281 * buffer; if the suite is not recognised, then the name is
282 * "unknown (0x****)" where "****" is the hexadecimal value of the suite.
283 * If the name does not fit in the provided buffer, then dst[0] is set
284 * to 0 (unless len is 0, in which case nothing is written), and -1 is
285 * returned. Otherwise, the name is written in dst[] (with a terminating
286 * 0), and this function returns 0.
288 int get_suite_name_ext(unsigned suite
, char *dst
, size_t len
);
291 * Tell whether a cipher suite uses ECDHE key exchange.
293 int uses_ecdhe(unsigned suite
);
296 * Print out all known names (for protocol versions, cipher suites...).
298 void list_names(void);
301 * Get the symbolic name for an elliptic curve (by ID).
303 const char *ec_curve_name(int curve
);
306 * Get the symbolic name for a hash function name (by ID).
308 const char *hash_function_name(int id
);
311 * Read a file completely. The returned block is allocated with xmalloc()
312 * and must be released by the caller.
313 * If the file cannot be found or read completely, or is empty, then an
314 * appropriate error message is written, and NULL is returned.
316 unsigned char *read_file(const char *fname
, size_t *len
);
319 * Write a file completely. This returns 0 on success, -1 on error. On
320 * error, an appropriate error message is printed.
322 int write_file(const char *fname
, const void *data
, size_t len
);
325 * This function returns non-zero if the provided buffer "looks like"
326 * a DER-encoded ASN.1 object (criteria: it has the tag for a SEQUENCE
327 * with a definite length that matches the total object length).
329 int looks_like_DER(const unsigned char *buf
, size_t len
);
332 * Type for a named blob (the 'name' is a normalised PEM header name).
341 * Release the contents of a named blob (buffer and name).
343 void free_pem_object_contents(pem_object
*po
);
346 * Decode a buffer as a PEM file, and return all objects. On error, NULL
347 * is returned and an error message is printed. Absence of any object
350 * The returned array is terminated by a dummy object whose 'name' is
351 * NULL. The number of objects (not counting the dummy terminator) is
354 pem_object
*decode_pem(const void *src
, size_t len
, size_t *num
);
357 * Get the certificate(s) from a file. This accepts both a single
358 * DER-encoded certificate, and a text file that contains
359 * PEM-encoded certificates (and possibly other objects, which are
362 * On decoding error, or if the file turns out to contain no certificate
363 * at all, then an error message is printed and NULL is returned.
365 * The returned array, and all referenced buffers, are allocated with
366 * xmalloc() and must be released by the caller. The returned array
367 * ends with a dummy entry whose 'data' field is NULL.
368 * The number of decoded certificates (not counting the dummy entry)
369 * is written into '*num'.
371 br_x509_certificate
*read_certificates(const char *fname
, size_t *num
);
374 * Release certificates. This releases all certificate data arrays,
375 * and the whole array as well.
377 void free_certificates(br_x509_certificate
*certs
, size_t num
);
380 * Interpret a certificate as a trust anchor. The trust anchor is
381 * newly allocated with xmalloc() and the caller must release it.
382 * On decoding error, an error message is printed, and this function
385 br_x509_trust_anchor
*certificate_to_trust_anchor(br_x509_certificate
*xc
);
388 * Type for a vector of trust anchors.
390 typedef VECTOR(br_x509_trust_anchor
) anchor_list
;
393 * Release contents for a trust anchor (assuming they were dynamically
394 * allocated with xmalloc()). The structure itself is NOT released.
396 void free_ta_contents(br_x509_trust_anchor
*ta
);
399 * Decode certificates from a file and interpret them as trust anchors.
400 * The trust anchors are added to the provided list. The number of found
401 * anchors is returned; on error, 0 is returned (finding no anchor at
402 * all is considered an error). An appropriate error message is displayed.
404 size_t read_trust_anchors(anchor_list
*dst
, const char *fname
);
407 * Get the "signer key type" for the certificate (key type of the
408 * issuing CA). On error, this prints a message on stderr, and returns 0.
410 int get_cert_signer_algo(br_x509_certificate
*xc
);
413 * Special "no anchor" X.509 validator that wraps around another X.509
414 * validator and turns "not trusted" error codes into success. This is
415 * by definition insecure, but convenient for debug purposes.
418 const br_x509_class
*vtable
;
419 const br_x509_class
**inner
;
420 } x509_noanchor_context
;
421 extern const br_x509_class x509_noanchor_vtable
;
424 * Initialise a "no anchor" X.509 validator.
426 void x509_noanchor_init(x509_noanchor_context
*xwc
,
427 const br_x509_class
**inner
);
430 * Aggregate type for a private key.
433 int key_type
; /* BR_KEYTYPE_RSA or BR_KEYTYPE_EC */
435 br_rsa_private_key rsa
;
436 br_ec_private_key ec
;
441 * Decode a private key from a file. On error, this prints an error
442 * message and returns NULL.
444 private_key
*read_private_key(const char *fname
);
447 * Free a private key.
449 void free_private_key(private_key
*sk
);
452 * Get the encoded OID for a given hash function (to use with PKCS#1
453 * signatures). If the hash function ID is 0 (for MD5+SHA-1), or if
454 * the ID is not one of the SHA-* functions (SHA-1, SHA-224, SHA-256,
455 * SHA-384, SHA-512), then this function returns NULL.
457 const unsigned char *get_hash_oid(int id
);
460 * Get a hash implementation by ID. This returns NULL if the hash
461 * implementation is not available.
463 const br_hash_class
*get_hash_impl(int id
);
466 * Find the symbolic name and the description for an error. If 'err' is
467 * recognised then the error symbolic name is returned; if 'comment' is
468 * not NULL then '*comment' is then set to a descriptive human-readable
469 * message. If the error code 'err' is not recognised, then '*comment' is
470 * untouched and this function returns NULL.
472 const char *find_error_name(int err
, const char **comment
);
475 * Find the symbolic name for an algorithm implementation. Provided
476 * pointer should be a pointer to a vtable or to a function, where
477 * appropriate. If not recognised, then the string "UNKNOWN" is returned.
479 * If 'long_name' is non-zero, then the returned name recalls the
480 * algorithm type as well; otherwise, only the core implementation name
481 * is returned (e.g. the long name could be 'aes_big_cbcenc' while the
482 * short name is 'big').
484 const char *get_algo_name(const void *algo
, int long_name
);
487 * Run a SSL engine, with a socket connected to the peer, and using
488 * stdin/stdout to exchange application data. The socket must be a
489 * non-blocking descriptor.
491 * To help with Win32 compatibility, the socket descriptor is provided
492 * as an "unsigned long" value.
495 * 0 SSL connection closed successfully
496 * x > 0 SSL error "x"
497 * -1 early socket close
498 * -2 stdout was closed, or something failed badly
500 int run_ssl_engine(br_ssl_engine_context
*eng
,
501 unsigned long fd
, unsigned flags
);
503 #define RUN_ENGINE_VERBOSE 0x0001 /* enable verbose messages */
504 #define RUN_ENGINE_TRACE 0x0002 /* hex dump of records */
507 * Do the "client" command. Returned value is 0 on success, -1 on failure.
508 * Command-line arguments start _after_ the command name.
510 int do_client(int argc
, char *argv
[]);
513 * Do the "server" command. Returned value is 0 on success, -1 on failure.
514 * Command-line arguments start _after_ the command name.
516 int do_server(int argc
, char *argv
[]);
519 * Do the "verify" command. Returned value is 0 on success, -1 on failure.
520 * Command-line arguments start _after_ the command name.
522 int do_verify(int argc
, char *argv
[]);
525 * Do the "skey" command. Returned value is 0 on success, -1 on failure.
526 * Command-line arguments start _after_ the command name.
528 int do_skey(int argc
, char *argv
[]);
531 * Do the "ta" command. Returned value is 0 on success, -1 on failure.
532 * Command-line arguments start _after_ the command name.
534 int do_ta(int argc
, char *argv
[]);
537 * Do the "chain" command. Returned value is 0 on success, -1 on failure.
538 * Command-line arguments start _after_ the command name.
540 int do_chain(int argc
, char *argv
[]);
543 * Do the "twrch" command. Returned value is 0 on success, -1 on failure
544 * (processing or arguments), or a non-zero exit code. Command-line
545 * arguments start _after_ the command name.
547 int do_twrch(int argc
, char *argv
[]);