Open eCard

h1. TLS-Design (iteration from 2012-10-08)

h2. TLS and related Classes

h3. BouncyCastle Classes

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

The "TlsCredentials":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/TlsCredentials.html and "TlsSignerCredentials":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/TlsSignerCredentials.html 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":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/DefaultTlsSignerCredentials.html.

The common entry point for TLS based communication is the "TlsClient":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/TlsClient.html interface in the lower left. In the current BC version, it has three abstract implementations ("DefaultTlsClient":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/DefaultTlsClient.html "PSKTlsClient":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/PSKTlsClient.html "SRPTlsClient":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/SRPTlsClient.html) which are missing the "getAuthentication()":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/TlsClient.html#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":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/CertificateRequest.html (see upper right) parameter in "getClientCredentials()":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/TlsAuthentication.html#getClientCredentials(org.bouncycastle.crypto.tls.CertificateRequest).

The last relevant class in this diagram is the "TlsProtocolHandler":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/TlsProtocolHandler.html. 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.

!bc-tls-classes.png!

h3. 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 [[TLS-Design#BouncyCastle-Classes|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 [[TLS-Design#Credential-Selection|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.

!oec-tls-classes.png!

h3. Apache http-core Classes

This diagram shows classes of and extensions to "Apache http-core":https://hc.apache.org/httpcomponents-core-ga/httpcore/index.html. 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":http://www.bouncycastle.org/docs/docs1.5on/org/bouncycastle/crypto/tls/TlsProtocolHandler.html from BouncyCastle emits streams rather than sockets as usually used in the implementations of "HttpClientConnection":https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/HttpClientConnection.html. The "AbstractHttpClientConnection":https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/impl/AbstractHttpClientConnection.html uses "SessionInputBuffer":https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/io/SessionInputBuffer.html and "SessionOutputBuffer":https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/io/SessionOutputBuffer.html internally to encapsulate the socket. A stream based implementation is needed as shown by the classes @StreamSessionInputBuffer@ and @StreamSessionOutputBuffer@.

"DefaultConnectionReuseStrategy":https://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/org/apache/http/impl/DefaultConnectionReuseStrategy.html is used to determine whether a connection (streams) can be reused after a request-response pair is processed by the HttpClientConnection.

!http-core-classes.png!

h2. Client creation

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

h3. 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.

!tls-client-creation.png!

h3. 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.

!tls-client-reuse.png!

h2. Credential Selection

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

!select-certificate.png!

!select-certificate-from-handles.png!

h1. TLS Design by HSCoburg

h2. BouncyCastle Implementation Design - class diagram

Description: This diagram shows the dependencies between the existing (prototype) implementation of TLS and its BouncyCastle dependencies before refactoring.

!uml_bouncycastleimplementation.png!

Description: This diagram shows the initialization of a TLS connection using the existing (prototype) implementation.

The top part where the client (module outside of transport artifact) interacts with TLSAuthenticationManager and UberClient is always optional and is the Open eCard specific implementation to handle multiple TlsClient implementations and credentials (e.g. smart cards and keystores). (needs better capsulation)

The only object needed to create a TLS connection is the TLSTransport implementation of the TransportInterface.

The interfaces that are used from inside TLS to communicate with the client (module outside of transport artifact) CertificateValidator Interface to validate the Server Certificate and a interface which capsules the GUI interface (to be done) to communicate with the User to select a Client Certificate and validate the server certificate when necessary. (This implementation of the GUI interface must not be in the TLS module itself.)

Therefore the only dependencies to the Open eCard client are a ConnectionHandle to the SAL and an implementation if the dispatcher interface to a SAL instance.

!uml_bouncycastleimplementation_seq.png!