< Back to Package Overview
Working with Client Identity Certificates
Servers are able to validate the identity of the client using Client Identity Certificates.
Avaya Client SDK Communications Package support builds on concepts outlined in Working with Certificates.
Client Certificates are supported with the following providers:
- SIP (SIP Servers and Session Border Controllers)
- Aura Personal Profile Manager (PPM)
- Avaya Multimedia Messaging (AMM)
- Avaya Aura Device Services (AADS)
- IPO (MTCTI Services)
The Client SDK does not provide validation of Client Certificates, and server validation responses are provided to your application.
Client Identity Certs / TLS mutual authentication on client connections
Client Identity Certificate is a digital certificate which confirms to the X.509 system. It is used by client systems to prove their identity to the remote server. At the start of a TLS session, the server (if configured to do so) may require the client application to submit a client certificate for authentication. Upon receiving the certificate, the server would then use it to identify the certificate's source and determine whether the client should be allowed access.
How to identify if a certificate is a client identity certificate
- In the given certificate details tab(double tap on installed cert), the certificates intended purpose has the following text: Proves your identity to a remote computer
- Verify that the Enhanced Key Usage field of the certificate has value of Client Authentication or OID set to (1.3.6.1.5.5.7.3.2)
Note: Verify that Key Usage field of the certificate has Key Encipherment attribute added. This is required for certificates used for data privacy, for encrypting messages.
How to install client identity certificate into Windows certificate store
- User can use certificate installation wizard to install client the identity certificate into windows certificate store.
- User can install client identity certificate at current user/local machine store locations.
- While installing client identity certificate, prefer option Automatically select the certificate store based on the type of certificate, so that certificate wizard will install certificate in correct windows certificate store.
- If you have installed client identity cert manually, ensure that you have installed client identity cert in MY Personal system store.
How to provide Client Identity Certificate to Client SDK
Client can provide client identity certificate using two ways:
User manually selects one identity cert from OS trust store: App can pass a client identity certificate from windows MY Personal certificate store (at current user/local machine) to Client SDK. Client SDK has provided an API to set the client certificate from Windows Personal Certificate store. API: SetClientIdentityCertificate
User manually upload a PKCS12 file from local directory into client: App can upload a PKCS12 file from directory location. Client SDK has provided API that securely stores a client identity certificate and a private key to use during mutual authentication. Here App has to pass certificate chain along with private key used for generating the certificate. API:SetClientIdentityCertificateChain(CertificateChain, private key)
Specifies the URL to be used to download a PKCS #12 file containing a client identity certificate and its private key. (PKCS12URL and PKCS12PASSWORD).
Server connections that support TLS Mutual Authentications
- SM (direct w/o SBC, Through SBC)
- Personal Profile Manager (PPM) (direct w/o SBC, Through SBC)
- AMM (direct w/o SBC, Through SBC)
- AADS (Default as off, direct w/o SBC, Through SBC, supported when certain conditions are
met)
- AAWG (direct w/o SBC, Through SBC)
Mutual TLS not supported on following TLS
LDAP - No (Limitation in client’s 3rd party library)
Unified portal (Default as off, Reason: Guest access can't support the TLS mutual authentication.)
UCCS - No (Limitation in server)
WCS - No(Limitation in server)
Main Client Identity Certificate APIs
- SetClientIdentityCertificateChain - Securely stores a client identity certificate and a private key to use during mutual authentication.
- SetClientIdentityCertificate - Set the client certificate from Windows Personal Certificate store to be used during mutual authentication.
- DeleteClientIdentityCertificateChain - Deletes a provisioned client identity certificate and a private key.
Client Identity Certificate Expiration Notification and Renew:
Client SDK has provided a property named as CertificateRenewalValue in SecurityPoliyConfiguration.
An integer value specifying the percentage(0 - 100) of certificate's max age after which client should issue a certificate renewal notification. Default value of this parameter is 90%.
This configuration shall be applied to any client identity certificate managed in Client SDK including user manually selected and regardless the source of the identity cert.
When the client certificate passes this interval, Client SDK will pass notification to App that certificate has expired.
If the used certificate will expire within the configured period, Client SDK will notify the App about it right after startup. Next notifications will be sent after 12 hours and it is not configurable.In every notification Client SDK provides nNumberOfDaysToExpire.
Identity Cert Revocation Error:
- Server will check the identity cert revocation.
- Client SDK will receive error from server, and Client SDK will pass this error as IDENTITY_REVOKED_CERTIFICATE to client app.
- User will need to take the action and select a new identity cert.
Client Identity failure codes: (Check from Binding layer perspective - if we can provide API link)
IDENTITY_NO_CERTIFICATE: The server rejected the request due to a missing client identity certificate.
IDENTITY_BAD_CERTIFICATE: The server rejected the request due to the identity certificate being corrupt, not having got verified correctly, etc.
IDENTITY_UNSUPPORTED_CERTIFICATE: The server rejected the request due to the identity certificate being of an unsupported type.
IDENTITY_REVOKED_CERTIFICATE: The server rejected the request due to the identity certificate being revoked by its signer.
IDENTITY_EXPIRED_CERTIFICATE: The server rejected the request due to the identity certificate being expired or not yet valid.
IDENTITY_UNKNOWN_CA: The server rejected the request due to the identity certificate being issued by an unknown certificate authority.
INVALID_IDENTITY_CERTIFICATE: Client identity certificate is rejected by the server.
Passing the Identity Certificate Chain
The following code snippet demonstrates how to pass the Certificate Chain to the Client SDK by using CertificateManager.
// Retrieve the client certificate chain from the key store or a keychain
// for the given alias.
List certificateChain =
new List(KeyChain.GetCertificateChain(mContext, alias));
// Retrive an associated RSA private key
AsymmetricAlgorithm PrivateKey = KeyChain.GetPrivateKey(mContext, alias);
// Set both client certificate chain and the private key.
// Catch exceptions in case of errors.
client.CertificateManager.SetClientIdentityCertificateChain(
clientCertificateChain,
privateKey);
// Client certificate has been successfully provisioned.
How to view / retrieve certificates
Use fields of the CertificateManager to obtain Certificate Chain and RSA private key used by the Client SDK.
// Retrieve a complete client certificate chain.
List clientCertificateChain =
client.CertificateManager.ClientIdentityCertificateChain.ToList();
// Retrieve the private key.
AsymmetricAlgorithm privateKey =
client.CertificateManager.ClientIdentityPrivateKey;
Certificate Expiration Notification and Renewal
You can register your application to receive expiration notifications.
Optionally use the SecurityPolicyConfiguration object to specify the percentage value (of client identity certificate's age) after which the certificate status notifications are issued.
// Create and initialise the Security Policy Configuration
// to use the Private Trust Store.
SecurityPolicyConfiguration securityPolicyConfiguration =
new SecurityPolicyConfiguration();
securityPolicyConfiguration.CertificateRenewalValue = 90;
// Instantiate an application delegate
AppCertificateExpiryDelegate certificateExpiryDelegate =
new AppCertificateExpiryDelegate();
// Set the CertificateExpiryNotification event handler
client.CertificateManager.CertificateExpiryNotification +=
new EventHandler(
certificateExpiryDelegate.onCertificateExpiry);
The Client SDK will notify your application event handler when the identity certificate approaches expiration.
class AppCertificateExpiryDelegate {
void onCertificateExpiry(object sender, CertificateExpiryEventArgs e)
{
// Add your code here. Use the e.NumberOfDaysToExpire and e.Certificate
// fields to provide warning to your user
}
}
Certificate Removal
- Stored certificates should be removed when the user configuration is reset to manufacturer default or application is uninstalled.
- When user selects a new identity cert, the old one shall be removed because only one client identity certificate is supported.
// Remove the certificate status event handler
client.CertificateManager.CertificateExpiryNotification -=
new EventHandler(
certificateExpiryDelegate.onCertificateExpiry);
// Delete the client certificate and a private key.
client.CertificateManager.DeleteClientIdentityCertificateChain();
Simple Certificate Enrollment Protocol (SCEP) Support
The Client SDK support SCEP to retrieve Identity Certificates.
Create the ScepConfiguration object and pass it to the Enroll() method of the CertificateManager object.
ScepConfiguration scepConfiguration = new ScepConfiguration();
// Populate scepConfiguration details.
EnrollmentCredentialProvider enrollmentCredentialProvider = new EnrollmentCredentialProvider(scepConfiguration.CertificateCommonName, scepConfiguration.ChallengePassword);
client.CertificateManager.Enroll(scepConfiguration, enrollmentCredentialProvider,
(chain, privateKey, result) =>
{
// Enroll completion handler
});
