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#ifndef _STANDALONE 29#include <stdio.h> 30#include <stdlib.h> 31#include <string.h> 32#include <stdint.h> 33 34#elif !defined(STAND_H) 35#include <stand.h> 36#endif 37 38#include "bearssl.h" 39 40/* 41 * malloc() wrapper: 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. 45 */ 46void *xmalloc(size_t len); 47 48/* 49 * free() wrapper, meant to release blocks allocated with xmalloc(). 50 */ 51void xfree(void *buf); 52 53/* 54 * Duplicate a character string into a newly allocated block. 55 */ 56char *xstrdup(const void *src); 57 58/* 59 * Allocate a new block with the provided length, filled with a copy 60 * of exactly that many bytes starting at address 'src'. 61 */ 62void *xblobdup(const void *src, size_t len); 63 64/* 65 * Duplicate a public key, into newly allocated blocks. The returned 66 * key must be later on released with xfreepkey(). 67 */ 68br_x509_pkey *xpkeydup(const br_x509_pkey *pk); 69 70/* 71 * Release a public key that was allocated with xpkeydup(). If pk is NULL, 72 * this function does nothing. 73 */ 74void xfreepkey(br_x509_pkey *pk); 75 76/* 77 * Macros for growable arrays. 78 */ 79 80/* 81 * Make a structure type for a vector of 'type'. 82 */ 83#define VECTOR(type) struct { \ 84 type *buf; \ 85 size_t ptr, len; \ 86 } 87 88/* 89 * Constant initialiser for a vector. 90 */ 91#define VEC_INIT { 0, 0, 0 } 92 93/* 94 * Clear a vector. 95 */ 96#define VEC_CLEAR(vec) do { \ 97 xfree((vec).buf); \ 98 (vec).buf = NULL; \ 99 (vec).ptr = 0; \ 100 (vec).len = 0; \ 101 } while (0) 102 103/* 104 * Clear a vector, first calling the provided function on each vector 105 * element. 106 */ 107#define VEC_CLEAREXT(vec, fun) do { \ 108 size_t vec_tmp; \ 109 for (vec_tmp = 0; vec_tmp < (vec).ptr; vec_tmp ++) { \ 110 (fun)(&(vec).buf[vec_tmp]); \ 111 } \ 112 VEC_CLEAR(vec); \ 113 } while (0) 114 115/* 116 * Add a value at the end of a vector. 117 */ 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); \ 122 } while (0) 123 124/* 125 * Add several values at the end of a vector. 126 */ 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; \ 134 } while (0) 135 136/* 137 * Access a vector element by index. This is a lvalue, and can be modified. 138 */ 139#define VEC_ELT(vec, idx) ((vec).buf[idx]) 140 141/* 142 * Get current vector length. 143 */ 144#define VEC_LEN(vec) ((vec).ptr) 145 146/* 147 * Copy all vector elements into a newly allocated block. 148 */ 149#define VEC_TOARRAY(vec) xblobdup((vec).buf, sizeof *((vec).buf) * (vec).ptr) 150 151/* 152 * Internal function used to handle memory allocations for vectors. 153 */ 154void *vector_expand(void *buf, 155 size_t esize, size_t *ptr, size_t *len, size_t extra); 156 157/* 158 * Type for a vector of bytes. 159 */ 160typedef VECTOR(unsigned char) bvector; 161 162/* 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 167 * ':'). 168 */ 169int eqstr(const char *s1, const char *s2); 170 171/* 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. 174 */ 175size_t parse_size(const char *s); 176 177/* 178 * Structure for a known protocol version. 179 */ 180typedef struct { 181 const char *name; 182 unsigned version; 183 const char *comment; 184} protocol_version; 185 186/* 187 * Known protocol versions. Last element has a NULL name. 188 */ 189extern const protocol_version protocol_versions[]; 190 191/* 192 * Parse a version name. If the name is not recognized, then an error 193 * message is printed, and 0 is returned. 194 */ 195unsigned parse_version(const char *name, size_t len); 196 197/* 198 * Type for a known hash function. 199 */ 200typedef struct { 201 const char *name; 202 const br_hash_class *hclass; 203 const char *comment; 204} hash_function; 205 206/* 207 * Known hash functions. Last element has a NULL name. 208 */ 209extern const hash_function hash_functions[]; 210 211/* 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. 216 */ 217unsigned parse_hash_functions(const char *arg); 218 219/* 220 * Get a curve name (by ID). If the curve ID is not known, this returns 221 * NULL. 222 */ 223const char *get_curve_name(int id); 224 225/* 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. 233 */ 234int get_curve_name_ext(int id, char *dst, size_t len); 235 236/* 237 * Type for a known cipher suite. 238 */ 239typedef struct { 240 const char *name; 241 uint16_t suite; 242 unsigned req; 243 const char *comment; 244} cipher_suite; 245 246/* 247 * Known cipher suites. Last element has a NULL name. 248 */ 249extern const cipher_suite cipher_suites[]; 250 251/* 252 * Flags for cipher suite requirements. 253 */ 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 */ 267 268/* 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'. 276 */ 277cipher_suite *parse_suites(const char *arg, size_t *num); 278 279/* 280 * Get the name of a cipher suite. Returned value is NULL if the suite is 281 * not recognized. 282 */ 283const char *get_suite_name(unsigned suite); 284 285/* 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. 293 */ 294int get_suite_name_ext(unsigned suite, char *dst, size_t len); 295 296/* 297 * Tell whether a cipher suite uses ECDHE key exchange. 298 */ 299int uses_ecdhe(unsigned suite); 300 301/* 302 * Print out all known names (for protocol versions, cipher suites...). 303 */ 304void list_names(void); 305 306/* 307 * Print out all known elliptic curve names. 308 */ 309void list_curves(void); 310 311/* 312 * Get the symbolic name for an elliptic curve (by ID). 313 */ 314const char *ec_curve_name(int curve); 315 316/* 317 * Get a curve by symbolic name. If the name is not recognized, -1 is 318 * returned. 319 */ 320int get_curve_by_name(const char *str); 321 322/* 323 * Get the symbolic name for a hash function name (by ID). 324 */ 325const char *hash_function_name(int id); 326 327/* 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. 332 */ 333unsigned char *read_file(const char *fname, size_t *len); 334 335/* 336 * Write a file completely. This returns 0 on success, -1 on error. On 337 * error, an appropriate error message is printed. 338 */ 339int write_file(const char *fname, const void *data, size_t len); 340 341/* 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). 345 */ 346int looks_like_DER(const unsigned char *buf, size_t len); 347 348/* 349 * Type for a named blob (the 'name' is a normalised PEM header name). 350 */ 351typedef struct { 352 char *name; 353 unsigned char *data; 354 size_t data_len; 355} pem_object; 356 357/* 358 * Release the contents of a named blob (buffer and name). 359 */ 360void free_pem_object_contents(pem_object *po); 361 362/* 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 365 * is an error. 366 * 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 369 * written in '*num'. 370 */ 371pem_object *decode_pem(const void *src, size_t len, size_t *num); 372 373/* 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 377 * then ignored). 378 * 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. 381 * 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'. 387 */ 388br_x509_certificate *read_certificates(const char *fname, size_t *num); 389 390/* 391 * Release certificates. This releases all certificate data arrays, 392 * and the whole array as well. 393 */ 394void free_certificates(br_x509_certificate *certs, size_t num); 395 396/* 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 400 * returns NULL. 401 */ 402br_x509_trust_anchor *certificate_to_trust_anchor(br_x509_certificate *xc); 403 404/* 405 * Type for a vector of trust anchors. 406 */ 407typedef VECTOR(br_x509_trust_anchor) anchor_list; 408 409/* 410 * Release contents for a trust anchor (assuming they were dynamically 411 * allocated with xmalloc()). The structure itself is NOT released. 412 */ 413void free_ta_contents(br_x509_trust_anchor *ta); 414 415/* 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. 420 */ 421size_t read_trust_anchors(anchor_list *dst, const char *fname); 422 423/* 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. 426 */ 427int get_cert_signer_algo(br_x509_certificate *xc); 428 429/* 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. 433 */ 434typedef struct { 435 const br_x509_class *vtable; 436 const br_x509_class **inner; 437} x509_noanchor_context; 438extern const br_x509_class x509_noanchor_vtable; 439 440/* 441 * Initialise a "no anchor" X.509 validator. 442 */ 443void x509_noanchor_init(x509_noanchor_context *xwc, 444 const br_x509_class **inner); 445 446/* 447 * Aggregate type for a private key. 448 */ 449typedef struct { 450 int key_type; /* BR_KEYTYPE_RSA or BR_KEYTYPE_EC */ 451 union { 452 br_rsa_private_key rsa; 453 br_ec_private_key ec; 454 } key; 455} private_key; 456 457/* 458 * Decode a private key from a file. On error, this prints an error 459 * message and returns NULL. 460 */ 461private_key *read_private_key(const char *fname); 462 463/* 464 * Free a private key. 465 */ 466void free_private_key(private_key *sk); 467 468/* 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. 473 */ 474const unsigned char *get_hash_oid(int id); 475 476/* 477 * Get a hash implementation by ID. This returns NULL if the hash 478 * implementation is not available. 479 */ 480const br_hash_class *get_hash_impl(int id); 481 482/* 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. 488 */ 489const char *find_error_name(int err, const char **comment); 490 491/* 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. 495 * 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'). 500 */ 501const char *get_algo_name(const void *algo, int long_name); 502 503/* 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. 507 * 508 * To help with Win32 compatibility, the socket descriptor is provided 509 * as an "unsigned long" value. 510 * 511 * Returned 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 516 */ 517int run_ssl_engine(br_ssl_engine_context *eng, 518 unsigned long fd, unsigned flags); 519 520#define RUN_ENGINE_VERBOSE 0x0001 /* enable verbose messages */ 521#define RUN_ENGINE_TRACE 0x0002 /* hex dump of records */ 522 523/* 524 * Do the "client" command. Returned value is 0 on success, -1 on failure. 525 * Command-line arguments start _after_ the command name. 526 */ 527int do_client(int argc, char *argv[]); 528 529/* 530 * Do the "server" command. Returned value is 0 on success, -1 on failure. 531 * Command-line arguments start _after_ the command name. 532 */ 533int do_server(int argc, char *argv[]); 534 535/* 536 * Do the "verify" command. Returned value is 0 on success, -1 on failure. 537 * Command-line arguments start _after_ the command name. 538 */ 539int do_verify(int argc, char *argv[]); 540 541/* 542 * Do the "skey" command. Returned value is 0 on success, -1 on failure. 543 * Command-line arguments start _after_ the command name. 544 */ 545int do_skey(int argc, char *argv[]); 546 547/* 548 * Do the "ta" command. Returned value is 0 on success, -1 on failure. 549 * Command-line arguments start _after_ the command name. 550 */ 551int do_ta(int argc, char *argv[]); 552 553/* 554 * Do the "chain" command. Returned value is 0 on success, -1 on failure. 555 * Command-line arguments start _after_ the command name. 556 */ 557int do_chain(int argc, char *argv[]); 558 559/* 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. 563 */ 564int do_twrch(int argc, char *argv[]); 565 566/* 567 * Do the "impl" command. Returned value is 0 on success, -1 on failure. 568 * Command-line arguments start _after_ the command name. 569 */ 570int do_impl(int argc, char *argv[]); 571 572#endif 573