• BlackBerry Dynamics
  • Runtime library for Android applications
  • 9.1.0.122
Package com.good.gd.pki

Public Key Infrastructure Integration. More...

Description

BlackBerry Dynamics can be integrated into a public key infrastructure (PKI) implementation. BlackBerry Dynamics has a number of capabilities for handling the X.509 public key certificates that would be associated with an end user within an enterprise PKI implementation.

Certificate Store Notifications

The BlackBerry Dynamics runtime maintains a secure certificate store on the device. The application code can be notified when certificates are added to, and removed from, the secure certificate store.

The typical usage of the notification interface is as follows.

  1. The application code creates a listener class that implements the CertificateListener interface, and registers an instance with the BlackBerry Dynamics runtime CertificateHandler.
    1. When the BlackBerry Dynamics runtime adds an X.509 certificate to its store, a notification is dispatched to the listener. The notification includes a reference to an object that represents the certificate.
  2. The application code in the listener extracts the certificate object from the notification.
  3. The application code can read the object properties to determine the characteristics of the certificate.

Certificate Listener

private void addCertificateListener() {
CertificateListener listener = new CertificateListener() {
@Override
public void onCertificatedAdded(Certificate certificate) {
Log.v("PKI", String.format(
"Certificate added. Serial Number: \"%s\".\n",
certificate.serialNumber()) );
byte[] certData = certificate.getBinaryX509DER();
javax.security.cert.X509Certificate detailedCertificate =
X509Certificate.getInstance(certData);
Log.v("PKI", String.format(
"Certificate added. Signature Algorithm:\"%s\".\n",
detailedCertificate.getSigAlgName() ));
}
@Override
public void onCertificateRemoved(Certificate certificate) {
Log.v("PKI", String.format(
"Certificate removed. Serial Number: \"%s\".\n",
certificate.serialNumber()) );
}
};
CertificateHandler.getInstance().addCertificateListener(listener);
}

The above snippet shows:

  • Creation of a certificate listener. The listener is an instance of an anonymous inner class.
  • Dummy implementation of the certificate added listener that:
    • Logs one field directly from the Certificate object.
    • Creates a native detailed certificate representation of the same object, and logs another field from it.
  • Dummy implementation of the certificate removed listener that logs one X.509 field.
  • Registration of the listener for notifications of certificate addition and removal.

See also
X509Certificate class reference on the android.com developer website.

User Credentials Profiles

The BlackBerry Dynamics runtime synchronizes User Credential Profile (UCP) configuration for app-based certificates from the enterprise management console.

Deprecated:
Since UEM 12.10, UCPs for app-based credentials are no longer supported. Native keystore UCPs are the recommended approach and enable the app to directly access user credentials within the device's key store without requiring importation of key material into the app.

Structure

BlackBerry Dynamics UCP configuration has the following structure.

User Credentials Profile
...
User Credentials Profile
|
|
+---- Credential
      ...
      Credential
      |
      |
      +---- User certificate
      |
      |
      +---- Auxiliary certificate
            ...
            Auxiliary certificate

The configuration can be traversed as follows.

Import

The BlackBerry Dynamics runtime has a programming interface by which credentials can be imported by the application code. The interface is session-based.

Deprecated:

Since UEM 12.10, UCPs for app-based credentials are no longer supported. Native keystore UCPs are the recommended approach and enable the app to directly access user credentials within the device's key store without requiring importation of key material into the app.

  • Start an import session by calling one of the import class methods in the Credential class.
  • Continue the session, if required, by making subsequent import calls.
  • Finish the session by calling the finalizeImport class method.

The import interface makes use of formats originally published as Public-Key Cryptography Standards (PKCS). These formats are identified by PKCS numbers.

See also
RFC 7292 PKCS #12: Personal Information Exchange Syntax on the ietf.org website.

Import Requirements

Successful use of the import interface depends on configuration at the enterprise. The end user must be activated against management console software that supports certificate import.

  • The BlackBerry Unified Endpoint Manager (UEM) server version 12.7 and later support this feature.
  • No version of the legacy Good Control server supports this feature.
See also
BlackBerry UEM Administration guide to application-based Public Key Infrastructure (PKI) connection on the help.blackberry.com website.

Profile State Changes and Import Requests

The state of a UCP, and the UCP configuration, can change. When this happens, the BlackBerry Dynamics runtime notifies the application code by dispatching a UCP event.

UCP events are also used to notify the application in the case that a requirement for credentials arises in another application, that doesn't have the capability to import credentials itself.

An application that has the certificate import capability should implement a UCP event observer, as follows.

To receive notifications, register a receiver class:

When a UCP state change occurs, the BlackBerry Dynamics runtime sends an Android Intent by local broadcast. The Intent will include a Bundle that specifies the details of the change. The CredentialsProfile class includes a number of helper methods for retrieving the details. The helpers are class methods that take an Intent as a parameter and return the detail value. For example, CredentialsProfile.getId(Instance) retrieves the UCP identifier. Note that there are also methods with the same names as the helpers that take no parameters, for example getId(), but these are just normal property value accessors that are called as instance methods.

This following code snippet illustrates registration of a UCP event receiver.

GDAndroid.getInstance().registerReceiver(new BroadcastReceiver() {
// Override annotation should go here
public void onReceive(Context context, Intent intent) {
String identifier = CredentialsProfile.getId(intent);
// ...
}
}, new IntentFilter(CredentialsProfile.GD_CREDENTIAL_PROFILE_STATE_CHANGE_ACTION));

Classes

class  Certificate
 X.509 Public Key Certificate. More...
 
class  CertificateHandler
 PKI certificate management interface. More...
 
interface  CertificateListener
 Certificate listener for PKI integration. More...
 
class  Credential
 User identity credential certificate chain. More...
 
class  CredentialException
 User Credentials Profile Exception. More...
 
class  CredentialsProfile
 User Credentials Profile. More...