blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Classes | Enumerations | Variables

Certificate Credential Import

Classes

Enumerations

Variables


Detailed Description

Use this programming interface to import electronic certificate credentials into the secure store. Imported credentials are managed within the User Credentials Profiles configuration.

User Credentials Profiles

The BlackBerry Dynamics runtime synchronizes User Credential Profile (UCP) configuration from the enterprise management console.

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.

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

Succesful 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.

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.

See also:
GDPKICertificate for a related interface.

Typedef Documentation

typedef void(* GDCredentialsProfileEventCb)(const struct GDCredentialsProfileEvent event, void *appData)

Pass a pointer to a function of this type as the cb parameter to the GDCredentialsProfile_register function.

The callback will be invoked when a User Credentials Profile (UCP) changes state. See below for the invocation parameters.

If multiple UCP state changes occur, the callback is invoked sequentially for each. Invocation can take place on any thread except the user interface thread. The callback should return immediately. If handling of a state change requires user interaction or lengthy processing, that should be scheduled. It shouldn't be executed synchronously in the callback itself.

Parameters:
eventGDCredentialsProfileEvent structure representing the UCP and the state change.
The data in the structure is only valid within the scope of this callback invocation. The implementation must copy any data that will be used outside the scope of the callback.
appDatavoid * pointer to the appData that was passed in the original GDCredentialsProfile_register call.

Enumeration Type Documentation

Values in this enumeration represent the possible states of a User Credentials Profile (UCP). The state element in a GDCredentialsProfile structure always takes one of these values, including the structure in a GDCredentialsProfileEvent dispatched to the application.

Enumerator:
GDCredentialsProfileStateImportDue 

Import of credentials is required.

This state can arise, for example, because:

  • The profile has recently been assigned to the user's account and credentials haven't yet been imported for it.
  • The credentials that were imported for the profile have expired.

The application should initiate import of credentials for the profile.

See also:
GDCredential_import
GDCredentialsProfileStateImportNow 

Another application has requested credentials.

This state arises when another application is requesting credentials, but they aren't yet available in the BlackBerry Dynamics secure store of this application. This could be for one of the following reasons, for example.

  • The user didn't complete the import of credentials at activation time.
  • The profile has recently been assigned to the user's account.

The user interface will have flipped to this application, which should initiate import of credentials for the profile straight away.

See also:
GDCredential_import
GDCredentialsProfileStateImported 

All credentials have been imported.

The application needn't take any action in this state.

GDCredentialsProfileStateModified 

The profile has been modified since credentials were imported.

For example, the display name of the profile has been changed. If the application displays the details of the profile to the user, then the display should be updated.

See also:
GDCredentialsProfile
GDCredentialsProfileStateRenewalDue 

Credentials will soon expire.

The application should initiate renewal of credentials for the profile when it is convenient to do so.

If renewal isn't initiated, the credentials will expire and the profile will become due for import. See the GDCredentialsProfileStateImportDue state, above.

GDCredentialsProfileStateDeleted 

Profile removed.

This state arises if the profile has been deleted or detached from the end user in the management console. If the application displays the details of the profile to the user, then the display should be updated.

See also:
GDCredentialsProfile

Function Documentation

bool GDCredential_import ( char **  profileId,
const struct GDData credential,
const char *  password,
struct GDError error 
)

Call this function to import credentials from a PKCS #12 file into the secure store.

The file must contain the leaf certificate, also known as the user certificate, and its matching private key. In addition, it may also contain auxiliary or intermediate certificates. The file mustn't contain multiple keys, nor any inapplicable certificates.

The credential will be associated with a User Credentials Profile (UCP) from the managment console. An identifier for the associated UCP will be returned by this function. The mechanism of return is the overwriting of a pointer that the application provides, in the profileId parameter, see below. The identifier can be compared to the id element of a GDCredentialsProfile instance.

If import fails, then this function returns false and writes a GDError structure into the location supplied in the error parameter, see below. The code value of the structure will be set according to the error condition, as follows.

  • GDErrorInvalidArgument if any input parameter has a wrong value, for example if the profileId pointer isn't NULL, or the credential data is NULL or zero length.
  • GDErrorNotMapped if the credential doesn't match the mapping criteria specified in any UCP that is assigned to the end user in the management console.
  • GDErrorWrongPassword if the PKCS #12 file couldn't be decrypted with the specified password.
  • GDErrorNotAllowed if the PKCS #12 file doesn't comply with the enterprise policy settings that apply to the end user. For example, the certificate file's encryption doesn't comply with the Federal Information Processing Standard (FIPS), if this is required by policy.
  • GDErrorGeneral for other conditions, such as the PKCS #12 file being corrupt, or missing the leaf certificate or private key.

After calling this function:

After finalization, the BlackBerry Dynamics runtime will:

  • Use the credentials in the application that imported them.
  • Share the credentials with other BlackBerry Dynamics applications activated by the same end user on the same device, if permitted by policy.
  • Enable management of the credentials in the enterprise BlackBerry Dynamics management console.
Parameters:
profileIdLocation of a pointer to char, i.e a pointer to a pointer. If the profile type is "localCertProvider", the pointer must be initialized to NULL by the caller, and the location will be overwritten with a pointer to a C string containing the identifier of the UCP with which the imported credentials are associated.
The C string will have been allocated by a malloc() function and must be released by the application code, by calling a free() function.
If the profile type is "localCertProvider2", the caller must must initialize the pointer with a C string containing the identifier of the UCP with which the imported credentials are to be associated.
credentialGDData containing the PKCS #12 file to be imported.
passwordNull-terminated string containing the password of the PKCS #12 file.
errorLocation of a GDError instance to be overwritten if import fails. See the error descriptions, above.
Returns:
true if import succeeded.
false otherwise.
void GDCredential_importDone ( )

Call this function to finalize import of credentials, for example after calling GDCredential_import one or more times. Also call this function if import was cancelled.

A credentials import could be in response to a request for credentials from another application. In that case, the user interface will have flipped to the importing application at the time of the request. Calling this function then causes the user interface to flip back to the requesting application.

bool GDCredential_list ( const char *  profileId,
size_t *  credentialCount,
struct GDCredential **  credentials,
struct GDError error 
)

This function returns the list of available credentials for a specified User Credentials Profile (UCP). The list will include credentials that have been imported or are otherwise available. The list can be empty, if there are no credentials available for the specified UCP.

This function returns the list, or an error code, by overwriting a number of memory locations supplied as parameters, see below.

Note the following about the returned list.

  • The list will be returned in a buffer containing a sequence of GDCredential structures, each corresponding to a credential, if any credentials are available.
  • The buffer containing the list must be released by the application code, by calling the GDCredential_free function, below.
  • If no credentials are available, NULL will be returned instead of a buffer.

This function can fail, in which case it returns false and writes a GDError structure into the location supplied in the error parameter, see below. The code value of the structure will be set according to the error condition, as follows.

  • GDErrorInvalidArgument if any input parameter has a wrong value, for example if the profileId is NULL.
  • GDErrorOutOfMemory if it wasn't possible to allocate memory for the returned list buffer, see above.
Parameters:
profileIdNull-terminated string containing the identifier of the UCP.
credentialCountLocation of a size_t that will be overwritten with the number of available credentials, which could be zero.
credentialsLocation of a pointer to GDCredential, i.e. a pointer to a pointer. The pointer must be initialized to NULL by the caller. The location will be overwritten with a pointer to a buffer containing the returned list of credentials, if any, see above.
errorLocation of a GDError instance to be overwritten if the function fails. See the error descriptions, above.
Returns:
true if a list was returned, or if there are no credentials available to the specified UCP.
false if an error was encountered.
void GDCredential_free ( struct GDCredential credentials,
size_t  credentialCount 
)

Call this function to release a credentials list buffer returned by the GDCredential_list function.

Parameters:
credentialsBuffer to release.
credentialCountsize_t representation of the number of structures in the buffer.
void GDCredentialsProfile_register ( GDCredentialsProfileEventCb  cb,
void *  appData 
)

Call this function to register a callback for notification of User Credentials Profile (UCP) state changes. If the application makes use of the credential importing feature, then a callback should be registered immediately after BlackBerry Dynamics authorization processing has completed.

The application will be notified when any UCP changes state. See the GDCredentialsProfileState reference documentation for descriptions of the different UCP states. Each UCP state change is notified exactly once.

UCP state changes can occur at any time that the application is running, including prior to registration of the callback. In the case that a backlog of state changes has accumulated prior to registration of a callback, the last state change for each UCP will be notified at the point of registration.

Additional application data can be passed to this function. This data will then be conveyed to the callback invocation, but is otherwise opaque to the BlackBerry Dynamics runtime.

Parameters:
cbGDCredentialsProfileEventCb implementation for the callback.
appDatavoid* pointer to the application data for the callback.
bool GDCredentialsProfile_list ( size_t *  profileCount,
struct GDCredentialsProfile **  profiles,
struct GDError error 
)

This function returns a list of User Credentials Profiles that are assigned to the current end user. Assignment will have been made in the enterprise BlackBerry Dynamics management console. The list can be empty, if there is no User Credentials Profile (UCP) assigned to the end user.

This function returns the list, or an error code, by overwriting a number of memory locations supplied as parameters, see below.

Note the following about the returned list.

  • The list will be returned in a buffer containing a sequence of GDCredentialsProfile structures, each corresponding to a UCP, if any profiles are available.
  • The buffer containing the list must be released by the application code, by calling the GDCredentialsProfile_free function, below.
  • If no profiles are available, NULL will be returned instead of a buffer.

This function can fail, in which case it returns false and writes a GDError structure into the location supplied in the error parameter, see below. The code value of the structure will be set according to the error condition, as follows.

  • GDErrorInvalidArgument if any input parameter has a wrong value, for example if profiles is NULL.
  • GDErrorOutOfMemory if it wasn't possible to allocate memory for the returned list buffer, see above.
  • GDErrorGeneral if it isn't possible to provide a list of profiles at the time this function was called.
Parameters:
profileCountLocation of a size_t that will be overwritten with the number of profiles, which could be zero.
profilesLocation of a pointer to GDCredentialsProfile, i.e. a pointer to a pointer. The pointer must be initialized to NULL by the caller. The location will be overwritten with a pointer to a buffer containing the returned list of profiles, if any, see above.
errorLocation of a GDError instance to be overwritten if the function fails. See the error descriptions, above.
Returns:
true if a list was returned, or if there are no profiles assigned to the current end user.
false if an error was encountered.
void GDCredentialsProfile_free ( struct GDCredentialsProfile profiles,
size_t  profileCount 
)

Call this function to release a profiles list buffer returned by the GDCredentialsProfile_list function.

Parameters:
profilesBuffer to release.
profileCountsize_t representation of the number of structures in the buffer.
void GDCredentialsProfile_unregister ( )

Call this function to cancel notification of User Credentials Profile (UCP) state changes. State changes that occur after cancellation may not be notified ever.

See also:
GDCredentialsProfile_register

Variable Documentation

const int32_t GDSuccess

No error occurred.

const int32_t GDErrorOutOfMemory

Memory allocation for results failed.

const int32_t GDErrorNotAuthorized

BlackBerry Dynamics authorization processing isn't complete.

const int32_t GDErrorNotFound

Profile not found.

const int32_t GDErrorNotMapped

Credential doesn't match the mapping criteria specified in any User Credential Profile that is assigned to the end user in the management console.

const int32_t GDErrorWrongPassword

Encrypted file couldn't be decrypted with the specified password.

const int32_t GDErrorGeneral

Error condition not covered by specific codes.

const int32_t GDErrorInvalidArgument

Input parameter has a wrong value.

const int32_t GDErrorNotAllowed

Certificate couldn't be imported because it doesn't comply with the enterprise policy settings that apply to the end user. For example, the certificate file's encryption doesn't comply with the Federal Information Processing Standard (FIPS), if this is required by policy.