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!