ssl_ticket.h

00001 /**
00002  * \file ssl_ticket.h
00003  *
00004  * \brief TLS server ticket callbacks implementation
00005  */
00006 /*
00007  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of mbed TLS (https://tls.mbed.org)
00023  */
00024 #ifndef MBEDTLS_SSL_TICKET_H
00025 #define MBEDTLS_SSL_TICKET_H
00026 
00027 #if !defined(MBEDTLS_CONFIG_FILE)
00028 #include "mbedtls/config.h"
00029 #else
00030 #include MBEDTLS_CONFIG_FILE
00031 #endif
00032 
00033 /*
00034  * This implementation of the session ticket callbacks includes key
00035  * management, rotating the keys periodically in order to preserve forward
00036  * secrecy, when MBEDTLS_HAVE_TIME is defined.
00037  */
00038 
00039 #include "mbedtls/ssl.h"
00040 #include "mbedtls/cipher.h"
00041 
00042 #if defined(MBEDTLS_THREADING_C)
00043 #include "mbedtls/threading.h"
00044 #endif
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 /**
00051  * \brief   Information for session ticket protection
00052  */
00053 typedef struct mbedtls_ssl_ticket_key
00054 {
00055     unsigned char name [4];          /*!< random key identifier              */
00056     uint32_t generation_time ;       /*!< key generation timestamp (seconds) */
00057     mbedtls_cipher_context_t ctx ;   /*!< context for auth enc/decryption    */
00058 }
00059 mbedtls_ssl_ticket_key;
00060 
00061 /**
00062  * \brief   Context for session ticket handling functions
00063  */
00064 typedef struct mbedtls_ssl_ticket_context
00065 {
00066     mbedtls_ssl_ticket_key keys [2]; /*!< ticket protection keys             */
00067     unsigned char active ;           /*!< index of the currently active key  */
00068 
00069     uint32_t ticket_lifetime ;       /*!< lifetime of tickets in seconds     */
00070 
00071     /** Callback for getting (pseudo-)random numbers                        */
00072     int  (*f_rng)(void *, unsigned char *, size_t);
00073     void *p_rng ;                    /*!< context for the RNG function       */
00074 
00075 #if defined(MBEDTLS_THREADING_C)
00076     mbedtls_threading_mutex_t mutex;
00077 #endif
00078 }
00079 mbedtls_ssl_ticket_context;
00080 
00081 /**
00082  * \brief           Initialize a ticket context.
00083  *                  (Just make it ready for mbedtls_ssl_ticket_setup()
00084  *                  or mbedtls_ssl_ticket_free().)
00085  *
00086  * \param ctx       Context to be initialized
00087  */
00088 void mbedtls_ssl_ticket_init( mbedtls_ssl_ticket_context *ctx );
00089 
00090 /**
00091  * \brief           Prepare context to be actually used
00092  *
00093  * \param ctx       Context to be set up
00094  * \param f_rng     RNG callback function
00095  * \param p_rng     RNG callback context
00096  * \param cipher    AEAD cipher to use for ticket protection.
00097  *                  Recommended value: MBEDTLS_CIPHER_AES_256_GCM.
00098  * \param lifetime  Tickets lifetime in seconds
00099  *                  Recommended value: 86400 (one day).
00100  *
00101  * \note            It is highly recommended to select a cipher that is at
00102  *                  least as strong as the the strongest ciphersuite
00103  *                  supported. Usually that means a 256-bit key.
00104  *
00105  * \note            The lifetime of the keys is twice the lifetime of tickets.
00106  *                  It is recommended to pick a reasonnable lifetime so as not
00107  *                  to negate the benefits of forward secrecy.
00108  *
00109  * \return          0 if successful,
00110  *                  or a specific MBEDTLS_ERR_XXX error code
00111  */
00112 int mbedtls_ssl_ticket_setup( mbedtls_ssl_ticket_context *ctx,
00113     int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
00114     mbedtls_cipher_type_t cipher,
00115     uint32_t lifetime );
00116 
00117 /**
00118  * \brief           Implementation of the ticket write callback
00119  *
00120  * \note            See \c mbedtls_ssl_ticket_write_t for description
00121  */
00122 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write;
00123 
00124 /**
00125  * \brief           Implementation of the ticket parse callback
00126  *
00127  * \note            See \c mbedtls_ssl_ticket_parse_t for description
00128  */
00129 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse;
00130 
00131 /**
00132  * \brief           Free a context's content and zeroize it.
00133  *
00134  * \param ctx       Context to be cleaned up
00135  */
00136 void mbedtls_ssl_ticket_free( mbedtls_ssl_ticket_context *ctx );
00137 
00138 #ifdef __cplusplus
00139 }
00140 #endif
00141 
00142 #endif /* ssl_ticket.h */