4  * Permission is hereby granted, free of charge, to any person obtaining 
51  * registry](http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4).
93  * Implementation note: SSL-level error codes should be in the 1..31
101 /** \brief SSL status: caller-provided parameter is incorrect. */
105     with the current context state (e.g. reading data while outgoing data
135     regards to the current engine state. */
267 	 * `*len` is set to 0 and a non-`NULL` pointer is returned.
306 	 * preceded by a 5-byte space which will receive the record
310 	 * both `*start` and `*end` to make room for any record-specific
326 	 * performed), _including_ the 5-byte header, and `*len` is
343  * \brief Context for a no-encryption engine.
345  * The no-encryption engine processes outgoing records during the initial
349 	/** \brief No-encryption engine vtable. */
353 /** \brief Static, constant vtable for the no-encryption engine. */
365  * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
404  * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
502  * GHASH implementation, and 4-byte IV.
536  * GHASH implementation, and 4-byte IV.
609  * Poly1305 implementation, key, and 12-byte IV.
641  * Poly1305 implementation, key, and 12-byte IV.
709  * and 4-byte IV.
742  * and 4-byte IV.
848 	 * The error code. When non-zero, then the state is "failed" and
878 	 * Shutdown flag: when set to non-zero, incoming record bytes
895 	 * -- if 'version_in' is 0, then it is set to the received version;
896 	 * -- otherwise, if the received version is not identical to
1005 	 * be large enough to accommodate an RSA-encrypted pre-master
1007 	 * RSA-4096, this means at least 512 bytes. (Other pad usages
1047 	 * Multi-hasher for the handshake messages. The handshake handler
1072 	 *  - the client sends no ALPN extension;
1073 	 *  - the server ignores any incoming ALPN extension.
1076 	 *  - the client sends an ALPN extension with all the names;
1077 	 *  - the server selects the first protocol in its list that
1130 	return cc->flags;  in br_ssl_engine_get_flags()
1142 	cc->flags = flags;  in br_ssl_engine_set_all_flags()
1157 	cc->flags |= flags;  in br_ssl_engine_add_flags()
1172 	cc->flags &= ~flags;  in br_ssl_engine_remove_flags()
1203  *   - If the client's certificate can be validated and its public key is
1207  *   - If using full-static ECDH, then a failure to validate the client's
1219  *   - On the client: the client sends a list of names, the server
1223  *   - On the server: the client sends a list of names, and the server
1253 	cc->version_min = (uint16_t)version_min;  in br_ssl_engine_set_versions()
1254 	cc->version_max = (uint16_t)version_max;  in br_ssl_engine_set_versions()
1266  * If the engine is for a client, the "signaling" pseudo-cipher suite
1270  * adding the fallback pseudo-suite is a good idea).
1290 	cc->x509ctx = x509ctx;  in br_ssl_engine_set_x509()
1301  *   - The client will send an ALPN extension, containing the names. If
1306  *   - The server will parse incoming ALPN extension (from clients), and
1319  * \param names   list of protocol names (zero-terminated).
1326 	ctx->protocol_names = names;  in br_ssl_engine_set_protocol_names()
1327 	ctx->protocol_names_num = (uint16_t)num;  in br_ssl_engine_set_protocol_names()
1333  * If this context was initialised with a non-empty list of protocol
1348 	k = ctx->selected_protocol;  in br_ssl_engine_get_selected_protocol()
1349 	return (k == 0 || k == 0xFFFF) ? NULL : ctx->protocol_names[k - 1];  in br_ssl_engine_get_selected_protocol()
1357  * may be set (MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512). If `impl`
1368 	br_multihash_setimpl(&ctx->mhash, id, impl);  in br_ssl_engine_set_hash()
1384 	return br_multihash_getimpl(&ctx->mhash, id);  in br_ssl_engine_get_hash()
1399 	cc->prf10 = impl;  in br_ssl_engine_set_prf10()
1403  * \brief Set the PRF implementation with SHA-256 (for TLS 1.2).
1406  * for the SHA-256 variant of the PRF used in TLS 1.2.
1414 	cc->prf_sha256 = impl;  in br_ssl_engine_set_prf_sha256()
1418  * \brief Set the PRF implementation with SHA-384 (for TLS 1.2).
1421  * for the SHA-384 variant of the PRF used in TLS 1.2.
1429 	cc->prf_sha384 = impl;  in br_ssl_engine_set_prf_sha384()
1444 	cc->iaes_cbcenc = impl_enc;  in br_ssl_engine_set_aes_cbc()
1445 	cc->iaes_cbcdec = impl_dec;  in br_ssl_engine_set_aes_cbc()
1453  * still being safe (in particular, constant-time). It also sets the
1470 	cc->iaes_ctr = impl;  in br_ssl_engine_set_aes_ctr()
1478  * system, while still being safe (in particular, constant-time). It also
1497 	cc->ides_cbcenc = impl_enc;  in br_ssl_engine_set_des_cbc()
1498 	cc->ides_cbcdec = impl_dec;  in br_ssl_engine_set_des_cbc()
1506  * still being safe (in particular, constant-time). It also sets the
1522 	cc->ighash = impl;  in br_ssl_engine_set_ghash()
1535 	cc->ichacha = ichacha;  in br_ssl_engine_set_chacha20()
1548 	cc->ipoly = ipoly;  in br_ssl_engine_set_poly1305()
1556  * local system, while still being safe (in particular, constant-time).
1573 	cc->iaes_ctrcbc = impl;  in br_ssl_engine_set_aes_ctrcbc()
1581  * system, while still being safe (in particular, constant-time). It also
1600 	cc->icbc_in = impl_in;  in br_ssl_engine_set_cbc()
1601 	cc->icbc_out = impl_out;  in br_ssl_engine_set_cbc()
1616 	cc->igcm_in = impl_in;  in br_ssl_engine_set_gcm()
1617 	cc->igcm_out = impl_out;  in br_ssl_engine_set_gcm()
1632 	cc->iccm_in = impl_in;  in br_ssl_engine_set_ccm()
1633 	cc->iccm_out = impl_out;  in br_ssl_engine_set_ccm()
1649 	cc->ichapol_in = impl_in;  in br_ssl_engine_set_chapol()
1650 	cc->ichapol_out = impl_out;  in br_ssl_engine_set_chapol()
1665 	cc->iec = iec;  in br_ssl_engine_set_ec()
1673  * implementation on the current system.
1688 	return cc->iec;  in br_ssl_engine_get_ec()
1705 	cc->irsavrfy = irsavrfy;  in br_ssl_engine_set_rsavrfy()
1712  * to the fastest implementation available on the current platform.
1728 	return cc->irsavrfy;  in br_ssl_engine_get_rsavrfy()
1738  * and full-static ECDH is not used).
1749 	cc->iecdsa = iecdsa;  in br_ssl_engine_set_ecdsa()
1756  * to the fastest implementation available on the current platform. This
1774 	return cc->iecdsa;  in br_ssl_engine_get_ecdsa()
1786  * If `bidi` is 0, then the engine will operate in half-duplex mode
1789  * is unsent data in the buffer). The optimal buffer size in half-duplex
1796  * enables full-duplex processing, but requires more RAM. The optimal
1797  * buffer size in full-duplex mode is `BR_SSL_BUFSIZE_BIDI`; if the
1805  * \param bidi        non-zero for full-duplex mode.
1817  * that it enforces full-duplex mode, and the two I/O buffers are
1857  * non-repeating value (e.g. current time, provided that the local clock
1886 	return cc->server_name;  in br_ssl_engine_get_server_name()
1902 	return cc->session.version;  in br_ssl_engine_get_version()
1913  * This function copies the current session parameters into the provided
1924 	memcpy(pp, &cc->session, sizeof *pp);  in br_ssl_engine_get_session_parameters()
1941 	memcpy(&cc->session, pp, sizeof *pp);  in br_ssl_engine_set_session_parameters()
1960 	return cc->ecdhe_curve;  in br_ssl_engine_get_ecdhe_curve()
1964  * \brief Get the current engine state.
1969  *   - `BR_SSL_CLOSED`
1973  *   - `BR_SSL_SENDREC`
1977  *   - `BR_SSL_RECVREC`
1981  *   - `BR_SSL_SENDAPP`
1985  *   - `BR_SSL_RECVAPP`
2004  * \return  the current engine state.
2029  * \return  0, or a non-zero error code.
2034 	return cc->err;  in br_ssl_engine_last_error()
2195  * `force` parameter is non-zero, then an empty record is assembled and
2200  * transparent "keep-alive" mechanism to maintain some low-level
2204  * \param force   non-zero to force sending an empty record.
2254  * zero bytes, by setting `context` to a non-`NULL` value but
2273  * Pre-declaration for the SSL client context.
2296 	 * curve, and static ECDH is used), this value is set to -1.
2299 	 * the protocol requirements: value must be 0 (MD5+SHA-1) for
2300 	 * a RSA signature, or 2 (SHA-1) for an ECDSA signature. Only
2309 	 * normally containing a DER-encoded certificate. The client
2381 	 * \brief Receive some more bytes for the current trust anchor name.
2395 	 * \brief End current trust anchor name.
2426 	 * the current protocol version. This is a bit field with the
2429 	 *   - If RSA signatures with hash function x are supported, then
2432 	 *   - If ECDSA signatures with hash function x are supported,
2435 	 *   - If static ECDH is supported, with a RSA-signed certificate,
2438 	 *   - If static ECDH is supported, with an ECDSA-signed certificate,
2443 	 *   - When using TLS 1.0 or 1.1, the hash function for RSA
2444 	 *     signatures is always the special MD5+SHA-1 (id 0), and the
2445 	 *     hash function for ECDSA signatures is always SHA-1 (id 2).
2447 	 *   - When using TLS 1.2, the list of hash functions is trimmed
2468 	 *   - the cipher suite uses `ECDH_RSA` or `ECDH_ECDSA`;
2470 	 *   - the server requests a client certificate;
2472 	 *   - the client has, and sends, a client certificate that
2475 	 *     structure was set to -1).
2478 	 * client-side ECDH: the provided `data` (of length `*len` bytes)
2488 	 *   - If the input array does not have the proper length for
2491 	 *   - If the input array has the proper length, then processing
2492 	 *     MUST be constant-time, even if the data is not a valid
2495 	 *   - This callback MUST check that the input point is valid.
2526 	 * this is the special header-less signature specified in TLS 1.0
2527 	 * and 1.1, with a 36-byte hash value. Otherwise, normal PKCS#1
2547  * \brief A single-chain RSA client certificate handler.
2567  * \brief A single-chain EC client certificate handler.
2666  *   - If RSA (PKCS#1 v1.5) is supported with hash function of ID `x`,
2667  *     then bit `x` is set (hash function ID is 0 for the special MD5+SHA-1,
2670  *   - If ECDSA is supported with hash function of ID `x`, then bit `8+x`
2673  *   - Newer algorithms are symbolic 16-bit identifiers that do not
2675  *     the TLS-level identifier is `0x0800+x` for a `x` in the 0..15
2688  * \return  the server-supported hash functions and signature algorithms.
2693 	return cc->hashes;  in br_ssl_client_get_server_hashes()
2708 	return cc->server_curve;  in br_ssl_client_get_server_curve()
2716  *    full    all supported versions and suites; constant-time implementations
2762 	cc->client_auth_vtable = pctx;  in br_ssl_client_set_client_certificate()
2766  * \brief Set the RSA public-key operations implementation.
2768  * This will be used to encrypt the pre-master secret with the server's
2769  * RSA public key (RSA-encryption cipher suites only).
2772  * \param irsapub   RSA public-key encryption implementation.
2777 	cc->irsapub = irsapub;  in br_ssl_client_set_rsapub()
2781  * \brief Set the "default" RSA implementation for public-key operations.
2784  * the pre-master secret, in `TLS_RSA_*` cipher suites) to the fastest
2785  * available on the current platform.
2801  * counting its 4-byte header. For instance, if `len` is set to 512,
2803  * header, and 521 bytes when counting the 5-byte record header.
2811 	cc->min_clienthello_len = len;  in br_ssl_client_set_min_clienthello_len()
2828  * If `resume_session` is non-zero and the context was previously used
2830  * server previously sent a non-empty session ID, and accepts the session
2841  * \param resume_session   non-zero to try session resumption.
2859 	cc->eng.session.session_id_len = 0;  in br_ssl_client_forget_session()
2931  * 16-bit integers.
2934  * The second element is the concatenation of four 4-bit elements which
2936  * order, these 4-bit elements are:
2938  *   - Bits 12 to 15: key exchange + server key type
2941 …*     | :-- | :----------------------- | :---------- | :------------------------------------------…
2948  *   - Bits 8 to 11: symmetric encryption algorithm
2951  *     | :-- | :--------------------- | :------------------- | :------------------ |
2953  *     |  1  | `BR_SSLENC_AES128_CBC` | AES-128/CBC          | 128                 |
2954  *     |  2  | `BR_SSLENC_AES256_CBC` | AES-256/CBC          | 256                 |
2955  *     |  3  | `BR_SSLENC_AES128_GCM` | AES-128/GCM          | 128                 |
2956  *     |  4  | `BR_SSLENC_AES256_GCM` | AES-256/GCM          | 256                 |
2959  *   - Bits 4 to 7: MAC algorithm
2962  *     | :-- | :----------------- | :----------- | :------------------------------------ |
2964  *     |  2  | `BR_SSLMAC_SHA1`   | HMAC/SHA-1   | Value matches `br_sha1_ID`            |
2965  *     |  4  | `BR_SSLMAC_SHA256` | HMAC/SHA-256 | Value matches `br_sha256_ID`          |
2966  *     |  5  | `BR_SSLMAC_SHA384` | HMAC/SHA-384 | Value matches `br_sha384_ID`          |
2968  *   - Bits 0 to 3: hash function for PRF when used with TLS-1.2
2971  *     | :-- | :----------------- | :------------ | :----------------------------------- |
2972  *     |  4  | `BR_SSLPRF_SHA256` | SHA-256       | Value matches `br_sha256_ID`         |
2973  *     |  5  | `BR_SSLPRF_SHA384` | SHA-384       | Value matches `br_sha384_ID`         |
2977  * that order: RSA key exchange (0), AES-128/GCM (3), AEAD integrity (0),
2978  * SHA-256 in the TLS PRF (4).
3011  * Pre-declaration for the SSL server context.
3030 	 * which the server _signs_ the ephemeral EC Diffie-Hellman
3035 	 *   - `0xFF00 + id`, where `id` is a hash function identifier
3036 	 *     (0 for MD5+SHA-1, or 2 to 6 for one of the SHA functions);
3038 	 *   - a full 16-bit identifier, lower than `0xFF00`.
3048 	 * to-be-signed data itself in `data`, i.e. the concatenation of
3050 	 * parameters. Furthermore, with TLS-1.2 and later, the 16-bit
3053 	 * RSA PKCS#1 v1.5 signature (the `01`) with SHA-256 as hash
3058 	 * MD5+SHA-1 (so use `0xFF00`), while ECDSA must use SHA-1
3072 	 * normally containing a DER-encoded certificate. The server
3089  * the client); it also performs the server-side computations involving
3141 	 * This callback is invoked to perform the server-side cryptographic
3147 	 * the 48-byte premaster secret copied back to the first 48 bytes
3150 	 *   - The caller makes sure that `*len` is at least 59 bytes.
3152 	 *   - This callback MUST check that the provided length matches
3155 	 *   - If the length matches that of the RSA key modulus, then
3156 	 *     processing MUST be constant-time, even if decryption fails,
3160 	 *   - This callback needs not check the two first bytes of the
3161 	 *     obtained pre-master secret (the caller will do that).
3163 	 *   - If an error is reported (0), then what the callback put
3173 	 *   - If the input array does not have the proper length for
3176 	 *   - If the input array has the proper length, then processing
3177 	 *     MUST be constant-time, even if the data is not a valid
3180 	 *   - This callback MUST check that the input point is valid.
3210 	 *   - `0xFF00 + id` for a hash function identifier `id`. In
3214 	 *     special MD5+SHA-1 concatenation (old-style RSA signing).
3216 	 *   - Another value, lower than `0xFF00`. The `data` buffer
3217 	 *     then contains the raw, non-hashed data to be signed
3237  * \brief A single-chain RSA policy handler.
3260  * \brief A single-chain EC policy handler.
3348  * search tree is maintained to keep lookups fast even with large
3465 	 * "tas" cannot be both non-NULL.
3483 	 * Server-specific implementations.
3500  * -- character 1: key exchange
3506  * -- character 2: version / PRF
3507  *      0 = TLS 1.0 / 1.1 with MD5+SHA-1
3508  *      2 = TLS 1.2 with SHA-256
3509  *      3 = TLS 1.2 with SHA-384
3510  * -- character 3: encryption
3542  * suites require a RSA-powered CA). The key type is either
3689  * as two 16-bit integers: the standard suite identifier, and its
3703 	*num = cc->client_suites_num;  in br_ssl_server_get_client_suites()
3704 	return cc->client_suites;  in br_ssl_server_get_client_suites()
3713  *   - If RSA (PKCS#1 v1.5) is supported with hash function of ID `x`,
3714  *     then bit `x` is set (hash function ID is 0 for the special MD5+SHA-1,
3717  *   - If ECDSA is supported with hash function of ID `x`, then bit `8+x`
3720  *   - Newer algorithms are symbolic 16-bit identifiers that do not
3722  *     the TLS-level identifier is `0x0800+x` for a `x` in the 0..15
3735  * \return  the client-supported hash functions and signature algorithms.
3740 	return cc->hashes;  in br_ssl_server_get_client_hashes()
3749  * \return  the client-supported elliptic curves.
3754 	return cc->curves;  in br_ssl_server_get_client_curves()
3782 	cc->policy_vtable = pctx;  in br_ssl_server_set_policy()
3818  * In order to support `TLS_ECDH_*` cipher suites (non-ephemeral ECDH),
3861 	cc->ta_names = ta_names;  in br_ssl_server_set_trust_anchor_names()
3862 	cc->tas = NULL;  in br_ssl_server_set_trust_anchor_names()
3863 	cc->num_tas = num;  in br_ssl_server_set_trust_anchor_names()
3870  * trust anchor names are provided not as an array of stand-alone names
3888 	cc->ta_names = NULL;  in br_ssl_server_set_trust_anchor_names_alt()
3889 	cc->tas = tas;  in br_ssl_server_set_trust_anchor_names_alt()
3890 	cc->num_tas = num;  in br_ssl_server_set_trust_anchor_names_alt()
3906 	cc->cache_vtable = vtable;  in br_ssl_server_set_cache()
3925  *                returned value is the number of read bytes, or -1 on error.
3930  *                returned value is the number of written bytes, or -1 on
3936  * as an error (-1). The callbacks shall endeavour to block until at least
3972  *   - Each callback receives an opaque context value (of type `void *`)
3975  *   - `low_read()` reads at least one byte, at most `len` bytes, from
3978  *   - `low_write()` writes at least one byte, at most `len` bytes, unto
3981  *   - The `len` parameter is never zero, and is always lower than 20000.
3983  *   - The number of processed bytes (read or written) is returned. Since
3986  *   - On error, the callbacks return -1. Reaching end-of-stream is an
3989  *   - Callbacks SHOULD NOT return 0. This is tolerated, as long as
3990  *     callbacks endeavour to block for some non-negligible amount of
3995  *   - Callbacks MAY return as soon as at least one byte is processed;
3997  *     Since SSL is a self-terminated protocol (each record has a length
4000  *   - Callbacks need not apply any buffering (for performance) since SSL
4026  * Returned value is the number of bytes read, or -1 on error. The
4030  * On error or SSL closure, this function returns -1. The caller should
4037  * \return  number of bytes obtained, or -1 on error.
4045  * or an error is reached. Returned value is 0 on success, -1 on error.
4052  * \return  0 on success, or -1 on error.
4063  * Returned value is the number of bytes written, or -1 on error. The
4066  * On error or SSL closure, this function returns -1. The caller should
4078  * \return  number of bytes written, or -1 on error.
4086  * written, or an error is reached. Returned value is 0 on success, -1
4098  * \return  0 on success, or -1 on error.
4114  * Returned value is 0 on success, -1 on error.
4117  * \return  0 on success, or -1 on error.
4127  * possible transport-level termination, if applicable (alternatively,
4128  * the underlying transport stream may be reused for non-SSL messages).
4130  * Returned value is 0 on success, -1 on error. A failure by the peer
4135  * \return  0 on success, or -1 on error.