1 /**
2  * \file ssl_ticket.h
3  *
4  * \brief TLS server ticket callbacks implementation
5  */
6 /*
7  *  Copyright The Mbed TLS Contributors
8  *  SPDX-License-Identifier: Apache-2.0
9  *
10  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
11  *  not use this file except in compliance with the License.
12  *  You may obtain a copy of the License at
13  *
14  *  http://www.apache.org/licenses/LICENSE-2.0
15  *
16  *  Unless required by applicable law or agreed to in writing, software
17  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19  *  See the License for the specific language governing permissions and
20  *  limitations under the License.
21  */
22 #ifndef MBEDTLS_SSL_TICKET_H
23 #define MBEDTLS_SSL_TICKET_H
24 
25 #if !defined(MBEDTLS_CONFIG_FILE)
26 #include "mbedtls/config.h"
27 #else
28 #include MBEDTLS_CONFIG_FILE
29 #endif
30 
31 /*
32  * This implementation of the session ticket callbacks includes key
33  * management, rotating the keys periodically in order to preserve forward
34  * secrecy, when MBEDTLS_HAVE_TIME is defined.
35  */
36 
37 #include "mbedtls/ssl.h"
38 #include "mbedtls/cipher.h"
39 
40 #if defined(MBEDTLS_THREADING_C)
41 #include "mbedtls/threading.h"
42 #endif
43 
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47 
48 /**
49  * \brief   Information for session ticket protection
50  */
51 typedef struct mbedtls_ssl_ticket_key
52 {
53     unsigned char name[4];          /*!< random key identifier              */
54     uint32_t generation_time;       /*!< key generation timestamp (seconds) */
55     mbedtls_cipher_context_t ctx;   /*!< context for auth enc/decryption    */
56 }
57 mbedtls_ssl_ticket_key;
58 
59 /**
60  * \brief   Context for session ticket handling functions
61  */
62 typedef struct mbedtls_ssl_ticket_context
63 {
64     mbedtls_ssl_ticket_key keys[2]; /*!< ticket protection keys             */
65     unsigned char active;           /*!< index of the currently active key  */
66 
67     uint32_t ticket_lifetime;       /*!< lifetime of tickets in seconds     */
68 
69     /** Callback for getting (pseudo-)random numbers                        */
70     int  (*f_rng)(void *, unsigned char *, size_t);
71     void *p_rng;                    /*!< context for the RNG function       */
72 
73 #if defined(MBEDTLS_THREADING_C)
74     mbedtls_threading_mutex_t mutex;
75 #endif
76 }
77 mbedtls_ssl_ticket_context;
78 
79 /**
80  * \brief           Initialize a ticket context.
81  *                  (Just make it ready for mbedtls_ssl_ticket_setup()
82  *                  or mbedtls_ssl_ticket_free().)
83  *
84  * \param ctx       Context to be initialized
85  */
86 void mbedtls_ssl_ticket_init( mbedtls_ssl_ticket_context *ctx );
87 
88 /**
89  * \brief           Prepare context to be actually used
90  *
91  * \param ctx       Context to be set up
92  * \param f_rng     RNG callback function
93  * \param p_rng     RNG callback context
94  * \param cipher    AEAD cipher to use for ticket protection.
95  *                  Recommended value: MBEDTLS_CIPHER_AES_256_GCM.
96  * \param lifetime  Tickets lifetime in seconds
97  *                  Recommended value: 86400 (one day).
98  *
99  * \note            It is highly recommended to select a cipher that is at
100  *                  least as strong as the strongest ciphersuite
101  *                  supported. Usually that means a 256-bit key.
102  *
103  * \note            The lifetime of the keys is twice the lifetime of tickets.
104  *                  It is recommended to pick a reasonable lifetime so as not
105  *                  to negate the benefits of forward secrecy.
106  *
107  * \return          0 if successful,
108  *                  or a specific MBEDTLS_ERR_XXX error code
109  */
110 int mbedtls_ssl_ticket_setup( mbedtls_ssl_ticket_context *ctx,
111     int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
112     mbedtls_cipher_type_t cipher,
113     uint32_t lifetime );
114 
115 /**
116  * \brief           Implementation of the ticket write callback
117  *
118  * \note            See \c mbedtls_ssl_ticket_write_t for description
119  */
120 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write;
121 
122 /**
123  * \brief           Implementation of the ticket parse callback
124  *
125  * \note            See \c mbedtls_ssl_ticket_parse_t for description
126  */
127 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse;
128 
129 /**
130  * \brief           Free a context's content and zeroize it.
131  *
132  * \param ctx       Context to be cleaned up
133  */
134 void mbedtls_ssl_ticket_free( mbedtls_ssl_ticket_context *ctx );
135 
136 #ifdef __cplusplus
137 }
138 #endif
139 
140 #endif /* ssl_ticket.h */
141