10957b409SSimon J. Gerraty /*
20957b409SSimon J. Gerraty * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
30957b409SSimon J. Gerraty *
40957b409SSimon J. Gerraty * Permission is hereby granted, free of charge, to any person obtaining
50957b409SSimon J. Gerraty * a copy of this software and associated documentation files (the
60957b409SSimon J. Gerraty * "Software"), to deal in the Software without restriction, including
70957b409SSimon J. Gerraty * without limitation the rights to use, copy, modify, merge, publish,
80957b409SSimon J. Gerraty * distribute, sublicense, and/or sell copies of the Software, and to
90957b409SSimon J. Gerraty * permit persons to whom the Software is furnished to do so, subject to
100957b409SSimon J. Gerraty * the following conditions:
110957b409SSimon J. Gerraty *
120957b409SSimon J. Gerraty * The above copyright notice and this permission notice shall be
130957b409SSimon J. Gerraty * included in all copies or substantial portions of the Software.
140957b409SSimon J. Gerraty *
150957b409SSimon J. Gerraty * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
160957b409SSimon J. Gerraty * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
170957b409SSimon J. Gerraty * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
180957b409SSimon J. Gerraty * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
190957b409SSimon J. Gerraty * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
200957b409SSimon J. Gerraty * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
210957b409SSimon J. Gerraty * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
220957b409SSimon J. Gerraty * SOFTWARE.
230957b409SSimon J. Gerraty */
240957b409SSimon J. Gerraty
250957b409SSimon J. Gerraty #ifndef BR_BEARSSL_SSL_H__
260957b409SSimon J. Gerraty #define BR_BEARSSL_SSL_H__
270957b409SSimon J. Gerraty
280957b409SSimon J. Gerraty #include <stddef.h>
290957b409SSimon J. Gerraty #include <stdint.h>
300957b409SSimon J. Gerraty
310957b409SSimon J. Gerraty #include "bearssl_block.h"
320957b409SSimon J. Gerraty #include "bearssl_hash.h"
330957b409SSimon J. Gerraty #include "bearssl_hmac.h"
340957b409SSimon J. Gerraty #include "bearssl_prf.h"
350957b409SSimon J. Gerraty #include "bearssl_rand.h"
360957b409SSimon J. Gerraty #include "bearssl_x509.h"
370957b409SSimon J. Gerraty
380957b409SSimon J. Gerraty #ifdef __cplusplus
390957b409SSimon J. Gerraty extern "C" {
400957b409SSimon J. Gerraty #endif
410957b409SSimon J. Gerraty
420957b409SSimon J. Gerraty /** \file bearssl_ssl.h
430957b409SSimon J. Gerraty *
440957b409SSimon J. Gerraty * # SSL
450957b409SSimon J. Gerraty *
460957b409SSimon J. Gerraty * For an overview of the SSL/TLS API, see [the BearSSL Web
470957b409SSimon J. Gerraty * site](https://www.bearssl.org/api1.html).
480957b409SSimon J. Gerraty *
490957b409SSimon J. Gerraty * The `BR_TLS_*` constants correspond to the standard cipher suites and
500957b409SSimon J. Gerraty * their values in the [IANA
510957b409SSimon J. Gerraty * registry](http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4).
520957b409SSimon J. Gerraty *
530957b409SSimon J. Gerraty * The `BR_ALERT_*` constants are for standard TLS alert messages. When
540957b409SSimon J. Gerraty * a fatal alert message is sent of received, then the SSL engine context
550957b409SSimon J. Gerraty * status is set to the sum of that alert value (an integer in the 0..255
560957b409SSimon J. Gerraty * range) and a fixed offset (`BR_ERR_SEND_FATAL_ALERT` for a sent alert,
570957b409SSimon J. Gerraty * `BR_ERR_RECV_FATAL_ALERT` for a received alert).
580957b409SSimon J. Gerraty */
590957b409SSimon J. Gerraty
600957b409SSimon J. Gerraty /** \brief Optimal input buffer size. */
610957b409SSimon J. Gerraty #define BR_SSL_BUFSIZE_INPUT (16384 + 325)
620957b409SSimon J. Gerraty
630957b409SSimon J. Gerraty /** \brief Optimal output buffer size. */
640957b409SSimon J. Gerraty #define BR_SSL_BUFSIZE_OUTPUT (16384 + 85)
650957b409SSimon J. Gerraty
660957b409SSimon J. Gerraty /** \brief Optimal buffer size for monodirectional engine
670957b409SSimon J. Gerraty (shared input/output buffer). */
680957b409SSimon J. Gerraty #define BR_SSL_BUFSIZE_MONO BR_SSL_BUFSIZE_INPUT
690957b409SSimon J. Gerraty
700957b409SSimon J. Gerraty /** \brief Optimal buffer size for bidirectional engine
710957b409SSimon J. Gerraty (single buffer split into two separate input/output buffers). */
720957b409SSimon J. Gerraty #define BR_SSL_BUFSIZE_BIDI (BR_SSL_BUFSIZE_INPUT + BR_SSL_BUFSIZE_OUTPUT)
730957b409SSimon J. Gerraty
740957b409SSimon J. Gerraty /*
750957b409SSimon J. Gerraty * Constants for known SSL/TLS protocol versions (SSL 3.0, TLS 1.0, TLS 1.1
760957b409SSimon J. Gerraty * and TLS 1.2). Note that though there is a constant for SSL 3.0, that
770957b409SSimon J. Gerraty * protocol version is not actually supported.
780957b409SSimon J. Gerraty */
790957b409SSimon J. Gerraty
800957b409SSimon J. Gerraty /** \brief Protocol version: SSL 3.0 (unsupported). */
810957b409SSimon J. Gerraty #define BR_SSL30 0x0300
820957b409SSimon J. Gerraty /** \brief Protocol version: TLS 1.0. */
830957b409SSimon J. Gerraty #define BR_TLS10 0x0301
840957b409SSimon J. Gerraty /** \brief Protocol version: TLS 1.1. */
850957b409SSimon J. Gerraty #define BR_TLS11 0x0302
860957b409SSimon J. Gerraty /** \brief Protocol version: TLS 1.2. */
870957b409SSimon J. Gerraty #define BR_TLS12 0x0303
880957b409SSimon J. Gerraty
890957b409SSimon J. Gerraty /*
900957b409SSimon J. Gerraty * Error constants. They are used to report the reason why a context has
910957b409SSimon J. Gerraty * been marked as failed.
920957b409SSimon J. Gerraty *
930957b409SSimon J. Gerraty * Implementation note: SSL-level error codes should be in the 1..31
940957b409SSimon J. Gerraty * range. The 32..63 range is for certificate decoding and validation
950957b409SSimon J. Gerraty * errors. Received fatal alerts imply an error code in the 256..511 range.
960957b409SSimon J. Gerraty */
970957b409SSimon J. Gerraty
980957b409SSimon J. Gerraty /** \brief SSL status: no error so far (0). */
990957b409SSimon J. Gerraty #define BR_ERR_OK 0
1000957b409SSimon J. Gerraty
1010957b409SSimon J. Gerraty /** \brief SSL status: caller-provided parameter is incorrect. */
1020957b409SSimon J. Gerraty #define BR_ERR_BAD_PARAM 1
1030957b409SSimon J. Gerraty
1040957b409SSimon J. Gerraty /** \brief SSL status: operation requested by the caller cannot be applied
1050957b409SSimon J. Gerraty with the current context state (e.g. reading data while outgoing data
1060957b409SSimon J. Gerraty is waiting to be sent). */
1070957b409SSimon J. Gerraty #define BR_ERR_BAD_STATE 2
1080957b409SSimon J. Gerraty
1090957b409SSimon J. Gerraty /** \brief SSL status: incoming protocol or record version is unsupported. */
1100957b409SSimon J. Gerraty #define BR_ERR_UNSUPPORTED_VERSION 3
1110957b409SSimon J. Gerraty
1120957b409SSimon J. Gerraty /** \brief SSL status: incoming record version does not match the expected
1130957b409SSimon J. Gerraty version. */
1140957b409SSimon J. Gerraty #define BR_ERR_BAD_VERSION 4
1150957b409SSimon J. Gerraty
1160957b409SSimon J. Gerraty /** \brief SSL status: incoming record length is invalid. */
1170957b409SSimon J. Gerraty #define BR_ERR_BAD_LENGTH 5
1180957b409SSimon J. Gerraty
1190957b409SSimon J. Gerraty /** \brief SSL status: incoming record is too large to be processed, or
1200957b409SSimon J. Gerraty buffer is too small for the handshake message to send. */
1210957b409SSimon J. Gerraty #define BR_ERR_TOO_LARGE 6
1220957b409SSimon J. Gerraty
1230957b409SSimon J. Gerraty /** \brief SSL status: decryption found an invalid padding, or the record
1240957b409SSimon J. Gerraty MAC is not correct. */
1250957b409SSimon J. Gerraty #define BR_ERR_BAD_MAC 7
1260957b409SSimon J. Gerraty
1270957b409SSimon J. Gerraty /** \brief SSL status: no initial entropy was provided, and none can be
1280957b409SSimon J. Gerraty obtained from the OS. */
1290957b409SSimon J. Gerraty #define BR_ERR_NO_RANDOM 8
1300957b409SSimon J. Gerraty
1310957b409SSimon J. Gerraty /** \brief SSL status: incoming record type is unknown. */
1320957b409SSimon J. Gerraty #define BR_ERR_UNKNOWN_TYPE 9
1330957b409SSimon J. Gerraty
1340957b409SSimon J. Gerraty /** \brief SSL status: incoming record or message has wrong type with
1350957b409SSimon J. Gerraty regards to the current engine state. */
1360957b409SSimon J. Gerraty #define BR_ERR_UNEXPECTED 10
1370957b409SSimon J. Gerraty
1380957b409SSimon J. Gerraty /** \brief SSL status: ChangeCipherSpec message from the peer has invalid
1390957b409SSimon J. Gerraty contents. */
1400957b409SSimon J. Gerraty #define BR_ERR_BAD_CCS 12
1410957b409SSimon J. Gerraty
1420957b409SSimon J. Gerraty /** \brief SSL status: alert message from the peer has invalid contents
1430957b409SSimon J. Gerraty (odd length). */
1440957b409SSimon J. Gerraty #define BR_ERR_BAD_ALERT 13
1450957b409SSimon J. Gerraty
1460957b409SSimon J. Gerraty /** \brief SSL status: incoming handshake message decoding failed. */
1470957b409SSimon J. Gerraty #define BR_ERR_BAD_HANDSHAKE 14
1480957b409SSimon J. Gerraty
1490957b409SSimon J. Gerraty /** \brief SSL status: ServerHello contains a session ID which is larger
1500957b409SSimon J. Gerraty than 32 bytes. */
1510957b409SSimon J. Gerraty #define BR_ERR_OVERSIZED_ID 15
1520957b409SSimon J. Gerraty
1530957b409SSimon J. Gerraty /** \brief SSL status: server wants to use a cipher suite that we did
1540957b409SSimon J. Gerraty not claim to support. This is also reported if we tried to advertise
1550957b409SSimon J. Gerraty a cipher suite that we do not support. */
1560957b409SSimon J. Gerraty #define BR_ERR_BAD_CIPHER_SUITE 16
1570957b409SSimon J. Gerraty
1580957b409SSimon J. Gerraty /** \brief SSL status: server wants to use a compression that we did not
1590957b409SSimon J. Gerraty claim to support. */
1600957b409SSimon J. Gerraty #define BR_ERR_BAD_COMPRESSION 17
1610957b409SSimon J. Gerraty
1620957b409SSimon J. Gerraty /** \brief SSL status: server's max fragment length does not match
1630957b409SSimon J. Gerraty client's. */
1640957b409SSimon J. Gerraty #define BR_ERR_BAD_FRAGLEN 18
1650957b409SSimon J. Gerraty
1660957b409SSimon J. Gerraty /** \brief SSL status: secure renegotiation failed. */
1670957b409SSimon J. Gerraty #define BR_ERR_BAD_SECRENEG 19
1680957b409SSimon J. Gerraty
1690957b409SSimon J. Gerraty /** \brief SSL status: server sent an extension type that we did not
1700957b409SSimon J. Gerraty announce, or used the same extension type several times in a single
1710957b409SSimon J. Gerraty ServerHello. */
1720957b409SSimon J. Gerraty #define BR_ERR_EXTRA_EXTENSION 20
1730957b409SSimon J. Gerraty
1740957b409SSimon J. Gerraty /** \brief SSL status: invalid Server Name Indication contents (when
1750957b409SSimon J. Gerraty used by the server, this extension shall be empty). */
1760957b409SSimon J. Gerraty #define BR_ERR_BAD_SNI 21
1770957b409SSimon J. Gerraty
1780957b409SSimon J. Gerraty /** \brief SSL status: invalid ServerHelloDone from the server (length
1790957b409SSimon J. Gerraty is not 0). */
1800957b409SSimon J. Gerraty #define BR_ERR_BAD_HELLO_DONE 22
1810957b409SSimon J. Gerraty
1820957b409SSimon J. Gerraty /** \brief SSL status: internal limit exceeded (e.g. server's public key
1830957b409SSimon J. Gerraty is too large). */
1840957b409SSimon J. Gerraty #define BR_ERR_LIMIT_EXCEEDED 23
1850957b409SSimon J. Gerraty
1860957b409SSimon J. Gerraty /** \brief SSL status: Finished message from peer does not match the
1870957b409SSimon J. Gerraty expected value. */
1880957b409SSimon J. Gerraty #define BR_ERR_BAD_FINISHED 24
1890957b409SSimon J. Gerraty
1900957b409SSimon J. Gerraty /** \brief SSL status: session resumption attempt with distinct version
1910957b409SSimon J. Gerraty or cipher suite. */
1920957b409SSimon J. Gerraty #define BR_ERR_RESUME_MISMATCH 25
1930957b409SSimon J. Gerraty
1940957b409SSimon J. Gerraty /** \brief SSL status: unsupported or invalid algorithm (ECDHE curve,
1950957b409SSimon J. Gerraty signature algorithm, hash function). */
1960957b409SSimon J. Gerraty #define BR_ERR_INVALID_ALGORITHM 26
1970957b409SSimon J. Gerraty
1980957b409SSimon J. Gerraty /** \brief SSL status: invalid signature (on ServerKeyExchange from
1990957b409SSimon J. Gerraty server, or in CertificateVerify from client). */
2000957b409SSimon J. Gerraty #define BR_ERR_BAD_SIGNATURE 27
2010957b409SSimon J. Gerraty
2020957b409SSimon J. Gerraty /** \brief SSL status: peer's public key does not have the proper type
2030957b409SSimon J. Gerraty or is not allowed for requested operation. */
2040957b409SSimon J. Gerraty #define BR_ERR_WRONG_KEY_USAGE 28
2050957b409SSimon J. Gerraty
2060957b409SSimon J. Gerraty /** \brief SSL status: client did not send a certificate upon request,
2070957b409SSimon J. Gerraty or the client certificate could not be validated. */
2080957b409SSimon J. Gerraty #define BR_ERR_NO_CLIENT_AUTH 29
2090957b409SSimon J. Gerraty
2100957b409SSimon J. Gerraty /** \brief SSL status: I/O error or premature close on underlying
2110957b409SSimon J. Gerraty transport stream. This error code is set only by the simplified
2120957b409SSimon J. Gerraty I/O API ("br_sslio_*"). */
2130957b409SSimon J. Gerraty #define BR_ERR_IO 31
2140957b409SSimon J. Gerraty
2150957b409SSimon J. Gerraty /** \brief SSL status: base value for a received fatal alert.
2160957b409SSimon J. Gerraty
2170957b409SSimon J. Gerraty When a fatal alert is received from the peer, the alert value
2180957b409SSimon J. Gerraty is added to this constant. */
2190957b409SSimon J. Gerraty #define BR_ERR_RECV_FATAL_ALERT 256
2200957b409SSimon J. Gerraty
2210957b409SSimon J. Gerraty /** \brief SSL status: base value for a sent fatal alert.
2220957b409SSimon J. Gerraty
2230957b409SSimon J. Gerraty When a fatal alert is sent to the peer, the alert value is added
2240957b409SSimon J. Gerraty to this constant. */
2250957b409SSimon J. Gerraty #define BR_ERR_SEND_FATAL_ALERT 512
2260957b409SSimon J. Gerraty
2270957b409SSimon J. Gerraty /* ===================================================================== */
2280957b409SSimon J. Gerraty
2290957b409SSimon J. Gerraty /**
2300957b409SSimon J. Gerraty * \brief Decryption engine for SSL.
2310957b409SSimon J. Gerraty *
2320957b409SSimon J. Gerraty * When processing incoming records, the SSL engine will use a decryption
2330957b409SSimon J. Gerraty * engine that uses a specific context structure, and has a set of
2340957b409SSimon J. Gerraty * methods (a vtable) that follows this template.
2350957b409SSimon J. Gerraty *
2360957b409SSimon J. Gerraty * The decryption engine is responsible for applying decryption, verifying
2370957b409SSimon J. Gerraty * MAC, and keeping track of the record sequence number.
2380957b409SSimon J. Gerraty */
2390957b409SSimon J. Gerraty typedef struct br_sslrec_in_class_ br_sslrec_in_class;
2400957b409SSimon J. Gerraty struct br_sslrec_in_class_ {
2410957b409SSimon J. Gerraty /**
2420957b409SSimon J. Gerraty * \brief Context size (in bytes).
2430957b409SSimon J. Gerraty */
2440957b409SSimon J. Gerraty size_t context_size;
2450957b409SSimon J. Gerraty
2460957b409SSimon J. Gerraty /**
2470957b409SSimon J. Gerraty * \brief Test validity of the incoming record length.
2480957b409SSimon J. Gerraty *
2490957b409SSimon J. Gerraty * This function returns 1 if the announced length for an
2500957b409SSimon J. Gerraty * incoming record is valid, 0 otherwise,
2510957b409SSimon J. Gerraty *
2520957b409SSimon J. Gerraty * \param ctx decryption engine context.
2530957b409SSimon J. Gerraty * \param record_len incoming record length.
2540957b409SSimon J. Gerraty * \return 1 of a valid length, 0 otherwise.
2550957b409SSimon J. Gerraty */
2560957b409SSimon J. Gerraty int (*check_length)(const br_sslrec_in_class *const *ctx,
2570957b409SSimon J. Gerraty size_t record_len);
2580957b409SSimon J. Gerraty
2590957b409SSimon J. Gerraty /**
2600957b409SSimon J. Gerraty * \brief Decrypt the incoming record.
2610957b409SSimon J. Gerraty *
2620957b409SSimon J. Gerraty * This function may assume that the record length is valid
2630957b409SSimon J. Gerraty * (it has been previously tested with `check_length()`).
2640957b409SSimon J. Gerraty * Decryption is done in place; `*len` is updated with the
2650957b409SSimon J. Gerraty * cleartext length, and the address of the first plaintext
2660957b409SSimon J. Gerraty * byte is returned. If the record is correct but empty, then
2670957b409SSimon J. Gerraty * `*len` is set to 0 and a non-`NULL` pointer is returned.
2680957b409SSimon J. Gerraty *
2690957b409SSimon J. Gerraty * On decryption/MAC error, `NULL` is returned.
2700957b409SSimon J. Gerraty *
2710957b409SSimon J. Gerraty * \param ctx decryption engine context.
2720957b409SSimon J. Gerraty * \param record_type record type (23 for application data, etc).
2730957b409SSimon J. Gerraty * \param version record version.
2740957b409SSimon J. Gerraty * \param payload address of encrypted payload.
2750957b409SSimon J. Gerraty * \param len pointer to payload length (updated).
2760957b409SSimon J. Gerraty * \return pointer to plaintext, or `NULL` on error.
2770957b409SSimon J. Gerraty */
2780957b409SSimon J. Gerraty unsigned char *(*decrypt)(const br_sslrec_in_class **ctx,
2790957b409SSimon J. Gerraty int record_type, unsigned version,
2800957b409SSimon J. Gerraty void *payload, size_t *len);
2810957b409SSimon J. Gerraty };
2820957b409SSimon J. Gerraty
2830957b409SSimon J. Gerraty /**
2840957b409SSimon J. Gerraty * \brief Encryption engine for SSL.
2850957b409SSimon J. Gerraty *
2860957b409SSimon J. Gerraty * When building outgoing records, the SSL engine will use an encryption
2870957b409SSimon J. Gerraty * engine that uses a specific context structure, and has a set of
2880957b409SSimon J. Gerraty * methods (a vtable) that follows this template.
2890957b409SSimon J. Gerraty *
2900957b409SSimon J. Gerraty * The encryption engine is responsible for applying encryption and MAC,
2910957b409SSimon J. Gerraty * and keeping track of the record sequence number.
2920957b409SSimon J. Gerraty */
2930957b409SSimon J. Gerraty typedef struct br_sslrec_out_class_ br_sslrec_out_class;
2940957b409SSimon J. Gerraty struct br_sslrec_out_class_ {
2950957b409SSimon J. Gerraty /**
2960957b409SSimon J. Gerraty * \brief Context size (in bytes).
2970957b409SSimon J. Gerraty */
2980957b409SSimon J. Gerraty size_t context_size;
2990957b409SSimon J. Gerraty
3000957b409SSimon J. Gerraty /**
3010957b409SSimon J. Gerraty * \brief Compute maximum plaintext sizes and offsets.
3020957b409SSimon J. Gerraty *
3030957b409SSimon J. Gerraty * When this function is called, the `*start` and `*end`
3040957b409SSimon J. Gerraty * values contain offsets designating the free area in the
3050957b409SSimon J. Gerraty * outgoing buffer for plaintext data; that free area is
3060957b409SSimon J. Gerraty * preceded by a 5-byte space which will receive the record
3070957b409SSimon J. Gerraty * header.
3080957b409SSimon J. Gerraty *
3090957b409SSimon J. Gerraty * The `max_plaintext()` function is responsible for adjusting
3100957b409SSimon J. Gerraty * both `*start` and `*end` to make room for any record-specific
3110957b409SSimon J. Gerraty * header, MAC, padding, and possible split.
3120957b409SSimon J. Gerraty *
3130957b409SSimon J. Gerraty * \param ctx encryption engine context.
3140957b409SSimon J. Gerraty * \param start pointer to start of plaintext offset (updated).
3150957b409SSimon J. Gerraty * \param end pointer to start of plaintext offset (updated).
3160957b409SSimon J. Gerraty */
3170957b409SSimon J. Gerraty void (*max_plaintext)(const br_sslrec_out_class *const *ctx,
3180957b409SSimon J. Gerraty size_t *start, size_t *end);
3190957b409SSimon J. Gerraty
3200957b409SSimon J. Gerraty /**
3210957b409SSimon J. Gerraty * \brief Perform record encryption.
3220957b409SSimon J. Gerraty *
3230957b409SSimon J. Gerraty * This function encrypts the record. The plaintext address and
3240957b409SSimon J. Gerraty * length are provided. Returned value is the start of the
3250957b409SSimon J. Gerraty * encrypted record (or sequence of records, if a split was
3260957b409SSimon J. Gerraty * performed), _including_ the 5-byte header, and `*len` is
3270957b409SSimon J. Gerraty * adjusted to the total size of the record(s), there again
3280957b409SSimon J. Gerraty * including the header(s).
3290957b409SSimon J. Gerraty *
3300957b409SSimon J. Gerraty * \param ctx decryption engine context.
3310957b409SSimon J. Gerraty * \param record_type record type (23 for application data, etc).
3320957b409SSimon J. Gerraty * \param version record version.
3330957b409SSimon J. Gerraty * \param plaintext address of plaintext.
3340957b409SSimon J. Gerraty * \param len pointer to plaintext length (updated).
3350957b409SSimon J. Gerraty * \return pointer to start of built record.
3360957b409SSimon J. Gerraty */
3370957b409SSimon J. Gerraty unsigned char *(*encrypt)(const br_sslrec_out_class **ctx,
3380957b409SSimon J. Gerraty int record_type, unsigned version,
3390957b409SSimon J. Gerraty void *plaintext, size_t *len);
3400957b409SSimon J. Gerraty };
3410957b409SSimon J. Gerraty
3420957b409SSimon J. Gerraty /**
3430957b409SSimon J. Gerraty * \brief Context for a no-encryption engine.
3440957b409SSimon J. Gerraty *
3450957b409SSimon J. Gerraty * The no-encryption engine processes outgoing records during the initial
3460957b409SSimon J. Gerraty * handshake, before encryption is applied.
3470957b409SSimon J. Gerraty */
3480957b409SSimon J. Gerraty typedef struct {
3490957b409SSimon J. Gerraty /** \brief No-encryption engine vtable. */
3500957b409SSimon J. Gerraty const br_sslrec_out_class *vtable;
3510957b409SSimon J. Gerraty } br_sslrec_out_clear_context;
3520957b409SSimon J. Gerraty
3530957b409SSimon J. Gerraty /** \brief Static, constant vtable for the no-encryption engine. */
3540957b409SSimon J. Gerraty extern const br_sslrec_out_class br_sslrec_out_clear_vtable;
3550957b409SSimon J. Gerraty
3560957b409SSimon J. Gerraty /* ===================================================================== */
3570957b409SSimon J. Gerraty
3580957b409SSimon J. Gerraty /**
3590957b409SSimon J. Gerraty * \brief Record decryption engine class, for CBC mode.
3600957b409SSimon J. Gerraty *
3610957b409SSimon J. Gerraty * This class type extends the decryption engine class with an
3620957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
3630957b409SSimon J. Gerraty * for CBC processing: block cipher implementation, block cipher key,
3640957b409SSimon J. Gerraty * HMAC parameters (hash function, key, MAC length), and IV. If the
3650957b409SSimon J. Gerraty * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
3660957b409SSimon J. Gerraty */
3670957b409SSimon J. Gerraty typedef struct br_sslrec_in_cbc_class_ br_sslrec_in_cbc_class;
3680957b409SSimon J. Gerraty struct br_sslrec_in_cbc_class_ {
3690957b409SSimon J. Gerraty /**
3700957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
3710957b409SSimon J. Gerraty */
3720957b409SSimon J. Gerraty br_sslrec_in_class inner;
3730957b409SSimon J. Gerraty
3740957b409SSimon J. Gerraty /**
3750957b409SSimon J. Gerraty * \brief Engine initialisation method.
3760957b409SSimon J. Gerraty *
3770957b409SSimon J. Gerraty * This method sets the vtable field in the context.
3780957b409SSimon J. Gerraty *
3790957b409SSimon J. Gerraty * \param ctx context to initialise.
3800957b409SSimon J. Gerraty * \param bc_impl block cipher implementation (CBC decryption).
3810957b409SSimon J. Gerraty * \param bc_key block cipher key.
3820957b409SSimon J. Gerraty * \param bc_key_len block cipher key length (in bytes).
3830957b409SSimon J. Gerraty * \param dig_impl hash function for HMAC.
3840957b409SSimon J. Gerraty * \param mac_key HMAC key.
3850957b409SSimon J. Gerraty * \param mac_key_len HMAC key length (in bytes).
3860957b409SSimon J. Gerraty * \param mac_out_len HMAC output length (in bytes).
3870957b409SSimon J. Gerraty * \param iv initial IV (or `NULL`).
3880957b409SSimon J. Gerraty */
3890957b409SSimon J. Gerraty void (*init)(const br_sslrec_in_cbc_class **ctx,
3900957b409SSimon J. Gerraty const br_block_cbcdec_class *bc_impl,
3910957b409SSimon J. Gerraty const void *bc_key, size_t bc_key_len,
3920957b409SSimon J. Gerraty const br_hash_class *dig_impl,
3930957b409SSimon J. Gerraty const void *mac_key, size_t mac_key_len, size_t mac_out_len,
3940957b409SSimon J. Gerraty const void *iv);
3950957b409SSimon J. Gerraty };
3960957b409SSimon J. Gerraty
3970957b409SSimon J. Gerraty /**
3980957b409SSimon J. Gerraty * \brief Record encryption engine class, for CBC mode.
3990957b409SSimon J. Gerraty *
4000957b409SSimon J. Gerraty * This class type extends the encryption engine class with an
4010957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
4020957b409SSimon J. Gerraty * for CBC processing: block cipher implementation, block cipher key,
4030957b409SSimon J. Gerraty * HMAC parameters (hash function, key, MAC length), and IV. If the
4040957b409SSimon J. Gerraty * IV is `NULL`, then a per-record IV will be used (TLS 1.1+).
4050957b409SSimon J. Gerraty */
4060957b409SSimon J. Gerraty typedef struct br_sslrec_out_cbc_class_ br_sslrec_out_cbc_class;
4070957b409SSimon J. Gerraty struct br_sslrec_out_cbc_class_ {
4080957b409SSimon J. Gerraty /**
4090957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
4100957b409SSimon J. Gerraty */
4110957b409SSimon J. Gerraty br_sslrec_out_class inner;
4120957b409SSimon J. Gerraty
4130957b409SSimon J. Gerraty /**
4140957b409SSimon J. Gerraty * \brief Engine initialisation method.
4150957b409SSimon J. Gerraty *
4160957b409SSimon J. Gerraty * This method sets the vtable field in the context.
4170957b409SSimon J. Gerraty *
4180957b409SSimon J. Gerraty * \param ctx context to initialise.
4190957b409SSimon J. Gerraty * \param bc_impl block cipher implementation (CBC encryption).
4200957b409SSimon J. Gerraty * \param bc_key block cipher key.
4210957b409SSimon J. Gerraty * \param bc_key_len block cipher key length (in bytes).
4220957b409SSimon J. Gerraty * \param dig_impl hash function for HMAC.
4230957b409SSimon J. Gerraty * \param mac_key HMAC key.
4240957b409SSimon J. Gerraty * \param mac_key_len HMAC key length (in bytes).
4250957b409SSimon J. Gerraty * \param mac_out_len HMAC output length (in bytes).
4260957b409SSimon J. Gerraty * \param iv initial IV (or `NULL`).
4270957b409SSimon J. Gerraty */
4280957b409SSimon J. Gerraty void (*init)(const br_sslrec_out_cbc_class **ctx,
4290957b409SSimon J. Gerraty const br_block_cbcenc_class *bc_impl,
4300957b409SSimon J. Gerraty const void *bc_key, size_t bc_key_len,
4310957b409SSimon J. Gerraty const br_hash_class *dig_impl,
4320957b409SSimon J. Gerraty const void *mac_key, size_t mac_key_len, size_t mac_out_len,
4330957b409SSimon J. Gerraty const void *iv);
4340957b409SSimon J. Gerraty };
4350957b409SSimon J. Gerraty
4360957b409SSimon J. Gerraty /**
4370957b409SSimon J. Gerraty * \brief Context structure for decrypting incoming records with
4380957b409SSimon J. Gerraty * CBC + HMAC.
4390957b409SSimon J. Gerraty *
4400957b409SSimon J. Gerraty * The first field points to the vtable. The other fields are opaque
4410957b409SSimon J. Gerraty * and shall not be accessed directly.
4420957b409SSimon J. Gerraty */
4430957b409SSimon J. Gerraty typedef struct {
4440957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
4450957b409SSimon J. Gerraty const br_sslrec_in_cbc_class *vtable;
4460957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
4470957b409SSimon J. Gerraty uint64_t seq;
4480957b409SSimon J. Gerraty union {
4490957b409SSimon J. Gerraty const br_block_cbcdec_class *vtable;
4500957b409SSimon J. Gerraty br_aes_gen_cbcdec_keys aes;
4510957b409SSimon J. Gerraty br_des_gen_cbcdec_keys des;
4520957b409SSimon J. Gerraty } bc;
4530957b409SSimon J. Gerraty br_hmac_key_context mac;
4540957b409SSimon J. Gerraty size_t mac_len;
4550957b409SSimon J. Gerraty unsigned char iv[16];
4560957b409SSimon J. Gerraty int explicit_IV;
4570957b409SSimon J. Gerraty #endif
4580957b409SSimon J. Gerraty } br_sslrec_in_cbc_context;
4590957b409SSimon J. Gerraty
4600957b409SSimon J. Gerraty /**
4610957b409SSimon J. Gerraty * \brief Static, constant vtable for record decryption with CBC.
4620957b409SSimon J. Gerraty */
4630957b409SSimon J. Gerraty extern const br_sslrec_in_cbc_class br_sslrec_in_cbc_vtable;
4640957b409SSimon J. Gerraty
4650957b409SSimon J. Gerraty /**
4660957b409SSimon J. Gerraty * \brief Context structure for encrypting outgoing records with
4670957b409SSimon J. Gerraty * CBC + HMAC.
4680957b409SSimon J. Gerraty *
4690957b409SSimon J. Gerraty * The first field points to the vtable. The other fields are opaque
4700957b409SSimon J. Gerraty * and shall not be accessed directly.
4710957b409SSimon J. Gerraty */
4720957b409SSimon J. Gerraty typedef struct {
4730957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
4740957b409SSimon J. Gerraty const br_sslrec_out_cbc_class *vtable;
4750957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
4760957b409SSimon J. Gerraty uint64_t seq;
4770957b409SSimon J. Gerraty union {
4780957b409SSimon J. Gerraty const br_block_cbcenc_class *vtable;
4790957b409SSimon J. Gerraty br_aes_gen_cbcenc_keys aes;
4800957b409SSimon J. Gerraty br_des_gen_cbcenc_keys des;
4810957b409SSimon J. Gerraty } bc;
4820957b409SSimon J. Gerraty br_hmac_key_context mac;
4830957b409SSimon J. Gerraty size_t mac_len;
4840957b409SSimon J. Gerraty unsigned char iv[16];
4850957b409SSimon J. Gerraty int explicit_IV;
4860957b409SSimon J. Gerraty #endif
4870957b409SSimon J. Gerraty } br_sslrec_out_cbc_context;
4880957b409SSimon J. Gerraty
4890957b409SSimon J. Gerraty /**
4900957b409SSimon J. Gerraty * \brief Static, constant vtable for record encryption with CBC.
4910957b409SSimon J. Gerraty */
4920957b409SSimon J. Gerraty extern const br_sslrec_out_cbc_class br_sslrec_out_cbc_vtable;
4930957b409SSimon J. Gerraty
4940957b409SSimon J. Gerraty /* ===================================================================== */
4950957b409SSimon J. Gerraty
4960957b409SSimon J. Gerraty /**
4970957b409SSimon J. Gerraty * \brief Record decryption engine class, for GCM mode.
4980957b409SSimon J. Gerraty *
4990957b409SSimon J. Gerraty * This class type extends the decryption engine class with an
5000957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
5010957b409SSimon J. Gerraty * for GCM processing: block cipher implementation, block cipher key,
5020957b409SSimon J. Gerraty * GHASH implementation, and 4-byte IV.
5030957b409SSimon J. Gerraty */
5040957b409SSimon J. Gerraty typedef struct br_sslrec_in_gcm_class_ br_sslrec_in_gcm_class;
5050957b409SSimon J. Gerraty struct br_sslrec_in_gcm_class_ {
5060957b409SSimon J. Gerraty /**
5070957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
5080957b409SSimon J. Gerraty */
5090957b409SSimon J. Gerraty br_sslrec_in_class inner;
5100957b409SSimon J. Gerraty
5110957b409SSimon J. Gerraty /**
5120957b409SSimon J. Gerraty * \brief Engine initialisation method.
5130957b409SSimon J. Gerraty *
5140957b409SSimon J. Gerraty * This method sets the vtable field in the context.
5150957b409SSimon J. Gerraty *
5160957b409SSimon J. Gerraty * \param ctx context to initialise.
5170957b409SSimon J. Gerraty * \param bc_impl block cipher implementation (CTR).
5180957b409SSimon J. Gerraty * \param key block cipher key.
5190957b409SSimon J. Gerraty * \param key_len block cipher key length (in bytes).
5200957b409SSimon J. Gerraty * \param gh_impl GHASH implementation.
5210957b409SSimon J. Gerraty * \param iv static IV (4 bytes).
5220957b409SSimon J. Gerraty */
5230957b409SSimon J. Gerraty void (*init)(const br_sslrec_in_gcm_class **ctx,
5240957b409SSimon J. Gerraty const br_block_ctr_class *bc_impl,
5250957b409SSimon J. Gerraty const void *key, size_t key_len,
5260957b409SSimon J. Gerraty br_ghash gh_impl,
5270957b409SSimon J. Gerraty const void *iv);
5280957b409SSimon J. Gerraty };
5290957b409SSimon J. Gerraty
5300957b409SSimon J. Gerraty /**
5310957b409SSimon J. Gerraty * \brief Record encryption engine class, for GCM mode.
5320957b409SSimon J. Gerraty *
5330957b409SSimon J. Gerraty * This class type extends the encryption engine class with an
5340957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
5350957b409SSimon J. Gerraty * for GCM processing: block cipher implementation, block cipher key,
5360957b409SSimon J. Gerraty * GHASH implementation, and 4-byte IV.
5370957b409SSimon J. Gerraty */
5380957b409SSimon J. Gerraty typedef struct br_sslrec_out_gcm_class_ br_sslrec_out_gcm_class;
5390957b409SSimon J. Gerraty struct br_sslrec_out_gcm_class_ {
5400957b409SSimon J. Gerraty /**
5410957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
5420957b409SSimon J. Gerraty */
5430957b409SSimon J. Gerraty br_sslrec_out_class inner;
5440957b409SSimon J. Gerraty
5450957b409SSimon J. Gerraty /**
5460957b409SSimon J. Gerraty * \brief Engine initialisation method.
5470957b409SSimon J. Gerraty *
5480957b409SSimon J. Gerraty * This method sets the vtable field in the context.
5490957b409SSimon J. Gerraty *
5500957b409SSimon J. Gerraty * \param ctx context to initialise.
5510957b409SSimon J. Gerraty * \param bc_impl block cipher implementation (CTR).
5520957b409SSimon J. Gerraty * \param key block cipher key.
5530957b409SSimon J. Gerraty * \param key_len block cipher key length (in bytes).
5540957b409SSimon J. Gerraty * \param gh_impl GHASH implementation.
5550957b409SSimon J. Gerraty * \param iv static IV (4 bytes).
5560957b409SSimon J. Gerraty */
5570957b409SSimon J. Gerraty void (*init)(const br_sslrec_out_gcm_class **ctx,
5580957b409SSimon J. Gerraty const br_block_ctr_class *bc_impl,
5590957b409SSimon J. Gerraty const void *key, size_t key_len,
5600957b409SSimon J. Gerraty br_ghash gh_impl,
5610957b409SSimon J. Gerraty const void *iv);
5620957b409SSimon J. Gerraty };
5630957b409SSimon J. Gerraty
5640957b409SSimon J. Gerraty /**
5650957b409SSimon J. Gerraty * \brief Context structure for processing records with GCM.
5660957b409SSimon J. Gerraty *
5670957b409SSimon J. Gerraty * The same context structure is used for encrypting and decrypting.
5680957b409SSimon J. Gerraty *
5690957b409SSimon J. Gerraty * The first field points to the vtable. The other fields are opaque
5700957b409SSimon J. Gerraty * and shall not be accessed directly.
5710957b409SSimon J. Gerraty */
5720957b409SSimon J. Gerraty typedef struct {
5730957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
5740957b409SSimon J. Gerraty union {
5750957b409SSimon J. Gerraty const void *gen;
5760957b409SSimon J. Gerraty const br_sslrec_in_gcm_class *in;
5770957b409SSimon J. Gerraty const br_sslrec_out_gcm_class *out;
5780957b409SSimon J. Gerraty } vtable;
5790957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
5800957b409SSimon J. Gerraty uint64_t seq;
5810957b409SSimon J. Gerraty union {
5820957b409SSimon J. Gerraty const br_block_ctr_class *vtable;
5830957b409SSimon J. Gerraty br_aes_gen_ctr_keys aes;
5840957b409SSimon J. Gerraty } bc;
5850957b409SSimon J. Gerraty br_ghash gh;
5860957b409SSimon J. Gerraty unsigned char iv[4];
5870957b409SSimon J. Gerraty unsigned char h[16];
5880957b409SSimon J. Gerraty #endif
5890957b409SSimon J. Gerraty } br_sslrec_gcm_context;
5900957b409SSimon J. Gerraty
5910957b409SSimon J. Gerraty /**
5920957b409SSimon J. Gerraty * \brief Static, constant vtable for record decryption with GCM.
5930957b409SSimon J. Gerraty */
5940957b409SSimon J. Gerraty extern const br_sslrec_in_gcm_class br_sslrec_in_gcm_vtable;
5950957b409SSimon J. Gerraty
5960957b409SSimon J. Gerraty /**
5970957b409SSimon J. Gerraty * \brief Static, constant vtable for record encryption with GCM.
5980957b409SSimon J. Gerraty */
5990957b409SSimon J. Gerraty extern const br_sslrec_out_gcm_class br_sslrec_out_gcm_vtable;
6000957b409SSimon J. Gerraty
6010957b409SSimon J. Gerraty /* ===================================================================== */
6020957b409SSimon J. Gerraty
6030957b409SSimon J. Gerraty /**
6040957b409SSimon J. Gerraty * \brief Record decryption engine class, for ChaCha20+Poly1305.
6050957b409SSimon J. Gerraty *
6060957b409SSimon J. Gerraty * This class type extends the decryption engine class with an
6070957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
6080957b409SSimon J. Gerraty * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
6090957b409SSimon J. Gerraty * Poly1305 implementation, key, and 12-byte IV.
6100957b409SSimon J. Gerraty */
6110957b409SSimon J. Gerraty typedef struct br_sslrec_in_chapol_class_ br_sslrec_in_chapol_class;
6120957b409SSimon J. Gerraty struct br_sslrec_in_chapol_class_ {
6130957b409SSimon J. Gerraty /**
6140957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
6150957b409SSimon J. Gerraty */
6160957b409SSimon J. Gerraty br_sslrec_in_class inner;
6170957b409SSimon J. Gerraty
6180957b409SSimon J. Gerraty /**
6190957b409SSimon J. Gerraty * \brief Engine initialisation method.
6200957b409SSimon J. Gerraty *
6210957b409SSimon J. Gerraty * This method sets the vtable field in the context.
6220957b409SSimon J. Gerraty *
6230957b409SSimon J. Gerraty * \param ctx context to initialise.
6240957b409SSimon J. Gerraty * \param ichacha ChaCha20 implementation.
6250957b409SSimon J. Gerraty * \param ipoly Poly1305 implementation.
6260957b409SSimon J. Gerraty * \param key secret key (32 bytes).
6270957b409SSimon J. Gerraty * \param iv static IV (12 bytes).
6280957b409SSimon J. Gerraty */
6290957b409SSimon J. Gerraty void (*init)(const br_sslrec_in_chapol_class **ctx,
6300957b409SSimon J. Gerraty br_chacha20_run ichacha,
6310957b409SSimon J. Gerraty br_poly1305_run ipoly,
6320957b409SSimon J. Gerraty const void *key, const void *iv);
6330957b409SSimon J. Gerraty };
6340957b409SSimon J. Gerraty
6350957b409SSimon J. Gerraty /**
6360957b409SSimon J. Gerraty * \brief Record encryption engine class, for ChaCha20+Poly1305.
6370957b409SSimon J. Gerraty *
6380957b409SSimon J. Gerraty * This class type extends the encryption engine class with an
6390957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
6400957b409SSimon J. Gerraty * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
6410957b409SSimon J. Gerraty * Poly1305 implementation, key, and 12-byte IV.
6420957b409SSimon J. Gerraty */
6430957b409SSimon J. Gerraty typedef struct br_sslrec_out_chapol_class_ br_sslrec_out_chapol_class;
6440957b409SSimon J. Gerraty struct br_sslrec_out_chapol_class_ {
6450957b409SSimon J. Gerraty /**
6460957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
6470957b409SSimon J. Gerraty */
6480957b409SSimon J. Gerraty br_sslrec_out_class inner;
6490957b409SSimon J. Gerraty
6500957b409SSimon J. Gerraty /**
6510957b409SSimon J. Gerraty * \brief Engine initialisation method.
6520957b409SSimon J. Gerraty *
6530957b409SSimon J. Gerraty * This method sets the vtable field in the context.
6540957b409SSimon J. Gerraty *
6550957b409SSimon J. Gerraty * \param ctx context to initialise.
6560957b409SSimon J. Gerraty * \param ichacha ChaCha20 implementation.
6570957b409SSimon J. Gerraty * \param ipoly Poly1305 implementation.
6580957b409SSimon J. Gerraty * \param key secret key (32 bytes).
6590957b409SSimon J. Gerraty * \param iv static IV (12 bytes).
6600957b409SSimon J. Gerraty */
6610957b409SSimon J. Gerraty void (*init)(const br_sslrec_out_chapol_class **ctx,
6620957b409SSimon J. Gerraty br_chacha20_run ichacha,
6630957b409SSimon J. Gerraty br_poly1305_run ipoly,
6640957b409SSimon J. Gerraty const void *key, const void *iv);
6650957b409SSimon J. Gerraty };
6660957b409SSimon J. Gerraty
6670957b409SSimon J. Gerraty /**
6680957b409SSimon J. Gerraty * \brief Context structure for processing records with ChaCha20+Poly1305.
6690957b409SSimon J. Gerraty *
6700957b409SSimon J. Gerraty * The same context structure is used for encrypting and decrypting.
6710957b409SSimon J. Gerraty *
6720957b409SSimon J. Gerraty * The first field points to the vtable. The other fields are opaque
6730957b409SSimon J. Gerraty * and shall not be accessed directly.
6740957b409SSimon J. Gerraty */
6750957b409SSimon J. Gerraty typedef struct {
6760957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
6770957b409SSimon J. Gerraty union {
6780957b409SSimon J. Gerraty const void *gen;
6790957b409SSimon J. Gerraty const br_sslrec_in_chapol_class *in;
6800957b409SSimon J. Gerraty const br_sslrec_out_chapol_class *out;
6810957b409SSimon J. Gerraty } vtable;
6820957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
6830957b409SSimon J. Gerraty uint64_t seq;
6840957b409SSimon J. Gerraty unsigned char key[32];
6850957b409SSimon J. Gerraty unsigned char iv[12];
6860957b409SSimon J. Gerraty br_chacha20_run ichacha;
6870957b409SSimon J. Gerraty br_poly1305_run ipoly;
6880957b409SSimon J. Gerraty #endif
6890957b409SSimon J. Gerraty } br_sslrec_chapol_context;
6900957b409SSimon J. Gerraty
6910957b409SSimon J. Gerraty /**
6920957b409SSimon J. Gerraty * \brief Static, constant vtable for record decryption with ChaCha20+Poly1305.
6930957b409SSimon J. Gerraty */
6940957b409SSimon J. Gerraty extern const br_sslrec_in_chapol_class br_sslrec_in_chapol_vtable;
6950957b409SSimon J. Gerraty
6960957b409SSimon J. Gerraty /**
6970957b409SSimon J. Gerraty * \brief Static, constant vtable for record encryption with ChaCha20+Poly1305.
6980957b409SSimon J. Gerraty */
6990957b409SSimon J. Gerraty extern const br_sslrec_out_chapol_class br_sslrec_out_chapol_vtable;
7000957b409SSimon J. Gerraty
7010957b409SSimon J. Gerraty /* ===================================================================== */
7020957b409SSimon J. Gerraty
7030957b409SSimon J. Gerraty /**
7040957b409SSimon J. Gerraty * \brief Record decryption engine class, for CCM mode.
7050957b409SSimon J. Gerraty *
7060957b409SSimon J. Gerraty * This class type extends the decryption engine class with an
7070957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
7080957b409SSimon J. Gerraty * for CCM processing: block cipher implementation, block cipher key,
7090957b409SSimon J. Gerraty * and 4-byte IV.
7100957b409SSimon J. Gerraty */
7110957b409SSimon J. Gerraty typedef struct br_sslrec_in_ccm_class_ br_sslrec_in_ccm_class;
7120957b409SSimon J. Gerraty struct br_sslrec_in_ccm_class_ {
7130957b409SSimon J. Gerraty /**
7140957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
7150957b409SSimon J. Gerraty */
7160957b409SSimon J. Gerraty br_sslrec_in_class inner;
7170957b409SSimon J. Gerraty
7180957b409SSimon J. Gerraty /**
7190957b409SSimon J. Gerraty * \brief Engine initialisation method.
7200957b409SSimon J. Gerraty *
7210957b409SSimon J. Gerraty * This method sets the vtable field in the context.
7220957b409SSimon J. Gerraty *
7230957b409SSimon J. Gerraty * \param ctx context to initialise.
7240957b409SSimon J. Gerraty * \param bc_impl block cipher implementation (CTR+CBC).
7250957b409SSimon J. Gerraty * \param key block cipher key.
7260957b409SSimon J. Gerraty * \param key_len block cipher key length (in bytes).
7270957b409SSimon J. Gerraty * \param iv static IV (4 bytes).
7280957b409SSimon J. Gerraty * \param tag_len tag length (in bytes)
7290957b409SSimon J. Gerraty */
7300957b409SSimon J. Gerraty void (*init)(const br_sslrec_in_ccm_class **ctx,
7310957b409SSimon J. Gerraty const br_block_ctrcbc_class *bc_impl,
7320957b409SSimon J. Gerraty const void *key, size_t key_len,
7330957b409SSimon J. Gerraty const void *iv, size_t tag_len);
7340957b409SSimon J. Gerraty };
7350957b409SSimon J. Gerraty
7360957b409SSimon J. Gerraty /**
7370957b409SSimon J. Gerraty * \brief Record encryption engine class, for CCM mode.
7380957b409SSimon J. Gerraty *
7390957b409SSimon J. Gerraty * This class type extends the encryption engine class with an
7400957b409SSimon J. Gerraty * initialisation method that receives the parameters needed
7410957b409SSimon J. Gerraty * for CCM processing: block cipher implementation, block cipher key,
7420957b409SSimon J. Gerraty * and 4-byte IV.
7430957b409SSimon J. Gerraty */
7440957b409SSimon J. Gerraty typedef struct br_sslrec_out_ccm_class_ br_sslrec_out_ccm_class;
7450957b409SSimon J. Gerraty struct br_sslrec_out_ccm_class_ {
7460957b409SSimon J. Gerraty /**
7470957b409SSimon J. Gerraty * \brief Superclass, as first vtable field.
7480957b409SSimon J. Gerraty */
7490957b409SSimon J. Gerraty br_sslrec_out_class inner;
7500957b409SSimon J. Gerraty
7510957b409SSimon J. Gerraty /**
7520957b409SSimon J. Gerraty * \brief Engine initialisation method.
7530957b409SSimon J. Gerraty *
7540957b409SSimon J. Gerraty * This method sets the vtable field in the context.
7550957b409SSimon J. Gerraty *
7560957b409SSimon J. Gerraty * \param ctx context to initialise.
7570957b409SSimon J. Gerraty * \param bc_impl block cipher implementation (CTR+CBC).
7580957b409SSimon J. Gerraty * \param key block cipher key.
7590957b409SSimon J. Gerraty * \param key_len block cipher key length (in bytes).
7600957b409SSimon J. Gerraty * \param iv static IV (4 bytes).
7610957b409SSimon J. Gerraty * \param tag_len tag length (in bytes)
7620957b409SSimon J. Gerraty */
7630957b409SSimon J. Gerraty void (*init)(const br_sslrec_out_ccm_class **ctx,
7640957b409SSimon J. Gerraty const br_block_ctrcbc_class *bc_impl,
7650957b409SSimon J. Gerraty const void *key, size_t key_len,
7660957b409SSimon J. Gerraty const void *iv, size_t tag_len);
7670957b409SSimon J. Gerraty };
7680957b409SSimon J. Gerraty
7690957b409SSimon J. Gerraty /**
7700957b409SSimon J. Gerraty * \brief Context structure for processing records with CCM.
7710957b409SSimon J. Gerraty *
7720957b409SSimon J. Gerraty * The same context structure is used for encrypting and decrypting.
7730957b409SSimon J. Gerraty *
7740957b409SSimon J. Gerraty * The first field points to the vtable. The other fields are opaque
7750957b409SSimon J. Gerraty * and shall not be accessed directly.
7760957b409SSimon J. Gerraty */
7770957b409SSimon J. Gerraty typedef struct {
7780957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
7790957b409SSimon J. Gerraty union {
7800957b409SSimon J. Gerraty const void *gen;
7810957b409SSimon J. Gerraty const br_sslrec_in_ccm_class *in;
7820957b409SSimon J. Gerraty const br_sslrec_out_ccm_class *out;
7830957b409SSimon J. Gerraty } vtable;
7840957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
7850957b409SSimon J. Gerraty uint64_t seq;
7860957b409SSimon J. Gerraty union {
7870957b409SSimon J. Gerraty const br_block_ctrcbc_class *vtable;
7880957b409SSimon J. Gerraty br_aes_gen_ctrcbc_keys aes;
7890957b409SSimon J. Gerraty } bc;
7900957b409SSimon J. Gerraty unsigned char iv[4];
7910957b409SSimon J. Gerraty size_t tag_len;
7920957b409SSimon J. Gerraty #endif
7930957b409SSimon J. Gerraty } br_sslrec_ccm_context;
7940957b409SSimon J. Gerraty
7950957b409SSimon J. Gerraty /**
7960957b409SSimon J. Gerraty * \brief Static, constant vtable for record decryption with CCM.
7970957b409SSimon J. Gerraty */
7980957b409SSimon J. Gerraty extern const br_sslrec_in_ccm_class br_sslrec_in_ccm_vtable;
7990957b409SSimon J. Gerraty
8000957b409SSimon J. Gerraty /**
8010957b409SSimon J. Gerraty * \brief Static, constant vtable for record encryption with CCM.
8020957b409SSimon J. Gerraty */
8030957b409SSimon J. Gerraty extern const br_sslrec_out_ccm_class br_sslrec_out_ccm_vtable;
8040957b409SSimon J. Gerraty
8050957b409SSimon J. Gerraty /* ===================================================================== */
8060957b409SSimon J. Gerraty
8070957b409SSimon J. Gerraty /**
8080957b409SSimon J. Gerraty * \brief Type for session parameters, to be saved for session resumption.
8090957b409SSimon J. Gerraty */
8100957b409SSimon J. Gerraty typedef struct {
8110957b409SSimon J. Gerraty /** \brief Session ID buffer. */
8120957b409SSimon J. Gerraty unsigned char session_id[32];
8130957b409SSimon J. Gerraty /** \brief Session ID length (in bytes, at most 32). */
8140957b409SSimon J. Gerraty unsigned char session_id_len;
8150957b409SSimon J. Gerraty /** \brief Protocol version. */
8160957b409SSimon J. Gerraty uint16_t version;
8170957b409SSimon J. Gerraty /** \brief Cipher suite. */
8180957b409SSimon J. Gerraty uint16_t cipher_suite;
8190957b409SSimon J. Gerraty /** \brief Master secret. */
8200957b409SSimon J. Gerraty unsigned char master_secret[48];
8210957b409SSimon J. Gerraty } br_ssl_session_parameters;
8220957b409SSimon J. Gerraty
8230957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
8240957b409SSimon J. Gerraty /*
8250957b409SSimon J. Gerraty * Maximum number of cipher suites supported by a client or server.
8260957b409SSimon J. Gerraty */
8270957b409SSimon J. Gerraty #define BR_MAX_CIPHER_SUITES 48
8280957b409SSimon J. Gerraty #endif
8290957b409SSimon J. Gerraty
8300957b409SSimon J. Gerraty /**
8310957b409SSimon J. Gerraty * \brief Context structure for SSL engine.
8320957b409SSimon J. Gerraty *
8330957b409SSimon J. Gerraty * This strucuture is common to the client and server; both the client
8340957b409SSimon J. Gerraty * context (`br_ssl_client_context`) and the server context
8350957b409SSimon J. Gerraty * (`br_ssl_server_context`) include a `br_ssl_engine_context` as their
8360957b409SSimon J. Gerraty * first field.
8370957b409SSimon J. Gerraty *
8380957b409SSimon J. Gerraty * The engine context manages records, including alerts, closures, and
8390957b409SSimon J. Gerraty * transitions to new encryption/MAC algorithms. Processing of handshake
8400957b409SSimon J. Gerraty * records is delegated to externally provided code. This structure
8410957b409SSimon J. Gerraty * should not be used directly.
8420957b409SSimon J. Gerraty *
8430957b409SSimon J. Gerraty * Structure contents are opaque and shall not be accessed directly.
8440957b409SSimon J. Gerraty */
8450957b409SSimon J. Gerraty typedef struct {
8460957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
8470957b409SSimon J. Gerraty /*
8480957b409SSimon J. Gerraty * The error code. When non-zero, then the state is "failed" and
8490957b409SSimon J. Gerraty * no I/O may occur until reset.
8500957b409SSimon J. Gerraty */
8510957b409SSimon J. Gerraty int err;
8520957b409SSimon J. Gerraty
8530957b409SSimon J. Gerraty /*
8540957b409SSimon J. Gerraty * Configured I/O buffers. They are either disjoint, or identical.
8550957b409SSimon J. Gerraty */
8560957b409SSimon J. Gerraty unsigned char *ibuf, *obuf;
8570957b409SSimon J. Gerraty size_t ibuf_len, obuf_len;
8580957b409SSimon J. Gerraty
8590957b409SSimon J. Gerraty /*
8600957b409SSimon J. Gerraty * Maximum fragment length applies to outgoing records; incoming
8610957b409SSimon J. Gerraty * records can be processed as long as they fit in the input
8620957b409SSimon J. Gerraty * buffer. It is guaranteed that incoming records at least as big
8630957b409SSimon J. Gerraty * as max_frag_len can be processed.
8640957b409SSimon J. Gerraty */
8650957b409SSimon J. Gerraty uint16_t max_frag_len;
8660957b409SSimon J. Gerraty unsigned char log_max_frag_len;
8670957b409SSimon J. Gerraty unsigned char peer_log_max_frag_len;
8680957b409SSimon J. Gerraty
8690957b409SSimon J. Gerraty /*
8700957b409SSimon J. Gerraty * Buffering management registers.
8710957b409SSimon J. Gerraty */
8720957b409SSimon J. Gerraty size_t ixa, ixb, ixc;
8730957b409SSimon J. Gerraty size_t oxa, oxb, oxc;
8740957b409SSimon J. Gerraty unsigned char iomode;
8750957b409SSimon J. Gerraty unsigned char incrypt;
8760957b409SSimon J. Gerraty
8770957b409SSimon J. Gerraty /*
8780957b409SSimon J. Gerraty * Shutdown flag: when set to non-zero, incoming record bytes
8790957b409SSimon J. Gerraty * will not be accepted anymore. This is used after a close_notify
8800957b409SSimon J. Gerraty * has been received: afterwards, the engine no longer claims that
8810957b409SSimon J. Gerraty * it could receive bytes from the transport medium.
8820957b409SSimon J. Gerraty */
8830957b409SSimon J. Gerraty unsigned char shutdown_recv;
8840957b409SSimon J. Gerraty
8850957b409SSimon J. Gerraty /*
8860957b409SSimon J. Gerraty * 'record_type_in' is set to the incoming record type when the
8870957b409SSimon J. Gerraty * record header has been received.
8880957b409SSimon J. Gerraty * 'record_type_out' is used to make the next outgoing record
8890957b409SSimon J. Gerraty * header when it is ready to go.
8900957b409SSimon J. Gerraty */
8910957b409SSimon J. Gerraty unsigned char record_type_in, record_type_out;
8920957b409SSimon J. Gerraty
8930957b409SSimon J. Gerraty /*
8940957b409SSimon J. Gerraty * When a record is received, its version is extracted:
8950957b409SSimon J. Gerraty * -- if 'version_in' is 0, then it is set to the received version;
8960957b409SSimon J. Gerraty * -- otherwise, if the received version is not identical to
8970957b409SSimon J. Gerraty * the 'version_in' contents, then a failure is reported.
8980957b409SSimon J. Gerraty *
8990957b409SSimon J. Gerraty * This implements the SSL requirement that all records shall
9000957b409SSimon J. Gerraty * use the negotiated protocol version, once decided (in the
9010957b409SSimon J. Gerraty * ServerHello). It is up to the handshake handler to adjust this
9020957b409SSimon J. Gerraty * field when necessary.
9030957b409SSimon J. Gerraty */
9040957b409SSimon J. Gerraty uint16_t version_in;
9050957b409SSimon J. Gerraty
9060957b409SSimon J. Gerraty /*
9070957b409SSimon J. Gerraty * 'version_out' is used when the next outgoing record is ready
9080957b409SSimon J. Gerraty * to go.
9090957b409SSimon J. Gerraty */
9100957b409SSimon J. Gerraty uint16_t version_out;
9110957b409SSimon J. Gerraty
9120957b409SSimon J. Gerraty /*
9130957b409SSimon J. Gerraty * Record handler contexts.
9140957b409SSimon J. Gerraty */
9150957b409SSimon J. Gerraty union {
9160957b409SSimon J. Gerraty const br_sslrec_in_class *vtable;
9170957b409SSimon J. Gerraty br_sslrec_in_cbc_context cbc;
9180957b409SSimon J. Gerraty br_sslrec_gcm_context gcm;
9190957b409SSimon J. Gerraty br_sslrec_chapol_context chapol;
9200957b409SSimon J. Gerraty br_sslrec_ccm_context ccm;
9210957b409SSimon J. Gerraty } in;
9220957b409SSimon J. Gerraty union {
9230957b409SSimon J. Gerraty const br_sslrec_out_class *vtable;
9240957b409SSimon J. Gerraty br_sslrec_out_clear_context clear;
9250957b409SSimon J. Gerraty br_sslrec_out_cbc_context cbc;
9260957b409SSimon J. Gerraty br_sslrec_gcm_context gcm;
9270957b409SSimon J. Gerraty br_sslrec_chapol_context chapol;
9280957b409SSimon J. Gerraty br_sslrec_ccm_context ccm;
9290957b409SSimon J. Gerraty } out;
9300957b409SSimon J. Gerraty
9310957b409SSimon J. Gerraty /*
9320957b409SSimon J. Gerraty * The "application data" flag. Value:
9330957b409SSimon J. Gerraty * 0 handshake is in process, no application data acceptable
9340957b409SSimon J. Gerraty * 1 application data can be sent and received
9350957b409SSimon J. Gerraty * 2 closing, no application data can be sent, but some
9360957b409SSimon J. Gerraty * can still be received (and discarded)
9370957b409SSimon J. Gerraty */
9380957b409SSimon J. Gerraty unsigned char application_data;
9390957b409SSimon J. Gerraty
9400957b409SSimon J. Gerraty /*
9410957b409SSimon J. Gerraty * Context RNG.
9420957b409SSimon J. Gerraty *
9430957b409SSimon J. Gerraty * rng_init_done is initially 0. It is set to 1 when the
9440957b409SSimon J. Gerraty * basic structure of the RNG is set, and 2 when some
9450957b409SSimon J. Gerraty * entropy has been pushed in. The value 2 marks the RNG
9460957b409SSimon J. Gerraty * as "properly seeded".
9470957b409SSimon J. Gerraty *
9480957b409SSimon J. Gerraty * rng_os_rand_done is initially 0. It is set to 1 when
9490957b409SSimon J. Gerraty * some seeding from the OS or hardware has been attempted.
9500957b409SSimon J. Gerraty */
9510957b409SSimon J. Gerraty br_hmac_drbg_context rng;
9520957b409SSimon J. Gerraty int rng_init_done;
9530957b409SSimon J. Gerraty int rng_os_rand_done;
9540957b409SSimon J. Gerraty
9550957b409SSimon J. Gerraty /*
9560957b409SSimon J. Gerraty * Supported minimum and maximum versions, and cipher suites.
9570957b409SSimon J. Gerraty */
9580957b409SSimon J. Gerraty uint16_t version_min;
9590957b409SSimon J. Gerraty uint16_t version_max;
9600957b409SSimon J. Gerraty uint16_t suites_buf[BR_MAX_CIPHER_SUITES];
9610957b409SSimon J. Gerraty unsigned char suites_num;
9620957b409SSimon J. Gerraty
9630957b409SSimon J. Gerraty /*
9640957b409SSimon J. Gerraty * For clients, the server name to send as a SNI extension. For
9650957b409SSimon J. Gerraty * servers, the name received in the SNI extension (if any).
9660957b409SSimon J. Gerraty */
9670957b409SSimon J. Gerraty char server_name[256];
9680957b409SSimon J. Gerraty
9690957b409SSimon J. Gerraty /*
9700957b409SSimon J. Gerraty * "Security parameters". These are filled by the handshake
9710957b409SSimon J. Gerraty * handler, and used when switching encryption state.
9720957b409SSimon J. Gerraty */
9730957b409SSimon J. Gerraty unsigned char client_random[32];
9740957b409SSimon J. Gerraty unsigned char server_random[32];
9750957b409SSimon J. Gerraty br_ssl_session_parameters session;
9760957b409SSimon J. Gerraty
9770957b409SSimon J. Gerraty /*
9780957b409SSimon J. Gerraty * ECDHE elements: curve and point from the peer. The server also
9790957b409SSimon J. Gerraty * uses that buffer for the point to send to the client.
9800957b409SSimon J. Gerraty */
9810957b409SSimon J. Gerraty unsigned char ecdhe_curve;
9820957b409SSimon J. Gerraty unsigned char ecdhe_point[133];
9830957b409SSimon J. Gerraty unsigned char ecdhe_point_len;
9840957b409SSimon J. Gerraty
9850957b409SSimon J. Gerraty /*
9860957b409SSimon J. Gerraty * Secure renegotiation (RFC 5746): 'reneg' can be:
9870957b409SSimon J. Gerraty * 0 first handshake (server support is not known)
9880957b409SSimon J. Gerraty * 1 peer does not support secure renegotiation
9890957b409SSimon J. Gerraty * 2 peer supports secure renegotiation
9900957b409SSimon J. Gerraty *
9910957b409SSimon J. Gerraty * The saved_finished buffer contains the client and the
9920957b409SSimon J. Gerraty * server "Finished" values from the last handshake, in
9930957b409SSimon J. Gerraty * that order (12 bytes each).
9940957b409SSimon J. Gerraty */
9950957b409SSimon J. Gerraty unsigned char reneg;
9960957b409SSimon J. Gerraty unsigned char saved_finished[24];
9970957b409SSimon J. Gerraty
9980957b409SSimon J. Gerraty /*
9990957b409SSimon J. Gerraty * Behavioural flags.
10000957b409SSimon J. Gerraty */
10010957b409SSimon J. Gerraty uint32_t flags;
10020957b409SSimon J. Gerraty
10030957b409SSimon J. Gerraty /*
10040957b409SSimon J. Gerraty * Context variables for the handshake processor. The 'pad' must
10050957b409SSimon J. Gerraty * be large enough to accommodate an RSA-encrypted pre-master
10060957b409SSimon J. Gerraty * secret, or an RSA signature; since we want to support up to
10070957b409SSimon J. Gerraty * RSA-4096, this means at least 512 bytes. (Other pad usages
10080957b409SSimon J. Gerraty * require its length to be at least 256.)
10090957b409SSimon J. Gerraty */
10100957b409SSimon J. Gerraty struct {
10110957b409SSimon J. Gerraty uint32_t *dp;
10120957b409SSimon J. Gerraty uint32_t *rp;
10130957b409SSimon J. Gerraty const unsigned char *ip;
10140957b409SSimon J. Gerraty } cpu;
10150957b409SSimon J. Gerraty uint32_t dp_stack[32];
10160957b409SSimon J. Gerraty uint32_t rp_stack[32];
10170957b409SSimon J. Gerraty unsigned char pad[512];
10180957b409SSimon J. Gerraty unsigned char *hbuf_in, *hbuf_out, *saved_hbuf_out;
10190957b409SSimon J. Gerraty size_t hlen_in, hlen_out;
10200957b409SSimon J. Gerraty void (*hsrun)(void *ctx);
10210957b409SSimon J. Gerraty
10220957b409SSimon J. Gerraty /*
10230957b409SSimon J. Gerraty * The 'action' value communicates OOB information between the
10240957b409SSimon J. Gerraty * engine and the handshake processor.
10250957b409SSimon J. Gerraty *
10260957b409SSimon J. Gerraty * From the engine:
10270957b409SSimon J. Gerraty * 0 invocation triggered by I/O
10280957b409SSimon J. Gerraty * 1 invocation triggered by explicit close
10290957b409SSimon J. Gerraty * 2 invocation triggered by explicit renegotiation
10300957b409SSimon J. Gerraty */
10310957b409SSimon J. Gerraty unsigned char action;
10320957b409SSimon J. Gerraty
10330957b409SSimon J. Gerraty /*
10340957b409SSimon J. Gerraty * State for alert messages. Value is either 0, or the value of
10350957b409SSimon J. Gerraty * the alert level byte (level is either 1 for warning, or 2 for
10360957b409SSimon J. Gerraty * fatal; we convert all other values to 'fatal').
10370957b409SSimon J. Gerraty */
10380957b409SSimon J. Gerraty unsigned char alert;
10390957b409SSimon J. Gerraty
10400957b409SSimon J. Gerraty /*
10410957b409SSimon J. Gerraty * Closure flags. This flag is set when a close_notify has been
10420957b409SSimon J. Gerraty * received from the peer.
10430957b409SSimon J. Gerraty */
10440957b409SSimon J. Gerraty unsigned char close_received;
10450957b409SSimon J. Gerraty
10460957b409SSimon J. Gerraty /*
10470957b409SSimon J. Gerraty * Multi-hasher for the handshake messages. The handshake handler
10480957b409SSimon J. Gerraty * is responsible for resetting it when appropriate.
10490957b409SSimon J. Gerraty */
10500957b409SSimon J. Gerraty br_multihash_context mhash;
10510957b409SSimon J. Gerraty
10520957b409SSimon J. Gerraty /*
10530957b409SSimon J. Gerraty * Pointer to the X.509 engine. The engine is supposed to be
10540957b409SSimon J. Gerraty * already initialized. It is used to validate the peer's
10550957b409SSimon J. Gerraty * certificate.
10560957b409SSimon J. Gerraty */
10570957b409SSimon J. Gerraty const br_x509_class **x509ctx;
10580957b409SSimon J. Gerraty
10590957b409SSimon J. Gerraty /*
10600957b409SSimon J. Gerraty * Certificate chain to send. This is used by both client and
10610957b409SSimon J. Gerraty * server, when they send their respective Certificate messages.
10620957b409SSimon J. Gerraty * If chain_len is 0, then chain may be NULL.
10630957b409SSimon J. Gerraty */
10640957b409SSimon J. Gerraty const br_x509_certificate *chain;
10650957b409SSimon J. Gerraty size_t chain_len;
10660957b409SSimon J. Gerraty const unsigned char *cert_cur;
10670957b409SSimon J. Gerraty size_t cert_len;
10680957b409SSimon J. Gerraty
10690957b409SSimon J. Gerraty /*
10700957b409SSimon J. Gerraty * List of supported protocol names (ALPN extension). If unset,
10710957b409SSimon J. Gerraty * (number of names is 0), then:
10720957b409SSimon J. Gerraty * - the client sends no ALPN extension;
10730957b409SSimon J. Gerraty * - the server ignores any incoming ALPN extension.
10740957b409SSimon J. Gerraty *
10750957b409SSimon J. Gerraty * Otherwise:
10760957b409SSimon J. Gerraty * - the client sends an ALPN extension with all the names;
10770957b409SSimon J. Gerraty * - the server selects the first protocol in its list that
10780957b409SSimon J. Gerraty * the client also supports, or fails (fatal alert 120)
10790957b409SSimon J. Gerraty * if the client sends an ALPN extension and there is no
10800957b409SSimon J. Gerraty * match.
10810957b409SSimon J. Gerraty *
10820957b409SSimon J. Gerraty * The 'selected_protocol' field contains 1+n if the matching
10830957b409SSimon J. Gerraty * name has index n in the list (the value is 0 if no match was
10840957b409SSimon J. Gerraty * performed, e.g. the peer did not send an ALPN extension).
10850957b409SSimon J. Gerraty */
10860957b409SSimon J. Gerraty const char **protocol_names;
10870957b409SSimon J. Gerraty uint16_t protocol_names_num;
10880957b409SSimon J. Gerraty uint16_t selected_protocol;
10890957b409SSimon J. Gerraty
10900957b409SSimon J. Gerraty /*
10910957b409SSimon J. Gerraty * Pointers to implementations; left to NULL for unsupported
10920957b409SSimon J. Gerraty * functions. For the raw hash functions, implementations are
10930957b409SSimon J. Gerraty * referenced from the multihasher (mhash field).
10940957b409SSimon J. Gerraty */
10950957b409SSimon J. Gerraty br_tls_prf_impl prf10;
10960957b409SSimon J. Gerraty br_tls_prf_impl prf_sha256;
10970957b409SSimon J. Gerraty br_tls_prf_impl prf_sha384;
10980957b409SSimon J. Gerraty const br_block_cbcenc_class *iaes_cbcenc;
10990957b409SSimon J. Gerraty const br_block_cbcdec_class *iaes_cbcdec;
11000957b409SSimon J. Gerraty const br_block_ctr_class *iaes_ctr;
11010957b409SSimon J. Gerraty const br_block_ctrcbc_class *iaes_ctrcbc;
11020957b409SSimon J. Gerraty const br_block_cbcenc_class *ides_cbcenc;
11030957b409SSimon J. Gerraty const br_block_cbcdec_class *ides_cbcdec;
11040957b409SSimon J. Gerraty br_ghash ighash;
11050957b409SSimon J. Gerraty br_chacha20_run ichacha;
11060957b409SSimon J. Gerraty br_poly1305_run ipoly;
11070957b409SSimon J. Gerraty const br_sslrec_in_cbc_class *icbc_in;
11080957b409SSimon J. Gerraty const br_sslrec_out_cbc_class *icbc_out;
11090957b409SSimon J. Gerraty const br_sslrec_in_gcm_class *igcm_in;
11100957b409SSimon J. Gerraty const br_sslrec_out_gcm_class *igcm_out;
11110957b409SSimon J. Gerraty const br_sslrec_in_chapol_class *ichapol_in;
11120957b409SSimon J. Gerraty const br_sslrec_out_chapol_class *ichapol_out;
11130957b409SSimon J. Gerraty const br_sslrec_in_ccm_class *iccm_in;
11140957b409SSimon J. Gerraty const br_sslrec_out_ccm_class *iccm_out;
11150957b409SSimon J. Gerraty const br_ec_impl *iec;
11160957b409SSimon J. Gerraty br_rsa_pkcs1_vrfy irsavrfy;
11170957b409SSimon J. Gerraty br_ecdsa_vrfy iecdsa;
11180957b409SSimon J. Gerraty #endif
11190957b409SSimon J. Gerraty } br_ssl_engine_context;
11200957b409SSimon J. Gerraty
11210957b409SSimon J. Gerraty /**
11220957b409SSimon J. Gerraty * \brief Get currently defined engine behavioural flags.
11230957b409SSimon J. Gerraty *
11240957b409SSimon J. Gerraty * \param cc SSL engine context.
11250957b409SSimon J. Gerraty * \return the flags.
11260957b409SSimon J. Gerraty */
11270957b409SSimon J. Gerraty static inline uint32_t
br_ssl_engine_get_flags(br_ssl_engine_context * cc)11280957b409SSimon J. Gerraty br_ssl_engine_get_flags(br_ssl_engine_context *cc)
11290957b409SSimon J. Gerraty {
11300957b409SSimon J. Gerraty return cc->flags;
11310957b409SSimon J. Gerraty }
11320957b409SSimon J. Gerraty
11330957b409SSimon J. Gerraty /**
11340957b409SSimon J. Gerraty * \brief Set all engine behavioural flags.
11350957b409SSimon J. Gerraty *
11360957b409SSimon J. Gerraty * \param cc SSL engine context.
11370957b409SSimon J. Gerraty * \param flags new value for all flags.
11380957b409SSimon J. Gerraty */
11390957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_all_flags(br_ssl_engine_context * cc,uint32_t flags)11400957b409SSimon J. Gerraty br_ssl_engine_set_all_flags(br_ssl_engine_context *cc, uint32_t flags)
11410957b409SSimon J. Gerraty {
11420957b409SSimon J. Gerraty cc->flags = flags;
11430957b409SSimon J. Gerraty }
11440957b409SSimon J. Gerraty
11450957b409SSimon J. Gerraty /**
11460957b409SSimon J. Gerraty * \brief Set some engine behavioural flags.
11470957b409SSimon J. Gerraty *
11480957b409SSimon J. Gerraty * The flags set in the `flags` parameter are set in the context; other
11490957b409SSimon J. Gerraty * flags are untouched.
11500957b409SSimon J. Gerraty *
11510957b409SSimon J. Gerraty * \param cc SSL engine context.
11520957b409SSimon J. Gerraty * \param flags additional set flags.
11530957b409SSimon J. Gerraty */
11540957b409SSimon J. Gerraty static inline void
br_ssl_engine_add_flags(br_ssl_engine_context * cc,uint32_t flags)11550957b409SSimon J. Gerraty br_ssl_engine_add_flags(br_ssl_engine_context *cc, uint32_t flags)
11560957b409SSimon J. Gerraty {
11570957b409SSimon J. Gerraty cc->flags |= flags;
11580957b409SSimon J. Gerraty }
11590957b409SSimon J. Gerraty
11600957b409SSimon J. Gerraty /**
11610957b409SSimon J. Gerraty * \brief Clear some engine behavioural flags.
11620957b409SSimon J. Gerraty *
11630957b409SSimon J. Gerraty * The flags set in the `flags` parameter are cleared from the context; other
11640957b409SSimon J. Gerraty * flags are untouched.
11650957b409SSimon J. Gerraty *
11660957b409SSimon J. Gerraty * \param cc SSL engine context.
11670957b409SSimon J. Gerraty * \param flags flags to remove.
11680957b409SSimon J. Gerraty */
11690957b409SSimon J. Gerraty static inline void
br_ssl_engine_remove_flags(br_ssl_engine_context * cc,uint32_t flags)11700957b409SSimon J. Gerraty br_ssl_engine_remove_flags(br_ssl_engine_context *cc, uint32_t flags)
11710957b409SSimon J. Gerraty {
11720957b409SSimon J. Gerraty cc->flags &= ~flags;
11730957b409SSimon J. Gerraty }
11740957b409SSimon J. Gerraty
11750957b409SSimon J. Gerraty /**
11760957b409SSimon J. Gerraty * \brief Behavioural flag: enforce server preferences.
11770957b409SSimon J. Gerraty *
11780957b409SSimon J. Gerraty * If this flag is set, then the server will enforce its own cipher suite
11790957b409SSimon J. Gerraty * preference order; otherwise, it follows the client preferences.
11800957b409SSimon J. Gerraty */
11810957b409SSimon J. Gerraty #define BR_OPT_ENFORCE_SERVER_PREFERENCES ((uint32_t)1 << 0)
11820957b409SSimon J. Gerraty
11830957b409SSimon J. Gerraty /**
11840957b409SSimon J. Gerraty * \brief Behavioural flag: disable renegotiation.
11850957b409SSimon J. Gerraty *
11860957b409SSimon J. Gerraty * If this flag is set, then renegotiations are rejected unconditionally:
11870957b409SSimon J. Gerraty * they won't be honoured if asked for programmatically, and requests from
11880957b409SSimon J. Gerraty * the peer are rejected.
11890957b409SSimon J. Gerraty */
11900957b409SSimon J. Gerraty #define BR_OPT_NO_RENEGOTIATION ((uint32_t)1 << 1)
11910957b409SSimon J. Gerraty
11920957b409SSimon J. Gerraty /**
11930957b409SSimon J. Gerraty * \brief Behavioural flag: tolerate lack of client authentication.
11940957b409SSimon J. Gerraty *
11950957b409SSimon J. Gerraty * If this flag is set in a server and the server requests a client
11960957b409SSimon J. Gerraty * certificate, but the authentication fails (the client does not send
11970957b409SSimon J. Gerraty * a certificate, or the client's certificate chain cannot be validated),
11980957b409SSimon J. Gerraty * then the connection keeps on. Without this flag, a failed client
11990957b409SSimon J. Gerraty * authentication terminates the connection.
12000957b409SSimon J. Gerraty *
12010957b409SSimon J. Gerraty * Notes:
12020957b409SSimon J. Gerraty *
12030957b409SSimon J. Gerraty * - If the client's certificate can be validated and its public key is
12040957b409SSimon J. Gerraty * supported, then a wrong signature value terminates the connection
12050957b409SSimon J. Gerraty * regardless of that flag.
12060957b409SSimon J. Gerraty *
12070957b409SSimon J. Gerraty * - If using full-static ECDH, then a failure to validate the client's
12080957b409SSimon J. Gerraty * certificate prevents the handshake from succeeding.
12090957b409SSimon J. Gerraty */
12100957b409SSimon J. Gerraty #define BR_OPT_TOLERATE_NO_CLIENT_AUTH ((uint32_t)1 << 2)
12110957b409SSimon J. Gerraty
12120957b409SSimon J. Gerraty /**
12130957b409SSimon J. Gerraty * \brief Behavioural flag: fail on application protocol mismatch.
12140957b409SSimon J. Gerraty *
12150957b409SSimon J. Gerraty * The ALPN extension ([RFC 7301](https://tools.ietf.org/html/rfc7301))
12160957b409SSimon J. Gerraty * allows the client to send a list of application protocol names, and
12170957b409SSimon J. Gerraty * the server to select one. A mismatch is one of the following occurrences:
12180957b409SSimon J. Gerraty *
12190957b409SSimon J. Gerraty * - On the client: the client sends a list of names, the server
12200957b409SSimon J. Gerraty * responds with a protocol name which is _not_ part of the list of
12210957b409SSimon J. Gerraty * names sent by the client.
12220957b409SSimon J. Gerraty *
12230957b409SSimon J. Gerraty * - On the server: the client sends a list of names, and the server
12240957b409SSimon J. Gerraty * is also configured with a list of names, but there is no common
12250957b409SSimon J. Gerraty * protocol name between the two lists.
12260957b409SSimon J. Gerraty *
12270957b409SSimon J. Gerraty * Normal behaviour in case of mismatch is to report no matching name
12280957b409SSimon J. Gerraty * (`br_ssl_engine_get_selected_protocol()` returns `NULL`) and carry on.
12290957b409SSimon J. Gerraty * If the flag is set, then a mismatch implies a protocol failure (if
12300957b409SSimon J. Gerraty * the mismatch is detected by the server, it will send a fatal alert).
12310957b409SSimon J. Gerraty *
12320957b409SSimon J. Gerraty * Note: even with this flag, `br_ssl_engine_get_selected_protocol()`
12330957b409SSimon J. Gerraty * may still return `NULL` if the client or the server does not send an
12340957b409SSimon J. Gerraty * ALPN extension at all.
12350957b409SSimon J. Gerraty */
12360957b409SSimon J. Gerraty #define BR_OPT_FAIL_ON_ALPN_MISMATCH ((uint32_t)1 << 3)
12370957b409SSimon J. Gerraty
12380957b409SSimon J. Gerraty /**
12390957b409SSimon J. Gerraty * \brief Set the minimum and maximum supported protocol versions.
12400957b409SSimon J. Gerraty *
12410957b409SSimon J. Gerraty * The two provided versions MUST be supported by the implementation
12420957b409SSimon J. Gerraty * (i.e. TLS 1.0, 1.1 and 1.2), and `version_max` MUST NOT be lower
12430957b409SSimon J. Gerraty * than `version_min`.
12440957b409SSimon J. Gerraty *
12450957b409SSimon J. Gerraty * \param cc SSL engine context.
12460957b409SSimon J. Gerraty * \param version_min minimum supported TLS version.
12470957b409SSimon J. Gerraty * \param version_max maximum supported TLS version.
12480957b409SSimon J. Gerraty */
12490957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_versions(br_ssl_engine_context * cc,unsigned version_min,unsigned version_max)12500957b409SSimon J. Gerraty br_ssl_engine_set_versions(br_ssl_engine_context *cc,
12510957b409SSimon J. Gerraty unsigned version_min, unsigned version_max)
12520957b409SSimon J. Gerraty {
1253*cc9e6590SSimon J. Gerraty cc->version_min = (uint16_t)version_min;
1254*cc9e6590SSimon J. Gerraty cc->version_max = (uint16_t)version_max;
12550957b409SSimon J. Gerraty }
12560957b409SSimon J. Gerraty
12570957b409SSimon J. Gerraty /**
12580957b409SSimon J. Gerraty * \brief Set the list of cipher suites advertised by this context.
12590957b409SSimon J. Gerraty *
12600957b409SSimon J. Gerraty * The provided array is copied into the context. It is the caller
12610957b409SSimon J. Gerraty * responsibility to ensure that all provided suites will be supported
12620957b409SSimon J. Gerraty * by the context. The engine context has enough room to receive _all_
12630957b409SSimon J. Gerraty * suites supported by the implementation. The provided array MUST NOT
12640957b409SSimon J. Gerraty * contain duplicates.
12650957b409SSimon J. Gerraty *
12660957b409SSimon J. Gerraty * If the engine is for a client, the "signaling" pseudo-cipher suite
12670957b409SSimon J. Gerraty * `TLS_FALLBACK_SCSV` can be added at the end of the list, if the
12680957b409SSimon J. Gerraty * calling application is performing a voluntary downgrade (voluntary
12690957b409SSimon J. Gerraty * downgrades are not recommended, but if such a downgrade is done, then
12700957b409SSimon J. Gerraty * adding the fallback pseudo-suite is a good idea).
12710957b409SSimon J. Gerraty *
12720957b409SSimon J. Gerraty * \param cc SSL engine context.
12730957b409SSimon J. Gerraty * \param suites cipher suites.
12740957b409SSimon J. Gerraty * \param suites_num number of cipher suites.
12750957b409SSimon J. Gerraty */
12760957b409SSimon J. Gerraty void br_ssl_engine_set_suites(br_ssl_engine_context *cc,
12770957b409SSimon J. Gerraty const uint16_t *suites, size_t suites_num);
12780957b409SSimon J. Gerraty
12790957b409SSimon J. Gerraty /**
12800957b409SSimon J. Gerraty * \brief Set the X.509 engine.
12810957b409SSimon J. Gerraty *
12820957b409SSimon J. Gerraty * The caller shall ensure that the X.509 engine is properly initialised.
12830957b409SSimon J. Gerraty *
12840957b409SSimon J. Gerraty * \param cc SSL engine context.
12850957b409SSimon J. Gerraty * \param x509ctx X.509 certificate validation context.
12860957b409SSimon J. Gerraty */
12870957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_x509(br_ssl_engine_context * cc,const br_x509_class ** x509ctx)12880957b409SSimon J. Gerraty br_ssl_engine_set_x509(br_ssl_engine_context *cc, const br_x509_class **x509ctx)
12890957b409SSimon J. Gerraty {
12900957b409SSimon J. Gerraty cc->x509ctx = x509ctx;
12910957b409SSimon J. Gerraty }
12920957b409SSimon J. Gerraty
12930957b409SSimon J. Gerraty /**
12940957b409SSimon J. Gerraty * \brief Set the supported protocol names.
12950957b409SSimon J. Gerraty *
12960957b409SSimon J. Gerraty * Protocol names are part of the ALPN extension ([RFC
12970957b409SSimon J. Gerraty * 7301](https://tools.ietf.org/html/rfc7301)). Each protocol name is a
12980957b409SSimon J. Gerraty * character string, containing no more than 255 characters (256 with the
12990957b409SSimon J. Gerraty * terminating zero). When names are set, then:
13000957b409SSimon J. Gerraty *
13010957b409SSimon J. Gerraty * - The client will send an ALPN extension, containing the names. If
13020957b409SSimon J. Gerraty * the server responds with an ALPN extension, the client will verify
13030957b409SSimon J. Gerraty * that the response contains one of its name, and report that name
13040957b409SSimon J. Gerraty * through `br_ssl_engine_get_selected_protocol()`.
13050957b409SSimon J. Gerraty *
13060957b409SSimon J. Gerraty * - The server will parse incoming ALPN extension (from clients), and
13070957b409SSimon J. Gerraty * try to find a common protocol; if none is found, the connection
13080957b409SSimon J. Gerraty * is aborted with a fatal alert. On match, a response ALPN extension
13090957b409SSimon J. Gerraty * is sent, and name is reported through
13100957b409SSimon J. Gerraty * `br_ssl_engine_get_selected_protocol()`.
13110957b409SSimon J. Gerraty *
13120957b409SSimon J. Gerraty * The provided array is linked in, and must remain valid while the
13130957b409SSimon J. Gerraty * connection is live.
13140957b409SSimon J. Gerraty *
13150957b409SSimon J. Gerraty * Names MUST NOT be empty. Names MUST NOT be longer than 255 characters
13160957b409SSimon J. Gerraty * (excluding the terminating 0).
13170957b409SSimon J. Gerraty *
13180957b409SSimon J. Gerraty * \param ctx SSL engine context.
13190957b409SSimon J. Gerraty * \param names list of protocol names (zero-terminated).
13200957b409SSimon J. Gerraty * \param num number of protocol names (MUST be 1 or more).
13210957b409SSimon J. Gerraty */
13220957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_protocol_names(br_ssl_engine_context * ctx,const char ** names,size_t num)13230957b409SSimon J. Gerraty br_ssl_engine_set_protocol_names(br_ssl_engine_context *ctx,
13240957b409SSimon J. Gerraty const char **names, size_t num)
13250957b409SSimon J. Gerraty {
13260957b409SSimon J. Gerraty ctx->protocol_names = names;
1327*cc9e6590SSimon J. Gerraty ctx->protocol_names_num = (uint16_t)num;
13280957b409SSimon J. Gerraty }
13290957b409SSimon J. Gerraty
13300957b409SSimon J. Gerraty /**
13310957b409SSimon J. Gerraty * \brief Get the selected protocol.
13320957b409SSimon J. Gerraty *
13330957b409SSimon J. Gerraty * If this context was initialised with a non-empty list of protocol
13340957b409SSimon J. Gerraty * names, and both client and server sent ALPN extensions during the
13350957b409SSimon J. Gerraty * handshake, and a common name was found, then that name is returned.
13360957b409SSimon J. Gerraty * Otherwise, `NULL` is returned.
13370957b409SSimon J. Gerraty *
13380957b409SSimon J. Gerraty * The returned pointer is one of the pointers provided to the context
13390957b409SSimon J. Gerraty * with `br_ssl_engine_set_protocol_names()`.
13400957b409SSimon J. Gerraty *
13410957b409SSimon J. Gerraty * \return the selected protocol, or `NULL`.
13420957b409SSimon J. Gerraty */
13430957b409SSimon J. Gerraty static inline const char *
br_ssl_engine_get_selected_protocol(br_ssl_engine_context * ctx)13440957b409SSimon J. Gerraty br_ssl_engine_get_selected_protocol(br_ssl_engine_context *ctx)
13450957b409SSimon J. Gerraty {
13460957b409SSimon J. Gerraty unsigned k;
13470957b409SSimon J. Gerraty
13480957b409SSimon J. Gerraty k = ctx->selected_protocol;
13490957b409SSimon J. Gerraty return (k == 0 || k == 0xFFFF) ? NULL : ctx->protocol_names[k - 1];
13500957b409SSimon J. Gerraty }
13510957b409SSimon J. Gerraty
13520957b409SSimon J. Gerraty /**
13530957b409SSimon J. Gerraty * \brief Set a hash function implementation (by ID).
13540957b409SSimon J. Gerraty *
13550957b409SSimon J. Gerraty * Hash functions set with this call will be used for SSL/TLS specific
13560957b409SSimon J. Gerraty * usages, not X.509 certificate validation. Only "standard" hash functions
13570957b409SSimon J. Gerraty * may be set (MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512). If `impl`
13580957b409SSimon J. Gerraty * is `NULL`, then the hash function support is removed, not added.
13590957b409SSimon J. Gerraty *
13600957b409SSimon J. Gerraty * \param ctx SSL engine context.
13610957b409SSimon J. Gerraty * \param id hash function identifier.
13620957b409SSimon J. Gerraty * \param impl hash function implementation (or `NULL`).
13630957b409SSimon J. Gerraty */
13640957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_hash(br_ssl_engine_context * ctx,int id,const br_hash_class * impl)13650957b409SSimon J. Gerraty br_ssl_engine_set_hash(br_ssl_engine_context *ctx,
13660957b409SSimon J. Gerraty int id, const br_hash_class *impl)
13670957b409SSimon J. Gerraty {
13680957b409SSimon J. Gerraty br_multihash_setimpl(&ctx->mhash, id, impl);
13690957b409SSimon J. Gerraty }
13700957b409SSimon J. Gerraty
13710957b409SSimon J. Gerraty /**
13720957b409SSimon J. Gerraty * \brief Get a hash function implementation (by ID).
13730957b409SSimon J. Gerraty *
13740957b409SSimon J. Gerraty * This function retrieves a hash function implementation which was
13750957b409SSimon J. Gerraty * set with `br_ssl_engine_set_hash()`.
13760957b409SSimon J. Gerraty *
13770957b409SSimon J. Gerraty * \param ctx SSL engine context.
13780957b409SSimon J. Gerraty * \param id hash function identifier.
13790957b409SSimon J. Gerraty * \return the hash function implementation (or `NULL`).
13800957b409SSimon J. Gerraty */
13810957b409SSimon J. Gerraty static inline const br_hash_class *
br_ssl_engine_get_hash(br_ssl_engine_context * ctx,int id)13820957b409SSimon J. Gerraty br_ssl_engine_get_hash(br_ssl_engine_context *ctx, int id)
13830957b409SSimon J. Gerraty {
13840957b409SSimon J. Gerraty return br_multihash_getimpl(&ctx->mhash, id);
13850957b409SSimon J. Gerraty }
13860957b409SSimon J. Gerraty
13870957b409SSimon J. Gerraty /**
13880957b409SSimon J. Gerraty * \brief Set the PRF implementation (for TLS 1.0 and 1.1).
13890957b409SSimon J. Gerraty *
13900957b409SSimon J. Gerraty * This function sets (or removes, if `impl` is `NULL`) the implementation
13910957b409SSimon J. Gerraty * for the PRF used in TLS 1.0 and 1.1.
13920957b409SSimon J. Gerraty *
13930957b409SSimon J. Gerraty * \param cc SSL engine context.
13940957b409SSimon J. Gerraty * \param impl PRF implementation (or `NULL`).
13950957b409SSimon J. Gerraty */
13960957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_prf10(br_ssl_engine_context * cc,br_tls_prf_impl impl)13970957b409SSimon J. Gerraty br_ssl_engine_set_prf10(br_ssl_engine_context *cc, br_tls_prf_impl impl)
13980957b409SSimon J. Gerraty {
13990957b409SSimon J. Gerraty cc->prf10 = impl;
14000957b409SSimon J. Gerraty }
14010957b409SSimon J. Gerraty
14020957b409SSimon J. Gerraty /**
14030957b409SSimon J. Gerraty * \brief Set the PRF implementation with SHA-256 (for TLS 1.2).
14040957b409SSimon J. Gerraty *
14050957b409SSimon J. Gerraty * This function sets (or removes, if `impl` is `NULL`) the implementation
14060957b409SSimon J. Gerraty * for the SHA-256 variant of the PRF used in TLS 1.2.
14070957b409SSimon J. Gerraty *
14080957b409SSimon J. Gerraty * \param cc SSL engine context.
14090957b409SSimon J. Gerraty * \param impl PRF implementation (or `NULL`).
14100957b409SSimon J. Gerraty */
14110957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_prf_sha256(br_ssl_engine_context * cc,br_tls_prf_impl impl)14120957b409SSimon J. Gerraty br_ssl_engine_set_prf_sha256(br_ssl_engine_context *cc, br_tls_prf_impl impl)
14130957b409SSimon J. Gerraty {
14140957b409SSimon J. Gerraty cc->prf_sha256 = impl;
14150957b409SSimon J. Gerraty }
14160957b409SSimon J. Gerraty
14170957b409SSimon J. Gerraty /**
14180957b409SSimon J. Gerraty * \brief Set the PRF implementation with SHA-384 (for TLS 1.2).
14190957b409SSimon J. Gerraty *
14200957b409SSimon J. Gerraty * This function sets (or removes, if `impl` is `NULL`) the implementation
14210957b409SSimon J. Gerraty * for the SHA-384 variant of the PRF used in TLS 1.2.
14220957b409SSimon J. Gerraty *
14230957b409SSimon J. Gerraty * \param cc SSL engine context.
14240957b409SSimon J. Gerraty * \param impl PRF implementation (or `NULL`).
14250957b409SSimon J. Gerraty */
14260957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_prf_sha384(br_ssl_engine_context * cc,br_tls_prf_impl impl)14270957b409SSimon J. Gerraty br_ssl_engine_set_prf_sha384(br_ssl_engine_context *cc, br_tls_prf_impl impl)
14280957b409SSimon J. Gerraty {
14290957b409SSimon J. Gerraty cc->prf_sha384 = impl;
14300957b409SSimon J. Gerraty }
14310957b409SSimon J. Gerraty
14320957b409SSimon J. Gerraty /**
14330957b409SSimon J. Gerraty * \brief Set the AES/CBC implementations.
14340957b409SSimon J. Gerraty *
14350957b409SSimon J. Gerraty * \param cc SSL engine context.
14360957b409SSimon J. Gerraty * \param impl_enc AES/CBC encryption implementation (or `NULL`).
14370957b409SSimon J. Gerraty * \param impl_dec AES/CBC decryption implementation (or `NULL`).
14380957b409SSimon J. Gerraty */
14390957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_aes_cbc(br_ssl_engine_context * cc,const br_block_cbcenc_class * impl_enc,const br_block_cbcdec_class * impl_dec)14400957b409SSimon J. Gerraty br_ssl_engine_set_aes_cbc(br_ssl_engine_context *cc,
14410957b409SSimon J. Gerraty const br_block_cbcenc_class *impl_enc,
14420957b409SSimon J. Gerraty const br_block_cbcdec_class *impl_dec)
14430957b409SSimon J. Gerraty {
14440957b409SSimon J. Gerraty cc->iaes_cbcenc = impl_enc;
14450957b409SSimon J. Gerraty cc->iaes_cbcdec = impl_dec;
14460957b409SSimon J. Gerraty }
14470957b409SSimon J. Gerraty
14480957b409SSimon J. Gerraty /**
14490957b409SSimon J. Gerraty * \brief Set the "default" AES/CBC implementations.
14500957b409SSimon J. Gerraty *
14510957b409SSimon J. Gerraty * This function configures in the engine the AES implementations that
14520957b409SSimon J. Gerraty * should provide best runtime performance on the local system, while
14530957b409SSimon J. Gerraty * still being safe (in particular, constant-time). It also sets the
14540957b409SSimon J. Gerraty * handlers for CBC records.
14550957b409SSimon J. Gerraty *
14560957b409SSimon J. Gerraty * \param cc SSL engine context.
14570957b409SSimon J. Gerraty */
14580957b409SSimon J. Gerraty void br_ssl_engine_set_default_aes_cbc(br_ssl_engine_context *cc);
14590957b409SSimon J. Gerraty
14600957b409SSimon J. Gerraty /**
14610957b409SSimon J. Gerraty * \brief Set the AES/CTR implementation.
14620957b409SSimon J. Gerraty *
14630957b409SSimon J. Gerraty * \param cc SSL engine context.
14640957b409SSimon J. Gerraty * \param impl AES/CTR encryption/decryption implementation (or `NULL`).
14650957b409SSimon J. Gerraty */
14660957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_aes_ctr(br_ssl_engine_context * cc,const br_block_ctr_class * impl)14670957b409SSimon J. Gerraty br_ssl_engine_set_aes_ctr(br_ssl_engine_context *cc,
14680957b409SSimon J. Gerraty const br_block_ctr_class *impl)
14690957b409SSimon J. Gerraty {
14700957b409SSimon J. Gerraty cc->iaes_ctr = impl;
14710957b409SSimon J. Gerraty }
14720957b409SSimon J. Gerraty
14730957b409SSimon J. Gerraty /**
14740957b409SSimon J. Gerraty * \brief Set the "default" implementations for AES/GCM (AES/CTR + GHASH).
14750957b409SSimon J. Gerraty *
14760957b409SSimon J. Gerraty * This function configures in the engine the AES/CTR and GHASH
14770957b409SSimon J. Gerraty * implementation that should provide best runtime performance on the local
14780957b409SSimon J. Gerraty * system, while still being safe (in particular, constant-time). It also
14790957b409SSimon J. Gerraty * sets the handlers for GCM records.
14800957b409SSimon J. Gerraty *
14810957b409SSimon J. Gerraty * \param cc SSL engine context.
14820957b409SSimon J. Gerraty */
14830957b409SSimon J. Gerraty void br_ssl_engine_set_default_aes_gcm(br_ssl_engine_context *cc);
14840957b409SSimon J. Gerraty
14850957b409SSimon J. Gerraty /**
14860957b409SSimon J. Gerraty * \brief Set the DES/CBC implementations.
14870957b409SSimon J. Gerraty *
14880957b409SSimon J. Gerraty * \param cc SSL engine context.
14890957b409SSimon J. Gerraty * \param impl_enc DES/CBC encryption implementation (or `NULL`).
14900957b409SSimon J. Gerraty * \param impl_dec DES/CBC decryption implementation (or `NULL`).
14910957b409SSimon J. Gerraty */
14920957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_des_cbc(br_ssl_engine_context * cc,const br_block_cbcenc_class * impl_enc,const br_block_cbcdec_class * impl_dec)14930957b409SSimon J. Gerraty br_ssl_engine_set_des_cbc(br_ssl_engine_context *cc,
14940957b409SSimon J. Gerraty const br_block_cbcenc_class *impl_enc,
14950957b409SSimon J. Gerraty const br_block_cbcdec_class *impl_dec)
14960957b409SSimon J. Gerraty {
14970957b409SSimon J. Gerraty cc->ides_cbcenc = impl_enc;
14980957b409SSimon J. Gerraty cc->ides_cbcdec = impl_dec;
14990957b409SSimon J. Gerraty }
15000957b409SSimon J. Gerraty
15010957b409SSimon J. Gerraty /**
15020957b409SSimon J. Gerraty * \brief Set the "default" DES/CBC implementations.
15030957b409SSimon J. Gerraty *
15040957b409SSimon J. Gerraty * This function configures in the engine the DES implementations that
15050957b409SSimon J. Gerraty * should provide best runtime performance on the local system, while
15060957b409SSimon J. Gerraty * still being safe (in particular, constant-time). It also sets the
15070957b409SSimon J. Gerraty * handlers for CBC records.
15080957b409SSimon J. Gerraty *
15090957b409SSimon J. Gerraty * \param cc SSL engine context.
15100957b409SSimon J. Gerraty */
15110957b409SSimon J. Gerraty void br_ssl_engine_set_default_des_cbc(br_ssl_engine_context *cc);
15120957b409SSimon J. Gerraty
15130957b409SSimon J. Gerraty /**
15140957b409SSimon J. Gerraty * \brief Set the GHASH implementation (used in GCM mode).
15150957b409SSimon J. Gerraty *
15160957b409SSimon J. Gerraty * \param cc SSL engine context.
15170957b409SSimon J. Gerraty * \param impl GHASH implementation (or `NULL`).
15180957b409SSimon J. Gerraty */
15190957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_ghash(br_ssl_engine_context * cc,br_ghash impl)15200957b409SSimon J. Gerraty br_ssl_engine_set_ghash(br_ssl_engine_context *cc, br_ghash impl)
15210957b409SSimon J. Gerraty {
15220957b409SSimon J. Gerraty cc->ighash = impl;
15230957b409SSimon J. Gerraty }
15240957b409SSimon J. Gerraty
15250957b409SSimon J. Gerraty /**
15260957b409SSimon J. Gerraty * \brief Set the ChaCha20 implementation.
15270957b409SSimon J. Gerraty *
15280957b409SSimon J. Gerraty * \param cc SSL engine context.
15290957b409SSimon J. Gerraty * \param ichacha ChaCha20 implementation (or `NULL`).
15300957b409SSimon J. Gerraty */
15310957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_chacha20(br_ssl_engine_context * cc,br_chacha20_run ichacha)15320957b409SSimon J. Gerraty br_ssl_engine_set_chacha20(br_ssl_engine_context *cc,
15330957b409SSimon J. Gerraty br_chacha20_run ichacha)
15340957b409SSimon J. Gerraty {
15350957b409SSimon J. Gerraty cc->ichacha = ichacha;
15360957b409SSimon J. Gerraty }
15370957b409SSimon J. Gerraty
15380957b409SSimon J. Gerraty /**
15390957b409SSimon J. Gerraty * \brief Set the Poly1305 implementation.
15400957b409SSimon J. Gerraty *
15410957b409SSimon J. Gerraty * \param cc SSL engine context.
15420957b409SSimon J. Gerraty * \param ipoly Poly1305 implementation (or `NULL`).
15430957b409SSimon J. Gerraty */
15440957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_poly1305(br_ssl_engine_context * cc,br_poly1305_run ipoly)15450957b409SSimon J. Gerraty br_ssl_engine_set_poly1305(br_ssl_engine_context *cc,
15460957b409SSimon J. Gerraty br_poly1305_run ipoly)
15470957b409SSimon J. Gerraty {
15480957b409SSimon J. Gerraty cc->ipoly = ipoly;
15490957b409SSimon J. Gerraty }
15500957b409SSimon J. Gerraty
15510957b409SSimon J. Gerraty /**
15520957b409SSimon J. Gerraty * \brief Set the "default" ChaCha20 and Poly1305 implementations.
15530957b409SSimon J. Gerraty *
15540957b409SSimon J. Gerraty * This function configures in the engine the ChaCha20 and Poly1305
15550957b409SSimon J. Gerraty * implementations that should provide best runtime performance on the
15560957b409SSimon J. Gerraty * local system, while still being safe (in particular, constant-time).
15570957b409SSimon J. Gerraty * It also sets the handlers for ChaCha20+Poly1305 records.
15580957b409SSimon J. Gerraty *
15590957b409SSimon J. Gerraty * \param cc SSL engine context.
15600957b409SSimon J. Gerraty */
15610957b409SSimon J. Gerraty void br_ssl_engine_set_default_chapol(br_ssl_engine_context *cc);
15620957b409SSimon J. Gerraty
15630957b409SSimon J. Gerraty /**
15640957b409SSimon J. Gerraty * \brief Set the AES/CTR+CBC implementation.
15650957b409SSimon J. Gerraty *
15660957b409SSimon J. Gerraty * \param cc SSL engine context.
15670957b409SSimon J. Gerraty * \param impl AES/CTR+CBC encryption/decryption implementation (or `NULL`).
15680957b409SSimon J. Gerraty */
15690957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_aes_ctrcbc(br_ssl_engine_context * cc,const br_block_ctrcbc_class * impl)15700957b409SSimon J. Gerraty br_ssl_engine_set_aes_ctrcbc(br_ssl_engine_context *cc,
15710957b409SSimon J. Gerraty const br_block_ctrcbc_class *impl)
15720957b409SSimon J. Gerraty {
15730957b409SSimon J. Gerraty cc->iaes_ctrcbc = impl;
15740957b409SSimon J. Gerraty }
15750957b409SSimon J. Gerraty
15760957b409SSimon J. Gerraty /**
15770957b409SSimon J. Gerraty * \brief Set the "default" implementations for AES/CCM.
15780957b409SSimon J. Gerraty *
15790957b409SSimon J. Gerraty * This function configures in the engine the AES/CTR+CBC
15800957b409SSimon J. Gerraty * implementation that should provide best runtime performance on the local
15810957b409SSimon J. Gerraty * system, while still being safe (in particular, constant-time). It also
15820957b409SSimon J. Gerraty * sets the handlers for CCM records.
15830957b409SSimon J. Gerraty *
15840957b409SSimon J. Gerraty * \param cc SSL engine context.
15850957b409SSimon J. Gerraty */
15860957b409SSimon J. Gerraty void br_ssl_engine_set_default_aes_ccm(br_ssl_engine_context *cc);
15870957b409SSimon J. Gerraty
15880957b409SSimon J. Gerraty /**
15890957b409SSimon J. Gerraty * \brief Set the record encryption and decryption engines for CBC + HMAC.
15900957b409SSimon J. Gerraty *
15910957b409SSimon J. Gerraty * \param cc SSL engine context.
15920957b409SSimon J. Gerraty * \param impl_in record CBC decryption implementation (or `NULL`).
15930957b409SSimon J. Gerraty * \param impl_out record CBC encryption implementation (or `NULL`).
15940957b409SSimon J. Gerraty */
15950957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_cbc(br_ssl_engine_context * cc,const br_sslrec_in_cbc_class * impl_in,const br_sslrec_out_cbc_class * impl_out)15960957b409SSimon J. Gerraty br_ssl_engine_set_cbc(br_ssl_engine_context *cc,
15970957b409SSimon J. Gerraty const br_sslrec_in_cbc_class *impl_in,
15980957b409SSimon J. Gerraty const br_sslrec_out_cbc_class *impl_out)
15990957b409SSimon J. Gerraty {
16000957b409SSimon J. Gerraty cc->icbc_in = impl_in;
16010957b409SSimon J. Gerraty cc->icbc_out = impl_out;
16020957b409SSimon J. Gerraty }
16030957b409SSimon J. Gerraty
16040957b409SSimon J. Gerraty /**
16050957b409SSimon J. Gerraty * \brief Set the record encryption and decryption engines for GCM.
16060957b409SSimon J. Gerraty *
16070957b409SSimon J. Gerraty * \param cc SSL engine context.
16080957b409SSimon J. Gerraty * \param impl_in record GCM decryption implementation (or `NULL`).
16090957b409SSimon J. Gerraty * \param impl_out record GCM encryption implementation (or `NULL`).
16100957b409SSimon J. Gerraty */
16110957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_gcm(br_ssl_engine_context * cc,const br_sslrec_in_gcm_class * impl_in,const br_sslrec_out_gcm_class * impl_out)16120957b409SSimon J. Gerraty br_ssl_engine_set_gcm(br_ssl_engine_context *cc,
16130957b409SSimon J. Gerraty const br_sslrec_in_gcm_class *impl_in,
16140957b409SSimon J. Gerraty const br_sslrec_out_gcm_class *impl_out)
16150957b409SSimon J. Gerraty {
16160957b409SSimon J. Gerraty cc->igcm_in = impl_in;
16170957b409SSimon J. Gerraty cc->igcm_out = impl_out;
16180957b409SSimon J. Gerraty }
16190957b409SSimon J. Gerraty
16200957b409SSimon J. Gerraty /**
16210957b409SSimon J. Gerraty * \brief Set the record encryption and decryption engines for CCM.
16220957b409SSimon J. Gerraty *
16230957b409SSimon J. Gerraty * \param cc SSL engine context.
16240957b409SSimon J. Gerraty * \param impl_in record CCM decryption implementation (or `NULL`).
16250957b409SSimon J. Gerraty * \param impl_out record CCM encryption implementation (or `NULL`).
16260957b409SSimon J. Gerraty */
16270957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_ccm(br_ssl_engine_context * cc,const br_sslrec_in_ccm_class * impl_in,const br_sslrec_out_ccm_class * impl_out)16280957b409SSimon J. Gerraty br_ssl_engine_set_ccm(br_ssl_engine_context *cc,
16290957b409SSimon J. Gerraty const br_sslrec_in_ccm_class *impl_in,
16300957b409SSimon J. Gerraty const br_sslrec_out_ccm_class *impl_out)
16310957b409SSimon J. Gerraty {
16320957b409SSimon J. Gerraty cc->iccm_in = impl_in;
16330957b409SSimon J. Gerraty cc->iccm_out = impl_out;
16340957b409SSimon J. Gerraty }
16350957b409SSimon J. Gerraty
16360957b409SSimon J. Gerraty /**
16370957b409SSimon J. Gerraty * \brief Set the record encryption and decryption engines for
16380957b409SSimon J. Gerraty * ChaCha20+Poly1305.
16390957b409SSimon J. Gerraty *
16400957b409SSimon J. Gerraty * \param cc SSL engine context.
16410957b409SSimon J. Gerraty * \param impl_in record ChaCha20 decryption implementation (or `NULL`).
16420957b409SSimon J. Gerraty * \param impl_out record ChaCha20 encryption implementation (or `NULL`).
16430957b409SSimon J. Gerraty */
16440957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_chapol(br_ssl_engine_context * cc,const br_sslrec_in_chapol_class * impl_in,const br_sslrec_out_chapol_class * impl_out)16450957b409SSimon J. Gerraty br_ssl_engine_set_chapol(br_ssl_engine_context *cc,
16460957b409SSimon J. Gerraty const br_sslrec_in_chapol_class *impl_in,
16470957b409SSimon J. Gerraty const br_sslrec_out_chapol_class *impl_out)
16480957b409SSimon J. Gerraty {
16490957b409SSimon J. Gerraty cc->ichapol_in = impl_in;
16500957b409SSimon J. Gerraty cc->ichapol_out = impl_out;
16510957b409SSimon J. Gerraty }
16520957b409SSimon J. Gerraty
16530957b409SSimon J. Gerraty /**
16540957b409SSimon J. Gerraty * \brief Set the EC implementation.
16550957b409SSimon J. Gerraty *
16560957b409SSimon J. Gerraty * The elliptic curve implementation will be used for ECDH and ECDHE
16570957b409SSimon J. Gerraty * cipher suites, and for ECDSA support.
16580957b409SSimon J. Gerraty *
16590957b409SSimon J. Gerraty * \param cc SSL engine context.
16600957b409SSimon J. Gerraty * \param iec EC implementation (or `NULL`).
16610957b409SSimon J. Gerraty */
16620957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_ec(br_ssl_engine_context * cc,const br_ec_impl * iec)16630957b409SSimon J. Gerraty br_ssl_engine_set_ec(br_ssl_engine_context *cc, const br_ec_impl *iec)
16640957b409SSimon J. Gerraty {
16650957b409SSimon J. Gerraty cc->iec = iec;
16660957b409SSimon J. Gerraty }
16670957b409SSimon J. Gerraty
16680957b409SSimon J. Gerraty /**
16690957b409SSimon J. Gerraty * \brief Set the "default" EC implementation.
16700957b409SSimon J. Gerraty *
16710957b409SSimon J. Gerraty * This function sets the elliptic curve implementation for ECDH and
16720957b409SSimon J. Gerraty * ECDHE cipher suites, and for ECDSA support. It selects the fastest
16730957b409SSimon J. Gerraty * implementation on the current system.
16740957b409SSimon J. Gerraty *
16750957b409SSimon J. Gerraty * \param cc SSL engine context.
16760957b409SSimon J. Gerraty */
16770957b409SSimon J. Gerraty void br_ssl_engine_set_default_ec(br_ssl_engine_context *cc);
16780957b409SSimon J. Gerraty
16790957b409SSimon J. Gerraty /**
16800957b409SSimon J. Gerraty * \brief Get the EC implementation configured in the provided engine.
16810957b409SSimon J. Gerraty *
16820957b409SSimon J. Gerraty * \param cc SSL engine context.
16830957b409SSimon J. Gerraty * \return the EC implementation.
16840957b409SSimon J. Gerraty */
16850957b409SSimon J. Gerraty static inline const br_ec_impl *
br_ssl_engine_get_ec(br_ssl_engine_context * cc)16860957b409SSimon J. Gerraty br_ssl_engine_get_ec(br_ssl_engine_context *cc)
16870957b409SSimon J. Gerraty {
16880957b409SSimon J. Gerraty return cc->iec;
16890957b409SSimon J. Gerraty }
16900957b409SSimon J. Gerraty
16910957b409SSimon J. Gerraty /**
16920957b409SSimon J. Gerraty * \brief Set the RSA signature verification implementation.
16930957b409SSimon J. Gerraty *
16940957b409SSimon J. Gerraty * On the client, this is used to verify the server's signature on its
16950957b409SSimon J. Gerraty * ServerKeyExchange message (for ECDHE_RSA cipher suites). On the server,
16960957b409SSimon J. Gerraty * this is used to verify the client's CertificateVerify message (if a
16970957b409SSimon J. Gerraty * client certificate is requested, and that certificate contains a RSA key).
16980957b409SSimon J. Gerraty *
16990957b409SSimon J. Gerraty * \param cc SSL engine context.
17000957b409SSimon J. Gerraty * \param irsavrfy RSA signature verification implementation.
17010957b409SSimon J. Gerraty */
17020957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_rsavrfy(br_ssl_engine_context * cc,br_rsa_pkcs1_vrfy irsavrfy)17030957b409SSimon J. Gerraty br_ssl_engine_set_rsavrfy(br_ssl_engine_context *cc, br_rsa_pkcs1_vrfy irsavrfy)
17040957b409SSimon J. Gerraty {
17050957b409SSimon J. Gerraty cc->irsavrfy = irsavrfy;
17060957b409SSimon J. Gerraty }
17070957b409SSimon J. Gerraty
17080957b409SSimon J. Gerraty /**
17090957b409SSimon J. Gerraty * \brief Set the "default" RSA implementation (signature verification).
17100957b409SSimon J. Gerraty *
17110957b409SSimon J. Gerraty * This function sets the RSA implementation (signature verification)
17120957b409SSimon J. Gerraty * to the fastest implementation available on the current platform.
17130957b409SSimon J. Gerraty *
17140957b409SSimon J. Gerraty * \param cc SSL engine context.
17150957b409SSimon J. Gerraty */
17160957b409SSimon J. Gerraty void br_ssl_engine_set_default_rsavrfy(br_ssl_engine_context *cc);
17170957b409SSimon J. Gerraty
17180957b409SSimon J. Gerraty /**
17190957b409SSimon J. Gerraty * \brief Get the RSA implementation (signature verification) configured
17200957b409SSimon J. Gerraty * in the provided engine.
17210957b409SSimon J. Gerraty *
17220957b409SSimon J. Gerraty * \param cc SSL engine context.
17230957b409SSimon J. Gerraty * \return the RSA signature verification implementation.
17240957b409SSimon J. Gerraty */
17250957b409SSimon J. Gerraty static inline br_rsa_pkcs1_vrfy
br_ssl_engine_get_rsavrfy(br_ssl_engine_context * cc)17260957b409SSimon J. Gerraty br_ssl_engine_get_rsavrfy(br_ssl_engine_context *cc)
17270957b409SSimon J. Gerraty {
17280957b409SSimon J. Gerraty return cc->irsavrfy;
17290957b409SSimon J. Gerraty }
17300957b409SSimon J. Gerraty
17310957b409SSimon J. Gerraty /*
17320957b409SSimon J. Gerraty * \brief Set the ECDSA implementation (signature verification).
17330957b409SSimon J. Gerraty *
17340957b409SSimon J. Gerraty * On the client, this is used to verify the server's signature on its
17350957b409SSimon J. Gerraty * ServerKeyExchange message (for ECDHE_ECDSA cipher suites). On the server,
17360957b409SSimon J. Gerraty * this is used to verify the client's CertificateVerify message (if a
17370957b409SSimon J. Gerraty * client certificate is requested, that certificate contains an EC key,
17380957b409SSimon J. Gerraty * and full-static ECDH is not used).
17390957b409SSimon J. Gerraty *
17400957b409SSimon J. Gerraty * The ECDSA implementation will use the EC core implementation configured
17410957b409SSimon J. Gerraty * in the engine context.
17420957b409SSimon J. Gerraty *
17430957b409SSimon J. Gerraty * \param cc client context.
17440957b409SSimon J. Gerraty * \param iecdsa ECDSA verification implementation.
17450957b409SSimon J. Gerraty */
17460957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_ecdsa(br_ssl_engine_context * cc,br_ecdsa_vrfy iecdsa)17470957b409SSimon J. Gerraty br_ssl_engine_set_ecdsa(br_ssl_engine_context *cc, br_ecdsa_vrfy iecdsa)
17480957b409SSimon J. Gerraty {
17490957b409SSimon J. Gerraty cc->iecdsa = iecdsa;
17500957b409SSimon J. Gerraty }
17510957b409SSimon J. Gerraty
17520957b409SSimon J. Gerraty /**
17530957b409SSimon J. Gerraty * \brief Set the "default" ECDSA implementation (signature verification).
17540957b409SSimon J. Gerraty *
17550957b409SSimon J. Gerraty * This function sets the ECDSA implementation (signature verification)
17560957b409SSimon J. Gerraty * to the fastest implementation available on the current platform. This
17570957b409SSimon J. Gerraty * call also sets the elliptic curve implementation itself, there again
17580957b409SSimon J. Gerraty * to the fastest EC implementation available.
17590957b409SSimon J. Gerraty *
17600957b409SSimon J. Gerraty * \param cc SSL engine context.
17610957b409SSimon J. Gerraty */
17620957b409SSimon J. Gerraty void br_ssl_engine_set_default_ecdsa(br_ssl_engine_context *cc);
17630957b409SSimon J. Gerraty
17640957b409SSimon J. Gerraty /**
17650957b409SSimon J. Gerraty * \brief Get the ECDSA implementation (signature verification) configured
17660957b409SSimon J. Gerraty * in the provided engine.
17670957b409SSimon J. Gerraty *
17680957b409SSimon J. Gerraty * \param cc SSL engine context.
17690957b409SSimon J. Gerraty * \return the ECDSA signature verification implementation.
17700957b409SSimon J. Gerraty */
17710957b409SSimon J. Gerraty static inline br_ecdsa_vrfy
br_ssl_engine_get_ecdsa(br_ssl_engine_context * cc)17720957b409SSimon J. Gerraty br_ssl_engine_get_ecdsa(br_ssl_engine_context *cc)
17730957b409SSimon J. Gerraty {
17740957b409SSimon J. Gerraty return cc->iecdsa;
17750957b409SSimon J. Gerraty }
17760957b409SSimon J. Gerraty
17770957b409SSimon J. Gerraty /**
17780957b409SSimon J. Gerraty * \brief Set the I/O buffer for the SSL engine.
17790957b409SSimon J. Gerraty *
17800957b409SSimon J. Gerraty * Once this call has been made, `br_ssl_client_reset()` or
17810957b409SSimon J. Gerraty * `br_ssl_server_reset()` MUST be called before using the context.
17820957b409SSimon J. Gerraty *
17830957b409SSimon J. Gerraty * The provided buffer will be used as long as the engine context is
17840957b409SSimon J. Gerraty * used. The caller is responsible for keeping it available.
17850957b409SSimon J. Gerraty *
17860957b409SSimon J. Gerraty * If `bidi` is 0, then the engine will operate in half-duplex mode
17870957b409SSimon J. Gerraty * (it won't be able to send data while there is unprocessed incoming
17880957b409SSimon J. Gerraty * data in the buffer, and it won't be able to receive data while there
17890957b409SSimon J. Gerraty * is unsent data in the buffer). The optimal buffer size in half-duplex
17900957b409SSimon J. Gerraty * mode is `BR_SSL_BUFSIZE_MONO`; if the buffer is larger, then extra
17910957b409SSimon J. Gerraty * bytes are ignored. If the buffer is smaller, then this limits the
17920957b409SSimon J. Gerraty * capacity of the engine to support all allowed record sizes.
17930957b409SSimon J. Gerraty *
17940957b409SSimon J. Gerraty * If `bidi` is 1, then the engine will split the buffer into two
17950957b409SSimon J. Gerraty * parts, for separate handling of outgoing and incoming data. This
17960957b409SSimon J. Gerraty * enables full-duplex processing, but requires more RAM. The optimal
17970957b409SSimon J. Gerraty * buffer size in full-duplex mode is `BR_SSL_BUFSIZE_BIDI`; if the
17980957b409SSimon J. Gerraty * buffer is larger, then extra bytes are ignored. If the buffer is
17990957b409SSimon J. Gerraty * smaller, then the split will favour the incoming part, so that
18000957b409SSimon J. Gerraty * interoperability is maximised.
18010957b409SSimon J. Gerraty *
18020957b409SSimon J. Gerraty * \param cc SSL engine context
18030957b409SSimon J. Gerraty * \param iobuf I/O buffer.
18040957b409SSimon J. Gerraty * \param iobuf_len I/O buffer length (in bytes).
18050957b409SSimon J. Gerraty * \param bidi non-zero for full-duplex mode.
18060957b409SSimon J. Gerraty */
18070957b409SSimon J. Gerraty void br_ssl_engine_set_buffer(br_ssl_engine_context *cc,
18080957b409SSimon J. Gerraty void *iobuf, size_t iobuf_len, int bidi);
18090957b409SSimon J. Gerraty
18100957b409SSimon J. Gerraty /**
18110957b409SSimon J. Gerraty * \brief Set the I/O buffers for the SSL engine.
18120957b409SSimon J. Gerraty *
18130957b409SSimon J. Gerraty * Once this call has been made, `br_ssl_client_reset()` or
18140957b409SSimon J. Gerraty * `br_ssl_server_reset()` MUST be called before using the context.
18150957b409SSimon J. Gerraty *
18160957b409SSimon J. Gerraty * This function is similar to `br_ssl_engine_set_buffer()`, except
18170957b409SSimon J. Gerraty * that it enforces full-duplex mode, and the two I/O buffers are
18180957b409SSimon J. Gerraty * provided as separate chunks.
18190957b409SSimon J. Gerraty *
18200957b409SSimon J. Gerraty * The macros `BR_SSL_BUFSIZE_INPUT` and `BR_SSL_BUFSIZE_OUTPUT`
18210957b409SSimon J. Gerraty * evaluate to the optimal (maximum) sizes for the input and output
18220957b409SSimon J. Gerraty * buffer, respectively.
18230957b409SSimon J. Gerraty *
18240957b409SSimon J. Gerraty * \param cc SSL engine context
18250957b409SSimon J. Gerraty * \param ibuf input buffer.
18260957b409SSimon J. Gerraty * \param ibuf_len input buffer length (in bytes).
18270957b409SSimon J. Gerraty * \param obuf output buffer.
18280957b409SSimon J. Gerraty * \param obuf_len output buffer length (in bytes).
18290957b409SSimon J. Gerraty */
18300957b409SSimon J. Gerraty void br_ssl_engine_set_buffers_bidi(br_ssl_engine_context *cc,
18310957b409SSimon J. Gerraty void *ibuf, size_t ibuf_len, void *obuf, size_t obuf_len);
18320957b409SSimon J. Gerraty
18330957b409SSimon J. Gerraty /**
18340957b409SSimon J. Gerraty * \brief Inject some "initial entropy" in the context.
18350957b409SSimon J. Gerraty *
18360957b409SSimon J. Gerraty * This entropy will be added to what can be obtained from the
18370957b409SSimon J. Gerraty * underlying operating system, if that OS is supported.
18380957b409SSimon J. Gerraty *
18390957b409SSimon J. Gerraty * This function may be called several times; all injected entropy chunks
18400957b409SSimon J. Gerraty * are cumulatively mixed.
18410957b409SSimon J. Gerraty *
18420957b409SSimon J. Gerraty * If entropy gathering from the OS is supported and compiled in, then this
18430957b409SSimon J. Gerraty * step is optional. Otherwise, it is mandatory to inject randomness, and
18440957b409SSimon J. Gerraty * the caller MUST take care to push (as one or several successive calls)
18450957b409SSimon J. Gerraty * enough entropy to achieve cryptographic resistance (at least 80 bits,
18460957b409SSimon J. Gerraty * preferably 128 or more). The engine will report an error if no entropy
18470957b409SSimon J. Gerraty * was provided and none can be obtained from the OS.
18480957b409SSimon J. Gerraty *
18490957b409SSimon J. Gerraty * Take care that this function cannot assess the cryptographic quality of
18500957b409SSimon J. Gerraty * the provided bytes.
18510957b409SSimon J. Gerraty *
18520957b409SSimon J. Gerraty * In all generality, "entropy" must here be considered to mean "that
18530957b409SSimon J. Gerraty * which the attacker cannot predict". If your OS/architecture does not
18540957b409SSimon J. Gerraty * have a suitable source of randomness, then you can make do with the
18550957b409SSimon J. Gerraty * combination of a large enough secret value (possibly a copy of an
18560957b409SSimon J. Gerraty * asymmetric private key that you also store on the system) AND a
18570957b409SSimon J. Gerraty * non-repeating value (e.g. current time, provided that the local clock
18580957b409SSimon J. Gerraty * cannot be reset or altered by the attacker).
18590957b409SSimon J. Gerraty *
18600957b409SSimon J. Gerraty * \param cc SSL engine context.
18610957b409SSimon J. Gerraty * \param data extra entropy to inject.
18620957b409SSimon J. Gerraty * \param len length of the extra data (in bytes).
18630957b409SSimon J. Gerraty */
18640957b409SSimon J. Gerraty void br_ssl_engine_inject_entropy(br_ssl_engine_context *cc,
18650957b409SSimon J. Gerraty const void *data, size_t len);
18660957b409SSimon J. Gerraty
18670957b409SSimon J. Gerraty /**
18680957b409SSimon J. Gerraty * \brief Get the "server name" in this engine.
18690957b409SSimon J. Gerraty *
18700957b409SSimon J. Gerraty * For clients, this is the name provided with `br_ssl_client_reset()`;
18710957b409SSimon J. Gerraty * for servers, this is the name received from the client as part of the
18720957b409SSimon J. Gerraty * ClientHello message. If there is no such name (e.g. the client did
18730957b409SSimon J. Gerraty * not send an SNI extension) then the returned string is empty
18740957b409SSimon J. Gerraty * (returned pointer points to a byte of value 0).
18750957b409SSimon J. Gerraty *
18760957b409SSimon J. Gerraty * The returned pointer refers to a buffer inside the context, which may
18770957b409SSimon J. Gerraty * be overwritten as part of normal SSL activity (even within the same
18780957b409SSimon J. Gerraty * connection, if a renegotiation occurs).
18790957b409SSimon J. Gerraty *
18800957b409SSimon J. Gerraty * \param cc SSL engine context.
18810957b409SSimon J. Gerraty * \return the server name (possibly empty).
18820957b409SSimon J. Gerraty */
18830957b409SSimon J. Gerraty static inline const char *
br_ssl_engine_get_server_name(const br_ssl_engine_context * cc)18840957b409SSimon J. Gerraty br_ssl_engine_get_server_name(const br_ssl_engine_context *cc)
18850957b409SSimon J. Gerraty {
18860957b409SSimon J. Gerraty return cc->server_name;
18870957b409SSimon J. Gerraty }
18880957b409SSimon J. Gerraty
18890957b409SSimon J. Gerraty /**
18900957b409SSimon J. Gerraty * \brief Get the protocol version.
18910957b409SSimon J. Gerraty *
18920957b409SSimon J. Gerraty * This function returns the protocol version that is used by the
18930957b409SSimon J. Gerraty * engine. That value is set after sending (for a server) or receiving
18940957b409SSimon J. Gerraty * (for a client) the ServerHello message.
18950957b409SSimon J. Gerraty *
18960957b409SSimon J. Gerraty * \param cc SSL engine context.
18970957b409SSimon J. Gerraty * \return the protocol version.
18980957b409SSimon J. Gerraty */
18990957b409SSimon J. Gerraty static inline unsigned
br_ssl_engine_get_version(const br_ssl_engine_context * cc)19000957b409SSimon J. Gerraty br_ssl_engine_get_version(const br_ssl_engine_context *cc)
19010957b409SSimon J. Gerraty {
19020957b409SSimon J. Gerraty return cc->session.version;
19030957b409SSimon J. Gerraty }
19040957b409SSimon J. Gerraty
19050957b409SSimon J. Gerraty /**
19060957b409SSimon J. Gerraty * \brief Get a copy of the session parameters.
19070957b409SSimon J. Gerraty *
19080957b409SSimon J. Gerraty * The session parameters are filled during the handshake, so this
19090957b409SSimon J. Gerraty * function shall not be called before completion of the handshake.
19100957b409SSimon J. Gerraty * The initial handshake is completed when the context first allows
19110957b409SSimon J. Gerraty * application data to be injected.
19120957b409SSimon J. Gerraty *
19130957b409SSimon J. Gerraty * This function copies the current session parameters into the provided
19140957b409SSimon J. Gerraty * structure. Beware that the session parameters include the master
19150957b409SSimon J. Gerraty * secret, which is sensitive data, to handle with great care.
19160957b409SSimon J. Gerraty *
19170957b409SSimon J. Gerraty * \param cc SSL engine context.
19180957b409SSimon J. Gerraty * \param pp destination structure for the session parameters.
19190957b409SSimon J. Gerraty */
19200957b409SSimon J. Gerraty static inline void
br_ssl_engine_get_session_parameters(const br_ssl_engine_context * cc,br_ssl_session_parameters * pp)19210957b409SSimon J. Gerraty br_ssl_engine_get_session_parameters(const br_ssl_engine_context *cc,
19220957b409SSimon J. Gerraty br_ssl_session_parameters *pp)
19230957b409SSimon J. Gerraty {
19240957b409SSimon J. Gerraty memcpy(pp, &cc->session, sizeof *pp);
19250957b409SSimon J. Gerraty }
19260957b409SSimon J. Gerraty
19270957b409SSimon J. Gerraty /**
19280957b409SSimon J. Gerraty * \brief Set the session parameters to the provided values.
19290957b409SSimon J. Gerraty *
19300957b409SSimon J. Gerraty * This function is meant to be used in the client, before doing a new
19310957b409SSimon J. Gerraty * handshake; a session resumption will be attempted with these
19320957b409SSimon J. Gerraty * parameters. In the server, this function has no effect.
19330957b409SSimon J. Gerraty *
19340957b409SSimon J. Gerraty * \param cc SSL engine context.
19350957b409SSimon J. Gerraty * \param pp source structure for the session parameters.
19360957b409SSimon J. Gerraty */
19370957b409SSimon J. Gerraty static inline void
br_ssl_engine_set_session_parameters(br_ssl_engine_context * cc,const br_ssl_session_parameters * pp)19380957b409SSimon J. Gerraty br_ssl_engine_set_session_parameters(br_ssl_engine_context *cc,
19390957b409SSimon J. Gerraty const br_ssl_session_parameters *pp)
19400957b409SSimon J. Gerraty {
19410957b409SSimon J. Gerraty memcpy(&cc->session, pp, sizeof *pp);
19420957b409SSimon J. Gerraty }
19430957b409SSimon J. Gerraty
19440957b409SSimon J. Gerraty /**
19450957b409SSimon J. Gerraty * \brief Get identifier for the curve used for key exchange.
19460957b409SSimon J. Gerraty *
19470957b409SSimon J. Gerraty * If the cipher suite uses ECDHE, then this function returns the
19480957b409SSimon J. Gerraty * identifier for the curve used for transient parameters. This is
19490957b409SSimon J. Gerraty * defined during the course of the handshake, when the ServerKeyExchange
19500957b409SSimon J. Gerraty * is sent (on the server) or received (on the client). If the
19510957b409SSimon J. Gerraty * cipher suite does not use ECDHE (e.g. static ECDH, or RSA key
19520957b409SSimon J. Gerraty * exchange), then this value is indeterminate.
19530957b409SSimon J. Gerraty *
19540957b409SSimon J. Gerraty * @param cc SSL engine context.
19550957b409SSimon J. Gerraty * @return the ECDHE curve identifier.
19560957b409SSimon J. Gerraty */
19570957b409SSimon J. Gerraty static inline int
br_ssl_engine_get_ecdhe_curve(br_ssl_engine_context * cc)19580957b409SSimon J. Gerraty br_ssl_engine_get_ecdhe_curve(br_ssl_engine_context *cc)
19590957b409SSimon J. Gerraty {
19600957b409SSimon J. Gerraty return cc->ecdhe_curve;
19610957b409SSimon J. Gerraty }
19620957b409SSimon J. Gerraty
19630957b409SSimon J. Gerraty /**
19640957b409SSimon J. Gerraty * \brief Get the current engine state.
19650957b409SSimon J. Gerraty *
19660957b409SSimon J. Gerraty * An SSL engine (client or server) has, at any time, a state which is
19670957b409SSimon J. Gerraty * the combination of zero, one or more of these flags:
19680957b409SSimon J. Gerraty *
19690957b409SSimon J. Gerraty * - `BR_SSL_CLOSED`
19700957b409SSimon J. Gerraty *
19710957b409SSimon J. Gerraty * Engine is finished, no more I/O (until next reset).
19720957b409SSimon J. Gerraty *
19730957b409SSimon J. Gerraty * - `BR_SSL_SENDREC`
19740957b409SSimon J. Gerraty *
19750957b409SSimon J. Gerraty * Engine has some bytes to send to the peer.
19760957b409SSimon J. Gerraty *
19770957b409SSimon J. Gerraty * - `BR_SSL_RECVREC`
19780957b409SSimon J. Gerraty *
19790957b409SSimon J. Gerraty * Engine expects some bytes from the peer.
19800957b409SSimon J. Gerraty *
19810957b409SSimon J. Gerraty * - `BR_SSL_SENDAPP`
19820957b409SSimon J. Gerraty *
19830957b409SSimon J. Gerraty * Engine may receive application data to send (or flush).
19840957b409SSimon J. Gerraty *
19850957b409SSimon J. Gerraty * - `BR_SSL_RECVAPP`
19860957b409SSimon J. Gerraty *
19870957b409SSimon J. Gerraty * Engine has obtained some application data from the peer,
19880957b409SSimon J. Gerraty * that should be read by the caller.
19890957b409SSimon J. Gerraty *
19900957b409SSimon J. Gerraty * If no flag at all is set (state value is 0), then the engine is not
19910957b409SSimon J. Gerraty * fully initialised yet.
19920957b409SSimon J. Gerraty *
19930957b409SSimon J. Gerraty * The `BR_SSL_CLOSED` flag is exclusive; when it is set, no other flag
19940957b409SSimon J. Gerraty * is set. To distinguish between a normal closure and an error, use
19950957b409SSimon J. Gerraty * `br_ssl_engine_last_error()`.
19960957b409SSimon J. Gerraty *
19970957b409SSimon J. Gerraty * Generally speaking, `BR_SSL_SENDREC` and `BR_SSL_SENDAPP` are mutually
19980957b409SSimon J. Gerraty * exclusive: the input buffer, at any point, either accumulates
19990957b409SSimon J. Gerraty * plaintext data, or contains an assembled record that is being sent.
20000957b409SSimon J. Gerraty * Similarly, `BR_SSL_RECVREC` and `BR_SSL_RECVAPP` are mutually exclusive.
20010957b409SSimon J. Gerraty * This may change in a future library version.
20020957b409SSimon J. Gerraty *
20030957b409SSimon J. Gerraty * \param cc SSL engine context.
20040957b409SSimon J. Gerraty * \return the current engine state.
20050957b409SSimon J. Gerraty */
20060957b409SSimon J. Gerraty unsigned br_ssl_engine_current_state(const br_ssl_engine_context *cc);
20070957b409SSimon J. Gerraty
20080957b409SSimon J. Gerraty /** \brief SSL engine state: closed or failed. */
20090957b409SSimon J. Gerraty #define BR_SSL_CLOSED 0x0001
20100957b409SSimon J. Gerraty /** \brief SSL engine state: record data is ready to be sent to the peer. */
20110957b409SSimon J. Gerraty #define BR_SSL_SENDREC 0x0002
20120957b409SSimon J. Gerraty /** \brief SSL engine state: engine may receive records from the peer. */
20130957b409SSimon J. Gerraty #define BR_SSL_RECVREC 0x0004
20140957b409SSimon J. Gerraty /** \brief SSL engine state: engine may accept application data to send. */
20150957b409SSimon J. Gerraty #define BR_SSL_SENDAPP 0x0008
20160957b409SSimon J. Gerraty /** \brief SSL engine state: engine has received application data. */
20170957b409SSimon J. Gerraty #define BR_SSL_RECVAPP 0x0010
20180957b409SSimon J. Gerraty
20190957b409SSimon J. Gerraty /**
20200957b409SSimon J. Gerraty * \brief Get the engine error indicator.
20210957b409SSimon J. Gerraty *
20220957b409SSimon J. Gerraty * The error indicator is `BR_ERR_OK` (0) if no error was encountered
20230957b409SSimon J. Gerraty * since the last call to `br_ssl_client_reset()` or
20240957b409SSimon J. Gerraty * `br_ssl_server_reset()`. Other status values are "sticky": they
20250957b409SSimon J. Gerraty * remain set, and prevent all I/O activity, until cleared. Only the
20260957b409SSimon J. Gerraty * reset calls clear the error indicator.
20270957b409SSimon J. Gerraty *
20280957b409SSimon J. Gerraty * \param cc SSL engine context.
20290957b409SSimon J. Gerraty * \return 0, or a non-zero error code.
20300957b409SSimon J. Gerraty */
20310957b409SSimon J. Gerraty static inline int
br_ssl_engine_last_error(const br_ssl_engine_context * cc)20320957b409SSimon J. Gerraty br_ssl_engine_last_error(const br_ssl_engine_context *cc)
20330957b409SSimon J. Gerraty {
20340957b409SSimon J. Gerraty return cc->err;
20350957b409SSimon J. Gerraty }
20360957b409SSimon J. Gerraty
20370957b409SSimon J. Gerraty /*
20380957b409SSimon J. Gerraty * There are four I/O operations, each identified by a symbolic name:
20390957b409SSimon J. Gerraty *
20400957b409SSimon J. Gerraty * sendapp inject application data in the engine
20410957b409SSimon J. Gerraty * recvapp retrieving application data from the engine
20420957b409SSimon J. Gerraty * sendrec sending records on the transport medium
20430957b409SSimon J. Gerraty * recvrec receiving records from the transport medium
20440957b409SSimon J. Gerraty *
20450957b409SSimon J. Gerraty * Terminology works thus: in a layered model where the SSL engine sits
20460957b409SSimon J. Gerraty * between the application and the network, "send" designates operations
20470957b409SSimon J. Gerraty * where bytes flow from application to network, and "recv" for the
20480957b409SSimon J. Gerraty * reverse operation. Application data (the plaintext that is to be
20490957b409SSimon J. Gerraty * conveyed through SSL) is "app", while encrypted records are "rec".
20500957b409SSimon J. Gerraty * Note that from the SSL engine point of view, "sendapp" and "recvrec"
20510957b409SSimon J. Gerraty * designate bytes that enter the engine ("inject" operation), while
20520957b409SSimon J. Gerraty * "recvapp" and "sendrec" designate bytes that exit the engine
20530957b409SSimon J. Gerraty * ("extract" operation).
20540957b409SSimon J. Gerraty *
20550957b409SSimon J. Gerraty * For the operation 'xxx', two functions are defined:
20560957b409SSimon J. Gerraty *
20570957b409SSimon J. Gerraty * br_ssl_engine_xxx_buf
20580957b409SSimon J. Gerraty * Returns a pointer and length to the buffer to use for that
20590957b409SSimon J. Gerraty * operation. '*len' is set to the number of bytes that may be read
20600957b409SSimon J. Gerraty * from the buffer (extract operation) or written to the buffer
20610957b409SSimon J. Gerraty * (inject operation). If no byte may be exchanged for that operation
20620957b409SSimon J. Gerraty * at that point, then '*len' is set to zero, and NULL is returned.
20630957b409SSimon J. Gerraty * The engine state is unmodified by this call.
20640957b409SSimon J. Gerraty *
20650957b409SSimon J. Gerraty * br_ssl_engine_xxx_ack
20660957b409SSimon J. Gerraty * Informs the engine that 'len' bytes have been read from the buffer
20670957b409SSimon J. Gerraty * (extract operation) or written to the buffer (inject operation).
20680957b409SSimon J. Gerraty * The 'len' value MUST NOT be zero. The 'len' value MUST NOT exceed
20690957b409SSimon J. Gerraty * that which was obtained from a preceding br_ssl_engine_xxx_buf()
20700957b409SSimon J. Gerraty * call.
20710957b409SSimon J. Gerraty */
20720957b409SSimon J. Gerraty
20730957b409SSimon J. Gerraty /**
20740957b409SSimon J. Gerraty * \brief Get buffer for application data to send.
20750957b409SSimon J. Gerraty *
20760957b409SSimon J. Gerraty * If the engine is ready to accept application data to send to the
20770957b409SSimon J. Gerraty * peer, then this call returns a pointer to the buffer where such
20780957b409SSimon J. Gerraty * data shall be written, and its length is written in `*len`.
20790957b409SSimon J. Gerraty * Otherwise, `*len` is set to 0 and `NULL` is returned.
20800957b409SSimon J. Gerraty *
20810957b409SSimon J. Gerraty * \param cc SSL engine context.
20820957b409SSimon J. Gerraty * \param len receives the application data output buffer length, or 0.
20830957b409SSimon J. Gerraty * \return the application data output buffer, or `NULL`.
20840957b409SSimon J. Gerraty */
20850957b409SSimon J. Gerraty unsigned char *br_ssl_engine_sendapp_buf(
20860957b409SSimon J. Gerraty const br_ssl_engine_context *cc, size_t *len);
20870957b409SSimon J. Gerraty
20880957b409SSimon J. Gerraty /**
20890957b409SSimon J. Gerraty * \brief Inform the engine of some new application data.
20900957b409SSimon J. Gerraty *
20910957b409SSimon J. Gerraty * After writing `len` bytes in the buffer returned by
20920957b409SSimon J. Gerraty * `br_ssl_engine_sendapp_buf()`, the application shall call this
20930957b409SSimon J. Gerraty * function to trigger any relevant processing. The `len` parameter
20940957b409SSimon J. Gerraty * MUST NOT be 0, and MUST NOT exceed the value obtained in the
20950957b409SSimon J. Gerraty * `br_ssl_engine_sendapp_buf()` call.
20960957b409SSimon J. Gerraty *
20970957b409SSimon J. Gerraty * \param cc SSL engine context.
20980957b409SSimon J. Gerraty * \param len number of bytes pushed (not zero).
20990957b409SSimon J. Gerraty */
21000957b409SSimon J. Gerraty void br_ssl_engine_sendapp_ack(br_ssl_engine_context *cc, size_t len);
21010957b409SSimon J. Gerraty
21020957b409SSimon J. Gerraty /**
21030957b409SSimon J. Gerraty * \brief Get buffer for received application data.
21040957b409SSimon J. Gerraty *
2105*cc9e6590SSimon J. Gerraty * If the engine has received application data from the peer, then this
21060957b409SSimon J. Gerraty * call returns a pointer to the buffer from where such data shall be
21070957b409SSimon J. Gerraty * read, and its length is written in `*len`. Otherwise, `*len` is set
21080957b409SSimon J. Gerraty * to 0 and `NULL` is returned.
21090957b409SSimon J. Gerraty *
21100957b409SSimon J. Gerraty * \param cc SSL engine context.
21110957b409SSimon J. Gerraty * \param len receives the application data input buffer length, or 0.
21120957b409SSimon J. Gerraty * \return the application data input buffer, or `NULL`.
21130957b409SSimon J. Gerraty */
21140957b409SSimon J. Gerraty unsigned char *br_ssl_engine_recvapp_buf(
21150957b409SSimon J. Gerraty const br_ssl_engine_context *cc, size_t *len);
21160957b409SSimon J. Gerraty
21170957b409SSimon J. Gerraty /**
21180957b409SSimon J. Gerraty * \brief Acknowledge some received application data.
21190957b409SSimon J. Gerraty *
21200957b409SSimon J. Gerraty * After reading `len` bytes from the buffer returned by
21210957b409SSimon J. Gerraty * `br_ssl_engine_recvapp_buf()`, the application shall call this
21220957b409SSimon J. Gerraty * function to trigger any relevant processing. The `len` parameter
21230957b409SSimon J. Gerraty * MUST NOT be 0, and MUST NOT exceed the value obtained in the
21240957b409SSimon J. Gerraty * `br_ssl_engine_recvapp_buf()` call.
21250957b409SSimon J. Gerraty *
21260957b409SSimon J. Gerraty * \param cc SSL engine context.
21270957b409SSimon J. Gerraty * \param len number of bytes read (not zero).
21280957b409SSimon J. Gerraty */
21290957b409SSimon J. Gerraty void br_ssl_engine_recvapp_ack(br_ssl_engine_context *cc, size_t len);
21300957b409SSimon J. Gerraty
21310957b409SSimon J. Gerraty /**
21320957b409SSimon J. Gerraty * \brief Get buffer for record data to send.
21330957b409SSimon J. Gerraty *
21340957b409SSimon J. Gerraty * If the engine has prepared some records to send to the peer, then this
21350957b409SSimon J. Gerraty * call returns a pointer to the buffer from where such data shall be
21360957b409SSimon J. Gerraty * read, and its length is written in `*len`. Otherwise, `*len` is set
21370957b409SSimon J. Gerraty * to 0 and `NULL` is returned.
21380957b409SSimon J. Gerraty *
21390957b409SSimon J. Gerraty * \param cc SSL engine context.
21400957b409SSimon J. Gerraty * \param len receives the record data output buffer length, or 0.
21410957b409SSimon J. Gerraty * \return the record data output buffer, or `NULL`.
21420957b409SSimon J. Gerraty */
21430957b409SSimon J. Gerraty unsigned char *br_ssl_engine_sendrec_buf(
21440957b409SSimon J. Gerraty const br_ssl_engine_context *cc, size_t *len);
21450957b409SSimon J. Gerraty
21460957b409SSimon J. Gerraty /**
21470957b409SSimon J. Gerraty * \brief Acknowledge some sent record data.
21480957b409SSimon J. Gerraty *
21490957b409SSimon J. Gerraty * After reading `len` bytes from the buffer returned by
21500957b409SSimon J. Gerraty * `br_ssl_engine_sendrec_buf()`, the application shall call this
21510957b409SSimon J. Gerraty * function to trigger any relevant processing. The `len` parameter
21520957b409SSimon J. Gerraty * MUST NOT be 0, and MUST NOT exceed the value obtained in the
21530957b409SSimon J. Gerraty * `br_ssl_engine_sendrec_buf()` call.
21540957b409SSimon J. Gerraty *
21550957b409SSimon J. Gerraty * \param cc SSL engine context.
21560957b409SSimon J. Gerraty * \param len number of bytes read (not zero).
21570957b409SSimon J. Gerraty */
21580957b409SSimon J. Gerraty void br_ssl_engine_sendrec_ack(br_ssl_engine_context *cc, size_t len);
21590957b409SSimon J. Gerraty
21600957b409SSimon J. Gerraty /**
21610957b409SSimon J. Gerraty * \brief Get buffer for incoming records.
21620957b409SSimon J. Gerraty *
21630957b409SSimon J. Gerraty * If the engine is ready to accept records from the peer, then this
21640957b409SSimon J. Gerraty * call returns a pointer to the buffer where such data shall be
21650957b409SSimon J. Gerraty * written, and its length is written in `*len`. Otherwise, `*len` is
21660957b409SSimon J. Gerraty * set to 0 and `NULL` is returned.
21670957b409SSimon J. Gerraty *
21680957b409SSimon J. Gerraty * \param cc SSL engine context.
21690957b409SSimon J. Gerraty * \param len receives the record data input buffer length, or 0.
21700957b409SSimon J. Gerraty * \return the record data input buffer, or `NULL`.
21710957b409SSimon J. Gerraty */
21720957b409SSimon J. Gerraty unsigned char *br_ssl_engine_recvrec_buf(
21730957b409SSimon J. Gerraty const br_ssl_engine_context *cc, size_t *len);
21740957b409SSimon J. Gerraty
21750957b409SSimon J. Gerraty /**
21760957b409SSimon J. Gerraty * \brief Inform the engine of some new record data.
21770957b409SSimon J. Gerraty *
21780957b409SSimon J. Gerraty * After writing `len` bytes in the buffer returned by
21790957b409SSimon J. Gerraty * `br_ssl_engine_recvrec_buf()`, the application shall call this
21800957b409SSimon J. Gerraty * function to trigger any relevant processing. The `len` parameter
21810957b409SSimon J. Gerraty * MUST NOT be 0, and MUST NOT exceed the value obtained in the
21820957b409SSimon J. Gerraty * `br_ssl_engine_recvrec_buf()` call.
21830957b409SSimon J. Gerraty *
21840957b409SSimon J. Gerraty * \param cc SSL engine context.
21850957b409SSimon J. Gerraty * \param len number of bytes pushed (not zero).
21860957b409SSimon J. Gerraty */
21870957b409SSimon J. Gerraty void br_ssl_engine_recvrec_ack(br_ssl_engine_context *cc, size_t len);
21880957b409SSimon J. Gerraty
21890957b409SSimon J. Gerraty /**
21900957b409SSimon J. Gerraty * \brief Flush buffered application data.
21910957b409SSimon J. Gerraty *
21920957b409SSimon J. Gerraty * If some application data has been buffered in the engine, then wrap
21930957b409SSimon J. Gerraty * it into a record and mark it for sending. If no application data has
21940957b409SSimon J. Gerraty * been buffered but the engine would be ready to accept some, AND the
21950957b409SSimon J. Gerraty * `force` parameter is non-zero, then an empty record is assembled and
21960957b409SSimon J. Gerraty * marked for sending. In all other cases, this function does nothing.
21970957b409SSimon J. Gerraty *
21980957b409SSimon J. Gerraty * Empty records are technically legal, but not all existing SSL/TLS
21990957b409SSimon J. Gerraty * implementations support them. Empty records can be useful as a
22000957b409SSimon J. Gerraty * transparent "keep-alive" mechanism to maintain some low-level
22010957b409SSimon J. Gerraty * network activity.
22020957b409SSimon J. Gerraty *
22030957b409SSimon J. Gerraty * \param cc SSL engine context.
22040957b409SSimon J. Gerraty * \param force non-zero to force sending an empty record.
22050957b409SSimon J. Gerraty */
22060957b409SSimon J. Gerraty void br_ssl_engine_flush(br_ssl_engine_context *cc, int force);
22070957b409SSimon J. Gerraty
22080957b409SSimon J. Gerraty /**
22090957b409SSimon J. Gerraty * \brief Initiate a closure.
22100957b409SSimon J. Gerraty *
22110957b409SSimon J. Gerraty * If, at that point, the context is open and in ready state, then a
22120957b409SSimon J. Gerraty * `close_notify` alert is assembled and marked for sending; this
22130957b409SSimon J. Gerraty * triggers the closure protocol. Otherwise, no such alert is assembled.
22140957b409SSimon J. Gerraty *
22150957b409SSimon J. Gerraty * \param cc SSL engine context.
22160957b409SSimon J. Gerraty */
22170957b409SSimon J. Gerraty void br_ssl_engine_close(br_ssl_engine_context *cc);
22180957b409SSimon J. Gerraty
22190957b409SSimon J. Gerraty /**
22200957b409SSimon J. Gerraty * \brief Initiate a renegotiation.
22210957b409SSimon J. Gerraty *
22220957b409SSimon J. Gerraty * If the engine is failed or closed, or if the peer is known not to
22230957b409SSimon J. Gerraty * support secure renegotiation (RFC 5746), or if renegotiations have
22240957b409SSimon J. Gerraty * been disabled with the `BR_OPT_NO_RENEGOTIATION` flag, or if there
22250957b409SSimon J. Gerraty * is buffered incoming application data, then this function returns 0
22260957b409SSimon J. Gerraty * and nothing else happens.
22270957b409SSimon J. Gerraty *
22280957b409SSimon J. Gerraty * Otherwise, this function returns 1, and a renegotiation attempt is
22290957b409SSimon J. Gerraty * triggered (if a handshake is already ongoing at that point, then
22300957b409SSimon J. Gerraty * no new handshake is triggered).
22310957b409SSimon J. Gerraty *
22320957b409SSimon J. Gerraty * \param cc SSL engine context.
22330957b409SSimon J. Gerraty * \return 1 on success, 0 on error.
22340957b409SSimon J. Gerraty */
22350957b409SSimon J. Gerraty int br_ssl_engine_renegotiate(br_ssl_engine_context *cc);
22360957b409SSimon J. Gerraty
22370957b409SSimon J. Gerraty /**
22380957b409SSimon J. Gerraty * \brief Export key material from a connected SSL engine (RFC 5705).
22390957b409SSimon J. Gerraty *
22400957b409SSimon J. Gerraty * This calls compute a secret key of arbitrary length from the master
22410957b409SSimon J. Gerraty * secret of a connected SSL engine. If the provided context is not
22420957b409SSimon J. Gerraty * currently in "application data" state (initial handshake is not
22430957b409SSimon J. Gerraty * finished, another handshake is ongoing, or the connection failed or
22440957b409SSimon J. Gerraty * was closed), then this function returns 0. Otherwise, a secret key of
22450957b409SSimon J. Gerraty * length `len` bytes is computed and written in the buffer pointed to
22460957b409SSimon J. Gerraty * by `dst`, and 1 is returned.
22470957b409SSimon J. Gerraty *
22480957b409SSimon J. Gerraty * The computed key follows the specification described in RFC 5705.
22490957b409SSimon J. Gerraty * That RFC includes two key computations, with and without a "context
22500957b409SSimon J. Gerraty * value". If `context` is `NULL`, then the variant without context is
22510957b409SSimon J. Gerraty * used; otherwise, the `context_len` bytes located at the address
22520957b409SSimon J. Gerraty * pointed to by `context` are used in the computation. Note that it
22530957b409SSimon J. Gerraty * is possible to have a "with context" key with a context length of
22540957b409SSimon J. Gerraty * zero bytes, by setting `context` to a non-`NULL` value but
22550957b409SSimon J. Gerraty * `context_len` to 0.
22560957b409SSimon J. Gerraty *
22570957b409SSimon J. Gerraty * When context bytes are used, the context length MUST NOT exceed
22580957b409SSimon J. Gerraty * 65535 bytes.
22590957b409SSimon J. Gerraty *
22600957b409SSimon J. Gerraty * \param cc SSL engine context.
22610957b409SSimon J. Gerraty * \param dst destination buffer for exported key.
22620957b409SSimon J. Gerraty * \param len exported key length (in bytes).
22630957b409SSimon J. Gerraty * \param label disambiguation label.
22640957b409SSimon J. Gerraty * \param context context value (or `NULL`).
22650957b409SSimon J. Gerraty * \param context_len context length (in bytes).
22660957b409SSimon J. Gerraty * \return 1 on success, 0 on error.
22670957b409SSimon J. Gerraty */
22680957b409SSimon J. Gerraty int br_ssl_key_export(br_ssl_engine_context *cc,
22690957b409SSimon J. Gerraty void *dst, size_t len, const char *label,
22700957b409SSimon J. Gerraty const void *context, size_t context_len);
22710957b409SSimon J. Gerraty
22720957b409SSimon J. Gerraty /*
22730957b409SSimon J. Gerraty * Pre-declaration for the SSL client context.
22740957b409SSimon J. Gerraty */
22750957b409SSimon J. Gerraty typedef struct br_ssl_client_context_ br_ssl_client_context;
22760957b409SSimon J. Gerraty
22770957b409SSimon J. Gerraty /**
22780957b409SSimon J. Gerraty * \brief Type for the client certificate, if requested by the server.
22790957b409SSimon J. Gerraty */
22800957b409SSimon J. Gerraty typedef struct {
22810957b409SSimon J. Gerraty /**
22820957b409SSimon J. Gerraty * \brief Authentication type.
22830957b409SSimon J. Gerraty *
22840957b409SSimon J. Gerraty * This is either `BR_AUTH_RSA` (RSA signature), `BR_AUTH_ECDSA`
22850957b409SSimon J. Gerraty * (ECDSA signature), or `BR_AUTH_ECDH` (static ECDH key exchange).
22860957b409SSimon J. Gerraty */
22870957b409SSimon J. Gerraty int auth_type;
22880957b409SSimon J. Gerraty
22890957b409SSimon J. Gerraty /**
22900957b409SSimon J. Gerraty * \brief Hash function for computing the CertificateVerify.
22910957b409SSimon J. Gerraty *
22920957b409SSimon J. Gerraty * This is the symbolic identifier for the hash function that
22930957b409SSimon J. Gerraty * will be used to produce the hash of handshake messages, to
22940957b409SSimon J. Gerraty * be signed into the CertificateVerify. For full static ECDH
22950957b409SSimon J. Gerraty * (client and server certificates are both EC in the same
22960957b409SSimon J. Gerraty * curve, and static ECDH is used), this value is set to -1.
22970957b409SSimon J. Gerraty *
22980957b409SSimon J. Gerraty * Take care that with TLS 1.0 and 1.1, that value MUST match
22990957b409SSimon J. Gerraty * the protocol requirements: value must be 0 (MD5+SHA-1) for
23000957b409SSimon J. Gerraty * a RSA signature, or 2 (SHA-1) for an ECDSA signature. Only
23010957b409SSimon J. Gerraty * TLS 1.2 allows for other hash functions.
23020957b409SSimon J. Gerraty */
23030957b409SSimon J. Gerraty int hash_id;
23040957b409SSimon J. Gerraty
23050957b409SSimon J. Gerraty /**
23060957b409SSimon J. Gerraty * \brief Certificate chain to send to the server.
23070957b409SSimon J. Gerraty *
23080957b409SSimon J. Gerraty * This is an array of `br_x509_certificate` objects, each
23090957b409SSimon J. Gerraty * normally containing a DER-encoded certificate. The client
23100957b409SSimon J. Gerraty * code does not try to decode these elements. If there is no
23110957b409SSimon J. Gerraty * chain to send to the server, then this pointer shall be
23120957b409SSimon J. Gerraty * set to `NULL`.
23130957b409SSimon J. Gerraty */
23140957b409SSimon J. Gerraty const br_x509_certificate *chain;
23150957b409SSimon J. Gerraty
23160957b409SSimon J. Gerraty /**
23170957b409SSimon J. Gerraty * \brief Certificate chain length (number of certificates).
23180957b409SSimon J. Gerraty *
23190957b409SSimon J. Gerraty * If there is no chain to send to the server, then this value
23200957b409SSimon J. Gerraty * shall be set to 0.
23210957b409SSimon J. Gerraty */
23220957b409SSimon J. Gerraty size_t chain_len;
23230957b409SSimon J. Gerraty
23240957b409SSimon J. Gerraty } br_ssl_client_certificate;
23250957b409SSimon J. Gerraty
23260957b409SSimon J. Gerraty /*
23270957b409SSimon J. Gerraty * Note: the constants below for signatures match the TLS constants.
23280957b409SSimon J. Gerraty */
23290957b409SSimon J. Gerraty
23300957b409SSimon J. Gerraty /** \brief Client authentication type: static ECDH. */
23310957b409SSimon J. Gerraty #define BR_AUTH_ECDH 0
23320957b409SSimon J. Gerraty /** \brief Client authentication type: RSA signature. */
23330957b409SSimon J. Gerraty #define BR_AUTH_RSA 1
23340957b409SSimon J. Gerraty /** \brief Client authentication type: ECDSA signature. */
23350957b409SSimon J. Gerraty #define BR_AUTH_ECDSA 3
23360957b409SSimon J. Gerraty
23370957b409SSimon J. Gerraty /**
23380957b409SSimon J. Gerraty * \brief Class type for a certificate handler (client side).
23390957b409SSimon J. Gerraty *
23400957b409SSimon J. Gerraty * A certificate handler selects a client certificate chain to send to
23410957b409SSimon J. Gerraty * the server, upon explicit request from that server. It receives
23420957b409SSimon J. Gerraty * the list of trust anchor DN from the server, and supported types
23430957b409SSimon J. Gerraty * of certificates and signatures, and returns the chain to use. It
23440957b409SSimon J. Gerraty * is also invoked to perform the corresponding private key operation
23450957b409SSimon J. Gerraty * (a signature, or an ECDH computation).
23460957b409SSimon J. Gerraty *
23470957b409SSimon J. Gerraty * The SSL client engine will first push the trust anchor DN with
23480957b409SSimon J. Gerraty * `start_name_list()`, `start_name()`, `append_name()`, `end_name()`
23490957b409SSimon J. Gerraty * and `end_name_list()`. Then it will call `choose()`, to select the
23500957b409SSimon J. Gerraty * actual chain (and signature/hash algorithms). Finally, it will call
23510957b409SSimon J. Gerraty * either `do_sign()` or `do_keyx()`, depending on the algorithm choices.
23520957b409SSimon J. Gerraty */
23530957b409SSimon J. Gerraty typedef struct br_ssl_client_certificate_class_ br_ssl_client_certificate_class;
23540957b409SSimon J. Gerraty struct br_ssl_client_certificate_class_ {
23550957b409SSimon J. Gerraty /**
23560957b409SSimon J. Gerraty * \brief Context size (in bytes).
23570957b409SSimon J. Gerraty */
23580957b409SSimon J. Gerraty size_t context_size;
23590957b409SSimon J. Gerraty
23600957b409SSimon J. Gerraty /**
23610957b409SSimon J. Gerraty * \brief Begin reception of a list of trust anchor names. This
23620957b409SSimon J. Gerraty * is called while parsing the incoming CertificateRequest.
23630957b409SSimon J. Gerraty *
23640957b409SSimon J. Gerraty * \param pctx certificate handler context.
23650957b409SSimon J. Gerraty */
23660957b409SSimon J. Gerraty void (*start_name_list)(const br_ssl_client_certificate_class **pctx);
23670957b409SSimon J. Gerraty
23680957b409SSimon J. Gerraty /**
23690957b409SSimon J. Gerraty * \brief Begin reception of a new trust anchor name.
23700957b409SSimon J. Gerraty *
23710957b409SSimon J. Gerraty * The total encoded name length is provided; it is less than
23720957b409SSimon J. Gerraty * 65535 bytes.
23730957b409SSimon J. Gerraty *
23740957b409SSimon J. Gerraty * \param pctx certificate handler context.
23750957b409SSimon J. Gerraty * \param len encoded name length (in bytes).
23760957b409SSimon J. Gerraty */
23770957b409SSimon J. Gerraty void (*start_name)(const br_ssl_client_certificate_class **pctx,
23780957b409SSimon J. Gerraty size_t len);
23790957b409SSimon J. Gerraty
23800957b409SSimon J. Gerraty /**
23810957b409SSimon J. Gerraty * \brief Receive some more bytes for the current trust anchor name.
23820957b409SSimon J. Gerraty *
23830957b409SSimon J. Gerraty * The provided reference (`data`) points to a transient buffer
23840957b409SSimon J. Gerraty * they may be reused as soon as this function returns. The chunk
23850957b409SSimon J. Gerraty * length (`len`) is never zero.
23860957b409SSimon J. Gerraty *
23870957b409SSimon J. Gerraty * \param pctx certificate handler context.
23880957b409SSimon J. Gerraty * \param data anchor name chunk.
23890957b409SSimon J. Gerraty * \param len anchor name chunk length (in bytes).
23900957b409SSimon J. Gerraty */
23910957b409SSimon J. Gerraty void (*append_name)(const br_ssl_client_certificate_class **pctx,
23920957b409SSimon J. Gerraty const unsigned char *data, size_t len);
23930957b409SSimon J. Gerraty
23940957b409SSimon J. Gerraty /**
23950957b409SSimon J. Gerraty * \brief End current trust anchor name.
23960957b409SSimon J. Gerraty *
23970957b409SSimon J. Gerraty * This function is called when all the encoded anchor name data
23980957b409SSimon J. Gerraty * has been provided.
23990957b409SSimon J. Gerraty *
24000957b409SSimon J. Gerraty * \param pctx certificate handler context.
24010957b409SSimon J. Gerraty */
24020957b409SSimon J. Gerraty void (*end_name)(const br_ssl_client_certificate_class **pctx);
24030957b409SSimon J. Gerraty
24040957b409SSimon J. Gerraty /**
24050957b409SSimon J. Gerraty * \brief End list of trust anchor names.
24060957b409SSimon J. Gerraty *
24070957b409SSimon J. Gerraty * This function is called when all the anchor names in the
24080957b409SSimon J. Gerraty * CertificateRequest message have been obtained.
24090957b409SSimon J. Gerraty *
24100957b409SSimon J. Gerraty * \param pctx certificate handler context.
24110957b409SSimon J. Gerraty */
24120957b409SSimon J. Gerraty void (*end_name_list)(const br_ssl_client_certificate_class **pctx);
24130957b409SSimon J. Gerraty
24140957b409SSimon J. Gerraty /**
24150957b409SSimon J. Gerraty * \brief Select client certificate and algorithms.
24160957b409SSimon J. Gerraty *
24170957b409SSimon J. Gerraty * This callback function shall fill the provided `choices`
24180957b409SSimon J. Gerraty * structure with the selected algorithms and certificate chain.
24190957b409SSimon J. Gerraty * The `hash_id`, `chain` and `chain_len` fields must be set. If
24200957b409SSimon J. Gerraty * the client cannot or does not wish to send a certificate,
24210957b409SSimon J. Gerraty * then it shall set `chain` to `NULL` and `chain_len` to 0.
24220957b409SSimon J. Gerraty *
24230957b409SSimon J. Gerraty * The `auth_types` parameter describes the authentication types,
24240957b409SSimon J. Gerraty * signature algorithms and hash functions that are supported by
24250957b409SSimon J. Gerraty * both the client context and the server, and compatible with
24260957b409SSimon J. Gerraty * the current protocol version. This is a bit field with the
24270957b409SSimon J. Gerraty * following contents:
24280957b409SSimon J. Gerraty *
24290957b409SSimon J. Gerraty * - If RSA signatures with hash function x are supported, then
24300957b409SSimon J. Gerraty * bit x is set.
24310957b409SSimon J. Gerraty *
24320957b409SSimon J. Gerraty * - If ECDSA signatures with hash function x are supported,
24330957b409SSimon J. Gerraty * then bit 8+x is set.
24340957b409SSimon J. Gerraty *
24350957b409SSimon J. Gerraty * - If static ECDH is supported, with a RSA-signed certificate,
24360957b409SSimon J. Gerraty * then bit 16 is set.
24370957b409SSimon J. Gerraty *
24380957b409SSimon J. Gerraty * - If static ECDH is supported, with an ECDSA-signed certificate,
24390957b409SSimon J. Gerraty * then bit 17 is set.
24400957b409SSimon J. Gerraty *
24410957b409SSimon J. Gerraty * Notes:
24420957b409SSimon J. Gerraty *
24430957b409SSimon J. Gerraty * - When using TLS 1.0 or 1.1, the hash function for RSA
24440957b409SSimon J. Gerraty * signatures is always the special MD5+SHA-1 (id 0), and the
24450957b409SSimon J. Gerraty * hash function for ECDSA signatures is always SHA-1 (id 2).
24460957b409SSimon J. Gerraty *
24470957b409SSimon J. Gerraty * - When using TLS 1.2, the list of hash functions is trimmed
24480957b409SSimon J. Gerraty * down to include only hash functions that the client context
24490957b409SSimon J. Gerraty * can support. The actual server list can be obtained with
24500957b409SSimon J. Gerraty * `br_ssl_client_get_server_hashes()`; that list may be used
24510957b409SSimon J. Gerraty * to select the certificate chain to send to the server.
24520957b409SSimon J. Gerraty *
24530957b409SSimon J. Gerraty * \param pctx certificate handler context.
24540957b409SSimon J. Gerraty * \param cc SSL client context.
24550957b409SSimon J. Gerraty * \param auth_types supported authentication types and algorithms.
24560957b409SSimon J. Gerraty * \param choices destination structure for the policy choices.
24570957b409SSimon J. Gerraty */
24580957b409SSimon J. Gerraty void (*choose)(const br_ssl_client_certificate_class **pctx,
24590957b409SSimon J. Gerraty const br_ssl_client_context *cc, uint32_t auth_types,
24600957b409SSimon J. Gerraty br_ssl_client_certificate *choices);
24610957b409SSimon J. Gerraty
24620957b409SSimon J. Gerraty /**
24630957b409SSimon J. Gerraty * \brief Perform key exchange (client part).
24640957b409SSimon J. Gerraty *
24650957b409SSimon J. Gerraty * This callback is invoked in case of a full static ECDH key
24660957b409SSimon J. Gerraty * exchange:
24670957b409SSimon J. Gerraty *
24680957b409SSimon J. Gerraty * - the cipher suite uses `ECDH_RSA` or `ECDH_ECDSA`;
24690957b409SSimon J. Gerraty *
24700957b409SSimon J. Gerraty * - the server requests a client certificate;
24710957b409SSimon J. Gerraty *
24720957b409SSimon J. Gerraty * - the client has, and sends, a client certificate that
24730957b409SSimon J. Gerraty * uses an EC key in the same curve as the server's key,
24740957b409SSimon J. Gerraty * and chooses static ECDH (the `hash_id` field in the choice
24750957b409SSimon J. Gerraty * structure was set to -1).
24760957b409SSimon J. Gerraty *
24770957b409SSimon J. Gerraty * In that situation, this callback is invoked to compute the
24780957b409SSimon J. Gerraty * client-side ECDH: the provided `data` (of length `*len` bytes)
24790957b409SSimon J. Gerraty * is the server's public key point (as decoded from its
24800957b409SSimon J. Gerraty * certificate), and the client shall multiply that point with
24810957b409SSimon J. Gerraty * its own private key, and write back the X coordinate of the
24820957b409SSimon J. Gerraty * resulting point in the same buffer, starting at offset 0.
24830957b409SSimon J. Gerraty * The `*len` value shall be modified to designate the actual
24840957b409SSimon J. Gerraty * length of the X coordinate.
24850957b409SSimon J. Gerraty *
24860957b409SSimon J. Gerraty * The callback must uphold the following:
24870957b409SSimon J. Gerraty *
24880957b409SSimon J. Gerraty * - If the input array does not have the proper length for
24890957b409SSimon J. Gerraty * an encoded curve point, then an error (0) shall be reported.
24900957b409SSimon J. Gerraty *
24910957b409SSimon J. Gerraty * - If the input array has the proper length, then processing
24920957b409SSimon J. Gerraty * MUST be constant-time, even if the data is not a valid
24930957b409SSimon J. Gerraty * encoded point.
24940957b409SSimon J. Gerraty *
24950957b409SSimon J. Gerraty * - This callback MUST check that the input point is valid.
24960957b409SSimon J. Gerraty *
24970957b409SSimon J. Gerraty * Returned value is 1 on success, 0 on error.
24980957b409SSimon J. Gerraty *
24990957b409SSimon J. Gerraty * \param pctx certificate handler context.
25000957b409SSimon J. Gerraty * \param data server public key point.
25010957b409SSimon J. Gerraty * \param len public key point length / X coordinate length.
25020957b409SSimon J. Gerraty * \return 1 on success, 0 on error.
25030957b409SSimon J. Gerraty */
25040957b409SSimon J. Gerraty uint32_t (*do_keyx)(const br_ssl_client_certificate_class **pctx,
25050957b409SSimon J. Gerraty unsigned char *data, size_t *len);
25060957b409SSimon J. Gerraty
25070957b409SSimon J. Gerraty /**
25080957b409SSimon J. Gerraty * \brief Perform a signature (client authentication).
25090957b409SSimon J. Gerraty *
25100957b409SSimon J. Gerraty * This callback is invoked when a client certificate was sent,
25110957b409SSimon J. Gerraty * and static ECDH is not used. It shall compute a signature,
25120957b409SSimon J. Gerraty * using the client's private key, over the provided hash value
25130957b409SSimon J. Gerraty * (which is the hash of all previous handshake messages).
25140957b409SSimon J. Gerraty *
25150957b409SSimon J. Gerraty * On input, the hash value to sign is in `data`, of size
25160957b409SSimon J. Gerraty * `hv_len`; the involved hash function is identified by
25170957b409SSimon J. Gerraty * `hash_id`. The signature shall be computed and written
25180957b409SSimon J. Gerraty * back into `data`; the total size of that buffer is `len`
25190957b409SSimon J. Gerraty * bytes.
25200957b409SSimon J. Gerraty *
25210957b409SSimon J. Gerraty * This callback shall verify that the signature length does not
25220957b409SSimon J. Gerraty * exceed `len` bytes, and abstain from writing the signature if
25230957b409SSimon J. Gerraty * it does not fit.
25240957b409SSimon J. Gerraty *
25250957b409SSimon J. Gerraty * For RSA signatures, the `hash_id` may be 0, in which case
25260957b409SSimon J. Gerraty * this is the special header-less signature specified in TLS 1.0
25270957b409SSimon J. Gerraty * and 1.1, with a 36-byte hash value. Otherwise, normal PKCS#1
25280957b409SSimon J. Gerraty * v1.5 signatures shall be computed.
25290957b409SSimon J. Gerraty *
25300957b409SSimon J. Gerraty * For ECDSA signatures, the signature value shall use the ASN.1
25310957b409SSimon J. Gerraty * based encoding.
25320957b409SSimon J. Gerraty *
25330957b409SSimon J. Gerraty * Returned value is the signature length (in bytes), or 0 on error.
25340957b409SSimon J. Gerraty *
25350957b409SSimon J. Gerraty * \param pctx certificate handler context.
25360957b409SSimon J. Gerraty * \param hash_id hash function identifier.
25370957b409SSimon J. Gerraty * \param hv_len hash value length (in bytes).
25380957b409SSimon J. Gerraty * \param data input/output buffer (hash value, then signature).
25390957b409SSimon J. Gerraty * \param len total buffer length (in bytes).
25400957b409SSimon J. Gerraty * \return signature length (in bytes) on success, or 0 on error.
25410957b409SSimon J. Gerraty */
25420957b409SSimon J. Gerraty size_t (*do_sign)(const br_ssl_client_certificate_class **pctx,
25430957b409SSimon J. Gerraty int hash_id, size_t hv_len, unsigned char *data, size_t len);
25440957b409SSimon J. Gerraty };
25450957b409SSimon J. Gerraty
25460957b409SSimon J. Gerraty /**
25470957b409SSimon J. Gerraty * \brief A single-chain RSA client certificate handler.
25480957b409SSimon J. Gerraty *
25490957b409SSimon J. Gerraty * This handler uses a single certificate chain, with a RSA
25500957b409SSimon J. Gerraty * signature. The list of trust anchor DN is ignored.
25510957b409SSimon J. Gerraty *
25520957b409SSimon J. Gerraty * Apart from the first field (vtable pointer), its contents are
25530957b409SSimon J. Gerraty * opaque and shall not be accessed directly.
25540957b409SSimon J. Gerraty */
25550957b409SSimon J. Gerraty typedef struct {
25560957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
25570957b409SSimon J. Gerraty const br_ssl_client_certificate_class *vtable;
25580957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
25590957b409SSimon J. Gerraty const br_x509_certificate *chain;
25600957b409SSimon J. Gerraty size_t chain_len;
25610957b409SSimon J. Gerraty const br_rsa_private_key *sk;
25620957b409SSimon J. Gerraty br_rsa_pkcs1_sign irsasign;
25630957b409SSimon J. Gerraty #endif
25640957b409SSimon J. Gerraty } br_ssl_client_certificate_rsa_context;
25650957b409SSimon J. Gerraty
25660957b409SSimon J. Gerraty /**
25670957b409SSimon J. Gerraty * \brief A single-chain EC client certificate handler.
25680957b409SSimon J. Gerraty *
25690957b409SSimon J. Gerraty * This handler uses a single certificate chain, with a RSA
25700957b409SSimon J. Gerraty * signature. The list of trust anchor DN is ignored.
25710957b409SSimon J. Gerraty *
25720957b409SSimon J. Gerraty * This handler may support both static ECDH, and ECDSA signatures
25730957b409SSimon J. Gerraty * (either usage may be selectively disabled).
25740957b409SSimon J. Gerraty *
25750957b409SSimon J. Gerraty * Apart from the first field (vtable pointer), its contents are
25760957b409SSimon J. Gerraty * opaque and shall not be accessed directly.
25770957b409SSimon J. Gerraty */
25780957b409SSimon J. Gerraty typedef struct {
25790957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
25800957b409SSimon J. Gerraty const br_ssl_client_certificate_class *vtable;
25810957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
25820957b409SSimon J. Gerraty const br_x509_certificate *chain;
25830957b409SSimon J. Gerraty size_t chain_len;
25840957b409SSimon J. Gerraty const br_ec_private_key *sk;
25850957b409SSimon J. Gerraty unsigned allowed_usages;
25860957b409SSimon J. Gerraty unsigned issuer_key_type;
25870957b409SSimon J. Gerraty const br_multihash_context *mhash;
25880957b409SSimon J. Gerraty const br_ec_impl *iec;
25890957b409SSimon J. Gerraty br_ecdsa_sign iecdsa;
25900957b409SSimon J. Gerraty #endif
25910957b409SSimon J. Gerraty } br_ssl_client_certificate_ec_context;
25920957b409SSimon J. Gerraty
25930957b409SSimon J. Gerraty /**
25940957b409SSimon J. Gerraty * \brief Context structure for a SSL client.
25950957b409SSimon J. Gerraty *
25960957b409SSimon J. Gerraty * The first field (called `eng`) is the SSL engine; all functions that
25970957b409SSimon J. Gerraty * work on a `br_ssl_engine_context` structure shall take as parameter
25980957b409SSimon J. Gerraty * a pointer to that field. The other structure fields are opaque and
25990957b409SSimon J. Gerraty * must not be accessed directly.
26000957b409SSimon J. Gerraty */
26010957b409SSimon J. Gerraty struct br_ssl_client_context_ {
26020957b409SSimon J. Gerraty /**
26030957b409SSimon J. Gerraty * \brief The encapsulated engine context.
26040957b409SSimon J. Gerraty */
26050957b409SSimon J. Gerraty br_ssl_engine_context eng;
26060957b409SSimon J. Gerraty
26070957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
26080957b409SSimon J. Gerraty /*
26090957b409SSimon J. Gerraty * Minimum ClientHello length; padding with an extension (RFC
26100957b409SSimon J. Gerraty * 7685) is added if necessary to match at least that length.
26110957b409SSimon J. Gerraty * Such padding is nominally unnecessary, but it has been used
26120957b409SSimon J. Gerraty * to work around some server implementation bugs.
26130957b409SSimon J. Gerraty */
26140957b409SSimon J. Gerraty uint16_t min_clienthello_len;
26150957b409SSimon J. Gerraty
26160957b409SSimon J. Gerraty /*
26170957b409SSimon J. Gerraty * Bit field for algoithms (hash + signature) supported by the
26180957b409SSimon J. Gerraty * server when requesting a client certificate.
26190957b409SSimon J. Gerraty */
26200957b409SSimon J. Gerraty uint32_t hashes;
26210957b409SSimon J. Gerraty
26220957b409SSimon J. Gerraty /*
26230957b409SSimon J. Gerraty * Server's public key curve.
26240957b409SSimon J. Gerraty */
26250957b409SSimon J. Gerraty int server_curve;
26260957b409SSimon J. Gerraty
26270957b409SSimon J. Gerraty /*
26280957b409SSimon J. Gerraty * Context for certificate handler.
26290957b409SSimon J. Gerraty */
26300957b409SSimon J. Gerraty const br_ssl_client_certificate_class **client_auth_vtable;
26310957b409SSimon J. Gerraty
26320957b409SSimon J. Gerraty /*
26330957b409SSimon J. Gerraty * Client authentication type.
26340957b409SSimon J. Gerraty */
26350957b409SSimon J. Gerraty unsigned char auth_type;
26360957b409SSimon J. Gerraty
26370957b409SSimon J. Gerraty /*
26380957b409SSimon J. Gerraty * Hash function to use for the client signature. This is 0xFF
26390957b409SSimon J. Gerraty * if static ECDH is used.
26400957b409SSimon J. Gerraty */
26410957b409SSimon J. Gerraty unsigned char hash_id;
26420957b409SSimon J. Gerraty
26430957b409SSimon J. Gerraty /*
26440957b409SSimon J. Gerraty * For the core certificate handlers, thus avoiding (in most
26450957b409SSimon J. Gerraty * cases) the need for an externally provided policy context.
26460957b409SSimon J. Gerraty */
26470957b409SSimon J. Gerraty union {
26480957b409SSimon J. Gerraty const br_ssl_client_certificate_class *vtable;
26490957b409SSimon J. Gerraty br_ssl_client_certificate_rsa_context single_rsa;
26500957b409SSimon J. Gerraty br_ssl_client_certificate_ec_context single_ec;
26510957b409SSimon J. Gerraty } client_auth;
26520957b409SSimon J. Gerraty
26530957b409SSimon J. Gerraty /*
26540957b409SSimon J. Gerraty * Implementations.
26550957b409SSimon J. Gerraty */
26560957b409SSimon J. Gerraty br_rsa_public irsapub;
26570957b409SSimon J. Gerraty #endif
26580957b409SSimon J. Gerraty };
26590957b409SSimon J. Gerraty
26600957b409SSimon J. Gerraty /**
26610957b409SSimon J. Gerraty * \brief Get the hash functions and signature algorithms supported by
26620957b409SSimon J. Gerraty * the server.
26630957b409SSimon J. Gerraty *
26640957b409SSimon J. Gerraty * This value is a bit field:
26650957b409SSimon J. Gerraty *
26660957b409SSimon J. Gerraty * - If RSA (PKCS#1 v1.5) is supported with hash function of ID `x`,
26670957b409SSimon J. Gerraty * then bit `x` is set (hash function ID is 0 for the special MD5+SHA-1,
26680957b409SSimon J. Gerraty * or 2 to 6 for the SHA family).
26690957b409SSimon J. Gerraty *
26700957b409SSimon J. Gerraty * - If ECDSA is supported with hash function of ID `x`, then bit `8+x`
26710957b409SSimon J. Gerraty * is set.
26720957b409SSimon J. Gerraty *
26730957b409SSimon J. Gerraty * - Newer algorithms are symbolic 16-bit identifiers that do not
26740957b409SSimon J. Gerraty * represent signature algorithm and hash function separately. If
26750957b409SSimon J. Gerraty * the TLS-level identifier is `0x0800+x` for a `x` in the 0..15
26760957b409SSimon J. Gerraty * range, then bit `16+x` is set.
26770957b409SSimon J. Gerraty *
26780957b409SSimon J. Gerraty * "New algorithms" are currently defined only in draft documents, so
26790957b409SSimon J. Gerraty * this support is subject to possible change. Right now (early 2017),
26800957b409SSimon J. Gerraty * this maps ed25519 (EdDSA on Curve25519) to bit 23, and ed448 (EdDSA
26810957b409SSimon J. Gerraty * on Curve448) to bit 24. If the identifiers on the wire change in
26820957b409SSimon J. Gerraty * future document, then the decoding mechanism in BearSSL will be
26830957b409SSimon J. Gerraty * amended to keep mapping ed25519 and ed448 on bits 23 and 24,
26840957b409SSimon J. Gerraty * respectively. Mapping of other new algorithms (e.g. RSA/PSS) is not
26850957b409SSimon J. Gerraty * guaranteed yet.
26860957b409SSimon J. Gerraty *
26870957b409SSimon J. Gerraty * \param cc client context.
26880957b409SSimon J. Gerraty * \return the server-supported hash functions and signature algorithms.
26890957b409SSimon J. Gerraty */
26900957b409SSimon J. Gerraty static inline uint32_t
br_ssl_client_get_server_hashes(const br_ssl_client_context * cc)26910957b409SSimon J. Gerraty br_ssl_client_get_server_hashes(const br_ssl_client_context *cc)
26920957b409SSimon J. Gerraty {
26930957b409SSimon J. Gerraty return cc->hashes;
26940957b409SSimon J. Gerraty }
26950957b409SSimon J. Gerraty
26960957b409SSimon J. Gerraty /**
26970957b409SSimon J. Gerraty * \brief Get the server key curve.
26980957b409SSimon J. Gerraty *
26990957b409SSimon J. Gerraty * This function returns the ID for the curve used by the server's public
27000957b409SSimon J. Gerraty * key. This is set when the server's certificate chain is processed;
27010957b409SSimon J. Gerraty * this value is 0 if the server's key is not an EC key.
27020957b409SSimon J. Gerraty *
27030957b409SSimon J. Gerraty * \return the server's public key curve ID, or 0.
27040957b409SSimon J. Gerraty */
27050957b409SSimon J. Gerraty static inline int
br_ssl_client_get_server_curve(const br_ssl_client_context * cc)27060957b409SSimon J. Gerraty br_ssl_client_get_server_curve(const br_ssl_client_context *cc)
27070957b409SSimon J. Gerraty {
27080957b409SSimon J. Gerraty return cc->server_curve;
27090957b409SSimon J. Gerraty }
27100957b409SSimon J. Gerraty
27110957b409SSimon J. Gerraty /*
27120957b409SSimon J. Gerraty * Each br_ssl_client_init_xxx() function sets the list of supported
27130957b409SSimon J. Gerraty * cipher suites and used implementations, as specified by the profile
27140957b409SSimon J. Gerraty * name 'xxx'. Defined profile names are:
27150957b409SSimon J. Gerraty *
27160957b409SSimon J. Gerraty * full all supported versions and suites; constant-time implementations
27170957b409SSimon J. Gerraty * TODO: add other profiles
27180957b409SSimon J. Gerraty */
27190957b409SSimon J. Gerraty
27200957b409SSimon J. Gerraty /**
27210957b409SSimon J. Gerraty * \brief SSL client profile: full.
27220957b409SSimon J. Gerraty *
27230957b409SSimon J. Gerraty * This function initialises the provided SSL client context with
27240957b409SSimon J. Gerraty * all supported algorithms and cipher suites. It also initialises
27250957b409SSimon J. Gerraty * a companion X.509 validation engine with all supported algorithms,
27260957b409SSimon J. Gerraty * and the provided trust anchors; the X.509 engine will be used by
27270957b409SSimon J. Gerraty * the client context to validate the server's certificate.
27280957b409SSimon J. Gerraty *
27290957b409SSimon J. Gerraty * \param cc client context to initialise.
27300957b409SSimon J. Gerraty * \param xc X.509 validation context to initialise.
27310957b409SSimon J. Gerraty * \param trust_anchors trust anchors to use.
27320957b409SSimon J. Gerraty * \param trust_anchors_num number of trust anchors.
27330957b409SSimon J. Gerraty */
27340957b409SSimon J. Gerraty void br_ssl_client_init_full(br_ssl_client_context *cc,
27350957b409SSimon J. Gerraty br_x509_minimal_context *xc,
27360957b409SSimon J. Gerraty const br_x509_trust_anchor *trust_anchors, size_t trust_anchors_num);
27370957b409SSimon J. Gerraty
27380957b409SSimon J. Gerraty /**
27390957b409SSimon J. Gerraty * \brief Clear the complete contents of a SSL client context.
27400957b409SSimon J. Gerraty *
27410957b409SSimon J. Gerraty * Everything is cleared, including the reference to the configured buffer,
27420957b409SSimon J. Gerraty * implementations, cipher suites and state. This is a preparatory step
27430957b409SSimon J. Gerraty * to assembling a custom profile.
27440957b409SSimon J. Gerraty *
27450957b409SSimon J. Gerraty * \param cc client context to clear.
27460957b409SSimon J. Gerraty */
27470957b409SSimon J. Gerraty void br_ssl_client_zero(br_ssl_client_context *cc);
27480957b409SSimon J. Gerraty
27490957b409SSimon J. Gerraty /**
27500957b409SSimon J. Gerraty * \brief Set an externally provided client certificate handler context.
27510957b409SSimon J. Gerraty *
27520957b409SSimon J. Gerraty * The handler's methods are invoked when the server requests a client
27530957b409SSimon J. Gerraty * certificate.
27540957b409SSimon J. Gerraty *
27550957b409SSimon J. Gerraty * \param cc client context.
27560957b409SSimon J. Gerraty * \param pctx certificate handler context (pointer to its vtable field).
27570957b409SSimon J. Gerraty */
27580957b409SSimon J. Gerraty static inline void
br_ssl_client_set_client_certificate(br_ssl_client_context * cc,const br_ssl_client_certificate_class ** pctx)27590957b409SSimon J. Gerraty br_ssl_client_set_client_certificate(br_ssl_client_context *cc,
27600957b409SSimon J. Gerraty const br_ssl_client_certificate_class **pctx)
27610957b409SSimon J. Gerraty {
27620957b409SSimon J. Gerraty cc->client_auth_vtable = pctx;
27630957b409SSimon J. Gerraty }
27640957b409SSimon J. Gerraty
27650957b409SSimon J. Gerraty /**
27660957b409SSimon J. Gerraty * \brief Set the RSA public-key operations implementation.
27670957b409SSimon J. Gerraty *
27680957b409SSimon J. Gerraty * This will be used to encrypt the pre-master secret with the server's
27690957b409SSimon J. Gerraty * RSA public key (RSA-encryption cipher suites only).
27700957b409SSimon J. Gerraty *
27710957b409SSimon J. Gerraty * \param cc client context.
27720957b409SSimon J. Gerraty * \param irsapub RSA public-key encryption implementation.
27730957b409SSimon J. Gerraty */
27740957b409SSimon J. Gerraty static inline void
br_ssl_client_set_rsapub(br_ssl_client_context * cc,br_rsa_public irsapub)27750957b409SSimon J. Gerraty br_ssl_client_set_rsapub(br_ssl_client_context *cc, br_rsa_public irsapub)
27760957b409SSimon J. Gerraty {
27770957b409SSimon J. Gerraty cc->irsapub = irsapub;
27780957b409SSimon J. Gerraty }
27790957b409SSimon J. Gerraty
27800957b409SSimon J. Gerraty /**
27810957b409SSimon J. Gerraty * \brief Set the "default" RSA implementation for public-key operations.
27820957b409SSimon J. Gerraty *
27830957b409SSimon J. Gerraty * This sets the RSA implementation in the client context (for encrypting
27840957b409SSimon J. Gerraty * the pre-master secret, in `TLS_RSA_*` cipher suites) to the fastest
27850957b409SSimon J. Gerraty * available on the current platform.
27860957b409SSimon J. Gerraty *
27870957b409SSimon J. Gerraty * \param cc client context.
27880957b409SSimon J. Gerraty */
27890957b409SSimon J. Gerraty void br_ssl_client_set_default_rsapub(br_ssl_client_context *cc);
27900957b409SSimon J. Gerraty
27910957b409SSimon J. Gerraty /**
27920957b409SSimon J. Gerraty * \brief Set the minimum ClientHello length (RFC 7685 padding).
27930957b409SSimon J. Gerraty *
27940957b409SSimon J. Gerraty * If this value is set and the ClientHello would be shorter, then
27950957b409SSimon J. Gerraty * the Pad ClientHello extension will be added with enough padding bytes
27960957b409SSimon J. Gerraty * to reach the target size. Because of the extension header, the resulting
27970957b409SSimon J. Gerraty * size will sometimes be slightly more than `len` bytes if the target
27980957b409SSimon J. Gerraty * size cannot be exactly met.
27990957b409SSimon J. Gerraty *
28000957b409SSimon J. Gerraty * The target length relates to the _contents_ of the ClientHello, not
28010957b409SSimon J. Gerraty * counting its 4-byte header. For instance, if `len` is set to 512,
28020957b409SSimon J. Gerraty * then the padding will bring the ClientHello size to 516 bytes with its
28030957b409SSimon J. Gerraty * header, and 521 bytes when counting the 5-byte record header.
28040957b409SSimon J. Gerraty *
28050957b409SSimon J. Gerraty * \param cc client context.
28060957b409SSimon J. Gerraty * \param len minimum ClientHello length (in bytes).
28070957b409SSimon J. Gerraty */
28080957b409SSimon J. Gerraty static inline void
br_ssl_client_set_min_clienthello_len(br_ssl_client_context * cc,uint16_t len)28090957b409SSimon J. Gerraty br_ssl_client_set_min_clienthello_len(br_ssl_client_context *cc, uint16_t len)
28100957b409SSimon J. Gerraty {
28110957b409SSimon J. Gerraty cc->min_clienthello_len = len;
28120957b409SSimon J. Gerraty }
28130957b409SSimon J. Gerraty
28140957b409SSimon J. Gerraty /**
28150957b409SSimon J. Gerraty * \brief Prepare or reset a client context for a new connection.
28160957b409SSimon J. Gerraty *
28170957b409SSimon J. Gerraty * The `server_name` parameter is used to fill the SNI extension; the
28180957b409SSimon J. Gerraty * X.509 "minimal" engine will also match that name against the server
28190957b409SSimon J. Gerraty * names included in the server's certificate. If the parameter is
28200957b409SSimon J. Gerraty * `NULL` then no SNI extension will be sent, and the X.509 "minimal"
28210957b409SSimon J. Gerraty * engine (if used for server certificate validation) will not check
28220957b409SSimon J. Gerraty * presence of any specific name in the received certificate.
28230957b409SSimon J. Gerraty *
28240957b409SSimon J. Gerraty * Therefore, setting the `server_name` to `NULL` shall be reserved
28250957b409SSimon J. Gerraty * to cases where alternate or additional methods are used to ascertain
28260957b409SSimon J. Gerraty * that the right server public key is used (e.g. a "known key" model).
28270957b409SSimon J. Gerraty *
28280957b409SSimon J. Gerraty * If `resume_session` is non-zero and the context was previously used
28290957b409SSimon J. Gerraty * then the session parameters may be reused (depending on whether the
28300957b409SSimon J. Gerraty * server previously sent a non-empty session ID, and accepts the session
28310957b409SSimon J. Gerraty * resumption). The session parameters for session resumption can also
28320957b409SSimon J. Gerraty * be set explicitly with `br_ssl_engine_set_session_parameters()`.
28330957b409SSimon J. Gerraty *
28340957b409SSimon J. Gerraty * On failure, the context is marked as failed, and this function
28350957b409SSimon J. Gerraty * returns 0. A possible failure condition is when no initial entropy
28360957b409SSimon J. Gerraty * was injected, and none could be obtained from the OS (either OS
28370957b409SSimon J. Gerraty * randomness gathering is not supported, or it failed).
28380957b409SSimon J. Gerraty *
28390957b409SSimon J. Gerraty * \param cc client context.
28400957b409SSimon J. Gerraty * \param server_name target server name, or `NULL`.
28410957b409SSimon J. Gerraty * \param resume_session non-zero to try session resumption.
28420957b409SSimon J. Gerraty * \return 0 on failure, 1 on success.
28430957b409SSimon J. Gerraty */
28440957b409SSimon J. Gerraty int br_ssl_client_reset(br_ssl_client_context *cc,
28450957b409SSimon J. Gerraty const char *server_name, int resume_session);
28460957b409SSimon J. Gerraty
28470957b409SSimon J. Gerraty /**
28480957b409SSimon J. Gerraty * \brief Forget any session in the context.
28490957b409SSimon J. Gerraty *
28500957b409SSimon J. Gerraty * This means that the next handshake that uses this context will
28510957b409SSimon J. Gerraty * necessarily be a full handshake (this applies both to new connections
28520957b409SSimon J. Gerraty * and to renegotiations).
28530957b409SSimon J. Gerraty *
28540957b409SSimon J. Gerraty * \param cc client context.
28550957b409SSimon J. Gerraty */
28560957b409SSimon J. Gerraty static inline void
br_ssl_client_forget_session(br_ssl_client_context * cc)28570957b409SSimon J. Gerraty br_ssl_client_forget_session(br_ssl_client_context *cc)
28580957b409SSimon J. Gerraty {
28590957b409SSimon J. Gerraty cc->eng.session.session_id_len = 0;
28600957b409SSimon J. Gerraty }
28610957b409SSimon J. Gerraty
28620957b409SSimon J. Gerraty /**
28630957b409SSimon J. Gerraty * \brief Set client certificate chain and key (single RSA case).
28640957b409SSimon J. Gerraty *
28650957b409SSimon J. Gerraty * This function sets a client certificate chain, that the client will
28660957b409SSimon J. Gerraty * send to the server whenever a client certificate is requested. This
28670957b409SSimon J. Gerraty * certificate uses an RSA public key; the corresponding private key is
28680957b409SSimon J. Gerraty * invoked for authentication. Trust anchor names sent by the server are
28690957b409SSimon J. Gerraty * ignored.
28700957b409SSimon J. Gerraty *
28710957b409SSimon J. Gerraty * The provided chain and private key are linked in the client context;
28720957b409SSimon J. Gerraty * they must remain valid as long as they may be used, i.e. normally
28730957b409SSimon J. Gerraty * for the duration of the connection, since they might be invoked
28740957b409SSimon J. Gerraty * again upon renegotiations.
28750957b409SSimon J. Gerraty *
28760957b409SSimon J. Gerraty * \param cc SSL client context.
28770957b409SSimon J. Gerraty * \param chain client certificate chain (SSL order: EE comes first).
28780957b409SSimon J. Gerraty * \param chain_len client chain length (number of certificates).
28790957b409SSimon J. Gerraty * \param sk client private key.
28800957b409SSimon J. Gerraty * \param irsasign RSA signature implementation (PKCS#1 v1.5).
28810957b409SSimon J. Gerraty */
28820957b409SSimon J. Gerraty void br_ssl_client_set_single_rsa(br_ssl_client_context *cc,
28830957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
28840957b409SSimon J. Gerraty const br_rsa_private_key *sk, br_rsa_pkcs1_sign irsasign);
28850957b409SSimon J. Gerraty
28860957b409SSimon J. Gerraty /*
28870957b409SSimon J. Gerraty * \brief Set the client certificate chain and key (single EC case).
28880957b409SSimon J. Gerraty *
28890957b409SSimon J. Gerraty * This function sets a client certificate chain, that the client will
28900957b409SSimon J. Gerraty * send to the server whenever a client certificate is requested. This
28910957b409SSimon J. Gerraty * certificate uses an EC public key; the corresponding private key is
28920957b409SSimon J. Gerraty * invoked for authentication. Trust anchor names sent by the server are
28930957b409SSimon J. Gerraty * ignored.
28940957b409SSimon J. Gerraty *
28950957b409SSimon J. Gerraty * The provided chain and private key are linked in the client context;
28960957b409SSimon J. Gerraty * they must remain valid as long as they may be used, i.e. normally
28970957b409SSimon J. Gerraty * for the duration of the connection, since they might be invoked
28980957b409SSimon J. Gerraty * again upon renegotiations.
28990957b409SSimon J. Gerraty *
29000957b409SSimon J. Gerraty * The `allowed_usages` is a combination of usages, namely
29010957b409SSimon J. Gerraty * `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`. The `BR_KEYTYPE_KEYX`
29020957b409SSimon J. Gerraty * value allows full static ECDH, while the `BR_KEYTYPE_SIGN` value
29030957b409SSimon J. Gerraty * allows ECDSA signatures. If ECDSA signatures are used, then an ECDSA
29040957b409SSimon J. Gerraty * signature implementation must be provided; otherwise, the `iecdsa`
29050957b409SSimon J. Gerraty * parameter may be 0.
29060957b409SSimon J. Gerraty *
29070957b409SSimon J. Gerraty * The `cert_issuer_key_type` value is either `BR_KEYTYPE_RSA` or
29080957b409SSimon J. Gerraty * `BR_KEYTYPE_EC`; it is the type of the public key used the the CA
29090957b409SSimon J. Gerraty * that issued (signed) the client certificate. That value is used with
29100957b409SSimon J. Gerraty * full static ECDH: support of the certificate by the server depends
29110957b409SSimon J. Gerraty * on how the certificate was signed. (Note: when using TLS 1.2, this
29120957b409SSimon J. Gerraty * parameter is ignored; but its value matters for TLS 1.0 and 1.1.)
29130957b409SSimon J. Gerraty *
29140957b409SSimon J. Gerraty * \param cc server context.
29150957b409SSimon J. Gerraty * \param chain server certificate chain to send.
29160957b409SSimon J. Gerraty * \param chain_len chain length (number of certificates).
29170957b409SSimon J. Gerraty * \param sk server private key (EC).
29180957b409SSimon J. Gerraty * \param allowed_usages allowed private key usages.
29190957b409SSimon J. Gerraty * \param cert_issuer_key_type issuing CA's key type.
29200957b409SSimon J. Gerraty * \param iec EC core implementation.
29210957b409SSimon J. Gerraty * \param iecdsa ECDSA signature implementation ("asn1" format).
29220957b409SSimon J. Gerraty */
29230957b409SSimon J. Gerraty void br_ssl_client_set_single_ec(br_ssl_client_context *cc,
29240957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
29250957b409SSimon J. Gerraty const br_ec_private_key *sk, unsigned allowed_usages,
29260957b409SSimon J. Gerraty unsigned cert_issuer_key_type,
29270957b409SSimon J. Gerraty const br_ec_impl *iec, br_ecdsa_sign iecdsa);
29280957b409SSimon J. Gerraty
29290957b409SSimon J. Gerraty /**
29300957b409SSimon J. Gerraty * \brief Type for a "translated cipher suite", as an array of two
29310957b409SSimon J. Gerraty * 16-bit integers.
29320957b409SSimon J. Gerraty *
29330957b409SSimon J. Gerraty * The first element is the cipher suite identifier (as used on the wire).
29340957b409SSimon J. Gerraty * The second element is the concatenation of four 4-bit elements which
29350957b409SSimon J. Gerraty * characterise the cipher suite contents. In most to least significant
29360957b409SSimon J. Gerraty * order, these 4-bit elements are:
29370957b409SSimon J. Gerraty *
29380957b409SSimon J. Gerraty * - Bits 12 to 15: key exchange + server key type
29390957b409SSimon J. Gerraty *
29400957b409SSimon J. Gerraty * | val | symbolic constant | suite type | details |
29410957b409SSimon J. Gerraty * | :-- | :----------------------- | :---------- | :----------------------------------------------- |
29420957b409SSimon J. Gerraty * | 0 | `BR_SSLKEYX_RSA` | RSA | RSA key exchange, key is RSA (encryption) |
29430957b409SSimon J. Gerraty * | 1 | `BR_SSLKEYX_ECDHE_RSA` | ECDHE_RSA | ECDHE key exchange, key is RSA (signature) |
29440957b409SSimon J. Gerraty * | 2 | `BR_SSLKEYX_ECDHE_ECDSA` | ECDHE_ECDSA | ECDHE key exchange, key is EC (signature) |
29450957b409SSimon J. Gerraty * | 3 | `BR_SSLKEYX_ECDH_RSA` | ECDH_RSA | Key is EC (key exchange), cert signed with RSA |
29460957b409SSimon J. Gerraty * | 4 | `BR_SSLKEYX_ECDH_ECDSA` | ECDH_ECDSA | Key is EC (key exchange), cert signed with ECDSA |
29470957b409SSimon J. Gerraty *
29480957b409SSimon J. Gerraty * - Bits 8 to 11: symmetric encryption algorithm
29490957b409SSimon J. Gerraty *
29500957b409SSimon J. Gerraty * | val | symbolic constant | symmetric encryption | key strength (bits) |
29510957b409SSimon J. Gerraty * | :-- | :--------------------- | :------------------- | :------------------ |
29520957b409SSimon J. Gerraty * | 0 | `BR_SSLENC_3DES_CBC` | 3DES/CBC | 168 |
29530957b409SSimon J. Gerraty * | 1 | `BR_SSLENC_AES128_CBC` | AES-128/CBC | 128 |
29540957b409SSimon J. Gerraty * | 2 | `BR_SSLENC_AES256_CBC` | AES-256/CBC | 256 |
29550957b409SSimon J. Gerraty * | 3 | `BR_SSLENC_AES128_GCM` | AES-128/GCM | 128 |
29560957b409SSimon J. Gerraty * | 4 | `BR_SSLENC_AES256_GCM` | AES-256/GCM | 256 |
29570957b409SSimon J. Gerraty * | 5 | `BR_SSLENC_CHACHA20` | ChaCha20/Poly1305 | 256 |
29580957b409SSimon J. Gerraty *
29590957b409SSimon J. Gerraty * - Bits 4 to 7: MAC algorithm
29600957b409SSimon J. Gerraty *
29610957b409SSimon J. Gerraty * | val | symbolic constant | MAC type | details |
29620957b409SSimon J. Gerraty * | :-- | :----------------- | :----------- | :------------------------------------ |
29630957b409SSimon J. Gerraty * | 0 | `BR_SSLMAC_AEAD` | AEAD | No dedicated MAC (encryption is AEAD) |
29640957b409SSimon J. Gerraty * | 2 | `BR_SSLMAC_SHA1` | HMAC/SHA-1 | Value matches `br_sha1_ID` |
29650957b409SSimon J. Gerraty * | 4 | `BR_SSLMAC_SHA256` | HMAC/SHA-256 | Value matches `br_sha256_ID` |
29660957b409SSimon J. Gerraty * | 5 | `BR_SSLMAC_SHA384` | HMAC/SHA-384 | Value matches `br_sha384_ID` |
29670957b409SSimon J. Gerraty *
29680957b409SSimon J. Gerraty * - Bits 0 to 3: hash function for PRF when used with TLS-1.2
29690957b409SSimon J. Gerraty *
29700957b409SSimon J. Gerraty * | val | symbolic constant | hash function | details |
29710957b409SSimon J. Gerraty * | :-- | :----------------- | :------------ | :----------------------------------- |
29720957b409SSimon J. Gerraty * | 4 | `BR_SSLPRF_SHA256` | SHA-256 | Value matches `br_sha256_ID` |
29730957b409SSimon J. Gerraty * | 5 | `BR_SSLPRF_SHA384` | SHA-384 | Value matches `br_sha384_ID` |
29740957b409SSimon J. Gerraty *
29750957b409SSimon J. Gerraty * For instance, cipher suite `TLS_RSA_WITH_AES_128_GCM_SHA256` has
29760957b409SSimon J. Gerraty * standard identifier 0x009C, and is translated to 0x0304, for, in
29770957b409SSimon J. Gerraty * that order: RSA key exchange (0), AES-128/GCM (3), AEAD integrity (0),
29780957b409SSimon J. Gerraty * SHA-256 in the TLS PRF (4).
29790957b409SSimon J. Gerraty */
29800957b409SSimon J. Gerraty typedef uint16_t br_suite_translated[2];
29810957b409SSimon J. Gerraty
29820957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
29830957b409SSimon J. Gerraty /*
29840957b409SSimon J. Gerraty * Constants are already documented in the br_suite_translated type.
29850957b409SSimon J. Gerraty */
29860957b409SSimon J. Gerraty
29870957b409SSimon J. Gerraty #define BR_SSLKEYX_RSA 0
29880957b409SSimon J. Gerraty #define BR_SSLKEYX_ECDHE_RSA 1
29890957b409SSimon J. Gerraty #define BR_SSLKEYX_ECDHE_ECDSA 2
29900957b409SSimon J. Gerraty #define BR_SSLKEYX_ECDH_RSA 3
29910957b409SSimon J. Gerraty #define BR_SSLKEYX_ECDH_ECDSA 4
29920957b409SSimon J. Gerraty
29930957b409SSimon J. Gerraty #define BR_SSLENC_3DES_CBC 0
29940957b409SSimon J. Gerraty #define BR_SSLENC_AES128_CBC 1
29950957b409SSimon J. Gerraty #define BR_SSLENC_AES256_CBC 2
29960957b409SSimon J. Gerraty #define BR_SSLENC_AES128_GCM 3
29970957b409SSimon J. Gerraty #define BR_SSLENC_AES256_GCM 4
29980957b409SSimon J. Gerraty #define BR_SSLENC_CHACHA20 5
29990957b409SSimon J. Gerraty
30000957b409SSimon J. Gerraty #define BR_SSLMAC_AEAD 0
30010957b409SSimon J. Gerraty #define BR_SSLMAC_SHA1 br_sha1_ID
30020957b409SSimon J. Gerraty #define BR_SSLMAC_SHA256 br_sha256_ID
30030957b409SSimon J. Gerraty #define BR_SSLMAC_SHA384 br_sha384_ID
30040957b409SSimon J. Gerraty
30050957b409SSimon J. Gerraty #define BR_SSLPRF_SHA256 br_sha256_ID
30060957b409SSimon J. Gerraty #define BR_SSLPRF_SHA384 br_sha384_ID
30070957b409SSimon J. Gerraty
30080957b409SSimon J. Gerraty #endif
30090957b409SSimon J. Gerraty
30100957b409SSimon J. Gerraty /*
30110957b409SSimon J. Gerraty * Pre-declaration for the SSL server context.
30120957b409SSimon J. Gerraty */
30130957b409SSimon J. Gerraty typedef struct br_ssl_server_context_ br_ssl_server_context;
30140957b409SSimon J. Gerraty
30150957b409SSimon J. Gerraty /**
30160957b409SSimon J. Gerraty * \brief Type for the server policy choices, taken after analysis of
30170957b409SSimon J. Gerraty * the client message (ClientHello).
30180957b409SSimon J. Gerraty */
30190957b409SSimon J. Gerraty typedef struct {
30200957b409SSimon J. Gerraty /**
30210957b409SSimon J. Gerraty * \brief Cipher suite to use with that client.
30220957b409SSimon J. Gerraty */
30230957b409SSimon J. Gerraty uint16_t cipher_suite;
30240957b409SSimon J. Gerraty
30250957b409SSimon J. Gerraty /**
30260957b409SSimon J. Gerraty * \brief Hash function or algorithm for signing the ServerKeyExchange.
30270957b409SSimon J. Gerraty *
30280957b409SSimon J. Gerraty * This parameter is ignored for `TLS_RSA_*` and `TLS_ECDH_*`
30290957b409SSimon J. Gerraty * cipher suites; it is used only for `TLS_ECDHE_*` suites, in
30300957b409SSimon J. Gerraty * which the server _signs_ the ephemeral EC Diffie-Hellman
30310957b409SSimon J. Gerraty * parameters sent to the client.
30320957b409SSimon J. Gerraty *
30330957b409SSimon J. Gerraty * This identifier must be one of the following values:
30340957b409SSimon J. Gerraty *
30350957b409SSimon J. Gerraty * - `0xFF00 + id`, where `id` is a hash function identifier
30360957b409SSimon J. Gerraty * (0 for MD5+SHA-1, or 2 to 6 for one of the SHA functions);
30370957b409SSimon J. Gerraty *
30380957b409SSimon J. Gerraty * - a full 16-bit identifier, lower than `0xFF00`.
30390957b409SSimon J. Gerraty *
30400957b409SSimon J. Gerraty * If the first option is used, then the SSL engine will
30410957b409SSimon J. Gerraty * compute the hash of the data that is to be signed, with the
30420957b409SSimon J. Gerraty * designated hash function. The `do_sign()` method will be
30430957b409SSimon J. Gerraty * invoked with that hash value provided in the the `data`
30440957b409SSimon J. Gerraty * buffer.
30450957b409SSimon J. Gerraty *
30460957b409SSimon J. Gerraty * If the second option is used, then the SSL engine will NOT
30470957b409SSimon J. Gerraty * compute a hash on the data; instead, it will provide the
30480957b409SSimon J. Gerraty * to-be-signed data itself in `data`, i.e. the concatenation of
30490957b409SSimon J. Gerraty * the client random, server random, and encoded ECDH
30500957b409SSimon J. Gerraty * parameters. Furthermore, with TLS-1.2 and later, the 16-bit
30510957b409SSimon J. Gerraty * identifier will be used "as is" in the protocol, in the
30520957b409SSimon J. Gerraty * SignatureAndHashAlgorithm; for instance, `0x0401` stands for
30530957b409SSimon J. Gerraty * RSA PKCS#1 v1.5 signature (the `01`) with SHA-256 as hash
30540957b409SSimon J. Gerraty * function (the `04`).
30550957b409SSimon J. Gerraty *
30560957b409SSimon J. Gerraty * Take care that with TLS 1.0 and 1.1, the hash function is
30570957b409SSimon J. Gerraty * constrainted by the protocol: RSA signature must use
30580957b409SSimon J. Gerraty * MD5+SHA-1 (so use `0xFF00`), while ECDSA must use SHA-1
30590957b409SSimon J. Gerraty * (`0xFF02`). Since TLS 1.0 and 1.1 don't include a
30600957b409SSimon J. Gerraty * SignatureAndHashAlgorithm field in their ServerKeyExchange
30610957b409SSimon J. Gerraty * messages, any value below `0xFF00` will be usable to send the
30620957b409SSimon J. Gerraty * raw ServerKeyExchange data to the `do_sign()` callback, but
30630957b409SSimon J. Gerraty * that callback must still follow the protocol requirements
30640957b409SSimon J. Gerraty * when generating the signature.
30650957b409SSimon J. Gerraty */
30660957b409SSimon J. Gerraty unsigned algo_id;
30670957b409SSimon J. Gerraty
30680957b409SSimon J. Gerraty /**
30690957b409SSimon J. Gerraty * \brief Certificate chain to send to the client.
30700957b409SSimon J. Gerraty *
30710957b409SSimon J. Gerraty * This is an array of `br_x509_certificate` objects, each
30720957b409SSimon J. Gerraty * normally containing a DER-encoded certificate. The server
30730957b409SSimon J. Gerraty * code does not try to decode these elements.
30740957b409SSimon J. Gerraty */
30750957b409SSimon J. Gerraty const br_x509_certificate *chain;
30760957b409SSimon J. Gerraty
30770957b409SSimon J. Gerraty /**
30780957b409SSimon J. Gerraty * \brief Certificate chain length (number of certificates).
30790957b409SSimon J. Gerraty */
30800957b409SSimon J. Gerraty size_t chain_len;
30810957b409SSimon J. Gerraty
30820957b409SSimon J. Gerraty } br_ssl_server_choices;
30830957b409SSimon J. Gerraty
30840957b409SSimon J. Gerraty /**
30850957b409SSimon J. Gerraty * \brief Class type for a policy handler (server side).
30860957b409SSimon J. Gerraty *
30870957b409SSimon J. Gerraty * A policy handler selects the policy parameters for a connection
30880957b409SSimon J. Gerraty * (cipher suite and other algorithms, and certificate chain to send to
30890957b409SSimon J. Gerraty * the client); it also performs the server-side computations involving
30900957b409SSimon J. Gerraty * its permanent private key.
30910957b409SSimon J. Gerraty *
30920957b409SSimon J. Gerraty * The SSL server engine will invoke first `choose()`, once the
30930957b409SSimon J. Gerraty * ClientHello message has been received, then either `do_keyx()`
30940957b409SSimon J. Gerraty * `do_sign()`, depending on the cipher suite.
30950957b409SSimon J. Gerraty */
30960957b409SSimon J. Gerraty typedef struct br_ssl_server_policy_class_ br_ssl_server_policy_class;
30970957b409SSimon J. Gerraty struct br_ssl_server_policy_class_ {
30980957b409SSimon J. Gerraty /**
30990957b409SSimon J. Gerraty * \brief Context size (in bytes).
31000957b409SSimon J. Gerraty */
31010957b409SSimon J. Gerraty size_t context_size;
31020957b409SSimon J. Gerraty
31030957b409SSimon J. Gerraty /**
31040957b409SSimon J. Gerraty * \brief Select algorithms and certificates for this connection.
31050957b409SSimon J. Gerraty *
31060957b409SSimon J. Gerraty * This callback function shall fill the provided `choices`
31070957b409SSimon J. Gerraty * structure with the policy choices for this connection. This
31080957b409SSimon J. Gerraty * entails selecting the cipher suite, hash function for signing
31090957b409SSimon J. Gerraty * the ServerKeyExchange (applicable only to ECDHE cipher suites),
31100957b409SSimon J. Gerraty * and certificate chain to send.
31110957b409SSimon J. Gerraty *
31120957b409SSimon J. Gerraty * The callback receives a pointer to the server context that
31130957b409SSimon J. Gerraty * contains the relevant data. In particular, the functions
31140957b409SSimon J. Gerraty * `br_ssl_server_get_client_suites()`,
31150957b409SSimon J. Gerraty * `br_ssl_server_get_client_hashes()` and
31160957b409SSimon J. Gerraty * `br_ssl_server_get_client_curves()` can be used to obtain
31170957b409SSimon J. Gerraty * the cipher suites, hash functions and elliptic curves
31180957b409SSimon J. Gerraty * supported by both the client and server, respectively. The
31190957b409SSimon J. Gerraty * `br_ssl_engine_get_version()` and `br_ssl_engine_get_server_name()`
31200957b409SSimon J. Gerraty * functions yield the protocol version and requested server name
31210957b409SSimon J. Gerraty * (SNI), respectively.
31220957b409SSimon J. Gerraty *
31230957b409SSimon J. Gerraty * This function may modify its context structure (`pctx`) in
31240957b409SSimon J. Gerraty * arbitrary ways to keep track of its own choices.
31250957b409SSimon J. Gerraty *
31260957b409SSimon J. Gerraty * This function shall return 1 if appropriate policy choices
31270957b409SSimon J. Gerraty * could be made, or 0 if this connection cannot be pursued.
31280957b409SSimon J. Gerraty *
31290957b409SSimon J. Gerraty * \param pctx policy context.
31300957b409SSimon J. Gerraty * \param cc SSL server context.
31310957b409SSimon J. Gerraty * \param choices destination structure for the policy choices.
31320957b409SSimon J. Gerraty * \return 1 on success, 0 on error.
31330957b409SSimon J. Gerraty */
31340957b409SSimon J. Gerraty int (*choose)(const br_ssl_server_policy_class **pctx,
31350957b409SSimon J. Gerraty const br_ssl_server_context *cc,
31360957b409SSimon J. Gerraty br_ssl_server_choices *choices);
31370957b409SSimon J. Gerraty
31380957b409SSimon J. Gerraty /**
31390957b409SSimon J. Gerraty * \brief Perform key exchange (server part).
31400957b409SSimon J. Gerraty *
31410957b409SSimon J. Gerraty * This callback is invoked to perform the server-side cryptographic
31420957b409SSimon J. Gerraty * operation for a key exchange that is not ECDHE. This callback
31430957b409SSimon J. Gerraty * uses the private key.
31440957b409SSimon J. Gerraty *
31450957b409SSimon J. Gerraty * **For RSA key exchange**, the provided `data` (of length `*len`
31460957b409SSimon J. Gerraty * bytes) shall be decrypted with the server's private key, and
31470957b409SSimon J. Gerraty * the 48-byte premaster secret copied back to the first 48 bytes
31480957b409SSimon J. Gerraty * of `data`.
31490957b409SSimon J. Gerraty *
31500957b409SSimon J. Gerraty * - The caller makes sure that `*len` is at least 59 bytes.
31510957b409SSimon J. Gerraty *
31520957b409SSimon J. Gerraty * - This callback MUST check that the provided length matches
31530957b409SSimon J. Gerraty * that of the key modulus; it shall report an error otherwise.
31540957b409SSimon J. Gerraty *
31550957b409SSimon J. Gerraty * - If the length matches that of the RSA key modulus, then
31560957b409SSimon J. Gerraty * processing MUST be constant-time, even if decryption fails,
31570957b409SSimon J. Gerraty * or the padding is incorrect, or the plaintext message length
31580957b409SSimon J. Gerraty * is not exactly 48 bytes.
31590957b409SSimon J. Gerraty *
31600957b409SSimon J. Gerraty * - This callback needs not check the two first bytes of the
31610957b409SSimon J. Gerraty * obtained pre-master secret (the caller will do that).
31620957b409SSimon J. Gerraty *
31630957b409SSimon J. Gerraty * - If an error is reported (0), then what the callback put
31640957b409SSimon J. Gerraty * in the first 48 bytes of `data` is unimportant (the caller
31650957b409SSimon J. Gerraty * will use random bytes instead).
31660957b409SSimon J. Gerraty *
31670957b409SSimon J. Gerraty * **For ECDH key exchange**, the provided `data` (of length `*len`
31680957b409SSimon J. Gerraty * bytes) is the elliptic curve point from the client. The
31690957b409SSimon J. Gerraty * callback shall multiply it with its private key, and store
31700957b409SSimon J. Gerraty * the resulting X coordinate in `data`, starting at offset 0,
31710957b409SSimon J. Gerraty * and set `*len` to the length of the X coordinate.
31720957b409SSimon J. Gerraty *
31730957b409SSimon J. Gerraty * - If the input array does not have the proper length for
31740957b409SSimon J. Gerraty * an encoded curve point, then an error (0) shall be reported.
31750957b409SSimon J. Gerraty *
31760957b409SSimon J. Gerraty * - If the input array has the proper length, then processing
31770957b409SSimon J. Gerraty * MUST be constant-time, even if the data is not a valid
31780957b409SSimon J. Gerraty * encoded point.
31790957b409SSimon J. Gerraty *
31800957b409SSimon J. Gerraty * - This callback MUST check that the input point is valid.
31810957b409SSimon J. Gerraty *
31820957b409SSimon J. Gerraty * Returned value is 1 on success, 0 on error.
31830957b409SSimon J. Gerraty *
31840957b409SSimon J. Gerraty * \param pctx policy context.
31850957b409SSimon J. Gerraty * \param data key exchange data from the client.
31860957b409SSimon J. Gerraty * \param len key exchange data length (in bytes).
31870957b409SSimon J. Gerraty * \return 1 on success, 0 on error.
31880957b409SSimon J. Gerraty */
31890957b409SSimon J. Gerraty uint32_t (*do_keyx)(const br_ssl_server_policy_class **pctx,
31900957b409SSimon J. Gerraty unsigned char *data, size_t *len);
31910957b409SSimon J. Gerraty
31920957b409SSimon J. Gerraty /**
31930957b409SSimon J. Gerraty * \brief Perform a signature (for a ServerKeyExchange message).
31940957b409SSimon J. Gerraty *
31950957b409SSimon J. Gerraty * This callback function is invoked for ECDHE cipher suites. On
31960957b409SSimon J. Gerraty * input, the hash value or message to sign is in `data`, of
31970957b409SSimon J. Gerraty * size `hv_len`; the involved hash function or algorithm is
31980957b409SSimon J. Gerraty * identified by `algo_id`. The signature shall be computed and
31990957b409SSimon J. Gerraty * written back into `data`; the total size of that buffer is
32000957b409SSimon J. Gerraty * `len` bytes.
32010957b409SSimon J. Gerraty *
32020957b409SSimon J. Gerraty * This callback shall verify that the signature length does not
32030957b409SSimon J. Gerraty * exceed `len` bytes, and abstain from writing the signature if
32040957b409SSimon J. Gerraty * it does not fit.
32050957b409SSimon J. Gerraty *
32060957b409SSimon J. Gerraty * The `algo_id` value matches that which was written in the
32070957b409SSimon J. Gerraty * `choices` structures by the `choose()` callback. This will be
32080957b409SSimon J. Gerraty * one of the following:
32090957b409SSimon J. Gerraty *
32100957b409SSimon J. Gerraty * - `0xFF00 + id` for a hash function identifier `id`. In
32110957b409SSimon J. Gerraty * that case, the `data` buffer contains a hash value
32120957b409SSimon J. Gerraty * already computed over the data that is to be signed,
32130957b409SSimon J. Gerraty * of length `hv_len`. The `id` may be 0 to designate the
32140957b409SSimon J. Gerraty * special MD5+SHA-1 concatenation (old-style RSA signing).
32150957b409SSimon J. Gerraty *
32160957b409SSimon J. Gerraty * - Another value, lower than `0xFF00`. The `data` buffer
32170957b409SSimon J. Gerraty * then contains the raw, non-hashed data to be signed
32180957b409SSimon J. Gerraty * (concatenation of the client and server randoms and
32190957b409SSimon J. Gerraty * ECDH parameters). The callback is responsible to apply
32200957b409SSimon J. Gerraty * any relevant hashing as part of the signing process.
32210957b409SSimon J. Gerraty *
32220957b409SSimon J. Gerraty * Returned value is the signature length (in bytes), or 0 on error.
32230957b409SSimon J. Gerraty *
32240957b409SSimon J. Gerraty * \param pctx policy context.
32250957b409SSimon J. Gerraty * \param algo_id hash function / algorithm identifier.
32260957b409SSimon J. Gerraty * \param data input/output buffer (message/hash, then signature).
32270957b409SSimon J. Gerraty * \param hv_len hash value or message length (in bytes).
32280957b409SSimon J. Gerraty * \param len total buffer length (in bytes).
32290957b409SSimon J. Gerraty * \return signature length (in bytes) on success, or 0 on error.
32300957b409SSimon J. Gerraty */
32310957b409SSimon J. Gerraty size_t (*do_sign)(const br_ssl_server_policy_class **pctx,
32320957b409SSimon J. Gerraty unsigned algo_id,
32330957b409SSimon J. Gerraty unsigned char *data, size_t hv_len, size_t len);
32340957b409SSimon J. Gerraty };
32350957b409SSimon J. Gerraty
32360957b409SSimon J. Gerraty /**
32370957b409SSimon J. Gerraty * \brief A single-chain RSA policy handler.
32380957b409SSimon J. Gerraty *
32390957b409SSimon J. Gerraty * This policy context uses a single certificate chain, and a RSA
32400957b409SSimon J. Gerraty * private key. The context can be restricted to only signatures or
32410957b409SSimon J. Gerraty * only key exchange.
32420957b409SSimon J. Gerraty *
32430957b409SSimon J. Gerraty * Apart from the first field (vtable pointer), its contents are
32440957b409SSimon J. Gerraty * opaque and shall not be accessed directly.
32450957b409SSimon J. Gerraty */
32460957b409SSimon J. Gerraty typedef struct {
32470957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
32480957b409SSimon J. Gerraty const br_ssl_server_policy_class *vtable;
32490957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
32500957b409SSimon J. Gerraty const br_x509_certificate *chain;
32510957b409SSimon J. Gerraty size_t chain_len;
32520957b409SSimon J. Gerraty const br_rsa_private_key *sk;
32530957b409SSimon J. Gerraty unsigned allowed_usages;
32540957b409SSimon J. Gerraty br_rsa_private irsacore;
32550957b409SSimon J. Gerraty br_rsa_pkcs1_sign irsasign;
32560957b409SSimon J. Gerraty #endif
32570957b409SSimon J. Gerraty } br_ssl_server_policy_rsa_context;
32580957b409SSimon J. Gerraty
32590957b409SSimon J. Gerraty /**
32600957b409SSimon J. Gerraty * \brief A single-chain EC policy handler.
32610957b409SSimon J. Gerraty *
32620957b409SSimon J. Gerraty * This policy context uses a single certificate chain, and an EC
32630957b409SSimon J. Gerraty * private key. The context can be restricted to only signatures or
32640957b409SSimon J. Gerraty * only key exchange.
32650957b409SSimon J. Gerraty *
32660957b409SSimon J. Gerraty * Due to how TLS is defined, this context must be made aware whether
32670957b409SSimon J. Gerraty * the server certificate was itself signed with RSA or ECDSA. The code
32680957b409SSimon J. Gerraty * does not try to decode the certificate to obtain that information.
32690957b409SSimon J. Gerraty *
32700957b409SSimon J. Gerraty * Apart from the first field (vtable pointer), its contents are
32710957b409SSimon J. Gerraty * opaque and shall not be accessed directly.
32720957b409SSimon J. Gerraty */
32730957b409SSimon J. Gerraty typedef struct {
32740957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
32750957b409SSimon J. Gerraty const br_ssl_server_policy_class *vtable;
32760957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
32770957b409SSimon J. Gerraty const br_x509_certificate *chain;
32780957b409SSimon J. Gerraty size_t chain_len;
32790957b409SSimon J. Gerraty const br_ec_private_key *sk;
32800957b409SSimon J. Gerraty unsigned allowed_usages;
32810957b409SSimon J. Gerraty unsigned cert_issuer_key_type;
32820957b409SSimon J. Gerraty const br_multihash_context *mhash;
32830957b409SSimon J. Gerraty const br_ec_impl *iec;
32840957b409SSimon J. Gerraty br_ecdsa_sign iecdsa;
32850957b409SSimon J. Gerraty #endif
32860957b409SSimon J. Gerraty } br_ssl_server_policy_ec_context;
32870957b409SSimon J. Gerraty
32880957b409SSimon J. Gerraty /**
32890957b409SSimon J. Gerraty * \brief Class type for a session parameter cache.
32900957b409SSimon J. Gerraty *
32910957b409SSimon J. Gerraty * Session parameters are saved in the cache with `save()`, and
32920957b409SSimon J. Gerraty * retrieved with `load()`. The cache implementation can apply any
32930957b409SSimon J. Gerraty * storage and eviction strategy that it sees fit. The SSL server
32940957b409SSimon J. Gerraty * context that performs the request is provided, so that its
32950957b409SSimon J. Gerraty * functionalities may be used by the implementation (e.g. hash
32960957b409SSimon J. Gerraty * functions or random number generation).
32970957b409SSimon J. Gerraty */
32980957b409SSimon J. Gerraty typedef struct br_ssl_session_cache_class_ br_ssl_session_cache_class;
32990957b409SSimon J. Gerraty struct br_ssl_session_cache_class_ {
33000957b409SSimon J. Gerraty /**
33010957b409SSimon J. Gerraty * \brief Context size (in bytes).
33020957b409SSimon J. Gerraty */
33030957b409SSimon J. Gerraty size_t context_size;
33040957b409SSimon J. Gerraty
33050957b409SSimon J. Gerraty /**
33060957b409SSimon J. Gerraty * \brief Record a session.
33070957b409SSimon J. Gerraty *
33080957b409SSimon J. Gerraty * This callback should record the provided session parameters.
33090957b409SSimon J. Gerraty * The `params` structure is transient, so its contents shall
33100957b409SSimon J. Gerraty * be copied into the cache. The session ID has been randomly
33110957b409SSimon J. Gerraty * generated and always has length exactly 32 bytes.
33120957b409SSimon J. Gerraty *
33130957b409SSimon J. Gerraty * \param ctx session cache context.
33140957b409SSimon J. Gerraty * \param server_ctx SSL server context.
33150957b409SSimon J. Gerraty * \param params session parameters to save.
33160957b409SSimon J. Gerraty */
33170957b409SSimon J. Gerraty void (*save)(const br_ssl_session_cache_class **ctx,
33180957b409SSimon J. Gerraty br_ssl_server_context *server_ctx,
33190957b409SSimon J. Gerraty const br_ssl_session_parameters *params);
33200957b409SSimon J. Gerraty
33210957b409SSimon J. Gerraty /**
33220957b409SSimon J. Gerraty * \brief Lookup a session in the cache.
33230957b409SSimon J. Gerraty *
33240957b409SSimon J. Gerraty * The session ID to lookup is in `params` and always has length
33250957b409SSimon J. Gerraty * exactly 32 bytes. If the session parameters are found in the
33260957b409SSimon J. Gerraty * cache, then the parameters shall be copied into the `params`
33270957b409SSimon J. Gerraty * structure. Returned value is 1 on successful lookup, 0
33280957b409SSimon J. Gerraty * otherwise.
33290957b409SSimon J. Gerraty *
33300957b409SSimon J. Gerraty * \param ctx session cache context.
33310957b409SSimon J. Gerraty * \param server_ctx SSL server context.
33320957b409SSimon J. Gerraty * \param params destination for session parameters.
33330957b409SSimon J. Gerraty * \return 1 if found, 0 otherwise.
33340957b409SSimon J. Gerraty */
33350957b409SSimon J. Gerraty int (*load)(const br_ssl_session_cache_class **ctx,
33360957b409SSimon J. Gerraty br_ssl_server_context *server_ctx,
33370957b409SSimon J. Gerraty br_ssl_session_parameters *params);
33380957b409SSimon J. Gerraty };
33390957b409SSimon J. Gerraty
33400957b409SSimon J. Gerraty /**
33410957b409SSimon J. Gerraty * \brief Context for a basic cache system.
33420957b409SSimon J. Gerraty *
33430957b409SSimon J. Gerraty * The system stores session parameters in a buffer provided at
33440957b409SSimon J. Gerraty * initialisation time. Each entry uses exactly 100 bytes, and
33450957b409SSimon J. Gerraty * buffer sizes up to 4294967295 bytes are supported.
33460957b409SSimon J. Gerraty *
33470957b409SSimon J. Gerraty * Entries are evicted with a LRU (Least Recently Used) policy. A
33480957b409SSimon J. Gerraty * search tree is maintained to keep lookups fast even with large
33490957b409SSimon J. Gerraty * caches.
33500957b409SSimon J. Gerraty *
33510957b409SSimon J. Gerraty * Apart from the first field (vtable pointer), the structure
33520957b409SSimon J. Gerraty * contents are opaque and shall not be accessed directly.
33530957b409SSimon J. Gerraty */
33540957b409SSimon J. Gerraty typedef struct {
33550957b409SSimon J. Gerraty /** \brief Pointer to vtable. */
33560957b409SSimon J. Gerraty const br_ssl_session_cache_class *vtable;
33570957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
33580957b409SSimon J. Gerraty unsigned char *store;
33590957b409SSimon J. Gerraty size_t store_len, store_ptr;
33600957b409SSimon J. Gerraty unsigned char index_key[32];
33610957b409SSimon J. Gerraty const br_hash_class *hash;
33620957b409SSimon J. Gerraty int init_done;
33630957b409SSimon J. Gerraty uint32_t head, tail, root;
33640957b409SSimon J. Gerraty #endif
33650957b409SSimon J. Gerraty } br_ssl_session_cache_lru;
33660957b409SSimon J. Gerraty
33670957b409SSimon J. Gerraty /**
33680957b409SSimon J. Gerraty * \brief Initialise a LRU session cache with the provided storage space.
33690957b409SSimon J. Gerraty *
33700957b409SSimon J. Gerraty * The provided storage space must remain valid as long as the cache
33710957b409SSimon J. Gerraty * is used. Arbitrary lengths are supported, up to 4294967295 bytes;
33720957b409SSimon J. Gerraty * each entry uses up exactly 100 bytes.
33730957b409SSimon J. Gerraty *
33740957b409SSimon J. Gerraty * \param cc session cache context.
33750957b409SSimon J. Gerraty * \param store storage space for cached entries.
33760957b409SSimon J. Gerraty * \param store_len storage space length (in bytes).
33770957b409SSimon J. Gerraty */
33780957b409SSimon J. Gerraty void br_ssl_session_cache_lru_init(br_ssl_session_cache_lru *cc,
33790957b409SSimon J. Gerraty unsigned char *store, size_t store_len);
33800957b409SSimon J. Gerraty
33810957b409SSimon J. Gerraty /**
33820957b409SSimon J. Gerraty * \brief Forget an entry in an LRU session cache.
33830957b409SSimon J. Gerraty *
33840957b409SSimon J. Gerraty * The session cache context must have been initialised. The entry
33850957b409SSimon J. Gerraty * with the provided session ID (of exactly 32 bytes) is looked for
33860957b409SSimon J. Gerraty * in the cache; if located, it is disabled.
33870957b409SSimon J. Gerraty *
33880957b409SSimon J. Gerraty * \param cc session cache context.
33890957b409SSimon J. Gerraty * \param id session ID to forget.
33900957b409SSimon J. Gerraty */
33910957b409SSimon J. Gerraty void br_ssl_session_cache_lru_forget(
33920957b409SSimon J. Gerraty br_ssl_session_cache_lru *cc, const unsigned char *id);
33930957b409SSimon J. Gerraty
33940957b409SSimon J. Gerraty /**
33950957b409SSimon J. Gerraty * \brief Context structure for a SSL server.
33960957b409SSimon J. Gerraty *
33970957b409SSimon J. Gerraty * The first field (called `eng`) is the SSL engine; all functions that
33980957b409SSimon J. Gerraty * work on a `br_ssl_engine_context` structure shall take as parameter
33990957b409SSimon J. Gerraty * a pointer to that field. The other structure fields are opaque and
34000957b409SSimon J. Gerraty * must not be accessed directly.
34010957b409SSimon J. Gerraty */
34020957b409SSimon J. Gerraty struct br_ssl_server_context_ {
34030957b409SSimon J. Gerraty /**
34040957b409SSimon J. Gerraty * \brief The encapsulated engine context.
34050957b409SSimon J. Gerraty */
34060957b409SSimon J. Gerraty br_ssl_engine_context eng;
34070957b409SSimon J. Gerraty
34080957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
34090957b409SSimon J. Gerraty /*
34100957b409SSimon J. Gerraty * Maximum version from the client.
34110957b409SSimon J. Gerraty */
34120957b409SSimon J. Gerraty uint16_t client_max_version;
34130957b409SSimon J. Gerraty
34140957b409SSimon J. Gerraty /*
34150957b409SSimon J. Gerraty * Session cache.
34160957b409SSimon J. Gerraty */
34170957b409SSimon J. Gerraty const br_ssl_session_cache_class **cache_vtable;
34180957b409SSimon J. Gerraty
34190957b409SSimon J. Gerraty /*
34200957b409SSimon J. Gerraty * Translated cipher suites supported by the client. The list
34210957b409SSimon J. Gerraty * is trimmed to include only the cipher suites that the
34220957b409SSimon J. Gerraty * server also supports; they are in the same order as in the
34230957b409SSimon J. Gerraty * client message.
34240957b409SSimon J. Gerraty */
34250957b409SSimon J. Gerraty br_suite_translated client_suites[BR_MAX_CIPHER_SUITES];
34260957b409SSimon J. Gerraty unsigned char client_suites_num;
34270957b409SSimon J. Gerraty
34280957b409SSimon J. Gerraty /*
34290957b409SSimon J. Gerraty * Hash functions supported by the client, with ECDSA and RSA
34300957b409SSimon J. Gerraty * (bit mask). For hash function with id 'x', set bit index is
34310957b409SSimon J. Gerraty * x for RSA, x+8 for ECDSA. For newer algorithms, with ID
34320957b409SSimon J. Gerraty * 0x08**, bit 16+k is set for algorithm 0x0800+k.
34330957b409SSimon J. Gerraty */
34340957b409SSimon J. Gerraty uint32_t hashes;
34350957b409SSimon J. Gerraty
34360957b409SSimon J. Gerraty /*
34370957b409SSimon J. Gerraty * Curves supported by the client (bit mask, for named curves).
34380957b409SSimon J. Gerraty */
34390957b409SSimon J. Gerraty uint32_t curves;
34400957b409SSimon J. Gerraty
34410957b409SSimon J. Gerraty /*
34420957b409SSimon J. Gerraty * Context for chain handler.
34430957b409SSimon J. Gerraty */
34440957b409SSimon J. Gerraty const br_ssl_server_policy_class **policy_vtable;
34450957b409SSimon J. Gerraty uint16_t sign_hash_id;
34460957b409SSimon J. Gerraty
34470957b409SSimon J. Gerraty /*
34480957b409SSimon J. Gerraty * For the core handlers, thus avoiding (in most cases) the
34490957b409SSimon J. Gerraty * need for an externally provided policy context.
34500957b409SSimon J. Gerraty */
34510957b409SSimon J. Gerraty union {
34520957b409SSimon J. Gerraty const br_ssl_server_policy_class *vtable;
34530957b409SSimon J. Gerraty br_ssl_server_policy_rsa_context single_rsa;
34540957b409SSimon J. Gerraty br_ssl_server_policy_ec_context single_ec;
34550957b409SSimon J. Gerraty } chain_handler;
34560957b409SSimon J. Gerraty
34570957b409SSimon J. Gerraty /*
34580957b409SSimon J. Gerraty * Buffer for the ECDHE private key.
34590957b409SSimon J. Gerraty */
34600957b409SSimon J. Gerraty unsigned char ecdhe_key[70];
34610957b409SSimon J. Gerraty size_t ecdhe_key_len;
34620957b409SSimon J. Gerraty
34630957b409SSimon J. Gerraty /*
34640957b409SSimon J. Gerraty * Trust anchor names for client authentication. "ta_names" and
34650957b409SSimon J. Gerraty * "tas" cannot be both non-NULL.
34660957b409SSimon J. Gerraty */
34670957b409SSimon J. Gerraty const br_x500_name *ta_names;
34680957b409SSimon J. Gerraty const br_x509_trust_anchor *tas;
34690957b409SSimon J. Gerraty size_t num_tas;
34700957b409SSimon J. Gerraty size_t cur_dn_index;
34710957b409SSimon J. Gerraty const unsigned char *cur_dn;
34720957b409SSimon J. Gerraty size_t cur_dn_len;
34730957b409SSimon J. Gerraty
34740957b409SSimon J. Gerraty /*
34750957b409SSimon J. Gerraty * Buffer for the hash value computed over all handshake messages
34760957b409SSimon J. Gerraty * prior to CertificateVerify, and identifier for the hash function.
34770957b409SSimon J. Gerraty */
34780957b409SSimon J. Gerraty unsigned char hash_CV[64];
34790957b409SSimon J. Gerraty size_t hash_CV_len;
34800957b409SSimon J. Gerraty int hash_CV_id;
34810957b409SSimon J. Gerraty
34820957b409SSimon J. Gerraty /*
34830957b409SSimon J. Gerraty * Server-specific implementations.
34840957b409SSimon J. Gerraty * (none for now)
34850957b409SSimon J. Gerraty */
34860957b409SSimon J. Gerraty #endif
34870957b409SSimon J. Gerraty };
34880957b409SSimon J. Gerraty
34890957b409SSimon J. Gerraty /*
34900957b409SSimon J. Gerraty * Each br_ssl_server_init_xxx() function sets the list of supported
34910957b409SSimon J. Gerraty * cipher suites and used implementations, as specified by the profile
34920957b409SSimon J. Gerraty * name 'xxx'. Defined profile names are:
34930957b409SSimon J. Gerraty *
34940957b409SSimon J. Gerraty * full_rsa all supported algorithm, server key type is RSA
34950957b409SSimon J. Gerraty * full_ec all supported algorithm, server key type is EC
34960957b409SSimon J. Gerraty * TODO: add other profiles
34970957b409SSimon J. Gerraty *
34980957b409SSimon J. Gerraty * Naming scheme for "minimal" profiles: min123
34990957b409SSimon J. Gerraty *
35000957b409SSimon J. Gerraty * -- character 1: key exchange
35010957b409SSimon J. Gerraty * r = RSA
35020957b409SSimon J. Gerraty * e = ECDHE_RSA
35030957b409SSimon J. Gerraty * f = ECDHE_ECDSA
35040957b409SSimon J. Gerraty * u = ECDH_RSA
35050957b409SSimon J. Gerraty * v = ECDH_ECDSA
35060957b409SSimon J. Gerraty * -- character 2: version / PRF
35070957b409SSimon J. Gerraty * 0 = TLS 1.0 / 1.1 with MD5+SHA-1
35080957b409SSimon J. Gerraty * 2 = TLS 1.2 with SHA-256
35090957b409SSimon J. Gerraty * 3 = TLS 1.2 with SHA-384
35100957b409SSimon J. Gerraty * -- character 3: encryption
35110957b409SSimon J. Gerraty * a = AES/CBC
35120957b409SSimon J. Gerraty * d = 3DES/CBC
35130957b409SSimon J. Gerraty * g = AES/GCM
35140957b409SSimon J. Gerraty * c = ChaCha20+Poly1305
35150957b409SSimon J. Gerraty */
35160957b409SSimon J. Gerraty
35170957b409SSimon J. Gerraty /**
35180957b409SSimon J. Gerraty * \brief SSL server profile: full_rsa.
35190957b409SSimon J. Gerraty *
35200957b409SSimon J. Gerraty * This function initialises the provided SSL server context with
35210957b409SSimon J. Gerraty * all supported algorithms and cipher suites that rely on a RSA
35220957b409SSimon J. Gerraty * key pair.
35230957b409SSimon J. Gerraty *
35240957b409SSimon J. Gerraty * \param cc server context to initialise.
35250957b409SSimon J. Gerraty * \param chain server certificate chain.
35260957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
35270957b409SSimon J. Gerraty * \param sk RSA private key.
35280957b409SSimon J. Gerraty */
35290957b409SSimon J. Gerraty void br_ssl_server_init_full_rsa(br_ssl_server_context *cc,
35300957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
35310957b409SSimon J. Gerraty const br_rsa_private_key *sk);
35320957b409SSimon J. Gerraty
35330957b409SSimon J. Gerraty /**
35340957b409SSimon J. Gerraty * \brief SSL server profile: full_ec.
35350957b409SSimon J. Gerraty *
35360957b409SSimon J. Gerraty * This function initialises the provided SSL server context with
35370957b409SSimon J. Gerraty * all supported algorithms and cipher suites that rely on an EC
35380957b409SSimon J. Gerraty * key pair.
35390957b409SSimon J. Gerraty *
35400957b409SSimon J. Gerraty * The key type of the CA that issued the server's certificate must
35410957b409SSimon J. Gerraty * be provided, since it matters for ECDH cipher suites (ECDH_RSA
35420957b409SSimon J. Gerraty * suites require a RSA-powered CA). The key type is either
35430957b409SSimon J. Gerraty * `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`.
35440957b409SSimon J. Gerraty *
35450957b409SSimon J. Gerraty * \param cc server context to initialise.
35460957b409SSimon J. Gerraty * \param chain server certificate chain.
35470957b409SSimon J. Gerraty * \param chain_len chain length (number of certificates).
35480957b409SSimon J. Gerraty * \param cert_issuer_key_type certificate issuer's key type.
35490957b409SSimon J. Gerraty * \param sk EC private key.
35500957b409SSimon J. Gerraty */
35510957b409SSimon J. Gerraty void br_ssl_server_init_full_ec(br_ssl_server_context *cc,
35520957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
35530957b409SSimon J. Gerraty unsigned cert_issuer_key_type, const br_ec_private_key *sk);
35540957b409SSimon J. Gerraty
35550957b409SSimon J. Gerraty /**
35560957b409SSimon J. Gerraty * \brief SSL server profile: minr2g.
35570957b409SSimon J. Gerraty *
35580957b409SSimon J. Gerraty * This profile uses only TLS_RSA_WITH_AES_128_GCM_SHA256. Server key is
35590957b409SSimon J. Gerraty * RSA, and RSA key exchange is used (not forward secure, but uses little
35600957b409SSimon J. Gerraty * CPU in the client).
35610957b409SSimon J. Gerraty *
35620957b409SSimon J. Gerraty * \param cc server context to initialise.
35630957b409SSimon J. Gerraty * \param chain server certificate chain.
35640957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
35650957b409SSimon J. Gerraty * \param sk RSA private key.
35660957b409SSimon J. Gerraty */
35670957b409SSimon J. Gerraty void br_ssl_server_init_minr2g(br_ssl_server_context *cc,
35680957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
35690957b409SSimon J. Gerraty const br_rsa_private_key *sk);
35700957b409SSimon J. Gerraty
35710957b409SSimon J. Gerraty /**
35720957b409SSimon J. Gerraty * \brief SSL server profile: mine2g.
35730957b409SSimon J. Gerraty *
35740957b409SSimon J. Gerraty * This profile uses only TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256. Server key
35750957b409SSimon J. Gerraty * is RSA, and ECDHE key exchange is used. This suite provides forward
35760957b409SSimon J. Gerraty * security, with a higher CPU expense on the client, and a somewhat
35770957b409SSimon J. Gerraty * larger code footprint (compared to "minr2g").
35780957b409SSimon J. Gerraty *
35790957b409SSimon J. Gerraty * \param cc server context to initialise.
35800957b409SSimon J. Gerraty * \param chain server certificate chain.
35810957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
35820957b409SSimon J. Gerraty * \param sk RSA private key.
35830957b409SSimon J. Gerraty */
35840957b409SSimon J. Gerraty void br_ssl_server_init_mine2g(br_ssl_server_context *cc,
35850957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
35860957b409SSimon J. Gerraty const br_rsa_private_key *sk);
35870957b409SSimon J. Gerraty
35880957b409SSimon J. Gerraty /**
35890957b409SSimon J. Gerraty * \brief SSL server profile: minf2g.
35900957b409SSimon J. Gerraty *
35910957b409SSimon J. Gerraty * This profile uses only TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256.
35920957b409SSimon J. Gerraty * Server key is EC, and ECDHE key exchange is used. This suite provides
35930957b409SSimon J. Gerraty * forward security, with a higher CPU expense on the client and server
35940957b409SSimon J. Gerraty * (by a factor of about 3 to 4), and a somewhat larger code footprint
35950957b409SSimon J. Gerraty * (compared to "minu2g" and "minv2g").
35960957b409SSimon J. Gerraty *
35970957b409SSimon J. Gerraty * \param cc server context to initialise.
35980957b409SSimon J. Gerraty * \param chain server certificate chain.
35990957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
36000957b409SSimon J. Gerraty * \param sk EC private key.
36010957b409SSimon J. Gerraty */
36020957b409SSimon J. Gerraty void br_ssl_server_init_minf2g(br_ssl_server_context *cc,
36030957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
36040957b409SSimon J. Gerraty const br_ec_private_key *sk);
36050957b409SSimon J. Gerraty
36060957b409SSimon J. Gerraty /**
36070957b409SSimon J. Gerraty * \brief SSL server profile: minu2g.
36080957b409SSimon J. Gerraty *
36090957b409SSimon J. Gerraty * This profile uses only TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256.
36100957b409SSimon J. Gerraty * Server key is EC, and ECDH key exchange is used; the issuing CA used
36110957b409SSimon J. Gerraty * a RSA key.
36120957b409SSimon J. Gerraty *
36130957b409SSimon J. Gerraty * The "minu2g" and "minv2g" profiles do not provide forward secrecy,
36140957b409SSimon J. Gerraty * but are the lightest on the server (for CPU usage), and are rather
36150957b409SSimon J. Gerraty * inexpensive on the client as well.
36160957b409SSimon J. Gerraty *
36170957b409SSimon J. Gerraty * \param cc server context to initialise.
36180957b409SSimon J. Gerraty * \param chain server certificate chain.
36190957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
36200957b409SSimon J. Gerraty * \param sk EC private key.
36210957b409SSimon J. Gerraty */
36220957b409SSimon J. Gerraty void br_ssl_server_init_minu2g(br_ssl_server_context *cc,
36230957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
36240957b409SSimon J. Gerraty const br_ec_private_key *sk);
36250957b409SSimon J. Gerraty
36260957b409SSimon J. Gerraty /**
36270957b409SSimon J. Gerraty * \brief SSL server profile: minv2g.
36280957b409SSimon J. Gerraty *
36290957b409SSimon J. Gerraty * This profile uses only TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256.
36300957b409SSimon J. Gerraty * Server key is EC, and ECDH key exchange is used; the issuing CA used
36310957b409SSimon J. Gerraty * an EC key.
36320957b409SSimon J. Gerraty *
36330957b409SSimon J. Gerraty * The "minu2g" and "minv2g" profiles do not provide forward secrecy,
36340957b409SSimon J. Gerraty * but are the lightest on the server (for CPU usage), and are rather
36350957b409SSimon J. Gerraty * inexpensive on the client as well.
36360957b409SSimon J. Gerraty *
36370957b409SSimon J. Gerraty * \param cc server context to initialise.
36380957b409SSimon J. Gerraty * \param chain server certificate chain.
36390957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
36400957b409SSimon J. Gerraty * \param sk EC private key.
36410957b409SSimon J. Gerraty */
36420957b409SSimon J. Gerraty void br_ssl_server_init_minv2g(br_ssl_server_context *cc,
36430957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
36440957b409SSimon J. Gerraty const br_ec_private_key *sk);
36450957b409SSimon J. Gerraty
36460957b409SSimon J. Gerraty /**
36470957b409SSimon J. Gerraty * \brief SSL server profile: mine2c.
36480957b409SSimon J. Gerraty *
36490957b409SSimon J. Gerraty * This profile uses only TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256.
36500957b409SSimon J. Gerraty * Server key is RSA, and ECDHE key exchange is used. This suite
36510957b409SSimon J. Gerraty * provides forward security.
36520957b409SSimon J. Gerraty *
36530957b409SSimon J. Gerraty * \param cc server context to initialise.
36540957b409SSimon J. Gerraty * \param chain server certificate chain.
36550957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
36560957b409SSimon J. Gerraty * \param sk RSA private key.
36570957b409SSimon J. Gerraty */
36580957b409SSimon J. Gerraty void br_ssl_server_init_mine2c(br_ssl_server_context *cc,
36590957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
36600957b409SSimon J. Gerraty const br_rsa_private_key *sk);
36610957b409SSimon J. Gerraty
36620957b409SSimon J. Gerraty /**
36630957b409SSimon J. Gerraty * \brief SSL server profile: minf2c.
36640957b409SSimon J. Gerraty *
36650957b409SSimon J. Gerraty * This profile uses only TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256.
36660957b409SSimon J. Gerraty * Server key is EC, and ECDHE key exchange is used. This suite provides
36670957b409SSimon J. Gerraty * forward security.
36680957b409SSimon J. Gerraty *
36690957b409SSimon J. Gerraty * \param cc server context to initialise.
36700957b409SSimon J. Gerraty * \param chain server certificate chain.
36710957b409SSimon J. Gerraty * \param chain_len certificate chain length (number of certificate).
36720957b409SSimon J. Gerraty * \param sk EC private key.
36730957b409SSimon J. Gerraty */
36740957b409SSimon J. Gerraty void br_ssl_server_init_minf2c(br_ssl_server_context *cc,
36750957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
36760957b409SSimon J. Gerraty const br_ec_private_key *sk);
36770957b409SSimon J. Gerraty
36780957b409SSimon J. Gerraty /**
36790957b409SSimon J. Gerraty * \brief Get the supported client suites.
36800957b409SSimon J. Gerraty *
36810957b409SSimon J. Gerraty * This function shall be called only after the ClientHello has been
36820957b409SSimon J. Gerraty * processed, typically from the policy engine. The returned array
36830957b409SSimon J. Gerraty * contains the cipher suites that are supported by both the client
36840957b409SSimon J. Gerraty * and the server; these suites are in client preference order, unless
36850957b409SSimon J. Gerraty * the `BR_OPT_ENFORCE_SERVER_PREFERENCES` flag was set, in which case
36860957b409SSimon J. Gerraty * they are in server preference order.
36870957b409SSimon J. Gerraty *
36880957b409SSimon J. Gerraty * The suites are _translated_, which means that each suite is given
36890957b409SSimon J. Gerraty * as two 16-bit integers: the standard suite identifier, and its
36900957b409SSimon J. Gerraty * translated version, broken down into its individual components,
36910957b409SSimon J. Gerraty * as explained with the `br_suite_translated` type.
36920957b409SSimon J. Gerraty *
36930957b409SSimon J. Gerraty * The returned array is allocated in the context and will be rewritten
36940957b409SSimon J. Gerraty * by each handshake.
36950957b409SSimon J. Gerraty *
36960957b409SSimon J. Gerraty * \param cc server context.
36970957b409SSimon J. Gerraty * \param num receives the array size (number of suites).
36980957b409SSimon J. Gerraty * \return the translated common cipher suites, in preference order.
36990957b409SSimon J. Gerraty */
37000957b409SSimon J. Gerraty static inline const br_suite_translated *
br_ssl_server_get_client_suites(const br_ssl_server_context * cc,size_t * num)37010957b409SSimon J. Gerraty br_ssl_server_get_client_suites(const br_ssl_server_context *cc, size_t *num)
37020957b409SSimon J. Gerraty {
37030957b409SSimon J. Gerraty *num = cc->client_suites_num;
37040957b409SSimon J. Gerraty return cc->client_suites;
37050957b409SSimon J. Gerraty }
37060957b409SSimon J. Gerraty
37070957b409SSimon J. Gerraty /**
37080957b409SSimon J. Gerraty * \brief Get the hash functions and signature algorithms supported by
37090957b409SSimon J. Gerraty * the client.
37100957b409SSimon J. Gerraty *
37110957b409SSimon J. Gerraty * This value is a bit field:
37120957b409SSimon J. Gerraty *
37130957b409SSimon J. Gerraty * - If RSA (PKCS#1 v1.5) is supported with hash function of ID `x`,
37140957b409SSimon J. Gerraty * then bit `x` is set (hash function ID is 0 for the special MD5+SHA-1,
37150957b409SSimon J. Gerraty * or 2 to 6 for the SHA family).
37160957b409SSimon J. Gerraty *
37170957b409SSimon J. Gerraty * - If ECDSA is supported with hash function of ID `x`, then bit `8+x`
37180957b409SSimon J. Gerraty * is set.
37190957b409SSimon J. Gerraty *
37200957b409SSimon J. Gerraty * - Newer algorithms are symbolic 16-bit identifiers that do not
37210957b409SSimon J. Gerraty * represent signature algorithm and hash function separately. If
37220957b409SSimon J. Gerraty * the TLS-level identifier is `0x0800+x` for a `x` in the 0..15
37230957b409SSimon J. Gerraty * range, then bit `16+x` is set.
37240957b409SSimon J. Gerraty *
37250957b409SSimon J. Gerraty * "New algorithms" are currently defined only in draft documents, so
37260957b409SSimon J. Gerraty * this support is subject to possible change. Right now (early 2017),
37270957b409SSimon J. Gerraty * this maps ed25519 (EdDSA on Curve25519) to bit 23, and ed448 (EdDSA
37280957b409SSimon J. Gerraty * on Curve448) to bit 24. If the identifiers on the wire change in
37290957b409SSimon J. Gerraty * future document, then the decoding mechanism in BearSSL will be
37300957b409SSimon J. Gerraty * amended to keep mapping ed25519 and ed448 on bits 23 and 24,
37310957b409SSimon J. Gerraty * respectively. Mapping of other new algorithms (e.g. RSA/PSS) is not
37320957b409SSimon J. Gerraty * guaranteed yet.
37330957b409SSimon J. Gerraty *
37340957b409SSimon J. Gerraty * \param cc server context.
37350957b409SSimon J. Gerraty * \return the client-supported hash functions and signature algorithms.
37360957b409SSimon J. Gerraty */
37370957b409SSimon J. Gerraty static inline uint32_t
br_ssl_server_get_client_hashes(const br_ssl_server_context * cc)37380957b409SSimon J. Gerraty br_ssl_server_get_client_hashes(const br_ssl_server_context *cc)
37390957b409SSimon J. Gerraty {
37400957b409SSimon J. Gerraty return cc->hashes;
37410957b409SSimon J. Gerraty }
37420957b409SSimon J. Gerraty
37430957b409SSimon J. Gerraty /**
37440957b409SSimon J. Gerraty * \brief Get the elliptic curves supported by the client.
37450957b409SSimon J. Gerraty *
37460957b409SSimon J. Gerraty * This is a bit field (bit x is set if curve of ID x is supported).
37470957b409SSimon J. Gerraty *
37480957b409SSimon J. Gerraty * \param cc server context.
37490957b409SSimon J. Gerraty * \return the client-supported elliptic curves.
37500957b409SSimon J. Gerraty */
37510957b409SSimon J. Gerraty static inline uint32_t
br_ssl_server_get_client_curves(const br_ssl_server_context * cc)37520957b409SSimon J. Gerraty br_ssl_server_get_client_curves(const br_ssl_server_context *cc)
37530957b409SSimon J. Gerraty {
37540957b409SSimon J. Gerraty return cc->curves;
37550957b409SSimon J. Gerraty }
37560957b409SSimon J. Gerraty
37570957b409SSimon J. Gerraty /**
37580957b409SSimon J. Gerraty * \brief Clear the complete contents of a SSL server context.
37590957b409SSimon J. Gerraty *
37600957b409SSimon J. Gerraty * Everything is cleared, including the reference to the configured buffer,
37610957b409SSimon J. Gerraty * implementations, cipher suites and state. This is a preparatory step
37620957b409SSimon J. Gerraty * to assembling a custom profile.
37630957b409SSimon J. Gerraty *
37640957b409SSimon J. Gerraty * \param cc server context to clear.
37650957b409SSimon J. Gerraty */
37660957b409SSimon J. Gerraty void br_ssl_server_zero(br_ssl_server_context *cc);
37670957b409SSimon J. Gerraty
37680957b409SSimon J. Gerraty /**
37690957b409SSimon J. Gerraty * \brief Set an externally provided policy context.
37700957b409SSimon J. Gerraty *
37710957b409SSimon J. Gerraty * The policy context's methods are invoked to decide the cipher suite
37720957b409SSimon J. Gerraty * and certificate chain, and to perform operations involving the server's
37730957b409SSimon J. Gerraty * private key.
37740957b409SSimon J. Gerraty *
37750957b409SSimon J. Gerraty * \param cc server context.
37760957b409SSimon J. Gerraty * \param pctx policy context (pointer to its vtable field).
37770957b409SSimon J. Gerraty */
37780957b409SSimon J. Gerraty static inline void
br_ssl_server_set_policy(br_ssl_server_context * cc,const br_ssl_server_policy_class ** pctx)37790957b409SSimon J. Gerraty br_ssl_server_set_policy(br_ssl_server_context *cc,
37800957b409SSimon J. Gerraty const br_ssl_server_policy_class **pctx)
37810957b409SSimon J. Gerraty {
37820957b409SSimon J. Gerraty cc->policy_vtable = pctx;
37830957b409SSimon J. Gerraty }
37840957b409SSimon J. Gerraty
37850957b409SSimon J. Gerraty /**
37860957b409SSimon J. Gerraty * \brief Set the server certificate chain and key (single RSA case).
37870957b409SSimon J. Gerraty *
37880957b409SSimon J. Gerraty * This function uses a policy context included in the server context.
37890957b409SSimon J. Gerraty * It configures use of a single server certificate chain with a RSA
37900957b409SSimon J. Gerraty * private key. The `allowed_usages` is a combination of usages, namely
37910957b409SSimon J. Gerraty * `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`; this enables or disables
37920957b409SSimon J. Gerraty * the corresponding cipher suites (i.e. `TLS_RSA_*` use the RSA key for
37930957b409SSimon J. Gerraty * key exchange, while `TLS_ECDHE_RSA_*` use the RSA key for signatures).
37940957b409SSimon J. Gerraty *
37950957b409SSimon J. Gerraty * \param cc server context.
37960957b409SSimon J. Gerraty * \param chain server certificate chain to send to the client.
37970957b409SSimon J. Gerraty * \param chain_len chain length (number of certificates).
37980957b409SSimon J. Gerraty * \param sk server private key (RSA).
37990957b409SSimon J. Gerraty * \param allowed_usages allowed private key usages.
38000957b409SSimon J. Gerraty * \param irsacore RSA core implementation.
38010957b409SSimon J. Gerraty * \param irsasign RSA signature implementation (PKCS#1 v1.5).
38020957b409SSimon J. Gerraty */
38030957b409SSimon J. Gerraty void br_ssl_server_set_single_rsa(br_ssl_server_context *cc,
38040957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
38050957b409SSimon J. Gerraty const br_rsa_private_key *sk, unsigned allowed_usages,
38060957b409SSimon J. Gerraty br_rsa_private irsacore, br_rsa_pkcs1_sign irsasign);
38070957b409SSimon J. Gerraty
38080957b409SSimon J. Gerraty /**
38090957b409SSimon J. Gerraty * \brief Set the server certificate chain and key (single EC case).
38100957b409SSimon J. Gerraty *
38110957b409SSimon J. Gerraty * This function uses a policy context included in the server context.
38120957b409SSimon J. Gerraty * It configures use of a single server certificate chain with an EC
38130957b409SSimon J. Gerraty * private key. The `allowed_usages` is a combination of usages, namely
38140957b409SSimon J. Gerraty * `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`; this enables or disables
38150957b409SSimon J. Gerraty * the corresponding cipher suites (i.e. `TLS_ECDH_*` use the EC key for
38160957b409SSimon J. Gerraty * key exchange, while `TLS_ECDHE_ECDSA_*` use the EC key for signatures).
38170957b409SSimon J. Gerraty *
38180957b409SSimon J. Gerraty * In order to support `TLS_ECDH_*` cipher suites (non-ephemeral ECDH),
38190957b409SSimon J. Gerraty * the algorithm type of the key used by the issuing CA to sign the
38200957b409SSimon J. Gerraty * server's certificate must be provided, as `cert_issuer_key_type`
38210957b409SSimon J. Gerraty * parameter (this value is either `BR_KEYTYPE_RSA` or `BR_KEYTYPE_EC`).
38220957b409SSimon J. Gerraty *
38230957b409SSimon J. Gerraty * \param cc server context.
38240957b409SSimon J. Gerraty * \param chain server certificate chain to send.
38250957b409SSimon J. Gerraty * \param chain_len chain length (number of certificates).
38260957b409SSimon J. Gerraty * \param sk server private key (EC).
38270957b409SSimon J. Gerraty * \param allowed_usages allowed private key usages.
38280957b409SSimon J. Gerraty * \param cert_issuer_key_type issuing CA's key type.
38290957b409SSimon J. Gerraty * \param iec EC core implementation.
38300957b409SSimon J. Gerraty * \param iecdsa ECDSA signature implementation ("asn1" format).
38310957b409SSimon J. Gerraty */
38320957b409SSimon J. Gerraty void br_ssl_server_set_single_ec(br_ssl_server_context *cc,
38330957b409SSimon J. Gerraty const br_x509_certificate *chain, size_t chain_len,
38340957b409SSimon J. Gerraty const br_ec_private_key *sk, unsigned allowed_usages,
38350957b409SSimon J. Gerraty unsigned cert_issuer_key_type,
38360957b409SSimon J. Gerraty const br_ec_impl *iec, br_ecdsa_sign iecdsa);
38370957b409SSimon J. Gerraty
38380957b409SSimon J. Gerraty /**
38390957b409SSimon J. Gerraty * \brief Activate client certificate authentication.
38400957b409SSimon J. Gerraty *
38410957b409SSimon J. Gerraty * The trust anchor encoded X.500 names (DN) to send to the client are
38420957b409SSimon J. Gerraty * provided. A client certificate will be requested and validated through
38430957b409SSimon J. Gerraty * the X.509 validator configured in the SSL engine. If `num` is 0, then
38440957b409SSimon J. Gerraty * client certificate authentication is disabled.
38450957b409SSimon J. Gerraty *
38460957b409SSimon J. Gerraty * If the client does not send a certificate, or on validation failure,
38470957b409SSimon J. Gerraty * the handshake aborts. Unauthenticated clients can be tolerated by
38480957b409SSimon J. Gerraty * setting the `BR_OPT_TOLERATE_NO_CLIENT_AUTH` flag.
38490957b409SSimon J. Gerraty *
38500957b409SSimon J. Gerraty * The provided array is linked in, not copied, so that pointer must
38510957b409SSimon J. Gerraty * remain valid as long as anchor names may be used.
38520957b409SSimon J. Gerraty *
38530957b409SSimon J. Gerraty * \param cc server context.
38540957b409SSimon J. Gerraty * \param ta_names encoded trust anchor names.
38550957b409SSimon J. Gerraty * \param num number of encoded trust anchor names.
38560957b409SSimon J. Gerraty */
38570957b409SSimon J. Gerraty static inline void
br_ssl_server_set_trust_anchor_names(br_ssl_server_context * cc,const br_x500_name * ta_names,size_t num)38580957b409SSimon J. Gerraty br_ssl_server_set_trust_anchor_names(br_ssl_server_context *cc,
38590957b409SSimon J. Gerraty const br_x500_name *ta_names, size_t num)
38600957b409SSimon J. Gerraty {
38610957b409SSimon J. Gerraty cc->ta_names = ta_names;
38620957b409SSimon J. Gerraty cc->tas = NULL;
38630957b409SSimon J. Gerraty cc->num_tas = num;
38640957b409SSimon J. Gerraty }
38650957b409SSimon J. Gerraty
38660957b409SSimon J. Gerraty /**
38670957b409SSimon J. Gerraty * \brief Activate client certificate authentication.
38680957b409SSimon J. Gerraty *
38690957b409SSimon J. Gerraty * This is a variant for `br_ssl_server_set_trust_anchor_names()`: the
38700957b409SSimon J. Gerraty * trust anchor names are provided not as an array of stand-alone names
38710957b409SSimon J. Gerraty * (`br_x500_name` structures), but as an array of trust anchors
38720957b409SSimon J. Gerraty * (`br_x509_trust_anchor` structures). The server engine itself will
38730957b409SSimon J. Gerraty * only use the `dn` field of each trust anchor. This is meant to allow
38740957b409SSimon J. Gerraty * defining a single array of trust anchors, to be used here and in the
38750957b409SSimon J. Gerraty * X.509 validation engine itself.
38760957b409SSimon J. Gerraty *
38770957b409SSimon J. Gerraty * The provided array is linked in, not copied, so that pointer must
38780957b409SSimon J. Gerraty * remain valid as long as anchor names may be used.
38790957b409SSimon J. Gerraty *
38800957b409SSimon J. Gerraty * \param cc server context.
38810957b409SSimon J. Gerraty * \param tas trust anchors (only names are used).
38820957b409SSimon J. Gerraty * \param num number of trust anchors.
38830957b409SSimon J. Gerraty */
38840957b409SSimon J. Gerraty static inline void
br_ssl_server_set_trust_anchor_names_alt(br_ssl_server_context * cc,const br_x509_trust_anchor * tas,size_t num)38850957b409SSimon J. Gerraty br_ssl_server_set_trust_anchor_names_alt(br_ssl_server_context *cc,
38860957b409SSimon J. Gerraty const br_x509_trust_anchor *tas, size_t num)
38870957b409SSimon J. Gerraty {
38880957b409SSimon J. Gerraty cc->ta_names = NULL;
38890957b409SSimon J. Gerraty cc->tas = tas;
38900957b409SSimon J. Gerraty cc->num_tas = num;
38910957b409SSimon J. Gerraty }
38920957b409SSimon J. Gerraty
38930957b409SSimon J. Gerraty /**
38940957b409SSimon J. Gerraty * \brief Configure the cache for session parameters.
38950957b409SSimon J. Gerraty *
38960957b409SSimon J. Gerraty * The cache context is provided as a pointer to its first field (vtable
38970957b409SSimon J. Gerraty * pointer).
38980957b409SSimon J. Gerraty *
38990957b409SSimon J. Gerraty * \param cc server context.
39000957b409SSimon J. Gerraty * \param vtable session cache context.
39010957b409SSimon J. Gerraty */
39020957b409SSimon J. Gerraty static inline void
br_ssl_server_set_cache(br_ssl_server_context * cc,const br_ssl_session_cache_class ** vtable)39030957b409SSimon J. Gerraty br_ssl_server_set_cache(br_ssl_server_context *cc,
39040957b409SSimon J. Gerraty const br_ssl_session_cache_class **vtable)
39050957b409SSimon J. Gerraty {
39060957b409SSimon J. Gerraty cc->cache_vtable = vtable;
39070957b409SSimon J. Gerraty }
39080957b409SSimon J. Gerraty
39090957b409SSimon J. Gerraty /**
39100957b409SSimon J. Gerraty * \brief Prepare or reset a server context for handling an incoming client.
39110957b409SSimon J. Gerraty *
39120957b409SSimon J. Gerraty * \param cc server context.
39130957b409SSimon J. Gerraty * \return 1 on success, 0 on error.
39140957b409SSimon J. Gerraty */
39150957b409SSimon J. Gerraty int br_ssl_server_reset(br_ssl_server_context *cc);
39160957b409SSimon J. Gerraty
39170957b409SSimon J. Gerraty /* ===================================================================== */
39180957b409SSimon J. Gerraty
39190957b409SSimon J. Gerraty /*
39200957b409SSimon J. Gerraty * Context for the simplified I/O context. The transport medium is accessed
39210957b409SSimon J. Gerraty * through the low_read() and low_write() callback functions, each with
39220957b409SSimon J. Gerraty * its own opaque context pointer.
39230957b409SSimon J. Gerraty *
39240957b409SSimon J. Gerraty * low_read() read some bytes, at most 'len' bytes, into data[]. The
39250957b409SSimon J. Gerraty * returned value is the number of read bytes, or -1 on error.
39260957b409SSimon J. Gerraty * The 'len' parameter is guaranteed never to exceed 20000,
39270957b409SSimon J. Gerraty * so the length always fits in an 'int' on all platforms.
39280957b409SSimon J. Gerraty *
39290957b409SSimon J. Gerraty * low_write() write up to 'len' bytes, to be read from data[]. The
39300957b409SSimon J. Gerraty * returned value is the number of written bytes, or -1 on
39310957b409SSimon J. Gerraty * error. The 'len' parameter is guaranteed never to exceed
39320957b409SSimon J. Gerraty * 20000, so the length always fits in an 'int' on all
39330957b409SSimon J. Gerraty * parameters.
39340957b409SSimon J. Gerraty *
39350957b409SSimon J. Gerraty * A socket closure (if the transport medium is a socket) should be reported
39360957b409SSimon J. Gerraty * as an error (-1). The callbacks shall endeavour to block until at least
39370957b409SSimon J. Gerraty * one byte can be read or written; a callback returning 0 at times is
39380957b409SSimon J. Gerraty * acceptable, but this normally leads to the callback being immediately
39390957b409SSimon J. Gerraty * called again, so the callback should at least always try to block for
39400957b409SSimon J. Gerraty * some time if no I/O can take place.
39410957b409SSimon J. Gerraty *
39420957b409SSimon J. Gerraty * The SSL engine naturally applies some buffering, so the callbacks need
39430957b409SSimon J. Gerraty * not apply buffers of their own.
39440957b409SSimon J. Gerraty */
39450957b409SSimon J. Gerraty /**
39460957b409SSimon J. Gerraty * \brief Context structure for the simplified SSL I/O wrapper.
39470957b409SSimon J. Gerraty *
39480957b409SSimon J. Gerraty * This structure is initialised with `br_sslio_init()`. Its contents
39490957b409SSimon J. Gerraty * are opaque and shall not be accessed directly.
39500957b409SSimon J. Gerraty */
39510957b409SSimon J. Gerraty typedef struct {
39520957b409SSimon J. Gerraty #ifndef BR_DOXYGEN_IGNORE
39530957b409SSimon J. Gerraty br_ssl_engine_context *engine;
39540957b409SSimon J. Gerraty int (*low_read)(void *read_context,
39550957b409SSimon J. Gerraty unsigned char *data, size_t len);
39560957b409SSimon J. Gerraty void *read_context;
39570957b409SSimon J. Gerraty int (*low_write)(void *write_context,
39580957b409SSimon J. Gerraty const unsigned char *data, size_t len);
39590957b409SSimon J. Gerraty void *write_context;
39600957b409SSimon J. Gerraty #endif
39610957b409SSimon J. Gerraty } br_sslio_context;
39620957b409SSimon J. Gerraty
39630957b409SSimon J. Gerraty /**
39640957b409SSimon J. Gerraty * \brief Initialise a simplified I/O wrapper context.
39650957b409SSimon J. Gerraty *
39660957b409SSimon J. Gerraty * The simplified I/O wrapper offers a simpler read/write API for a SSL
39670957b409SSimon J. Gerraty * engine (client or server), using the provided callback functions for
39680957b409SSimon J. Gerraty * reading data from, or writing data to, the transport medium.
39690957b409SSimon J. Gerraty *
39700957b409SSimon J. Gerraty * The callback functions have the following semantics:
39710957b409SSimon J. Gerraty *
39720957b409SSimon J. Gerraty * - Each callback receives an opaque context value (of type `void *`)
39730957b409SSimon J. Gerraty * that the callback may use arbitrarily (or possibly ignore).
39740957b409SSimon J. Gerraty *
39750957b409SSimon J. Gerraty * - `low_read()` reads at least one byte, at most `len` bytes, from
39760957b409SSimon J. Gerraty * the transport medium. Read bytes shall be written in `data`.
39770957b409SSimon J. Gerraty *
39780957b409SSimon J. Gerraty * - `low_write()` writes at least one byte, at most `len` bytes, unto
39790957b409SSimon J. Gerraty * the transport medium. The bytes to write are read from `data`.
39800957b409SSimon J. Gerraty *
39810957b409SSimon J. Gerraty * - The `len` parameter is never zero, and is always lower than 20000.
39820957b409SSimon J. Gerraty *
39830957b409SSimon J. Gerraty * - The number of processed bytes (read or written) is returned. Since
39840957b409SSimon J. Gerraty * that number is less than 20000, it always fits on an `int`.
39850957b409SSimon J. Gerraty *
39860957b409SSimon J. Gerraty * - On error, the callbacks return -1. Reaching end-of-stream is an
39870957b409SSimon J. Gerraty * error. Errors are permanent: the SSL connection is terminated.
39880957b409SSimon J. Gerraty *
39890957b409SSimon J. Gerraty * - Callbacks SHOULD NOT return 0. This is tolerated, as long as
39900957b409SSimon J. Gerraty * callbacks endeavour to block for some non-negligible amount of
39910957b409SSimon J. Gerraty * time until at least one byte can be sent or received (if a
39920957b409SSimon J. Gerraty * callback returns 0, then the wrapper invokes it again
39930957b409SSimon J. Gerraty * immediately).
39940957b409SSimon J. Gerraty *
39950957b409SSimon J. Gerraty * - Callbacks MAY return as soon as at least one byte is processed;
39960957b409SSimon J. Gerraty * they MAY also insist on reading or writing _all_ requested bytes.
39970957b409SSimon J. Gerraty * Since SSL is a self-terminated protocol (each record has a length
39980957b409SSimon J. Gerraty * header), this does not change semantics.
39990957b409SSimon J. Gerraty *
40000957b409SSimon J. Gerraty * - Callbacks need not apply any buffering (for performance) since SSL
40010957b409SSimon J. Gerraty * itself uses buffers.
40020957b409SSimon J. Gerraty *
40030957b409SSimon J. Gerraty * \param ctx wrapper context to initialise.
40040957b409SSimon J. Gerraty * \param engine SSL engine to wrap.
40050957b409SSimon J. Gerraty * \param low_read callback for reading data from the transport.
40060957b409SSimon J. Gerraty * \param read_context context pointer for `low_read()`.
40070957b409SSimon J. Gerraty * \param low_write callback for writing data on the transport.
40080957b409SSimon J. Gerraty * \param write_context context pointer for `low_write()`.
40090957b409SSimon J. Gerraty */
40100957b409SSimon J. Gerraty void br_sslio_init(br_sslio_context *ctx,
40110957b409SSimon J. Gerraty br_ssl_engine_context *engine,
40120957b409SSimon J. Gerraty int (*low_read)(void *read_context,
40130957b409SSimon J. Gerraty unsigned char *data, size_t len),
40140957b409SSimon J. Gerraty void *read_context,
40150957b409SSimon J. Gerraty int (*low_write)(void *write_context,
40160957b409SSimon J. Gerraty const unsigned char *data, size_t len),
40170957b409SSimon J. Gerraty void *write_context);
40180957b409SSimon J. Gerraty
40190957b409SSimon J. Gerraty /**
40200957b409SSimon J. Gerraty * \brief Read some application data from a SSL connection.
40210957b409SSimon J. Gerraty *
40220957b409SSimon J. Gerraty * If `len` is zero, then this function returns 0 immediately. In
40230957b409SSimon J. Gerraty * all other cases, it never returns 0.
40240957b409SSimon J. Gerraty *
40250957b409SSimon J. Gerraty * This call returns only when at least one byte has been obtained.
40260957b409SSimon J. Gerraty * Returned value is the number of bytes read, or -1 on error. The
40270957b409SSimon J. Gerraty * number of bytes always fits on an 'int' (data from a single SSL/TLS
40280957b409SSimon J. Gerraty * record is returned).
40290957b409SSimon J. Gerraty *
40300957b409SSimon J. Gerraty * On error or SSL closure, this function returns -1. The caller should
40310957b409SSimon J. Gerraty * inspect the error status on the SSL engine to distinguish between
40320957b409SSimon J. Gerraty * normal closure and error.
40330957b409SSimon J. Gerraty *
40340957b409SSimon J. Gerraty * \param cc SSL wrapper context.
40350957b409SSimon J. Gerraty * \param dst destination buffer for application data.
40360957b409SSimon J. Gerraty * \param len maximum number of bytes to obtain.
40370957b409SSimon J. Gerraty * \return number of bytes obtained, or -1 on error.
40380957b409SSimon J. Gerraty */
40390957b409SSimon J. Gerraty int br_sslio_read(br_sslio_context *cc, void *dst, size_t len);
40400957b409SSimon J. Gerraty
40410957b409SSimon J. Gerraty /**
40420957b409SSimon J. Gerraty * \brief Read application data from a SSL connection.
40430957b409SSimon J. Gerraty *
40440957b409SSimon J. Gerraty * This calls returns only when _all_ requested `len` bytes are read,
40450957b409SSimon J. Gerraty * or an error is reached. Returned value is 0 on success, -1 on error.
40460957b409SSimon J. Gerraty * A normal (verified) SSL closure before that many bytes are obtained
40470957b409SSimon J. Gerraty * is reported as an error by this function.
40480957b409SSimon J. Gerraty *
40490957b409SSimon J. Gerraty * \param cc SSL wrapper context.
40500957b409SSimon J. Gerraty * \param dst destination buffer for application data.
40510957b409SSimon J. Gerraty * \param len number of bytes to obtain.
40520957b409SSimon J. Gerraty * \return 0 on success, or -1 on error.
40530957b409SSimon J. Gerraty */
40540957b409SSimon J. Gerraty int br_sslio_read_all(br_sslio_context *cc, void *dst, size_t len);
40550957b409SSimon J. Gerraty
40560957b409SSimon J. Gerraty /**
40570957b409SSimon J. Gerraty * \brief Write some application data unto a SSL connection.
40580957b409SSimon J. Gerraty *
40590957b409SSimon J. Gerraty * If `len` is zero, then this function returns 0 immediately. In
40600957b409SSimon J. Gerraty * all other cases, it never returns 0.
40610957b409SSimon J. Gerraty *
40620957b409SSimon J. Gerraty * This call returns only when at least one byte has been written.
40630957b409SSimon J. Gerraty * Returned value is the number of bytes written, or -1 on error. The
40640957b409SSimon J. Gerraty * number of bytes always fits on an 'int' (less than 20000).
40650957b409SSimon J. Gerraty *
40660957b409SSimon J. Gerraty * On error or SSL closure, this function returns -1. The caller should
40670957b409SSimon J. Gerraty * inspect the error status on the SSL engine to distinguish between
40680957b409SSimon J. Gerraty * normal closure and error.
40690957b409SSimon J. Gerraty *
40700957b409SSimon J. Gerraty * **Important:** SSL is buffered; a "written" byte is a byte that was
40710957b409SSimon J. Gerraty * injected into the wrapped SSL engine, but this does not necessarily mean
40720957b409SSimon J. Gerraty * that it has been scheduled for sending. Use `br_sslio_flush()` to
40730957b409SSimon J. Gerraty * ensure that all pending data has been sent to the transport medium.
40740957b409SSimon J. Gerraty *
40750957b409SSimon J. Gerraty * \param cc SSL wrapper context.
40760957b409SSimon J. Gerraty * \param src source buffer for application data.
40770957b409SSimon J. Gerraty * \param len maximum number of bytes to write.
40780957b409SSimon J. Gerraty * \return number of bytes written, or -1 on error.
40790957b409SSimon J. Gerraty */
40800957b409SSimon J. Gerraty int br_sslio_write(br_sslio_context *cc, const void *src, size_t len);
40810957b409SSimon J. Gerraty
40820957b409SSimon J. Gerraty /**
40830957b409SSimon J. Gerraty * \brief Write application data unto a SSL connection.
40840957b409SSimon J. Gerraty *
40850957b409SSimon J. Gerraty * This calls returns only when _all_ requested `len` bytes have been
40860957b409SSimon J. Gerraty * written, or an error is reached. Returned value is 0 on success, -1
40870957b409SSimon J. Gerraty * on error. A normal (verified) SSL closure before that many bytes are
40880957b409SSimon J. Gerraty * written is reported as an error by this function.
40890957b409SSimon J. Gerraty *
40900957b409SSimon J. Gerraty * **Important:** SSL is buffered; a "written" byte is a byte that was
40910957b409SSimon J. Gerraty * injected into the wrapped SSL engine, but this does not necessarily mean
40920957b409SSimon J. Gerraty * that it has been scheduled for sending. Use `br_sslio_flush()` to
40930957b409SSimon J. Gerraty * ensure that all pending data has been sent to the transport medium.
40940957b409SSimon J. Gerraty *
40950957b409SSimon J. Gerraty * \param cc SSL wrapper context.
40960957b409SSimon J. Gerraty * \param src source buffer for application data.
40970957b409SSimon J. Gerraty * \param len number of bytes to write.
40980957b409SSimon J. Gerraty * \return 0 on success, or -1 on error.
40990957b409SSimon J. Gerraty */
41000957b409SSimon J. Gerraty int br_sslio_write_all(br_sslio_context *cc, const void *src, size_t len);
41010957b409SSimon J. Gerraty
41020957b409SSimon J. Gerraty /**
41030957b409SSimon J. Gerraty * \brief Flush pending data.
41040957b409SSimon J. Gerraty *
41050957b409SSimon J. Gerraty * This call makes sure that any buffered application data in the
41060957b409SSimon J. Gerraty * provided context (including the wrapped SSL engine) has been sent
41070957b409SSimon J. Gerraty * to the transport medium (i.e. accepted by the `low_write()` callback
41080957b409SSimon J. Gerraty * method). If there is no such pending data, then this function does
41090957b409SSimon J. Gerraty * nothing (and returns a success, i.e. 0).
41100957b409SSimon J. Gerraty *
41110957b409SSimon J. Gerraty * If the underlying transport medium has its own buffers, then it is
41120957b409SSimon J. Gerraty * up to the caller to ensure the corresponding flushing.
41130957b409SSimon J. Gerraty *
41140957b409SSimon J. Gerraty * Returned value is 0 on success, -1 on error.
41150957b409SSimon J. Gerraty *
41160957b409SSimon J. Gerraty * \param cc SSL wrapper context.
41170957b409SSimon J. Gerraty * \return 0 on success, or -1 on error.
41180957b409SSimon J. Gerraty */
41190957b409SSimon J. Gerraty int br_sslio_flush(br_sslio_context *cc);
41200957b409SSimon J. Gerraty
41210957b409SSimon J. Gerraty /**
41220957b409SSimon J. Gerraty * \brief Close the SSL connection.
41230957b409SSimon J. Gerraty *
41240957b409SSimon J. Gerraty * This call runs the SSL closure protocol (sending a `close_notify`,
41250957b409SSimon J. Gerraty * receiving the response `close_notify`). When it returns, the SSL
41260957b409SSimon J. Gerraty * connection is finished. It is still up to the caller to manage the
41270957b409SSimon J. Gerraty * possible transport-level termination, if applicable (alternatively,
41280957b409SSimon J. Gerraty * the underlying transport stream may be reused for non-SSL messages).
41290957b409SSimon J. Gerraty *
41300957b409SSimon J. Gerraty * Returned value is 0 on success, -1 on error. A failure by the peer
41310957b409SSimon J. Gerraty * to process the complete closure protocol (i.e. sending back the
41320957b409SSimon J. Gerraty * `close_notify`) is an error.
41330957b409SSimon J. Gerraty *
41340957b409SSimon J. Gerraty * \param cc SSL wrapper context.
41350957b409SSimon J. Gerraty * \return 0 on success, or -1 on error.
41360957b409SSimon J. Gerraty */
41370957b409SSimon J. Gerraty int br_sslio_close(br_sslio_context *cc);
41380957b409SSimon J. Gerraty
41390957b409SSimon J. Gerraty /* ===================================================================== */
41400957b409SSimon J. Gerraty
41410957b409SSimon J. Gerraty /*
41420957b409SSimon J. Gerraty * Symbolic constants for cipher suites.
41430957b409SSimon J. Gerraty */
41440957b409SSimon J. Gerraty
41450957b409SSimon J. Gerraty /* From RFC 5246 */
41460957b409SSimon J. Gerraty #define BR_TLS_NULL_WITH_NULL_NULL 0x0000
41470957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_NULL_MD5 0x0001
41480957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_NULL_SHA 0x0002
41490957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_NULL_SHA256 0x003B
41500957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_RC4_128_MD5 0x0004
41510957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_RC4_128_SHA 0x0005
41520957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A
41530957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_128_CBC_SHA 0x002F
41540957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
41550957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_128_CBC_SHA256 0x003C
41560957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_256_CBC_SHA256 0x003D
41570957b409SSimon J. Gerraty #define BR_TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 0x000D
41580957b409SSimon J. Gerraty #define BR_TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 0x0010
41590957b409SSimon J. Gerraty #define BR_TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 0x0013
41600957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 0x0016
41610957b409SSimon J. Gerraty #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA 0x0030
41620957b409SSimon J. Gerraty #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA 0x0031
41630957b409SSimon J. Gerraty #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA 0x0032
41640957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA 0x0033
41650957b409SSimon J. Gerraty #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA 0x0036
41660957b409SSimon J. Gerraty #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA 0x0037
41670957b409SSimon J. Gerraty #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA 0x0038
41680957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0039
41690957b409SSimon J. Gerraty #define BR_TLS_DH_DSS_WITH_AES_128_CBC_SHA256 0x003E
41700957b409SSimon J. Gerraty #define BR_TLS_DH_RSA_WITH_AES_128_CBC_SHA256 0x003F
41710957b409SSimon J. Gerraty #define BR_TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 0x0040
41720957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 0x0067
41730957b409SSimon J. Gerraty #define BR_TLS_DH_DSS_WITH_AES_256_CBC_SHA256 0x0068
41740957b409SSimon J. Gerraty #define BR_TLS_DH_RSA_WITH_AES_256_CBC_SHA256 0x0069
41750957b409SSimon J. Gerraty #define BR_TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 0x006A
41760957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 0x006B
41770957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_RC4_128_MD5 0x0018
41780957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 0x001B
41790957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA 0x0034
41800957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA 0x003A
41810957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_AES_128_CBC_SHA256 0x006C
41820957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_AES_256_CBC_SHA256 0x006D
41830957b409SSimon J. Gerraty
41840957b409SSimon J. Gerraty /* From RFC 4492 */
41850957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_NULL_SHA 0xC001
41860957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_RC4_128_SHA 0xC002
41870957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC003
41880957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 0xC004
41890957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 0xC005
41900957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006
41910957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 0xC007
41920957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 0xC008
41930957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009
41940957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A
41950957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_NULL_SHA 0xC00B
41960957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_RC4_128_SHA 0xC00C
41970957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 0xC00D
41980957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 0xC00E
41990957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 0xC00F
42000957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010
42010957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_RC4_128_SHA 0xC011
42020957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 0xC012
42030957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013
42040957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014
42050957b409SSimon J. Gerraty #define BR_TLS_ECDH_anon_WITH_NULL_SHA 0xC015
42060957b409SSimon J. Gerraty #define BR_TLS_ECDH_anon_WITH_RC4_128_SHA 0xC016
42070957b409SSimon J. Gerraty #define BR_TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 0xC017
42080957b409SSimon J. Gerraty #define BR_TLS_ECDH_anon_WITH_AES_128_CBC_SHA 0xC018
42090957b409SSimon J. Gerraty #define BR_TLS_ECDH_anon_WITH_AES_256_CBC_SHA 0xC019
42100957b409SSimon J. Gerraty
42110957b409SSimon J. Gerraty /* From RFC 5288 */
42120957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_128_GCM_SHA256 0x009C
42130957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_256_GCM_SHA384 0x009D
42140957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 0x009E
42150957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 0x009F
42160957b409SSimon J. Gerraty #define BR_TLS_DH_RSA_WITH_AES_128_GCM_SHA256 0x00A0
42170957b409SSimon J. Gerraty #define BR_TLS_DH_RSA_WITH_AES_256_GCM_SHA384 0x00A1
42180957b409SSimon J. Gerraty #define BR_TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 0x00A2
42190957b409SSimon J. Gerraty #define BR_TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 0x00A3
42200957b409SSimon J. Gerraty #define BR_TLS_DH_DSS_WITH_AES_128_GCM_SHA256 0x00A4
42210957b409SSimon J. Gerraty #define BR_TLS_DH_DSS_WITH_AES_256_GCM_SHA384 0x00A5
42220957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_AES_128_GCM_SHA256 0x00A6
42230957b409SSimon J. Gerraty #define BR_TLS_DH_anon_WITH_AES_256_GCM_SHA384 0x00A7
42240957b409SSimon J. Gerraty
42250957b409SSimon J. Gerraty /* From RFC 5289 */
42260957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023
42270957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024
42280957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 0xC025
42290957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 0xC026
42300957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027
42310957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028
42320957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 0xC029
42330957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 0xC02A
42340957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B
42350957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C
42360957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 0xC02D
42370957b409SSimon J. Gerraty #define BR_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 0xC02E
42380957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F
42390957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030
42400957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031
42410957b409SSimon J. Gerraty #define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032
42420957b409SSimon J. Gerraty
42430957b409SSimon J. Gerraty /* From RFC 6655 and 7251 */
42440957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_128_CCM 0xC09C
42450957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_256_CCM 0xC09D
42460957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_128_CCM_8 0xC0A0
42470957b409SSimon J. Gerraty #define BR_TLS_RSA_WITH_AES_256_CCM_8 0xC0A1
42480957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM 0xC0AC
42490957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM 0xC0AD
42500957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 0xC0AE
42510957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8 0xC0AF
42520957b409SSimon J. Gerraty
42530957b409SSimon J. Gerraty /* From RFC 7905 */
42540957b409SSimon J. Gerraty #define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8
42550957b409SSimon J. Gerraty #define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9
42560957b409SSimon J. Gerraty #define BR_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCAA
42570957b409SSimon J. Gerraty #define BR_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB
42580957b409SSimon J. Gerraty #define BR_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC
42590957b409SSimon J. Gerraty #define BR_TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAD
42600957b409SSimon J. Gerraty #define BR_TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAE
42610957b409SSimon J. Gerraty
42620957b409SSimon J. Gerraty /* From RFC 7507 */
42630957b409SSimon J. Gerraty #define BR_TLS_FALLBACK_SCSV 0x5600
42640957b409SSimon J. Gerraty
42650957b409SSimon J. Gerraty /*
42660957b409SSimon J. Gerraty * Symbolic constants for alerts.
42670957b409SSimon J. Gerraty */
42680957b409SSimon J. Gerraty #define BR_ALERT_CLOSE_NOTIFY 0
42690957b409SSimon J. Gerraty #define BR_ALERT_UNEXPECTED_MESSAGE 10
42700957b409SSimon J. Gerraty #define BR_ALERT_BAD_RECORD_MAC 20
42710957b409SSimon J. Gerraty #define BR_ALERT_RECORD_OVERFLOW 22
42720957b409SSimon J. Gerraty #define BR_ALERT_DECOMPRESSION_FAILURE 30
42730957b409SSimon J. Gerraty #define BR_ALERT_HANDSHAKE_FAILURE 40
42740957b409SSimon J. Gerraty #define BR_ALERT_BAD_CERTIFICATE 42
42750957b409SSimon J. Gerraty #define BR_ALERT_UNSUPPORTED_CERTIFICATE 43
42760957b409SSimon J. Gerraty #define BR_ALERT_CERTIFICATE_REVOKED 44
42770957b409SSimon J. Gerraty #define BR_ALERT_CERTIFICATE_EXPIRED 45
42780957b409SSimon J. Gerraty #define BR_ALERT_CERTIFICATE_UNKNOWN 46
42790957b409SSimon J. Gerraty #define BR_ALERT_ILLEGAL_PARAMETER 47
42800957b409SSimon J. Gerraty #define BR_ALERT_UNKNOWN_CA 48
42810957b409SSimon J. Gerraty #define BR_ALERT_ACCESS_DENIED 49
42820957b409SSimon J. Gerraty #define BR_ALERT_DECODE_ERROR 50
42830957b409SSimon J. Gerraty #define BR_ALERT_DECRYPT_ERROR 51
42840957b409SSimon J. Gerraty #define BR_ALERT_PROTOCOL_VERSION 70
42850957b409SSimon J. Gerraty #define BR_ALERT_INSUFFICIENT_SECURITY 71
42860957b409SSimon J. Gerraty #define BR_ALERT_INTERNAL_ERROR 80
42870957b409SSimon J. Gerraty #define BR_ALERT_USER_CANCELED 90
42880957b409SSimon J. Gerraty #define BR_ALERT_NO_RENEGOTIATION 100
42890957b409SSimon J. Gerraty #define BR_ALERT_UNSUPPORTED_EXTENSION 110
42900957b409SSimon J. Gerraty #define BR_ALERT_NO_APPLICATION_PROTOCOL 120
42910957b409SSimon J. Gerraty
42920957b409SSimon J. Gerraty #ifdef __cplusplus
42930957b409SSimon J. Gerraty }
42940957b409SSimon J. Gerraty #endif
42950957b409SSimon J. Gerraty
42960957b409SSimon J. Gerraty #endif
4297