TLS-Design (iteration from 2012-10-08)¶

TLS and related Classes¶

BouncyCastle Classes¶

This diagram shows the TLS classes as available in the BouncyCastle library.

The TlsCredentials and TlsSignerCredentials interface are located in the upper left of the diagram. These interfaces are used in a TLS client authentication to get the client certificate and to produce a signature. For the use of software certificates, BouncyCastle comes with the implementation DefaultTlsSignerCredentials.

The common entry point for TLS based communication is the TlsClient interface in the lower left. In the current BC version, it has three abstract implementations (DefaultTlsClient PSKTlsClient SRPTlsClient) which are missing the getAuthentication() function.
The class returned by this function has two responsibilities. The fist is the validation of the server certificate and the second is the selection of a client credential depending on the supplied CAs. The CAs can be extracted from the CertificateRequest (see upper right) parameter in getClientCredentials().

The last relevant class in this diagram is the TlsProtocolHandler. Given a bidirectional stream (usually based on a socket) and a TlsClient, a new bidirectional stream can be extracted which wraps the original stream in a TLS channel. This handler implements the general TLS protocol and triggers the certificate validation and client authentication.

Open eCard Classes¶

This diagram shows classes that make use of the BouncyCastle classes in order to select and use custom credentials for the TLS authentication.

The TlsClient interface introduced in BouncyCastle Classes is extended with a setAuthentication() function and called ClientCertTlsClient. Each client implementing this new interface can be configured at runtime to use a different server certificate validation and to support client authentication. The implementations are derived from the ones in BouncyCastle, so no functions other than getAuthentication and setAuthentication must be implemented.

The TlsAuthentication interface has no implementation in BouncyCastle. With the new capability to compose the TlsClient at runtime, it also makes sense to compose the TlsAuthentication this way.
TlsNoAuthentication implements the certificate verification part, but raises an error, when client authentication is requested. Based on this implementation, the TlsAuthenticationSelector creates the appropriate TlsSignerCredentials for the requested CAs and given restrictions (ConnectionHandle) by the activation (see diagram in Credential Selection.
The credential is either selected from a software certificate keystore (SoftKeyStore) or by inspecting the SALs token. In the latter case, a SALSignerCredentials instance is created and memorized in the selector if further TLS channels must be opened.

Apache http-core Classes¶

This diagram shows classes of and extensions to Apache http-core. This library is needed in order to isolate TLS channels from each other. Connection sharing must be explicitly controlled for high security requirements.

The TlsProtocolHandler from BouncyCastle emits streams rather than sockets as usually used in the implementations of HttpClientConnection. The AbstractHttpClientConnection uses SessionInputBuffer and SessionOutputBuffer internally to encapsulate the socket. A stream based implementation is needed as shown by the classes StreamSessionInputBuffer and StreamSessionOutputBuffer.
DefaultConnectionReuseStrategy is used to determine whether a connection (streams) can be reused after a request-response pair is processed by the HttpClientConnection.

Client creation¶

The two following diagrams show how the a TLS channel is established and reused in a HTTPS context.

TLS Channel Establishment¶

The following diagram explains how the BouncyCastle classes and the extensions from the Open eCard App can be used to establish a secured connection.

HTTPS Connection Reuse¶

The following diagram shows the process of opening a HTTPS connection, sending and receiving data and finally determining whether the streams of the secure channel can be reused or not.

Credential Selection¶

The following two activity charts show the process how a credential is selected for the authentication.