< Back to Package Overview
Working with Certificates
Trust Store
During the Transport Layer Security (TLS) setup process, a trust relationship between the client and server must be established. A trust store is a necessary resource to support this process.
A tutorial on Public-Key Infrastructure (PKI) in general and working with certificates on Android is outside the scope of this document. Please refer to Google Developer - Security with HTTPS and SSL if you would like more information on this topic.
The default behavior of the Avaya Client SDK Communications Package for Android is to use the platform trust store for trust chain validation for any TLS connections initiated by Client SDK.
When using the default configuration, simply add certificates to the trust store of the Android device where your application will be running. Client SDK will access the platform trust store directly as needed.
Note: On Android, the instructions to access and install certificates may vary from device to device. For example, the instructions for Nexus can be found here . When in doubt please consult the documentation for your device to ensure the correct steps are being followed.
Private Trust Store
As an alternative to the use of the Platform Trust Store Avaya Client SDK provides a facility called the Private Trust Store. The Private Trust Store is a trust store implemented and maintained by Client SDK. The Private Trust store allows the administrator of Client SDK based applications complete control over the certificates that are used by Client SDK, independently of the certificates in the Platform Trust Store. Client SDK will use both i.e. the platform trust store & private trust store even though the private trust store is configured.
Note: Each Client SDK based application has its own instance of the Private Trust Store. This implies that when multiple applications are running on the same device, each application Private Trust Store instance must be populated and managed independently. There is no support for sharing of a single Private Trust Store instance across multiple applications on the same device. If multiple applications running on the same device require access to a common trust store the Platform Trust store must be used.
The following code snippet demonstrates how to enable a Private Trust Store. By default, the Platform Trust Store will be used.
SecurityPolicyConfiguration
CertificateManager
// Create and initialise the Security Policy Configuration to use the Private Trust Store.
SecurityPolicyConfiguration securityPolicyConfig = new SecurityPolicyConfiguration();
securityPolicyConfig.setPrivateTrustStoreEnabled(true);
// Use the trust anchors from both private and system trust store.
// For trust anchors to be exclusively used from the private trust store,
// use TrustStoreMode.PRIVATE_ONLY.
securityPolicyConfig.setTrustStoreMode(TrustStoreMode.PRIVATE_AND_SYSTEM);
// Instantiate a list of certificates.
List trustedAnchors = new ArrayList();
// Populate CA Certificates in the trustedAnchors as required.
// Acquire the certificateManager object from the instantiated Client instance.
client.CertificateManager.setCertificates(trustedAnchors);
// PrivateTrustStore is now created and populated.
All private trust store certificates must be managed as a set. Individual certificates cannot be added to, or removed from, the private trust store. It is the clients responsibility to determine if the contents of the private trust store needs to change.
SecurityPolicyConfiguration
CertificateManager
Refreshing Private Trust Store Certificates
// Create and initialise the Security Policy Configuration
// to use the Private Trust Store.
SecurityPolicyConfiguration securityPolicyConfig =
new SecurityPolicyConfiguration();
securityPolicyConfig.setPrivateTrustStoreEnabled(true);
// Use the trust anchors from both private and system trust store.
// For trust anchors to be exclusively used from the private trust store,
// use TrustStoreMode.PRIVATE_ONLY.
securityPolicyConfig.setTrustStoreMode(TrustStoreMode.PRIVATE_AND_SYSTEM);
// Instantiate a list of certificates.
List trustedAnchors = new ArrayList();
// Populate CA Certificates in the trustedAnchors as required.
if (client.CertificateManager.IsCertificateStoreInUse()) {
// Remove existing certificates.
client.CertificateManager.deleteCertificateStore();
// Add new certificates.
client.CertificateManager.setCertificates(trustedAnchors);
}
How to view / retrieve certificates from the Private Trust Store.
List certs;
if (client.CertificateManager.IsCertificateStoreInUse()) {
certs = client.CertificateManager.getCertificates();
}
Certificate Validation
Client SDK will validate server certificates for network connections instantiated by Client SDK. Client SDK provides a certification validation API to allow your application to delegate the certificate validation process to Client SDK, providing a consistent security behaviour for all your application secure networking. If your applications is implementing its own certificate validate, it is not mandatory that Client SDK Certificate Validation API be used. If your application is implementing its own certificate validation, then Client SDK Private Trust Store should not be used. Client SDK Certificate Validation is described at CertificateManager
Setting Trust Store Mode
The trusted anchors (root, intermediate CA certificates) used for certificate validation can be controlled via a configurable TrustStoreMode parameter.
By default, Client SDK will use the trusted anchors from its private trust store and platform (system) trust stores (PRIVATE_AND_SYSTEM).
However, trusted anchors from the private trust store can be exclusively used by setting trust store mode to PRIVATE_ONLY for certificate validation, by changing the configuration.
Use the setTrustStoreMode() method of the SecurityPolicyConfiguration object to set TrustStoreMode parameter.
Basic Validation
When Client SDK is configured with the Private Trust Store, the Trusted Anchors (CA certificates) are used from the Private Trust Store.
CertificateValidationCompletionHandler
Hostname Validation
Certificate Hostname Validation is a configurable option in Client SDK.
SecurityPolicyConfiguration
When Certificate Hostname Validation is enabled Client SDK first checks the SAN (SubjectAlternativeName) for the hostname/IP to which the connection was intended. If the hostname/IP is not found in a SAN field Client SDK checks the certificate's Common Name (CN) field.
Note: For SIP certificates there is an additional check that requires the SIP domain to also be present in a SAN (SubjectAltName) field to allow the server certificate from the SIP Controller to be validated.
Avaya Demo Certificates
If your application will be used in an environment that is using Avaya Demo Certificates you must disable Hostname Validation in your application. Avaya Demo certificates do not have a proper IP address/hostname in the CN or SAN fields (because they were issued by Avaya as demo certificates prior to installation of the server). Therefore Hostname validation will always fail for Avaya Demo Certificates.
Note: Avaya strongly recommends that Demo Certificates be removed from servers and replaced with certificates specific to your deployment immediately.
