Botan  1.11.15
src/lib/tls/tls_session.h
Go to the documentation of this file.
00001 /*
00002 * TLS Session
00003 * (C) 2011-2012,2015 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_TLS_SESSION_STATE_H__
00009 #define BOTAN_TLS_SESSION_STATE_H__
00010 
00011 #include <botan/x509cert.h>
00012 #include <botan/tls_version.h>
00013 #include <botan/tls_ciphersuite.h>
00014 #include <botan/tls_magic.h>
00015 #include <botan/tls_server_info.h>
00016 #include <botan/secmem.h>
00017 #include <botan/symkey.h>
00018 #include <chrono>
00019 
00020 namespace Botan {
00021 
00022 namespace TLS {
00023 
00024 /**
00025 * Class representing a TLS session state
00026 */
00027 class BOTAN_DLL Session
00028    {
00029    public:
00030 
00031       /**
00032       * Uninitialized session
00033       */
00034       Session() :
00035          m_start_time(std::chrono::system_clock::time_point::min()),
00036          m_version(),
00037          m_ciphersuite(0),
00038          m_compression_method(0),
00039          m_connection_side(static_cast<Connection_Side>(0)),
00040          m_fragment_size(0)
00041             {}
00042 
00043       /**
00044       * New session (sets session start time)
00045       */
00046       Session(const std::vector<byte>& session_id,
00047               const secure_vector<byte>& master_secret,
00048               Protocol_Version version,
00049               u16bit ciphersuite,
00050               byte compression_method,
00051               Connection_Side side,
00052               size_t fragment_size,
00053               const std::vector<X509_Certificate>& peer_certs,
00054               const std::vector<byte>& session_ticket,
00055               const Server_Information& server_info,
00056               const std::string& srp_identifier,
00057               u16bit srtp_profile);
00058 
00059       /**
00060       * Load a session from DER representation (created by DER_encode)
00061       */
00062       Session(const byte ber[], size_t ber_len);
00063 
00064       /**
00065       * Load a session from PEM representation (created by PEM_encode)
00066       */
00067       Session(const std::string& pem);
00068 
00069       /**
00070       * Encode this session data for storage
00071       * @warning if the master secret is compromised so is the
00072       * session traffic
00073       */
00074       secure_vector<byte> DER_encode() const;
00075 
00076       /**
00077       * Encrypt a session (useful for serialization or session tickets)
00078       */
00079       std::vector<byte> encrypt(const SymmetricKey& key,
00080                                 RandomNumberGenerator& rng) const;
00081 
00082 
00083       /**
00084       * Decrypt a session created by encrypt
00085       * @param ctext the ciphertext returned by encrypt
00086       * @param ctext_size the size of ctext in bytes
00087       * @param key the same key used by the encrypting side
00088       */
00089       static Session decrypt(const byte ctext[],
00090                              size_t ctext_size,
00091                              const SymmetricKey& key);
00092 
00093       /**
00094       * Decrypt a session created by encrypt
00095       * @param ctext the ciphertext returned by encrypt
00096       * @param key the same key used by the encrypting side
00097       */
00098       static inline Session decrypt(const std::vector<byte>& ctext,
00099                                     const SymmetricKey& key)
00100          {
00101          return Session::decrypt(&ctext[0], ctext.size(), key);
00102          }
00103 
00104       /**
00105       * Encode this session data for storage
00106       * @warning if the master secret is compromised so is the
00107       * session traffic
00108       */
00109       std::string PEM_encode() const;
00110 
00111       /**
00112       * Get the version of the saved session
00113       */
00114       Protocol_Version version() const { return m_version; }
00115 
00116       /**
00117       * Get the ciphersuite code of the saved session
00118       */
00119       u16bit ciphersuite_code() const { return m_ciphersuite; }
00120 
00121       /**
00122       * Get the ciphersuite info of the saved session
00123       */
00124       Ciphersuite ciphersuite() const { return Ciphersuite::by_id(m_ciphersuite); }
00125 
00126       /**
00127       * Get the compression method used in the saved session
00128       */
00129       byte compression_method() const { return m_compression_method; }
00130 
00131       /**
00132       * Get which side of the connection the resumed session we are/were
00133       * acting as.
00134       */
00135       Connection_Side side() const { return m_connection_side; }
00136 
00137       /**
00138       * Get the SRP identity (if sent by the client in the initial handshake)
00139       */
00140       const std::string& srp_identifier() const { return m_srp_identifier; }
00141 
00142       /**
00143       * Get the saved master secret
00144       */
00145       const secure_vector<byte>& master_secret() const { return m_master_secret; }
00146 
00147       /**
00148       * Get the session identifier
00149       */
00150       const std::vector<byte>& session_id() const { return m_identifier; }
00151 
00152       /**
00153       * Get the negotiated maximum fragment size (or 0 if default)
00154       */
00155       size_t fragment_size() const { return m_fragment_size; }
00156 
00157       /**
00158       * Get the negotiated DTLS-SRTP algorithm (RFC 5764)
00159       */
00160       u16bit dtls_srtp_profile() const { return m_srtp_profile; }
00161 
00162       /**
00163       * Return the certificate chain of the peer (possibly empty)
00164       */
00165       const std::vector<X509_Certificate>& peer_certs() const { return m_peer_certs; }
00166 
00167       /**
00168       * Get the wall clock time this session began
00169       */
00170       std::chrono::system_clock::time_point start_time() const { return m_start_time; }
00171 
00172       /**
00173       * Return how long this session has existed (in seconds)
00174       */
00175       std::chrono::seconds session_age() const;
00176 
00177       /**
00178       * Return the session ticket the server gave us
00179       */
00180       const std::vector<byte>& session_ticket() const { return m_session_ticket; }
00181 
00182       const Server_Information& server_info() const { return m_server_info; }
00183 
00184    private:
00185       enum { TLS_SESSION_PARAM_STRUCT_VERSION = 20150104 };
00186 
00187       std::chrono::system_clock::time_point m_start_time;
00188 
00189       std::vector<byte> m_identifier;
00190       std::vector<byte> m_session_ticket; // only used by client side
00191       secure_vector<byte> m_master_secret;
00192 
00193       Protocol_Version m_version;
00194       u16bit m_ciphersuite;
00195       byte m_compression_method;
00196       Connection_Side m_connection_side;
00197       u16bit m_srtp_profile;
00198 
00199       size_t m_fragment_size;
00200 
00201       std::vector<X509_Certificate> m_peer_certs;
00202       Server_Information m_server_info; // optional
00203       std::string m_srp_identifier; // optional
00204    };
00205 
00206 }
00207 
00208 }
00209 
00210 #endif