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

!oec-tls-classes.png!

h3. Apache http-core Classes

!http-core-classes.png!

h2. Client creation

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

!tls-client-creation.png!

!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 (old version left here until design is finished)

h2. Bouncy Castle TLS authentication classes

!bc-tls.png!

h2. TLS authentication implementation classes

!sal-tls.png!

h2. TLS authentication sequence

!sal-tls-sequence.png!

h1. TLS Design by HSCoburg

h2. Bouncycastle Implementation Design - class diagramm

Description: TODO

!uml_bouncycastleimplementation.png!