-
Notifications
You must be signed in to change notification settings - Fork 22
Transport Layer Security (TLS)
Botan supports both client and server implementations of the SSL/TLS protocols, including SSL v3, TLS v1.0, TLS v1.1, and TLS v1.2 (the insecure and obsolete SSL v2 protocol is not supported, beyond processing SSL v2 client hellos which some clients still send for backwards compatibility with ancient servers). There is also support for DTLS (v1.0 and v1.2), a variant of TLS adapted for operation on datagram transports such as UDP and SCTP. DTLS support should be considered as beta quality and further testing is invited.
The TLS implementation does not know anything about sockets or the
network layer. Instead, it calls a user provided callback (hereafter
output_fn) whenever it has data that it would want to send to the
other party (for instance, by writing it to a network socket), and
whenever the application receives some data from the counterparty (for
instance, by reading from a network socket) it passes that information
to TLS using TLSChannel.receivedData. If the data
passed in results in some change in the state, such as a handshake
completing, or some data or an alert being received from the other
side, then a user provided callback will be invoked. If the reader is
familiar with OpenSSL's BIO layer, it might be analogous to saying the
only way of interacting with Botan's TLS is via a BIO_mem I/O
abstraction. This makes the library completely agnostic to how you
write your network layer, be it blocking sockets, libevent, a
message queue, etc.
The callbacks that TLS calls have the signatures
void outputFn(in ubyte[] data)TLS requests that all bytes of data be queued up to send to the
counterparty. After this function returns, data will be
overwritten, so a copy of the input must be made if the callback
cannot send the data immediately.
void dataCb(in ubyte[] data)Called whenever application data is received from the other side
of the connection, in which case data array specifies
the data received. This array will be overwritten sometime after
the callback returns, so again a copy should be made if need be.
void alertCb(Alert alert, in ubyte[] data)Called when an alert is received. Normally, data.ptr is null and
data.length is 0, as most alerts have no associated data. However,
if TLS heartbeats (see RFC 6520) were negotiated, and we
initiated a heartbeat, then if/when the other party responds,
alertCb will be called with whatever data was included in
the heartbeat response (if any) along with a pseudo-alert value
of HEARTBEAT_PAYLOAD.
bool handshake_cb(in TLSSession session);Called whenever a negotiation completes. This can happen more than once on any connection. The session parameter provides information about the session which was established.
If this function returns false, the session will not be cached for later resumption.
If this function wishes to cancel the handshake, it can throw an exception which will send a close message to the counterparty and reset the connection state.
TLS servers and clients share an interface called TLSChannel. A
TLS channel (either client or server object) has these methods
available
size_t receivedData(in byte* buf, size_t buf_size);This function is used to provide data sent by the counterparty (eg data that you read off the socket layer). Depending on the current protocol state and the amount of data provided this may result in one or more callback functions that were provided to the constructor being called.
The return value of receivedData specifies how many more
bytes of input are needed to make any progress, unless the end of
the data fell exactly on a message boundary, in which case it
will return 0 instead.
void send(in byte* buf, size_t buf_size);If the connection has completed the initial handshake process, the data provided is sent to the counterparty as TLS traffic. Otherwise, an exception is thrown.
void close();A close notification is sent to the counterparty, and the internal state is cleared.
void sendAlert(in Alert alert);Some other alert is sent to the counterparty. If the alert is fatal, the internal state is cleared.
bool isActive();Returns true if and only if a handshake has been completed on this connection and the connection has not been subsequently closed.
bool isClosed();Returns true if and only if either a close notification or a fatal alert message have been either sent or received.
bool timeoutCheck();This function does nothing unless the channel represents a DTLS connection and a handshake is actively in progress. In this case it will check the current timeout state and potentially initiate retransmission of handshake packets. Returns true if a timeout condition occurred.
void renegotiate(bool force_full_renegotiation = false);Initiates a renegotiation. The counterparty is allowed by the
protocol to ignore this request. If a successful renegotiation
occurs, the handshake_cb callback will be called again.
If force_full_renegotiation is false, then the client will
attempt to simply renew the current session - this will refresh
the symmetric keys but will not change the session master
secret. Otherwise it will initiate a completely new session.
For a server, if force_full_renegotiation is false, then a
session resumption will be allowed if the client attempts
it. Otherwise the server will prevent resumption and force the
creation of a new session.
Vector!X509Certificate peerCertChain();Returns the certificate chain of the counterparty. When acting as a client, this value will be non-empty unless the client's policy allowed anonymous connections and the server then chose an anonymous ciphersuite. Acting as a server, this value will ordinarily be empty, unless the server requested a certificate and the client responded with one.
SymmetricKey keyMaterialExport(in string label,
in string context,
size_t length);Returns an exported key of length bytes derived from label,
context, and the session's master secret and client and server
random values. This key will be unique to this connection, and
as long as the session master secret remains secure an attacker
should not be able to guess the key.
Per RFC 5705, label should begin with "EXPERIMENTAL" unless
the label has been standardized in an RFC.
class TLSClient contains the following methods:
this(void delegate(in ubyte[]) output_fn,
void delegate(in ubyte[]) data_cb,
TLSAlert delegate(in ubyte[]) alert_cb,
bool delegate(in TLS_Session) handshake_cb,
TLSSessionManager session_manager,
TLSCredentialsManager credendials_manager,
TLSPolicy policy,
RandomNumberGenerator rng,
in TLSServerInformation server_info,
in TLSProtocolVersion offer_version,
Vector!string next_protocols,
size_t reserved_io_buffer_size);Initialize a new TLS client. The constructor will immediately initiate a new session.
The output_fn callback will be called with output that
should be sent to the counterparty. For instance this will be
called immediately from the constructor after the client hello
message is constructed. An implementation of output_fn is
allowed to defer the write (for instance if writing when the
callback occurs would block), but should eventually write the data
to the counterparty in order.
The data_cb will be called with data sent by the counterparty
after it has been processed. The byte array and size_t represent
the plaintext value and size.
The alert_cb will be called when a protocol alert is received,
commonly with a close alert during connection teardown.
The handshake_cb function is called when a handshake
(either initial or renegotiation) is completed. The return value of
the callback specifies if the session should be cached for later
resumption. If the function for some reason desires to prevent the
connection from completing, it should throw an exception
(preferably a TLSException, which can provide more specific alert
information to the counterparty). The class TLSSession
provides information about the session that was just established.
The session_manager is an interface for storing TLS sessions,
which allows for session resumption upon reconnecting to a server.
In the absence of a need for persistent sessions, use
class TLSSessionManagerInMemory which caches
connections for the lifetime of a single process. See
TLS Session Managers for more about session managers.
The credentials_manager is an interface that will be called to
retrieve any certificates, secret keys, pre-shared keys, or SRP
intformation; see Credentials Manager for more information.
Use server_info to specify the DNS name of the server you are
attempting to connect to, if you know it. This helps the server
select what certificate to use and helps the client validate the
connection.
Use offer_version to control the version of TLS you wish the
client to offer. Normally, you'll want to offer the most recent
version of (D)TLS that is available, however some broken servers are
intolerant of certain versions being offered, and for classes of
applications that have to deal with such servers (typically web
browsers) it may be necessary to implement a version backdown
strategy if the initial attempt fails.
Setting offer_version is also used to offer DTLS instead of TLS;
use TLSProtocolVersion.latestDtlsVersion.
Optionally, the client will advertise the next_protocols to
the server using the ALPN extension.
The optional reserved_io_buffer_size specifies how many bytes to
pre-allocate in the I/O buffers. Use this if you want to control
how much memory the channel uses initially (the buffers will be
resized as needed to process inputs). Otherwise some reasonable
default is used.
class TLSServer contains the following methods:
this(void delegate(in ubyte[]) output_fn,
void delegate(in ubyte[]) data_cb,
TLSAlert delegate(in ubyte[]) alert_cb,
TLSSession_Manager session_manager,
TLSCredentialsManager creds,
in TLSPolicy policy,
RandomNumberGenerator rng,
string delegate(in Vector!string) proto_chooser,
bool is_datagram = false,
bool reserved_io_buffer_size);The first 7 arguments as well as the final argument
reserved_io_buffer_size, are treated similarly to the TLSClent.
The (optional) argument, proto_chooser, is a function called if the
client sent the ALPN extension to negotiate an application
protocol. In that case, the function should choose a protocol to use
and return it. Alternately it can throw an exception to abort the
exchange; the ALPN specification says that if this occurs the alert
should be of type NO_APPLICATION_PROTOCOL.
The argument is_datagram specifies if this is a TLS or DTLS server;
unlike clients, which know what type of protocol (TLS vs DTLS) they
are negotiating from the start via the offer_version, servers would
not until they actually receive a hello without this parameter.
string nextProtocol() const;If a handshake has completed, and if the client indicated a next protocol (ie, the protocol that it intends to run over this TLS connection) this return value will specify it. The next-protocol extension is somewhat unusual in that it applies to the connection rather than the session. The next protocol can not change during a renegotiation, but might change across different connections using that session.
TLS allows clients and servers to support session resumption, where the end point retains some information about an established session and then reuse that information to bootstrap a new session in way that is much cheaper computationally than a full handshake.
Every time your handshake callback is called, a new session has been
established, and a TLSSession class is included that provides
information about that session:
TLSProtocolVersion Version() const;Returns the TLSProtocolVersion object that was negotiated
TLSCiphersuite ciphersuite() const;Returns the TLSCiphersuite that was negotiated.
TLSServerInformation serverInfo() const;Returns information that identifies the server side of the connection. This is useful for the client in that it identifies what was originally passed to the constructor. For the server, it includes the name the client specified in the server name indicator extension.
Vector!X509Certificate peerCerts() constReturns the certificate chain of the peer
string srpIdentifier() constIf an SRP ciphersuite was used, then this is the identifier that was used for authentication.
bool secureNenegotiation() constReturns true if the connection was negotiated with the
correct extensions to prevent the renegotiation attack.
There are also functions for serialization and deserializing sessions:
from class TLS_Session:
Vector!ubyte encrypt(in SymmetricKey key, RandomNumberGenerator rng);Encrypts a session using a symmetric key key and returns a raw
binary value that can later be passed to decrypt. The key
may be of any length.
Currently the implementation uses AES-256 in CBC mode with a SHA-256 HMAC. The keys for these are derived from key using KDF2(SHA-256).
static TLSSession decrypt(in ubyte* ciphertext, size_t length, in SymmetricKey key);Decrypts a session that was encrypted previously with
encrypt and key, or throws an exception if decryption
fails.
Secure_Vector!ubyte DER_encode() const;Returns a serialized version of the session.
You may want sessions stored in a specific format or storage type. To
do so, implement the TLS_Session_Manager interface and pass your
implementation to the TLS_Client or TLS_Server constructor.
class TLSSessionMananger contains the following methods:
void save(in TLSSession session);Save a new session. It is possible that this sessions session ID will replicate a session ID already stored, in which case the new session information should overwrite the previous information.
void removeEntry(in Vector!ubyte session_id)Remove the session identified by session_id. Future attempts
at resumption should fail for this session.
bool loadFromSessionId(in Vector!ubyte session_id, TLSSession session);Attempt to resume a session identified by session_id. If
located, session is set to the session data previously passed
to save, and true is returned. Otherwise session is not
modified and false is returned.
bool loadFromServerInfo(in TLSServerInformation server, TLSSession session);Attempt to resume a session with a known server.
Duration sessionLifetime() constReturns the expected maximum lifetime of a session when using this session manager. Will return 0 if the lifetime is unknown or has no explicit expiration policy.
The TLSSessionManagerInMemory implementation saves sessions
in memory, with an upper bound on the maximum number of sessions and
the lifetime of a session.
It is safe to share a single object across many threads as it uses a lock internally.
from class TLSSessionManagersInMemory:
this(RandomNumberGenerator rng,
size_t max_sessions = 1000,
Duration session_lifetime = 7200);Limits the maximum number of saved sessions to max_sessions, and
expires all sessions older than session_lifetime.
The TLSSessionManagerNoop implementation does not save
sessions at all, and thus session resumption always fails. Its
constructor has no arguments.
This session manager is only available if support for SQLite3 was
enabled at build time. If the macro
BOTAN_HAS_TLS_SQLITE3_SESSION_MANAGER is defined, then
botan.tls.session_manager_sqlite contains
TLSSessionManagerSQLite which stores sessions persistently to
a sqlite3 database. The session data is encrypted using a passphrase,
and stored in two tables, named tls_sessions (which holds the
actual session information) and tls_sessions_metadata (which holds
the PBKDF information).
from class TLSSessionManagerSQLite:
this(in string passphrase,
RandomNumberGenerator rng,
in string db_filename,
size_t max_sessions = 1000,
Duration session_lifetime = 7200);Uses the sqlite3 database named by db_filename.
TLSPolicy is how an application can control details of what will
be negotiated during a handshake.
from class TLSPolicy:
Vector!string allowedCiphers() const;Returns the list of ciphers we are willing to negotiate, in order of preference.
Default: "AES-256/GCM", "AES-128/GCM", "AES-256/CCM", "AES-128/CCM", "AES-256/CCM-8", "AES-128/CCM-8", "AES-256", "AES-128"
Also allowed: "Camellia-256/GCM", "Camellia-128/GCM", "Camellia-256", "Camellia-128", "SEED", "3DES", "RC4"
Vector!string allowedMacs() const;Returns the list of algorithms we are willing to use for message authentication, in order of preference.
Default: "AEAD", "SHA-384", "SHA-256", "SHA-1"
Also allowed: "MD5"
Vector!string allowedKeyExchangeMethods() const;Returns the list of key exchange methods we are willing to use, in order of preference.
Default: "ECDH", "DH", "RSA"
Also allowed: "SRP_SHA", "ECDHE_PSK", "DHE_PSK", "PSK"
Vector!string allowedSignatureHashes() const;Returns the list of algorithms we are willing to use for public key signatures, in order of preference.
Default: "SHA-512", "SHA-384", "SHA-256", "SHA-224"
Also allowed (although not recommended): "MD5", "SHA-1"
This is only used with TLS v1.2. In earlier versions of the protocol, signatures are fixed to using only SHA-1 (for DSA/ECDSA) or a MD5/SHA-1 pair (for RSA).
Vector!string allowedSignatureMethods() const;Default: "ECDSA", "RSA", "DSA"
Also allowed: "" (meaning anonymous)
Vector!string allowedEccCurves() const;Return a list of ECC curves we are willing to use, in order of preference.
Default: "brainpool512r1", "brainpool384r1", "brainpool256r1", "secp521r1", "secp384r1", "secp256r1", "secp256k1"
Also allowed: "secp224r1", "secp224k1", "secp192r1", "secp192k1", "secp160r2", "secp160r1", "secp160k1"
Vector!ubyte compression() const;Return the list of compression methods we are willing to use, in order of preference. Default is null compression only.
TLS compression is not currently supported.
bool acceptableProtocolVersion(TLSProtocolVersion version);Return true if this version of the protocol is one that we are willing to negotiate.
Default: Accepts TLS v1.0 or higher, or DTLS v1.2 Note that SSLv3 is rejected by default.
bool serverUsesOwnCiphersuitePreferences() const;If this returns true, a server will pick the cipher it prefers the most out of the client's list. Otherwise, it will negotiate the first cipher in the client's ciphersuite list that it supports.
bool negotiateHeartbeatSupport() const;If this function returns true, clients will offer the heartbeat support extension, and servers will respond to clients offering the extension. Otherwise, clients will not offer heartbeat support and servers will ignore clients offering heartbeat support.
If this returns true, callers should expect to handle heartbeat
data in their alert_cb.
Default: false
bool allowServerInitiatedRenegotiation() const;If this function returns true, a client will accept a
server-initiated renegotiation attempt. Otherwise it will send
the server a non-fatal no_renegotiation alert.
Default: true
bool allowInsecureRenegotiation() const;If this function returns true, we will allow renegotiation attempts even if the counterparty does not support the RFC 5746 extensions.
Default: false
DLGroup dhGroup() const;For ephemeral Diffie-Hellman key exchange, the server sends a group parameter. Return the group parameter a server should use.
Default: 2048 bit IETF IPsec group ("modp/ietf/2048")
size_t minimumDhGroupSize() const;Return the minimum size in bits for a Diffie-Hellman group that a client will accept. Due to the design of the protocol the client has only two options - accept the group, or reject it with a fatal alert then attempt to reconnect after disabling ephemeral Diffie-Hellman.
Default: 1024 bits
bool hideUnknownUsers() const;The SRP and PSK suites work using an identifier along with a
shared secret. If this function returns true, when an identifier
that the server does not recognize is provided by a client, a
random shared secret will be generated in such a way that a
client should not be able to tell the difference between the
identifier not being known and the secret being wrong. This can
help protect against some username probing attacks. If it
returns false, the server will instead send an
unknown_psk_identity alert when an unknown identifier is
used.
Default: false
Duration sessionTicketLifetime() constReturn the lifetime of session tickets. Each session includes the
start time. Sessions resumptions using tickets older than
sessionTicketLifetime duration will fail, forcing a full
renegotiation.
Default: 86400 seconds (1 day)
from class TLSCiphersuite:
ushort ciphersuiteCode() const;Return the numerical code for this ciphersuite
string toString() const;Return the ful name of ciphersuite (for example "RSA_WITH_RC4_128_SHA" or "ECDHE_RSA_WITH_AES_128_GCM_SHA256")
string kexAlgo() const;Return the key exchange algorithm of this ciphersuite
string sigAlgo() const;Return the signature algorithm of this ciphersuite
string cipherAlgo() const;Return the cipher algorithm of this ciphersuite
string macAlgo() constReturn the authentication algorithm of this ciphersuite
A TLSAlert is passed to every invocation of a channel's alert_cb.
from class TLSAlert
bool isValid() const;Return true if this alert is not a null alert
bool isFatal() const;Return true if this alert is fatal. A fatal alert causes the connection to be immediately disconnected. Otherwise, the alert is a warning and the connection remains valid.
Type type() const;Returns the type of the alert as an enum
string typeString();Returns the type of the alert as a string
TLS has several different versions with slightly different behaviors.
The TLSProtocolVersion class represents a specific version:
enum VersionCodeSSL_V3, TLS_V10, TLS_V11, TLS_V12, DTLS_V10,
DTLS_V12
static TLSProtocolVersion latestTlsVersion();Returns the latest version of TLS supported by this implementation (currently TLS v1.2)
static TLSProtocolVersion latestDtlsVersion();Returns the latest version of DTLS supported by this implementation (currently DTLS v1.2)
this(Version_Code named_version);Create a specific version
ubyte majorVersion() const;Returns major number of the protocol version
ubyte minorVersion() const;Returns minor number of the protocol version
string toString() const;Returns string description of the version, for instance "SSL v3", "TLS v1.1", or "DTLS v1.0".
static TLSProtocolVersion latestTlsVersion();Returns the latest version of the TLS protocol known to the library (currently TLS v1.2)
static TLSProtocolVersion latestDtlsVersion()Returns the latest version of the DTLS protocol known to the library (currently DTLS v1.2)