lsquic_enc_sess.h revision 2f7aa658
1/* Copyright (c) 2017 - 2019 LiteSpeed Technologies Inc.  See LICENSE. */
2#ifndef LSQUIC_ENC_SESS_H
3#define LSQUIC_ENC_SESS_H 1
4
5struct lsquic_alarmset;
6struct lsquic_engine_public;
7struct lsquic_packet_out;
8struct lsquic_packet_in;
9struct stream_wrapper;
10struct ver_neg;
11struct lsquic_conn;
12struct transport_params;
13struct lsquic_cid;
14struct ssl_stream_method_st;
15struct ssl_st;
16struct sockaddr;
17struct conn_cid_elem;
18
19#define DNONC_LENGTH 32
20#define SRST_LENGTH 16
21
22/* From [draft-ietf-quic-tls-14]:
23 *
24 * Data is protected using a number of encryption levels:
25 *
26 * o  Plaintext
27 *
28 * o  Early Data (0-RTT) Keys
29 *
30 * o  Handshake Keys
31 *
32 * o  Application Data (1-RTT) Keys
33 */
34
35/* This enum maps to the list above */
36enum enc_level
37{
38    ENC_LEV_CLEAR,
39    ENC_LEV_EARLY,
40    ENC_LEV_INIT,
41    ENC_LEV_FORW,
42    N_ENC_LEVS
43};
44
45enum handshake_error            /* TODO: rename this enum */
46{
47    DATA_NOT_ENOUGH = -2,
48    DATA_FORMAT_ERROR = -1,
49    HS_ERROR = -1,
50    DATA_NO_ERROR = 0,
51    HS_SHLO = 0,
52    HS_1RTT = 1,
53    HS_SREJ = 2,
54    HS_DELAYED = 3,
55    HS_PK_OFFLOAD = 4,
56};
57
58#ifndef LSQUIC_KEEP_ENC_SESS_HISTORY
59#   ifndef NDEBUG
60#       define LSQUIC_KEEP_ENC_SESS_HISTORY 1
61#   else
62#       define LSQUIC_KEEP_ENC_SESS_HISTORY 0
63#   endif
64#endif
65
66#if LSQUIC_KEEP_ENC_SESS_HISTORY
67#define ESHIST_BITS 7
68#define ESHIST_MASK ((1 << ESHIST_BITS) - 1)
69#define ESHIST_STR_SIZE ((1 << ESHIST_BITS) + 1)
70#endif
71
72enum enc_packout { ENCPA_OK, ENCPA_NOMEM, ENCPA_BADCRYPT, };
73
74enum dec_packin {
75    DECPI_OK,
76    DECPI_NOMEM,
77    DECPI_TOO_SHORT,
78    DECPI_NOT_YET,
79    DECPI_BADCRYPT,
80    DECPI_VIOLATION,
81};
82
83typedef void enc_session_t;
84
85struct enc_session_funcs_common
86{
87    /* Global initialization: call once per implementation */
88    int (*esf_global_init)(int flags);
89
90    /* Global cleanup: call once per implementation */
91    void (*esf_global_cleanup) (void);
92
93    const char *
94    (*esf_cipher) (enc_session_t *);
95
96    int
97    (*esf_keysize) (enc_session_t *);
98
99    int
100    (*esf_alg_keysize) (enc_session_t *);
101
102    enum enc_packout
103    (*esf_encrypt_packet) (enc_session_t *, const struct lsquic_engine_public *,
104        struct lsquic_conn *, struct lsquic_packet_out *);
105
106    enum dec_packin
107    (*esf_decrypt_packet)(enc_session_t *, struct lsquic_engine_public *,
108        const struct lsquic_conn *, struct lsquic_packet_in *);
109
110    struct stack_st_X509 *
111    (*esf_get_server_cert_chain) (enc_session_t *);
112
113    int
114    (*esf_verify_reset_token) (enc_session_t *, const unsigned char *, size_t);
115
116    int
117    (*esf_did_zero_rtt_succeed) (enc_session_t *);
118
119    int
120    (*esf_is_zero_rtt_enabled) (enc_session_t *);
121
122    unsigned
123    esf_tag_len;
124};
125
126struct enc_session_funcs_gquic
127{
128#if LSQUIC_KEEP_ENC_SESS_HISTORY
129    /* Grab encryption session history */
130    void (*esf_get_hist) (enc_session_t *,
131                                            char buf[ESHIST_STR_SIZE]);
132#endif
133
134    /* Destroy enc session */
135    void (*esf_destroy)(enc_session_t *enc_session);
136
137    /* Return true if handshake has been completed */
138    int (*esf_is_hsk_done)(enc_session_t *enc_session);
139
140    /* Get value of setting specified by `tag' */
141    int (*esf_get_peer_setting) (enc_session_t *, uint32_t tag,
142                                                                uint32_t *val);
143
144    /* Get value of peer option (that from COPT array) */
145    int (*esf_get_peer_option) (enc_session_t *enc_session,
146                                                                uint32_t tag);
147
148    /* Create server session */
149    enc_session_t *
150    (*esf_create_server) (lsquic_cid_t cid, const struct lsquic_engine_public *);
151
152    /* out_len should have init value as the max length of out */
153    enum handshake_error
154    (*esf_handle_chlo) (enc_session_t *enc_session, enum lsquic_version,
155                const uint8_t *in, int in_len, time_t t,
156                const struct sockaddr *ip_addr, const struct sockaddr *local,
157                uint8_t *out, size_t *out_len,
158                uint8_t nonce[DNONC_LENGTH], int *nonce_set);
159
160    void (*esf_hsk_destroy)(void *hsk_ctx);
161
162#ifndef NDEBUG
163    /* Need to expose this function for testing */
164    int (*esf_determine_diversification_key) (enc_session_t *,
165                              uint8_t *diversification_nonce, int is_client);
166#endif
167
168    const char *
169    (*esf_get_ua) (enc_session_t *);
170
171    int
172    (*esf_have_key_gt_one) (enc_session_t *enc_session);
173
174#ifndef NDEBUG
175    /* Functions that are only relevant in maintest.  We may want to get rid
176     * of them somehow and only use the public API to test.
177     */
178
179    uint8_t
180    (*esf_have_key) (enc_session_t *);
181
182    void
183    (*esf_set_have_key) (enc_session_t *, uint8_t);
184
185    const unsigned char *
186    (*esf_get_enc_key_i) (enc_session_t *);
187
188    const unsigned char *
189    (*esf_get_dec_key_i) (enc_session_t *);
190
191    const unsigned char *
192    (*esf_get_enc_key_nonce_i) (enc_session_t *);
193
194    const unsigned char *
195    (*esf_get_dec_key_nonce_i) (enc_session_t *);
196
197    const unsigned char *
198    (*esf_get_enc_key_nonce_f) (enc_session_t *);
199
200    const unsigned char *
201    (*esf_get_dec_key_nonce_f) (enc_session_t *);
202#endif /* !defined(NDEBUG) */
203
204#if LSQUIC_ENABLE_HANDSHAKE_DISABLE
205    void
206    (*esf_set_handshake_completed) (enc_session_t *);
207#endif
208
209    /* Create client session */
210    enc_session_t *
211    (*esf_create_client) (const char *domain, lsquic_cid_t cid,
212                                    const struct lsquic_engine_public *,
213                                    const unsigned char *, size_t);
214
215    /* -1 error, 0, OK, response in `buf' */
216    int
217    (*esf_gen_chlo) (enc_session_t *, enum lsquic_version,
218                                                uint8_t *buf, size_t *len);
219
220    int
221    (*esf_handle_chlo_reply) (enc_session_t *,
222                                                const uint8_t *data, int len);
223
224    size_t
225    (*esf_mem_used)(enc_session_t *);
226
227    /* Zero-rtt serialization needs the knowledge of the QUIC version, that's
228     * why there is a separate method for thus.  Plus, we want to be able to
229     * call it after the "handshake is done" callback is called.
230     */
231    void (*esf_maybe_dispatch_zero_rtt) (enc_session_t *,
232            struct lsquic_conn *conn,
233            void (*cb)(struct lsquic_conn *, const unsigned char *, size_t));
234
235    void (*esf_reset_cid) (enc_session_t *, const lsquic_cid_t *);
236};
237
238enum iquic_handshake_status {
239    IHS_WANT_READ,
240    IHS_WANT_WRITE,
241    IHS_STOP,
242};
243
244struct crypto_stream_if
245{
246    ssize_t     (*csi_write) (void *stream, const void *buf, size_t len);
247    int         (*csi_flush) (void *stream);
248    ssize_t     (*csi_readf) (void *stream,
249        size_t (*readf)(void *, const unsigned char *, size_t, int), void *ctx);
250    int         (*csi_wantwrite) (void *stream, int is_want);
251    int         (*csi_wantread) (void *stream, int is_want);
252    enum enc_level
253                (*csi_enc_level) (void *stream);
254};
255
256struct enc_session_funcs_iquic
257{
258    enc_session_t *
259    (*esfi_create_client) (const char *domain, struct lsquic_engine_public *,
260                           struct lsquic_conn *, const struct lsquic_cid *,
261                           const struct ver_neg *, void *(crypto_streams)[4],
262                           const struct crypto_stream_if *,
263                           const unsigned char *, size_t,
264                           struct lsquic_alarmset *, unsigned);
265
266    void
267    (*esfi_destroy) (enc_session_t *);
268
269    struct ssl_st *
270    (*esfi_get_ssl) (enc_session_t *);
271
272    struct transport_params *
273    (*esfi_get_peer_transport_params) (enc_session_t *);
274
275    int
276    (*esfi_reset_dcid) (enc_session_t *, const struct lsquic_cid *,
277                                                const struct lsquic_cid *);
278
279    int
280    (*esfi_init_server) (enc_session_t *);
281
282    void
283    (*esfi_set_conn) (enc_session_t *, struct lsquic_conn *);
284
285    void
286    (*esfi_set_streams) (enc_session_t *, void *(crypto_streams)[4],
287                           const struct crypto_stream_if *);
288
289    enc_session_t *
290    (*esfi_create_server) (struct lsquic_engine_public *, struct lsquic_conn *,
291                                                    const struct lsquic_cid *,
292                           void *(crypto_streams)[4],
293                           const struct crypto_stream_if *,
294                           const struct lsquic_cid *odcid);
295
296    void
297    (*esfi_shake_stream)(enc_session_t *, struct lsquic_stream *,
298                         const char *);
299
300    void
301    (*esfi_1rtt_acked)(enc_session_t *);
302};
303
304extern
305#ifdef NDEBUG
306const
307#endif
308struct enc_session_funcs_common lsquic_enc_session_common_gquic_1;
309extern const struct enc_session_funcs_common lsquic_enc_session_common_ietf_v1;
310
311extern
312#ifdef NDEBUG
313const
314#endif
315struct enc_session_funcs_gquic lsquic_enc_session_gquic_gquic_1;
316
317extern const struct enc_session_funcs_iquic lsquic_enc_session_iquic_ietf_v1;
318
319#define select_esf_common_by_ver(ver) ( \
320    ver == LSQVER_ID23 ? &lsquic_enc_session_common_ietf_v1 : \
321    ver == LSQVER_ID24 ? &lsquic_enc_session_common_ietf_v1 : \
322    ver == LSQVER_VERNEG ? &lsquic_enc_session_common_ietf_v1 : \
323    &lsquic_enc_session_common_gquic_1 )
324
325#define select_esf_gquic_by_ver(ver) ( \
326    ver ? &lsquic_enc_session_gquic_gquic_1 : &lsquic_enc_session_gquic_gquic_1)
327
328#define select_esf_iquic_by_ver(ver) ( \
329    ver ? &lsquic_enc_session_iquic_ietf_v1 : &lsquic_enc_session_iquic_ietf_v1)
330
331extern const char *const lsquic_enclev2str[];
332
333extern const struct lsquic_stream_if lsquic_cry_sm_if;
334
335extern const struct lsquic_stream_if lsquic_mini_cry_sm_if;
336
337/* RFC 7301, Section 3.2 */
338#define ALERT_NO_APPLICATION_PROTOCOL 120
339
340enum lsquic_version
341lsquic_zero_rtt_version (const unsigned char *, size_t);
342
343/* This is seems to be true for all of the ciphers used by IETF QUIC.
344 * XXX: Perhaps add a check?
345 */
346#define IQUIC_TAG_LEN 16
347
348#endif
349