6.2.15 Managing SSL Connections

At times it is desirable to load and use self-signed certificates, certificates generated from a single trusted certificate authority (CA), or even simple server certificates. It may also be necessary to use client certificates to communicate with external resources. To ease this process, the SSL service can be utilized (see 6.6.7 SSL Service). This service provides methods to load client and server certificates from the filesystem. Methods are also present to aid in creating connections that automatically trust all server certificates and connections.

Several points should be noted when using the SSL Service:

• Certificate files can be in the PEM file format and do not need to be in the DER format (as is typical of Java security).
• Each method returns an instance of SSLSocketFactory, which can then be used to create simple sockets or, in combination with another client library of choice, create a connection.
• If the client certificate password is non-null, it will be used to decrypt the protected client certificate.
• This service is not needed when performing SSL communications with trusted certificates, such as those for HTTPS enabled websites that do not have a self-signed certificate.
• If the file name of the certificate file (client or server) is relative (no leading '/' character), it will be loaded from the mws.certificates.location configuration parameter (see 8.2  MWS Configuration).
  • The default value of mws.certificates.location is MWS_HOME/etc/ssl.crt.
• Both the client certificate alias and password can be null. In this case, the client certificate must not be encrypted and the client certificate's default alias (the first subject CN) will be used.
• The lenient socket factory and hostname verifier automatically trust all server certificates. Because of this, they present a large security hole. Only use these methods in development or in fully trusted environments.

Example

To create a socket to a server that requires a client certificate, the following code can be used:

package example

import com.adaptc.mws.plugins.*

class SSLConnectionPlugin extends AbstractPlugin {
	ISslService sslService

	public void poll() {
		// This certificate is not encrypted and will be the only certificate 
presented to the
		// connecting end of the socket.
		// This file will be loaded from MWS_HOME + mws.certificates.location + 
my-cert.pem.
		String clientCert = "my-cert.pem"

		def socketFactory = sslService.getSocketFactory(clientCert, null, null)
		def socket = socketFactory.createSocket("hostname.com", 443)
		// Write and read from the socket as desired…
	}
}

To create an HTTPS URL connection to a server that has a self-signed certificate, the following code can be used. Note that this is very typical of client libraries – they have a method to set the SSL socket factory used when creating connections.

package example

import com.adaptc.mws.plugins.*

class SSLConnectionPlugin extends AbstractPlugin {
	ISslService sslService

	public void poll() {
		// This certificate represents either the server public certificate or 
the CA's certificate.
		// Since the path is absolute it will not be loaded from the MWS_HOME 
directory.
		String serverCert = "/etc/ssl/certs/server-cert.pem"

		def socketFactory = sslService.getSocketFactory(serverCert)

		// Open connection to URL
		HttpsURLConnection conn = "https://hostname.com:443/test".toURL()
.openConnection()
		conn.setSSLSocketFactory(socketFactory)

		// Retrieve page content and do with as desired…
		def pageContent = conn.getInputStream().text
	}
}