Overview

Clover devices are preloaded with a collection of trusted root certificates. These root certificates are used when an Android application makes a connection to a web server to determine the authenticity of the server and establish a secure TLS connection. If a web server presents a leaf certificate that chains up to a built-in trusted root certificate, then the connection proceeds normally.

Issue with certificates on earlier models of Clover devices

Over time, Certificate Authorities (CAs) like Digicert and Let's Encrypt issue new root certificates, which are used to sign new leaf certificates for various web servers. These new root certificates are not present on earlier models of Clover devices, resulting in TLS connection errors when applications on these devices try to connect to web servers using the latest root certificates.

Workaround for certificate issues on Clover devices

To remedy the issue as an application developer, you have three options:

1. Use the Android Network Security Configuration XML—If your application is only supported on Clover devices running Android 6.0 or higher, you can use the Android Network Security Configuration XML to add the root certificate that your web server uses to the list of trust anchors. See instructions.
2. Write code to configure either the HTTP/TLS client, the WebView, or both—If your application supports Clover devices running versions of Android earlier than 6.0, you must manually write code to configure your HTTP/TLS client or WebView to trust the root certificate that your web server uses. See instructions.
3. Select an authority certificate that is supported on old and new Clover devices—If you can't or don't want to update your device application, and if your certificate authority (CA) permits it (or you can find another that does), select a CA that is compatible with both earlier and newer models of Clover devices. You can select the alternate authority when obtaining a server certificate. See instructions.

In any case, you should get a copy of your web server's current root certificate authority.

Recommendation for developers

• Note that all common web browsers, such as Chrome, Firefox, and Safari, offer mechanisms to download the certificate chain from a web server, including the root certificate. Whenever you renew your web server certificate, confirm the root certificate authority and verify whether it has changed from the previous or existing root authority to determine if any action is necessary.

• Run the following code on a Clover device to get a list of all root certificates currently installed on the device supported by your application.

	TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
List<Certificate> x509Certificates = new ArrayList<>();
trustManagerFactory.init((KeyStore) null);
for (TrustManager t : trustManagerFactory.getTrustManagers()) {
    x509Certificates.addAll(Arrays.asList(((X509TrustManager) t).getAcceptedIssuers()));
}
for (Certificate c : x509Certificates) {
    Log.i(TAG, "Cert: " + c);
}

• Use Android Emulators running the same operating system (OS) version as Clover devices to determine the trusted root certificate list. You need to contact your certificate authority (CA) to see what certificates are available and if there is any option that matches one of the certificates supported by the old and new Clover device models that your application supports.

Detailed instructions

Option 1: Use the Android Network Security Configuration XML

In Android 6.0, the Network Security Configuration gives developers better control over the server certificates that are trusted by their application. The Network Security Configuration uses XML files with a network-security-config tag. You can use the configuration only if your application is not available on Clover devices running Android versions older than 6.0, such as Clover Flex 1, Clover Mini 1, and Clover Station 1. If your app is not available on these devices, you can follow the instructions here to trust additional CAs using a copy of your web server's root CA certificate: Network security configuration—Trust additional CAs.

Option 2: Write code to configure your HTTP/TLS client and/or WebView

• For HTTP/TLS client—The code necessary to add a trusted root certificate for your application varies depending on which HTTP/TLS client your application is using to make network calls to your server. You can use the TrustKit-Android library to reduce the amount of custom code they write. See the documentation links at GitHub TrustKit-Android for more information.

  Note that this implementation does not support all features of standard Android network security configuration. In particular, base-config is not supported, so you must use domain-config with this library.

• For WebView—If your application uses Android WebView to interact with your web server, see the following Stack Overflow answer that describes a mechanism to get Android WebView to trust additional certificates.

Option 3: Select an authority certificate that is supported on Clover devices

This is the least recommended option since it likely only delays the inevitable result that very old root certificates may eventually not be trusted on both earlier and newer models of Clover devices and that certificate authorities may completely stop issuing certificates that chain up to very old root certificates. However, it does provide a solution that works without making any changes to an existing deployed application.

For more information on Clover device certificates, see FAQs—Device certificates.