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
34 #elif !defined(STAND_H)
42 * -- If len is 0, then NULL is returned.
43 * -- If len is non-zero, and allocation fails, then an error message is
44 * printed and the process exits with an error code.
46 void *xmalloc(size_t len);
49 * free() wrapper, meant to release blocks allocated with xmalloc().
51 void xfree(void *buf);
54 * Duplicate a character string into a newly allocated block.
56 char *xstrdup(const void *src);
59 * Allocate a new block with the provided length, filled with a copy
60 * of exactly that many bytes starting at address 'src'.
62 void *xblobdup(const void *src, size_t len);
65 * Duplicate a public key, into newly allocated blocks. The returned
66 * key must be later on released with xfreepkey().
68 br_x509_pkey *xpkeydup(const br_x509_pkey *pk);
71 * Release a public key that was allocated with xpkeydup(). If pk is NULL,
72 * this function does nothing.
74 void xfreepkey(br_x509_pkey *pk);
77 * Macros for growable arrays.
81 * Make a structure type for a vector of 'type'.
83 #define VECTOR(type) struct { \
89 * Constant initialiser for a vector.
91 #define VEC_INIT { 0, 0, 0 }
96 #define VEC_CLEAR(vec) do { \
104 * Clear a vector, first calling the provided function on each vector
107 #define VEC_CLEAREXT(vec, fun) do { \
109 for (vec_tmp = 0; vec_tmp < (vec).ptr; vec_tmp ++) { \
110 (fun)(&(vec).buf[vec_tmp]); \
116 * Add a value at the end of a vector.
118 #define VEC_ADD(vec, x) do { \
119 (vec).buf = vector_expand((vec).buf, sizeof *((vec).buf), \
120 &(vec).ptr, &(vec).len, 1); \
121 (vec).buf[(vec).ptr ++] = (x); \
125 * Add several values at the end of a vector.
127 #define VEC_ADDMANY(vec, xp, num) do { \
128 size_t vec_num = (num); \
129 (vec).buf = vector_expand((vec).buf, sizeof *((vec).buf), \
130 &(vec).ptr, &(vec).len, vec_num); \
131 memcpy((vec).buf + (vec).ptr, \
132 (xp), vec_num * sizeof *((vec).buf)); \
133 (vec).ptr += vec_num; \
137 * Access a vector element by index. This is a lvalue, and can be modified.
139 #define VEC_ELT(vec, idx) ((vec).buf[idx])
142 * Get current vector length.
144 #define VEC_LEN(vec) ((vec).ptr)
147 * Copy all vector elements into a newly allocated block.
149 #define VEC_TOARRAY(vec) xblobdup((vec).buf, sizeof *((vec).buf) * (vec).ptr)
152 * Internal function used to handle memory allocations for vectors.
154 void *vector_expand(void *buf,
155 size_t esize, size_t *ptr, size_t *len, size_t extra);
158 * Type for a vector of bytes.
160 typedef VECTOR(unsigned char) bvector;
163 * Compare two strings for equality; returned value is 1 if the strings
164 * are to be considered equal, 0 otherwise. Comparison is case-insensitive
165 * (ASCII letters only) and skips some characters (all whitespace, defined
166 * as ASCII codes 0 to 32 inclusive, and also '-', '_', '.', '/', '+' and
169 int eqstr(const char *s1, const char *s2);
172 * Convert a string to a positive integer (size_t). Returned value is
173 * (size_t)-1 on error. On error, an explicit error message is printed.
175 size_t parse_size(const char *s);
178 * Structure for a known protocol version.
187 * Known protocol versions. Last element has a NULL name.
189 extern const protocol_version protocol_versions[];
192 * Parse a version name. If the name is not recognized, then an error
193 * message is printed, and 0 is returned.
195 unsigned parse_version(const char *name, size_t len);
198 * Type for a known hash function.
202 const br_hash_class *hclass;
207 * Known hash functions. Last element has a NULL name.
209 extern const hash_function hash_functions[];
212 * Parse hash function names. This function expects a comma-separated
213 * list of names, and returns a bit mask corresponding to the matched
214 * names. If one of the name does not match, or the list is empty, then
215 * an error message is printed, and 0 is returned.
217 unsigned parse_hash_functions(const char *arg);
220 * Get a curve name (by ID). If the curve ID is not known, this returns
223 const char *get_curve_name(int id);
226 * Get a curve name (by ID). The name is written in the provided buffer
227 * (zero-terminated). If the curve ID is not known, the name is
228 * "unknown (***)" where "***" is the decimal value of the identifier.
229 * If the name does not fit in the provided buffer, then dst[0] is set
230 * to 0 (unless len is 0, in which case nothing is written), and -1 is
231 * returned. Otherwise, the name is written in dst[] (with a terminating
232 * 0), and this function returns 0.
234 int get_curve_name_ext(int id, char *dst, size_t len);
237 * Type for a known cipher suite.
247 * Known cipher suites. Last element has a NULL name.
249 extern const cipher_suite cipher_suites[];
252 * Flags for cipher suite requirements.
254 #define REQ_TLS12 0x0001 /* suite needs TLS 1.2 */
255 #define REQ_SHA1 0x0002 /* suite needs SHA-1 */
256 #define REQ_SHA256 0x0004 /* suite needs SHA-256 */
257 #define REQ_SHA384 0x0008 /* suite needs SHA-384 */
258 #define REQ_AESCBC 0x0010 /* suite needs AES/CBC encryption */
259 #define REQ_AESGCM 0x0020 /* suite needs AES/GCM encryption */
260 #define REQ_AESCCM 0x0040 /* suite needs AES/CCM encryption */
261 #define REQ_CHAPOL 0x0080 /* suite needs ChaCha20+Poly1305 */
262 #define REQ_3DESCBC 0x0100 /* suite needs 3DES/CBC encryption */
263 #define REQ_RSAKEYX 0x0200 /* suite uses RSA key exchange */
264 #define REQ_ECDHE_RSA 0x0400 /* suite uses ECDHE_RSA key exchange */
265 #define REQ_ECDHE_ECDSA 0x0800 /* suite uses ECDHE_ECDSA key exchange */
266 #define REQ_ECDH 0x1000 /* suite uses static ECDH key exchange */
269 * Parse a list of cipher suite names. The names are comma-separated. If
270 * one of the name is not recognised, or the list is empty, then an
271 * appropriate error message is printed, and NULL is returned.
272 * The returned array is allocated with xmalloc() and must be released
273 * by the caller. That array is terminated with a dummy entry whose 'name'
274 * field is NULL. The number of entries (not counting the dummy entry)
275 * is also written into '*num'.
277 cipher_suite *parse_suites(const char *arg, size_t *num);
280 * Get the name of a cipher suite. Returned value is NULL if the suite is
283 const char *get_suite_name(unsigned suite);
286 * Get the name of a cipher suite. The name is written in the provided
287 * buffer; if the suite is not recognised, then the name is
288 * "unknown (0x****)" where "****" is the hexadecimal value of the suite.
289 * If the name does not fit in the provided buffer, then dst[0] is set
290 * to 0 (unless len is 0, in which case nothing is written), and -1 is
291 * returned. Otherwise, the name is written in dst[] (with a terminating
292 * 0), and this function returns 0.
294 int get_suite_name_ext(unsigned suite, char *dst, size_t len);
297 * Tell whether a cipher suite uses ECDHE key exchange.
299 int uses_ecdhe(unsigned suite);
302 * Print out all known names (for protocol versions, cipher suites...).
304 void list_names(void);
307 * Print out all known elliptic curve names.
309 void list_curves(void);
312 * Get the symbolic name for an elliptic curve (by ID).
314 const char *ec_curve_name(int curve);
317 * Get a curve by symbolic name. If the name is not recognized, -1 is
320 int get_curve_by_name(const char *str);
323 * Get the symbolic name for a hash function name (by ID).
325 const char *hash_function_name(int id);
328 * Read a file completely. The returned block is allocated with xmalloc()
329 * and must be released by the caller.
330 * If the file cannot be found or read completely, or is empty, then an
331 * appropriate error message is written, and NULL is returned.
333 unsigned char *read_file(const char *fname, size_t *len);
336 * Write a file completely. This returns 0 on success, -1 on error. On
337 * error, an appropriate error message is printed.
339 int write_file(const char *fname, const void *data, size_t len);
342 * This function returns non-zero if the provided buffer "looks like"
343 * a DER-encoded ASN.1 object (criteria: it has the tag for a SEQUENCE
344 * with a definite length that matches the total object length).
346 int looks_like_DER(const unsigned char *buf, size_t len);
349 * Type for a named blob (the 'name' is a normalised PEM header name).
358 * Release the contents of a named blob (buffer and name).
360 void free_pem_object_contents(pem_object *po);
363 * Decode a buffer as a PEM file, and return all objects. On error, NULL
364 * is returned and an error message is printed. Absence of any object
367 * The returned array is terminated by a dummy object whose 'name' is
368 * NULL. The number of objects (not counting the dummy terminator) is
371 pem_object *decode_pem(const void *src, size_t len, size_t *num);
374 * Get the certificate(s) from a file. This accepts both a single
375 * DER-encoded certificate, and a text file that contains
376 * PEM-encoded certificates (and possibly other objects, which are
379 * On decoding error, or if the file turns out to contain no certificate
380 * at all, then an error message is printed and NULL is returned.
382 * The returned array, and all referenced buffers, are allocated with
383 * xmalloc() and must be released by the caller. The returned array
384 * ends with a dummy entry whose 'data' field is NULL.
385 * The number of decoded certificates (not counting the dummy entry)
386 * is written into '*num'.
388 br_x509_certificate *read_certificates(const char *fname, size_t *num);
391 * Release certificates. This releases all certificate data arrays,
392 * and the whole array as well.
394 void free_certificates(br_x509_certificate *certs, size_t num);
397 * Interpret a certificate as a trust anchor. The trust anchor is
398 * newly allocated with xmalloc() and the caller must release it.
399 * On decoding error, an error message is printed, and this function
402 br_x509_trust_anchor *certificate_to_trust_anchor(br_x509_certificate *xc);
405 * Type for a vector of trust anchors.
407 typedef VECTOR(br_x509_trust_anchor) anchor_list;
410 * Release contents for a trust anchor (assuming they were dynamically
411 * allocated with xmalloc()). The structure itself is NOT released.
413 void free_ta_contents(br_x509_trust_anchor *ta);
416 * Decode certificates from a file and interpret them as trust anchors.
417 * The trust anchors are added to the provided list. The number of found
418 * anchors is returned; on error, 0 is returned (finding no anchor at
419 * all is considered an error). An appropriate error message is displayed.
421 size_t read_trust_anchors(anchor_list *dst, const char *fname);
424 * Get the "signer key type" for the certificate (key type of the
425 * issuing CA). On error, this prints a message on stderr, and returns 0.
427 int get_cert_signer_algo(br_x509_certificate *xc);
430 * Special "no anchor" X.509 validator that wraps around another X.509
431 * validator and turns "not trusted" error codes into success. This is
432 * by definition insecure, but convenient for debug purposes.
435 const br_x509_class *vtable;
436 const br_x509_class **inner;
437 } x509_noanchor_context;
438 extern const br_x509_class x509_noanchor_vtable;
441 * Initialise a "no anchor" X.509 validator.
443 void x509_noanchor_init(x509_noanchor_context *xwc,
444 const br_x509_class **inner);
447 * Aggregate type for a private key.
450 int key_type; /* BR_KEYTYPE_RSA or BR_KEYTYPE_EC */
452 br_rsa_private_key rsa;
453 br_ec_private_key ec;
458 * Decode a private key from a file. On error, this prints an error
459 * message and returns NULL.
461 private_key *read_private_key(const char *fname);
464 * Free a private key.
466 void free_private_key(private_key *sk);
469 * Get the encoded OID for a given hash function (to use with PKCS#1
470 * signatures). If the hash function ID is 0 (for MD5+SHA-1), or if
471 * the ID is not one of the SHA-* functions (SHA-1, SHA-224, SHA-256,
472 * SHA-384, SHA-512), then this function returns NULL.
474 const unsigned char *get_hash_oid(int id);
477 * Get a hash implementation by ID. This returns NULL if the hash
478 * implementation is not available.
480 const br_hash_class *get_hash_impl(int id);
483 * Find the symbolic name and the description for an error. If 'err' is
484 * recognised then the error symbolic name is returned; if 'comment' is
485 * not NULL then '*comment' is then set to a descriptive human-readable
486 * message. If the error code 'err' is not recognised, then '*comment' is
487 * untouched and this function returns NULL.
489 const char *find_error_name(int err, const char **comment);
492 * Find the symbolic name for an algorithm implementation. Provided
493 * pointer should be a pointer to a vtable or to a function, where
494 * appropriate. If not recognised, then the string "UNKNOWN" is returned.
496 * If 'long_name' is non-zero, then the returned name recalls the
497 * algorithm type as well; otherwise, only the core implementation name
498 * is returned (e.g. the long name could be 'aes_big_cbcenc' while the
499 * short name is 'big').
501 const char *get_algo_name(const void *algo, int long_name);
504 * Run a SSL engine, with a socket connected to the peer, and using
505 * stdin/stdout to exchange application data. The socket must be a
506 * non-blocking descriptor.
508 * To help with Win32 compatibility, the socket descriptor is provided
509 * as an "unsigned long" value.
512 * 0 SSL connection closed successfully
513 * x > 0 SSL error "x"
514 * -1 early socket close
515 * -2 stdout was closed, or something failed badly
517 int run_ssl_engine(br_ssl_engine_context *eng,
518 unsigned long fd, unsigned flags);
520 #define RUN_ENGINE_VERBOSE 0x0001 /* enable verbose messages */
521 #define RUN_ENGINE_TRACE 0x0002 /* hex dump of records */
524 * Do the "client" command. Returned value is 0 on success, -1 on failure.
525 * Command-line arguments start _after_ the command name.
527 int do_client(int argc, char *argv[]);
530 * Do the "server" command. Returned value is 0 on success, -1 on failure.
531 * Command-line arguments start _after_ the command name.
533 int do_server(int argc, char *argv[]);
536 * Do the "verify" command. Returned value is 0 on success, -1 on failure.
537 * Command-line arguments start _after_ the command name.
539 int do_verify(int argc, char *argv[]);
542 * Do the "skey" command. Returned value is 0 on success, -1 on failure.
543 * Command-line arguments start _after_ the command name.
545 int do_skey(int argc, char *argv[]);
548 * Do the "ta" command. Returned value is 0 on success, -1 on failure.
549 * Command-line arguments start _after_ the command name.
551 int do_ta(int argc, char *argv[]);
554 * Do the "chain" command. Returned value is 0 on success, -1 on failure.
555 * Command-line arguments start _after_ the command name.
557 int do_chain(int argc, char *argv[]);
560 * Do the "twrch" command. Returned value is 0 on success, -1 on failure
561 * (processing or arguments), or a non-zero exit code. Command-line
562 * arguments start _after_ the command name.
564 int do_twrch(int argc, char *argv[]);
567 * Do the "impl" command. Returned value is 0 on success, -1 on failure.
568 * Command-line arguments start _after_ the command name.
570 int do_impl(int argc, char *argv[]);