Custom Client Key Support for Android
As of v.7.0.0, the ThingWorx Edge Java SDK supports custom client keys in Android applications:
• The ClientConfigurator class supports paths for keystores and trust stores.
 |
The certificates are handled differently between Android and the standard JVM.
|
• The example applications for the Android SDK include client key configuration.
• The custom client key has been tested against the ThingWorx Platform running in a docker container.
This support differs from the original Android SDK, as follows:
• Not exposing the SSL/TLS context allows the ClientConfigurator to be based solely on configuration parameters. Any changes made to the ClientConfigurator parameters directly modify the connection itself. Exposing the SSL context allows settings made by the ClientConfigurator to be overridden, such as ignoreSSLErrors, since this directly modifies the trust chain in the SSL context.
• The Java SDK provides a clean separation between the Android samples and the core generic Java functionality. Normally, certificates are read from the Android resource tree. This code is specific to Android, and the new ClientConfigurator settings for Android-specific mutual authentication deal only in Strings and streams to maintain this isolation.
Android-Specific Functions for Client Key Support
The setAndroidKeyStoreFactory() and setAndroidTrustStoreFactory() options added to the ClientConfigurator class require an AndroidKeystoreFactory class instance as a value. Here is an example to help you understand:
config.setAndroidKeyStoreFactory(new AndroidKeystoreFactory() {
@Override
public InputStream createStream() {
return applicationContext.getResources()
.openRawResource(R.raw.keystore);
}
@Override
public char[] getPassword() {
return "thingworx".toCharArray();
}
@Override
public String getStoreType() {
return "BKS";
}
});
In this example, you can see the information that the Android application must provide, all collected in one place: Note that the getPassword() function should be implemented using an encrypted store to protect your key store password in production.
|
|
The only type of keystore that Android supports is BKS.
|
Here is an example of setting your client trust store of trusted certificates for validating your ThingWorx Platform. Note that it differs from the AndroidKeystoreFactory above because it has the useSystemStore() method which will append any CA certificates present in the Android System keystore to your keystore when it is created.
config.setAndroidTrustStoreFactory(new AndroidTruststoreFactory() {
@Override
public InputStream createStream() {
return applicationContext.getResources()
.openRawResource(R.raw.truststore);
}
@Override
public char[] getPassword() {
return "thingworx".toCharArray();
}
@Override
public String getStoreType() {
return "BKS";
}
@Override
public boolean useSystemStore() {
return true;
}
});
See the example applications in the Java SDK installation, such as the android-shell or android-steam-sensor in the ThingworxActivity.java class to see how this configuration is done in a real application. Note that Android does not support the commonly used JKS keystore format and supports BKS formatted stores instead.
Also, inside each example is an import directory of ThingWorx entities that should be imported into your ThingWorx Platform for that example to use. Additionally, each example contains a directory called tomcat-ssl-config with both sample certificates and a sample connector that you can add to your Tomcat server.xml file to stand up mutual authentication support in your test environment.