51  * registry](http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4).
54  * a fatal alert message is sent of received, then the SSL engine context
66 /** \brief Optimal buffer size for monodirectional engine
70 /** \brief Optimal buffer size for bidirectional engine
93  * Implementation note: SSL-level error codes should be in the 1..31
101 /** \brief SSL status: caller-provided parameter is incorrect. */
135     regards to the current engine state. */
230  * \brief Decryption engine for SSL.
232  * When processing incoming records, the SSL engine will use a decryption
233  * engine that uses a specific context structure, and has a set of
236  * The decryption engine is responsible for applying decryption, verifying
252 	 * \param ctx          decryption engine context.
267 	 * `*len` is set to 0 and a non-`NULL` pointer is returned.
271 	 * \param ctx           decryption engine context.
284  * \brief Encryption engine for SSL.
286  * When building outgoing records, the SSL engine will use an encryption
287  * engine that uses a specific context structure, and has a set of
290  * The encryption engine is responsible for applying encryption and MAC,
306 	 * preceded by a 5-byte space which will receive the record
310 	 * both `*start` and `*end` to make room for any record-specific
313 	 * \param ctx     encryption engine context.
326 	 * performed), _including_ the 5-byte header, and `*len` is
330 	 * \param ctx           decryption engine context.
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. */
359  * \brief Record decryption engine class, for CBC mode.
361  * This class type extends the decryption engine class with an
363  * for CBC processing: block cipher implementation, block cipher key,
365  * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
375 	 * \brief Engine initialisation method.
398  * \brief Record encryption engine class, for CBC mode.
400  * This class type extends the encryption engine class with an
402  * for CBC processing: block cipher implementation, block cipher key,
404  * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
414 	 * \brief Engine initialisation method.
497  * \brief Record decryption engine class, for GCM mode.
499  * This class type extends the decryption engine class with an
501  * for GCM processing: block cipher implementation, block cipher key,
502  * GHASH implementation, and 4-byte IV.
512 	 * \brief Engine initialisation method.
531  * \brief Record encryption engine class, for GCM mode.
533  * This class type extends the encryption engine class with an
535  * for GCM processing: block cipher implementation, block cipher key,
536  * GHASH implementation, and 4-byte IV.
546 	 * \brief Engine initialisation method.
565  * \brief Context structure for processing records with GCM.
604  * \brief Record decryption engine class, for ChaCha20+Poly1305.
606  * This class type extends the decryption engine class with an
608  * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
609  * Poly1305 implementation, key, and 12-byte IV.
619 	 * \brief Engine initialisation method.
636  * \brief Record encryption engine class, for ChaCha20+Poly1305.
638  * This class type extends the encryption engine class with an
640  * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
641  * Poly1305 implementation, key, and 12-byte IV.
651 	 * \brief Engine initialisation method.
668  * \brief Context structure for processing records with ChaCha20+Poly1305.
704  * \brief Record decryption engine class, for CCM mode.
706  * This class type extends the decryption engine class with an
708  * for CCM processing: block cipher implementation, block cipher key,
709  * and 4-byte IV.
719 	 * \brief Engine initialisation method.
737  * \brief Record encryption engine class, for CCM mode.
739  * This class type extends the encryption engine class with an
741  * for CCM processing: block cipher implementation, block cipher key,
742  * and 4-byte IV.
752 	 * \brief Engine initialisation method.
770  * \brief Context structure for processing records with CCM.
831  * \brief Context structure for SSL engine.
838  * The engine context manages records, including alerts, closures, and
839  * transitions to new encryption/MAC algorithms. Processing of handshake
848 	 * The error code. When non-zero, then the state is "failed" and
878 	 * Shutdown flag: when set to non-zero, incoming record bytes
880 	 * has been received: afterwards, the engine no longer claims that
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
1024 	 * engine and the handshake processor.
1026 	 * From the engine:
1047 	 * Multi-hasher for the handshake messages. The handshake handler
1053 	 * Pointer to the X.509 engine. The engine is supposed to be
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
1122  * \brief Get currently defined engine behavioural flags.
1124  * \param cc   SSL engine context.
1130 	return cc->flags;  in br_ssl_engine_get_flags()
1134  * \brief Set all engine behavioural flags.
1136  * \param cc      SSL engine context.
1142 	cc->flags = flags;  in br_ssl_engine_set_all_flags()
1146  * \brief Set some engine behavioural flags.
1151  * \param cc      SSL engine context.
1157 	cc->flags |= flags;  in br_ssl_engine_add_flags()
1161  * \brief Clear some engine behavioural flags.
1166  * \param cc      SSL engine context.
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
1245  * \param cc            SSL engine context.
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()
1262  * by the context. The engine context has enough room to receive _all_
1266  * If the engine is for a client, the "signaling" pseudo-cipher suite
1270  * adding the fallback pseudo-suite is a good idea).
1272  * \param cc           SSL engine context.
1280  * \brief Set the X.509 engine.
1282  * The caller shall ensure that the X.509 engine is properly initialised.
1284  * \param cc        SSL engine context.
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
1318  * \param ctx     SSL engine context.
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`
1360  * \param ctx    SSL engine context.
1368 	br_multihash_setimpl(&ctx->mhash, id, impl);  in br_ssl_engine_set_hash()
1377  * \param ctx   SSL engine context.
1384 	return br_multihash_getimpl(&ctx->mhash, id);  in br_ssl_engine_get_hash()
1393  * \param cc     SSL engine context.
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.
1408  * \param cc     SSL engine context.
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.
1423  * \param cc     SSL engine context.
1429 	cc->prf_sha384 = impl;  in br_ssl_engine_set_prf_sha384()
1435  * \param cc         SSL engine context.
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()
1451  * This function configures in the engine the AES implementations that
1453  * still being safe (in particular, constant-time). It also sets the
1456  * \param cc   SSL engine context.
1463  * \param cc     SSL engine context.
1470 	cc->iaes_ctr = impl;  in br_ssl_engine_set_aes_ctr()
1476  * This function configures in the engine the AES/CTR and GHASH
1478  * system, while still being safe (in particular, constant-time). It also
1481  * \param cc   SSL engine context.
1488  * \param cc         SSL engine context.
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()
1504  * This function configures in the engine the DES implementations that
1506  * still being safe (in particular, constant-time). It also sets the
1509  * \param cc   SSL engine context.
1516  * \param cc     SSL engine context.
1522 	cc->ighash = impl;  in br_ssl_engine_set_ghash()
1528  * \param cc        SSL engine context.
1535 	cc->ichacha = ichacha;  in br_ssl_engine_set_chacha20()
1541  * \param cc      SSL engine context.
1548 	cc->ipoly = ipoly;  in br_ssl_engine_set_poly1305()
1554  * This function configures in the engine the ChaCha20 and Poly1305
1556  * local system, while still being safe (in particular, constant-time).
1559  * \param cc   SSL engine context.
1566  * \param cc     SSL engine context.
1573 	cc->iaes_ctrcbc = impl;  in br_ssl_engine_set_aes_ctrcbc()
1579  * This function configures in the engine the AES/CTR+CBC
1581  * system, while still being safe (in particular, constant-time). It also
1584  * \param cc   SSL engine context.
1591  * \param cc         SSL engine context.
1600 	cc->icbc_in = impl_in;  in br_ssl_engine_set_cbc()
1601 	cc->icbc_out = impl_out;  in br_ssl_engine_set_cbc()
1607  * \param cc         SSL engine context.
1616 	cc->igcm_in = impl_in;  in br_ssl_engine_set_gcm()
1617 	cc->igcm_out = impl_out;  in br_ssl_engine_set_gcm()
1623  * \param cc         SSL engine context.
1632 	cc->iccm_in = impl_in;  in br_ssl_engine_set_ccm()
1633 	cc->iccm_out = impl_out;  in br_ssl_engine_set_ccm()
1640  * \param cc         SSL engine context.
1649 	cc->ichapol_in = impl_in;  in br_ssl_engine_set_chapol()
1650 	cc->ichapol_out = impl_out;  in br_ssl_engine_set_chapol()
1659  * \param cc    SSL engine context.
1665 	cc->iec = iec;  in br_ssl_engine_set_ec()
1675  * \param cc   SSL engine context.
1680  * \brief Get the EC implementation configured in the provided engine.
1682  * \param cc   SSL engine context.
1688 	return cc->iec;  in br_ssl_engine_get_ec()
1699  * \param cc         SSL engine context.
1705 	cc->irsavrfy = irsavrfy;  in br_ssl_engine_set_rsavrfy()
1714  * \param cc   SSL engine context.
1720  * in the provided engine.
1722  * \param cc   SSL engine context.
1728 	return cc->irsavrfy;  in br_ssl_engine_get_rsavrfy()
1738  * and full-static ECDH is not used).
1741  * in the engine context.
1749 	cc->iecdsa = iecdsa;  in br_ssl_engine_set_ecdsa()
1760  * \param cc   SSL engine context.
1766  * in the provided engine.
1768  * \param cc   SSL engine context.
1774 	return cc->iecdsa;  in br_ssl_engine_get_ecdsa()
1778  * \brief Set the I/O buffer for the SSL engine.
1783  * The provided buffer will be used as long as the engine context is
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
1792  * capacity of the engine to support all allowed record sizes.
1794  * If `bidi` is 1, then the engine will split the buffer into two
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
1802  * \param cc          SSL engine context
1805  * \param bidi        non-zero for full-duplex mode.
1811  * \brief Set the I/O buffers for the SSL engine.
1817  * that it enforces full-duplex mode, and the two I/O buffers are
1824  * \param cc         SSL engine context
1846  * preferably 128 or more). The engine will report an error if no entropy
1857  * non-repeating value (e.g. current time, provided that the local clock
1860  * \param cc     SSL engine context.
1868  * \brief Get the "server name" in this engine.
1880  * \param cc   SSL engine context.
1886 	return cc->server_name;  in br_ssl_engine_get_server_name()
1893  * engine. That value is set after sending (for a server) or receiving
1896  * \param cc   SSL engine context.
1902 	return cc->session.version;  in br_ssl_engine_get_version()
1917  * \param cc   SSL engine context.
1924 	memcpy(pp, &cc->session, sizeof *pp);  in br_ssl_engine_get_session_parameters()
1934  * \param cc   SSL engine context.
1941 	memcpy(&cc->session, pp, sizeof *pp);  in br_ssl_engine_set_session_parameters()
1954  * @param cc   SSL engine context.
1960 	return cc->ecdhe_curve;  in br_ssl_engine_get_ecdhe_curve()
1964  * \brief Get the current engine state.
1966  * An SSL engine (client or server) has, at any time, a state which is
1969  *   - `BR_SSL_CLOSED`
1971  *     Engine is finished, no more I/O (until next reset).
1973  *   - `BR_SSL_SENDREC`
1975  *     Engine has some bytes to send to the peer.
1977  *   - `BR_SSL_RECVREC`
1979  *     Engine expects some bytes from the peer.
1981  *   - `BR_SSL_SENDAPP`
1983  *     Engine may receive application data to send (or flush).
1985  *   - `BR_SSL_RECVAPP`
1987  *     Engine has obtained some application data from the peer,
1990  * If no flag at all is set (state value is 0), then the engine is not
2003  * \param cc   SSL engine context.
2004  * \return  the current engine state.
2008 /** \brief SSL engine state: closed or failed. */
2010 /** \brief SSL engine state: record data is ready to be sent to the peer. */
2012 /** \brief SSL engine state: engine may receive records from the peer. */
2014 /** \brief SSL engine state: engine may accept application data to send. */
2016 /** \brief SSL engine state: engine has received application data. */
2020  * \brief Get the engine error indicator.
2028  * \param cc   SSL engine context.
2029  * \return  0, or a non-zero error code.
2034 	return cc->err;  in br_ssl_engine_last_error()
2040  *   sendapp   inject application data in the engine
2041  *   recvapp   retrieving application data from the engine
2045  * Terminology works thus: in a layered model where the SSL engine sits
2050  * Note that from the SSL engine point of view, "sendapp" and "recvrec"
2051  * designate bytes that enter the engine ("inject" operation), while
2052  * "recvapp" and "sendrec" designate bytes that exit the engine
2063  *      The engine state is unmodified by this call.
2066  *      Informs the engine that 'len' bytes have been read from the buffer
2076  * If the engine is ready to accept application data to send to the
2081  * \param cc    SSL engine context.
2089  * \brief Inform the engine of some new application data.
2093  * function to trigger any relevant processing. The `len` parameter
2097  * \param cc    SSL engine context.
2105  * If the engine has received application data from the peer, then this
2110  * \param cc    SSL engine context.
2122  * function to trigger any relevant processing. The `len` parameter
2126  * \param cc    SSL engine context.
2134  * If the engine has prepared some records to send to the peer, then this
2139  * \param cc    SSL engine context.
2151  * function to trigger any relevant processing. The `len` parameter
2155  * \param cc    SSL engine context.
2163  * If the engine is ready to accept records from the peer, then this
2168  * \param cc    SSL engine context.
2176  * \brief Inform the engine of some new record data.
2180  * function to trigger any relevant processing. The `len` parameter
2184  * \param cc    SSL engine context.
2192  * If some application data has been buffered in the engine, then wrap
2194  * been buffered but the engine would be ready to accept some, AND the
2195  * `force` parameter is non-zero, then an empty record is assembled and
2200  * transparent "keep-alive" mechanism to maintain some low-level
2203  * \param cc      SSL engine context.
2204  * \param force   non-zero to force sending an empty record.
2215  * \param cc   SSL engine context.
2222  * If the engine is failed or closed, or if the peer is known not to
2232  * \param cc   SSL engine context.
2238  * \brief Export key material from a connected SSL engine (RFC 5705).
2241  * secret of a connected SSL engine. If the provided context is not
2254  * zero bytes, by setting `context` to a non-`NULL` value but
2260  * \param cc            SSL engine context.
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
2347  * The SSL client engine will first push the trust anchor DN with
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.
2596  * The first field (called `eng`) is the SSL engine; all functions that
2603 	 * \brief The encapsulated engine context.
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
2725  * a companion X.509 validation engine with all supported algorithms,
2726  * and the provided trust anchors; the X.509 engine will be used by
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
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()
2818  * X.509 "minimal" engine will also match that name against the server
2821  * engine (if used for server certificate validation) will not check
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`.
3040 	 * If the first option is used, then the SSL engine will
3046 	 * If the second option is used, then the SSL engine will NOT
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
3092  * The SSL server engine will invoke first `choose()`, once the
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.
3397  * The first field (called `eng`) is the SSL engine; all functions that
3404 	 * \brief The encapsulated engine context.
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
3682  * processed, typically from the policy engine. The returned array
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),
3843  * the X.509 validator configured in the SSL engine. If `num` is 0, then
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
3872  * (`br_x509_trust_anchor` structures). The server engine itself will
3875  * X.509 validation engine itself.
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
3942  * The SSL engine naturally applies some buffering, so the callbacks need
3953 	br_ssl_engine_context *engine;  member
3967  * engine (client or server), using the provided callback functions for
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
4004  * \param engine          SSL engine to wrap.
4011 	br_ssl_engine_context *engine,
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
4031  * inspect the error status on the SSL engine to distinguish between
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
4067  * inspect the error status on the SSL engine to distinguish between
4071  * injected into the wrapped SSL engine, but this does not necessarily mean
4078  * \return  number of bytes written, or -1 on error.
4086  * written, or an error is reached. Returned value is 0 on success, -1
4091  * injected into the wrapped SSL engine, but this does not necessarily mean
4098  * \return  0 on success, or -1 on error.
4106  * provided context (including the wrapped SSL engine) has been sent
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.