Activating Secured Tunneling Mode (SSL)

	Introduction This document explains how to contact ENOVIA servers behind firewalls through tunneled and secured communications using Secure Socket Layer (SSL). SSL is implemented by inserting an additional protocol layer between the applicative messages (IIOP or HTTP protocols) and the transport protocol (TCP/IP). For the moment SSL is only applicable on top of HTTP Tunneling. SSL is added to a working solution. Unlike the "port redirection only" solution, the provided SSL-tunneling components imply heavy performance overhead due to the additional handling of the SSL protocol. SSL has also some impacts on the deployment and the administration due to the usage of certificates: to engage SSL communications, each peer must have access to its private key, its certificate, and the list of certificates it can accept from the other peers as detailed in the next section.
	Quick overview of SSL communications The general purpose of the SSL specification is to provide basics security features such as strong authentication using public key cryptography and certificates, confidentiality using symmetric encryption algorithms, and data integrity using message digest algorithms. Authentication allows a client and a server application to verify the identity of each other during the so-called handshake protocol to be detailed next, confidentiality ensures that all data transmitted between client and server applications cannot be understood by a third party, and integrity allows to detect if those data were modified during transmission. In SSL, authentication is based on public key cryptography. Each application has a public (widespread) key and an associated private (secret) key: only one of this key can decrypt data encrypted by the other key. This feature allows an application to prove its identity by encrypting data with its private key: as no other application has access to this secret key, the encoded data must come from the true application. Then any other application can check the content of the data by decoding it with the public key issued by the application. To prove that a public key (and thus the associated private key) really originates from a given application, a mechanism of certificates is needed. Certificates are digital documents whose role is to bind a public key to the identity of an application, and whose format has been standardized (X509 recommendation). A certificate is commonly issued and digitally signed by a third-party organization called a Certificate Authority or CA (e.g. Verisign, Thawte, etc.) that verifies the match between a public key and the name of the application. In order to validate the certificate of a given application, all other parties this application wants to engage SSL communications with must explicitly trust the CA that signed it. Each new connection is followed by the SSL handshake protocol whose implementation is based on time-consuming algorithms. Here is a summary of the main steps involved in the SSL handshake: The client initiates communications by sending the initial SSL handshake message to the server The server responds by sending its certificate to the client that contains its public key and requests the client's certificate The client uses the received certificate to authenticate the server by answering "yes" to two main questions: Is the issuing CA a trusted CA? Does issuing CA's public key validate issuer's digital signature? If step (3) is successful, the client sends its certificate (along with some data, digitally signed by its private key) and a secret encrypted with the server's public key The server uses the received certificate and data to authenticate the client by answering "yes" to three main questions: Does the client's public key validate the digitally signed data? Is the issuing CA a trusted CA? Does issuing CA's public key validate issuer's digital signature? If step (5) is successful, the server decrypts the secret with its private key and generates the session key (on its side, the client has generated the same session key from the shared secret) The session key is a symmetric key that will be used to encrypt and decrypt all subsequent messages exchanged between the two parties. The client sends a message to the server to inform it that the client portion of the handshake is done and that the session key will encrypt future messages The server sends a message to the client to inform it that the server portion of the handshake is done and that the session key will encrypt future messages From now on, each message sent (respectively received) is encrypted (respectively decrypted) using the shared session key and the integrity of each message is checked by calculating a digest. In this SSL-Tunneling solution, the actual implementation of the SSL client and server processes are based on the Java Secured Socket Extension specification (JSSE). The version of the JSSE specification used in the current implementation is 1.0.2. This means that, to enable SSL communications between the clients and the servers, a specific provider for JSSE 1.0.2 has to be installed and properly configured on each peer on top of the existing JDK 1.3 installation. In other words, JDK 1.3 and JSSE 1.0.2 software are software requirements for SSL tunneling on clients and servers. A non-commercial reference implementation of JSSE 1.0.2 is provided by Sun Microsystems, Inc.
	Network considerations As far as the server network is concerned, no additional configuration for the firewall is needed since the port 443 or any other ports dedicated to SSL-enabled protocols can be used. However, this is not mandatory and any other port can be used, provided it is open on the firewall. As said above, SSL is based on strong authentication using certificates. During the so-called SSL handshake, the server sends its certificate to the client. The client verifies the validity of the certificate to authenticate the server host. Reciprocally, but optionally in the current SSL specification, the client sends its own certificate back to the server so that the server can authenticate the client host by checking the validity of the client's certificate. Hence, it is required that the SSL server process be running on a host publicly accessible to clients or located in the DMZ of the server network for the SSL handshake to occur successfully between this server host and every client peers. Note that on the server network, both direct and SSL-enabled connections are allowed with the same Orbix daemon. All servers and clients lying inside the firewall can connect to all other servers without SSL tunneling. As far as the client network is concerned, security is still managed by a firewall and/or a HTTP proxy server, that enforce rules on which client can connect to which server. In particular, the SSL client process is able to handle authentication challenges issued by the HTTP proxy server (only base-64 "Basic" authentication is currently supported). Once again, for the SSL handshake to occur successfully, it is required that the SSL communications be enabled through the HTTP proxy server. Practically, this means that the HTTP CONNECT method has to be explicitly allowed in the HTTP proxy server configuration on the secured port the server is listening to. With this configuration, the HTTP proxy server does not interfere in the encrypted communications and especially in the client/server mutual authentication procedure or handshake. Here is a view of a typical configuration for SSL tunneling:
	Client-side Deployment

	Server-side Deployment
	The SSL server process The file CATTunnelServer.conf is provided and is located in <Install Path>/docs/javaserver. The content of this file is a series of properties that set the behavior of the SSL server process and have to be customized. There are two kinds of parameters in this file : the general parameters and the security parameters. To enable SSL on server modify Security parameters Security parameters These parameters are intimately linked to the JSSE implementation that is to be used along with this solution. All of them are optional provided the JSSE implementation is correctly configured on the server host. Excepting the so-called "secured" and "authenticateClient" parameters, most of them point to some Java-specific security properties that have to be set according to the documentation delivered with your JSSE provider's implementation. Each parameter and its Java equivalent is detailed next for the JSSE implementation provided by Sun Microsystems, Inc. The JAVA_HOME variable refers to the directory where the JRE 1.3 is installed. secured : boolean (true/false) to enable/disable SSL communications (default is false: SSL off). authenticateClient : boolean (true/false) used to force clients to authenticate to the server (default is false: no client authentication). Client authentication is optional in SSL specification. securityProvider : specifies the fully qualified name of the provider class. This parameter can be blank if properly set in the Java security properties file (JAVA_HOME/lib/security/java.security) using the line `security.provider.n=...` where n is the preference order of this provider. For Sun JSSE it is "com.sun.net.ssl.internal.ssl.Provider." keyStore : specifies the location of the file where key materials are stored on the server host. Key material include the public and private key pair(s) and the corresponding certificate(s). This parameter is a Java system property that has no default value. To enable SSL communications, this parameter must be set to the actual key material of the server host and all clients must trust this certificate or the CA that issued this certificate. keyStoreType : specifies the type of the key materials. The default is "JKS" (value of keystore.type in the file JAVA_HOME/lib/security/java.security) keyStorePassword : specifies the password used to open the key store. The default is "". Mandatory along with keyStore. keyManagerType : specifies the type of the implementation managing the key store. This parameter can be set in the file JAVA_HOME/lib/security/java.security using the line `sun.ssl.keymanager.type=...` The default value is "SunX509" with Sun JSSE provider. trustStore : specifies the location of the file where trusted certificates are stored on the server host. This is a Java system property which defaults to JAVA_HOME/lib/security/jssecacerts or JAVA_HOME/lib/security/cacerts if the first file does not exist. If client authentication is not used, you can left it blank. trustStoreType : same as keyStoreType. trustStorePassword : specifies the password used to open the trust store. The default is "" so that this parameter is mandatory when client authentication is on. trustManagerType : specifies the type of the implementation managing the trust store. This parameter can be set in the file JAVA_HOME/lib/security/java.security using the line `sun.ssl.trustmanager.type=...` The default value is "SunX509" with Sun JSSE provider. Two examples of a customized CATTunnelServer.conf file is given in the summary section.
	Example of the Overall Deployment without proxy To review the preceding points, here is an example of a typical deployment though simplified, going from the server to the client applications, explained step by step.
	Server network Let's suppose a host named "S1" in the DMZ of the server network. On "S1" an ENOVIA server will be running, with Orbix daemon port 1570 and a range of IIOP ports from 1590 to 1790. This host has a public IP address that can be resolved anywhere by a name service lookup given the name "S1". Let's suppose its operating system is Solaris 8. Install a Java Runtime Environment 1.3. The variable JAVA_HOME will be /usr/j2se/jre. The command line /usr/j2se/jre/bin/java -fullversion should give something like: java full version "1.3.1_02-b02" Complete the JRE 1.3 installation with the installation of a JSSE 1.0.2 provider To make things clearer, let's say this is Sun JSSE provider ( http://java.sun.com/products/jsse/ ). Once the JSSE software is downloaded and unzipped, copy the extension jar files jsse.jar, jcert.jar, and jnet.jar to the directory /usr/j2se/jre/lib/ext. Create the key material for the server host We will use the Java keytool utility. Type: `/usr/j2se/jre/bin/keytool -genkey -keystore /usr/j2se/jre/lib/security/serverkeys -alias enovia -storepass passphrase -keypass passphrase` keytool will prompt you for information to put into the certificate. The first and last names should be set to the server name, here "S1." The key store "serverkeys" now contains the certificate of the server. This certificate must be delivered to all clients so that they can add it to their list of trusted certificates. To export the certificate to a file, use the keytool command: `/usr/j2se/jre/bin/keytool -export -keystore /usr/j2se/jre/lib/security/serverkeys -alias enovia -storepass passphrase -file server.cer` The file "server.cer" can be distributed to the clients. Install the ENOVIA server as explained in the dedicated documentation. We suppose the installation is located in the directory <Install Path>, which will be something like: `/usr/DassaultSystemes/B18/solaris_a` Edit the file <Install Path>/docs/javaserver/SSLTunnelServer.conf to configure the SSL tunnel server process. `listenPort=443` `forwardHost=` `forwardPorts=1570,1590-1790` `webHost=` `webPort=` `retry=10` `delay=1` `secured=true` `authenticateClient=false` `securityProvider=com.sun.net.ssl.internal.ssl.Provider` `keyStore=/usr/j2se/jre/lib/security/serverkeys` `keyStoreType=JKS` `keyStorePassword=passphrase` `keyManagerType=SunX509` `trustStore=` `trustStoreType=` `trustStorePassword=` `trustManagerType=` Set the three environment variables CATTunnelingMode, CATTunnelingPropertiesFileName, and CATTunnelingPropertiesFilePath in the file whose name is given in <Install Path>/EnvName.txt and location is given in <Install Path>/EnvDir.txt. CATTunnelingMode=http CATTunnelingPropertiesFileName=CATTunnelStartupServer.conf CATTunnelingPropertiesFilePath=<Install Path>/docs/javaserver Start the starter process "CATTunnelStartup" with the following command line: `<Install Path>/code/command/catstart -run CATTunnelStartup` Check that the Java process is running. Otherwise edit the file <Install Path>/docs/javaserver/CATTunnelStartupServer.conf and replace line `ssl.solaris_a=com.dassault_systemes...` with line `ssl.solaris_a=-Xbootclasspath/p:/usr/j2se/jre/lib/ext/jsse.jar:/usr/j2se/jre/lib/ext/jnet.jar:/usr/j2se/jre/lib/ext/jcert.jar com.dassault_systemes...` and restart CATTunnelStartup. This should force the JVM to enable SSL.

	Clients On the client network, we suppose that a HTTP proxy server is running on a host named "MyHttpProxy," and is listening to the typical port 8080. This HTTP proxy server is configured to let go out only authorized users with valid Internet ID and password. Moreover it is configured to authorize the HTTP CONNECT method on port 443. We suppose that the client machine has Windows for operating system. Install a Java Runtime Environment 1.3. The variable JAVA_HOME will be "C:\Program Files\IBM\Java13\jre". The command line "C:\Program Files\IBM\Java13\jre\bin\java" -fullversion should give something like: java.exe full version "J2RE 1.3.0 IBM build cn130-20020124" This JRE 1.3 installation comes with its own JSSE provider. Import the server's certificate from the file "server.cer" into the trust store of the client host Again we use the keytool utility: `"C:\Program Files\IBM\Java13\jre\bin\keytool" -import -keystore "C:\Program Files\IBM\Java13\jre\lib\security\jssecacerts" -alias enovia -file server.cer -storepass changeit` Then, answer yes to the question : Trust this certificate? Now the trust store "jssecacerts" contains the certificate of the server which is explicitly trusted by the client host.