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.

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.
The application code in the listener extracts the certificate object from the notification.
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 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.

Call the CredentialsProfile.getMap class method to get the list of profiles that are assigned to the current end user. Each is represented by a CredentialsProfile instance.
Call the getCredentials instance method to get the credentials within a particular profile. Each is represented by a Credential instance.
Call the getUserCertificate and getAuxCertificates instance methods to get the certificates associated with a particular credential. Each is represented by a Certificate instance.

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:

Instantiate a native BroadcastReceiver object.
Call the GDAndroid registerReceiver method.
- Pass a reference to the object as the receiver parameter.
- Pass an Intent Filter for GD_CREDENTIAL_PROFILE_STATE_CHANGE_ACTION as the filter parameter.

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 Credential profile. More...