TLS-Design » History » Revision 19
Revision 18 (Simon Potzernheim, 10/17/2012 02:53 PM) → Revision 19/20 (Hans-Martin Haase, 08/24/2015 08:18 AM)
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 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. 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 softcert 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 securtiy 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 Bouncycastle Implementation Design - class diagram diagramm Description: This diagram shows the dependencies between the existing (prototype) implementation of TLS tls and its BouncyCastle bouncycastle dependencies before refactoring. !uml_bouncycastleimplementation.png! Description: This diagram shows the initialization of a TLS 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 openecard specific implementation to handle multiple TlsClient implementations and credentials (e.g. smart cards smartcards and keystores). (needs better capsulation) The only object needed to create a TLS tls connection is the TLSTransport implementation of the TransportInterface. The interfaces that are used from inside TLS tls to communicate with the client (module outside of transport artifact) CertificateValidator Interface to validate the Server Certificate Certifiacte 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 gui interface must not be in the TLS tls module itself.) Therefore the only dependencies to the Open eCard openecard client are a ConnectionHandle connectionhandle to the SAL sal and an implementation if the dispatcher interface to a SAL sal instance. !uml_bouncycastleimplementation_seq.png!