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!