Execute MATLAB Functions Using HTTPS

Connecting to a MATLAB^® Production Server™ instance over HTTPS provides a secure channel for executing MATLAB functions. To establish an HTTPS connection with a MATLAB Production Server instance using a Java^® client:

1. Ensure that the server instance is configured to use HTTPS. For more information, see Enable HTTPS.

2. Configure the client environment for using SSL.

3. Create the program proxy using the HTTPS URL of the deployed application. For more information about writing a client program using the MATLAB Production Server Java client library, see Create MATLAB Production Server Java Client Using MWHttpClient Class.

The MATLAB Production Server Java client API provides hooks for the following:

• Disabling security protocols to protect against the POODLE vulnerability.

• Providing your own HostnameVerifier implementation.

• Implementing server authorization beyond that provided by HTTPS.

Configure Client Environment for SSL

Before your client application can send HTTPS requests to a server instance, the root SSL certificate of the server must be present in the Java trust store on the client machine. If the server uses a self-signed certificate or if the root certificate of the server signed by a certificate authority (CA) is not present in the Java trust store, obtain the server certificate from the MATLAB Production Server administrator or export the certificate using a browser, then import the server certificate into the Java trust store.

Export and Save SSL Certificate

You can use any browser to save the server certificate on the client machine. The procedure to save the certificate using Google Chrome^® follows.

1. Navigate to the server instance URL https://server FQDN:port/api/health using Google Chrome.

2. In the Google Chrome address bar, click the padlock icon or the warning icon, depending on whether the server instance uses a CA-signed SSL certificate or a self-signed SSL certificate.

3. Click Certificate > Details > Copy to File. This opens a wizard that lets you export the SSL certificate. Click Next.

4. You can use the default format selection of DER encoded binary X.509 (.CER). Click Next.

5. Specify the location and file name to export the certificate, then click Next.

6. Click Finish to complete exporting the certificate.

Add Certificate to Java Trust Store

The default Java trust store is located in ${JAVA_HOME}\lib\security\cacerts. You can use the keytool utility located in ${JDK_HOME}\bin to import the SSL certificate of the server into the trust store on the client machine. For more information, see keytool.

Import the server certificate to the Java trust store of the client machine using the following command:

C:\tmp>keytool -importcert -file PATH_TO_SERVER_CERTIFICATE\server_cert.cer -keystore client.truststore

Doing so imports the server certificate server_cert.cer into a trust store and generates a client.truststore file in the current working directory. You can specify client.truststore file as the trust store when you write the client program to establish a secure proxy connection.

To use a location other than the default for the client trust store, set the trust store location and password using Java system properties, either using Java code or when running you Java client program the command line.

• Set Java system properties in your code:

  System.setProperty("javax.net.ssl.trustStore",
                     "PATH_TO_TRUSTSTORE\\client.truststore");
  System.setProperty("javax.net.ssl.trustStorePassword",
                     "TS_PASSWORD");
  MWClient client = new MWHttpClient();
  URL sslURL = new URL("https://server FQDN:port/myApplication");
  
  MyProxy sslProxy = client.createProxy(sslURL, MyProxy.class);

• Set Java system properties using the command line at run time:

  C:\>java -Djavax.net.ssl.trustStore="client.truststore" -Djavax.net.ssl.trustStorePassword="TS_PASSWORD" CLIENT_NAME

To connect to a server that requires client-side authentication, a client certificate must also be present in the key store of the client. For more information, see Establish Secure Connection Using Client Authentication.

Establish Secure Proxy Connection

After your client machine is configured to use the server certificate or if the server uses a CA-signed SSL certificate that Java trusts, you can write your client program to create a secure proxy connection with the server using the following code:

MWClient client = new MWHttpClient();
URL sslURL = new URL("https://server FQDN:port/myApplication");
MyProxy sslProxy = client.createProxy(sslURL, MyProxy.class);

Doing so creates a secure proxy connection with the server instance running at https://server FQDN:port to communicate with the deployed application myApplication. The connection uses the MWHttpClient constructor and the proxy object reference sslProxy.

sslProxy checks the default Java trust store of the client machine to perform the HTTPS server authentication. If the server requests client authentication, the HTTPS handshake fails because the default SSLContext object created by the JRE does not provide a key store.

Establish Secure Connection Using Client Authentication

Before a .NET client can communicate with a server instance that requires client authentication, you must create a client certificate.

Create Client Certificate

1. On the client machine, create a client certificate in JKS format in the key store.

   C:\tmp>keytool -genkey -alias javaclient -keystore client.jks

   The command creates a certificate client.jks with an alias javaclient.

2. In your client program, set the key store location using the file client.jks and password using Java system properties.

   System.setProperty("javax.net.ssl.keyStore", "PATH_TO_KEYSTORE\\client.jks");
   System.setProperty("javax.net.ssl.keyStorePassword", "keystore_pass");
   MWClient client = new MWHttpClient();
   URL sslURL = new URL("https://hostname:port/myApplication");
   MyProxy sslProxy = client.createProxy(sslURL, MyProxy.class);

Save Client Certificate on Server

1. Export the public client certificate client.jks in DER format using keytool, then transform it to PEM format using openssl.

   C:\tmp>keytool -export -keystore client.jks -alias javaclient -file client.cer
   C:\tmp>openssl x509 -inform DER -in client.cer -outform PEM -text -out client_cert.pem

2. The MATLAB Production Server administrator must save the client certificate client_cert.pem on the server instance and set the x509-ca-file-store in the server configuration file main_config. For information on configuring the server for client authentication, see Configure Client Authentication.

Handle Exceptions

Override Certificate Check

If the self-signed certificate or the root CA certificate of the server is not present in the Java trust store on the client machine, and there is no mismatch between the host name of the HTTPS URL for MATLAB function execution and the common name (CN) of the SSL certificate of the server, then running your client program results in the following exception:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: 
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: 
unable to find valid certification path to requested target

Use one of the following options to handle this exception:

• Add the SSL certificate of the server to the Java trust store on the client machine. For more information, see Add Certificate to Java Trust Store.

• Override the certificate check and accept the untrusted certificate using the following code. The code provides a custom implementation of the MWSSLConfig interface to use a custom SSLContext implementation.

  MWSSLConfig sslConfig = new MWSSLDefaultConfig(){
      public SSLContext getSSLContext(){
          try {
              TrustManager[] trustAllCerts = new TrustManager[] {
                  new X509TrustManager() {
                      public java.security.cert.X509Certificate[] getAcceptedIssuers() {
                          return null;
                      }
   
                      public void checkClientTrusted(X509Certificate[] certs, String authType) {  }
   
                      public void checkServerTrusted(X509Certificate[] certs, String authType) {  }
                  }
              };
   
              SSLContext sc = SSLContext.getInstance("SSL");
              sc.init(null, trustAllCerts, new java.security.SecureRandom());
              return sc;
          } catch(Exception ex){
              throw new RuntimeException("Error creating SSLContext : ", ex);
          }
      }
  };
           
  // Create a non-interruptible MWHttpClient instance
  final MWClient client = new MWHttpClient(sslConfig);

  This option is not recommended for a production environment.

Disable Host Name Verification

If there is a mismatch between the host name of the HTTPS URL for MATLAB function execution and the CN of the SSL certificate on the server, you can override the certificate check to disable host name verification using the following code in your client program:

class MySSLConfig extends MWSSLDefaultConfig {
  public HostnameVerifier getHostnameVerifier() {
    return new HostnameVerifier() {
      public boolean verify(String s, SSLSession sslSession) {
        return true;
      }
    };
  }
}

A MATLAB Production Server deployment on Azure^® uses a self-signed SSL certificate by default. Replacing the self-signed certificate with a CA-signed certificate is recommended. However, if you want to use the self-signed certificate and send HTTPS requests to the server, client programs must disable host name verification to avoid encountering an exception caused by a failure in host name verification. The verification fails due to a mismatch between the host names in the HTTPS URL for MATLAB function execution and the common name (CN) of the self-signed certificate. The host name for the MATLAB execution endpoint has the value <uniqueID>.<location>.cloudapp.azure.com, but the CN has the value azure.com. For information about MATLAB Production Server on Azure, see Azure Deployment for MATLAB Production Server (BYOL) and Azure Deployment for MATLAB Production Server (PAYG).

Sample Code

Sample client program for communicating with a server using HTTPS follows.

 MagicAsync.java

import java.net.URL;
import java.util.concurrent.Future;
import com.mathworks.mps.client.*;
import javax.net.ssl.HostnameVerifier;
import javax.net.ssl.SSLSession;

class MyConfig extends MWHttpClientDefaultConfig{
  public boolean isInterruptible() { return true; }
  public int getMaxConnectionsPerAddress() { return 10; }
}

class MySSLConfig extends MWSSLDefaultConfig {
  public HostnameVerifier getHostnameVerifier() {
    return new HostnameVerifier() {  
      public boolean verify(String s, SSLSession sslSession) {
        return true;
      }
    };
  }
}

public class MagicAsync{
  public static void main(String[] args){
    MWClient client = new MWHttpClient( new MyConfig(), new MySSLConfig() );

    try{
      MWInvokable invokable = client.createComponentProxy(new URL("https://localhost:9920/mymagic"));

      MWInvokeRequest<double[][]> httpRequest = new MWInvokeRequest("mymagic", double[][].class);
      httpRequest.setInputParams(4);
      httpRequest.setNargout(1);

      MWRequest<double[][]> request = invokable.invokeAsync(httpRequest, null);
      Future<double[][]> f = request.getFuture();

      double[][] res = f.get();
      printResult(res);
    }
    catch(Exception ex){
      System.out.println(ex);
    }
    finally{
      client.close();
    }
  }

  private static void printResult(double[][] result){
    for(double[] row : result){
      for(double element : row){
        System.out.print(element + " ");
      }
    System.out.println();
    }
  }
}

Related Topics

• Customize Security Configuration
• Enable HTTPS
• Create MATLAB Production Server Java Client Using MWHttpClient Class

External Websites

• keytool