Classes | |
struct | GDX509Certificate |
X.509 Public Key Certificate. More... | |
struct | GDCredential |
struct | GDCredentialsProfile |
User Credential profile. More... | |
struct | GDCredentialsProfileEvent |
User Credential profile event. More... | |
Enumerations | |
enum | GDCredentialsProfileState { GDCredentialsProfileStateImportDue, GDCredentialsProfileStateImportNow, GDCredentialsProfileStateImported, GDCredentialsProfileStateModified, GDCredentialsProfileStateRenewalDue, GDCredentialsProfileStateDeleted } |
User Credential profile states. More... | |
Variables | |
const int32_t | GDSuccess |
Success. More... | |
const int32_t | GDErrorOutOfMemory |
Out of memory. More... | |
const int32_t | GDErrorNotAuthorized |
Not authorized. More... | |
const int32_t | GDErrorNotFound |
Not found. More... | |
const int32_t | GDErrorNotMapped |
Not mapped to a User Credential Profile. More... | |
const int32_t | GDErrorWrongPassword |
Wrong password. More... | |
const int32_t | GDErrorGeneral |
General error. More... | |
const int32_t | GDErrorInvalidArgument |
Invalid argument. More... | |
const int32_t | GDErrorNotAllowed |
Not allowed. More... | |
bool | GDCredential_import (char **profileId, const struct GDData *credential, const char *password, struct GDError *error) |
Import electronic certificate credentials from a PKCS #12 file. More... | |
bool | GDCredential_importPEM (char **profileId, const struct GDData *credential, const char *password, struct GDError *error) |
Import electronic certificate credentials from a PEM container. More... | |
void | GDCredential_importDone (void) |
Finalize credential import. More... | |
bool | GDCredential_undoImport (const char *profileId) |
Remove all credentials for a given User Credential Profile. More... | |
struct GDCredential * | GDCredential_find (const char *issuer, const char *serial) |
Find a credential. More... | |
bool | GDCredential_remove_credential (const struct GDCredential *credential) |
Remove an imported or device credential. More... | |
bool | GDCredential_remove (const char *issuer, const char *serial) |
Remove an imported or device credential. More... | |
bool | GDCredential_list (const char *profileId, size_t *credentialCount, struct GDCredential **credentials, struct GDError *error) |
List available credentials for a User Credential Profile. More... | |
void | GDCredential_free (struct GDCredential *credentials, size_t credentialCount) |
Free a returned credentials buffer. More... | |
typedef void(* | GDCredentialsProfileEventCb) (const struct GDCredentialsProfileEvent event, void *appData) |
Type for User Credential profile callback implementation. More... | |
void | GDCredentialsProfile_register (GDCredentialsProfileEventCb cb, void *appData) |
Register for notification of User Credential profile state changes. More... | |
void | GDCredentialsProfile_register_type (GDCredentialsProfileType type, GDCredentialsProfileEventCb cb, void *appData) |
Register User Credential profile. More... | |
bool | GDCredentialsProfile_is_type_registered (GDCredentialsProfileType type) |
Check if registered for a User Credential profile type. More... | |
bool | GDCredentialsProfile_list (size_t *profileCount, struct GDCredentialsProfile **profiles, struct GDError *error) |
List User Credential profiles. More... | |
int | GDCredentialsProfile_days_until_expiry (const char *profileId) |
Days until the next credential expires. More... | |
int | GDCredentialsProfile_days_until_renewal_due (const char *profileId) |
Days until the next credential is due to be renewed. More... | |
void | GDCredentialsProfile_begin_enrolment (const char *profileId) |
Begin enrolment for a User Credential profile. More... | |
void | GDCredentialsProfile_begin_enrolment_type (GDCredentialsProfileType type) |
Begin enrolment for all User Credential profiles of the same type. More... | |
bool | GDCredentialsProfile_can_reset_type (GDCredentialsProfileType type) |
Determine whether a User Credential profile of a specific type can be reset. More... | |
void | GDCredentialsProfile_reset_type (GDCredentialsProfileType type) |
Reset all the User Credential profiles of the same type. More... | |
void | GDCredentialsProfile_free (struct GDCredentialsProfile *profiles, size_t profileCount) |
Free a returned profiles buffer. More... | |
void | GDCredentialsProfile_unregister (void) |
Unregister from notification of app-based User Credential profile state changes. More... | |
void | GDCredentialsProfile_unregister_type (GDCredentialsProfileType type) |
Unregister from notification of User Credential profile state changes. More... | |
Use this programming interface to import electronic certificate credentials into the secure store. Imported credentials are managed within the User Credentials Profiles configuration.
The BlackBerry Dynamics runtime synchronizes User Credential Profile (UCP) configuration for app-based certificates from the enterprise management console.
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.
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.
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 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.
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 Credential 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.
event | GDCredentialsProfileEvent 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. |
appData | void * pointer to the appData that was passed in the original GDCredentialsProfile_register call. |
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 | Setup of credentials is required. This state can arise, for example, because:
The application may initiate setup of User Credential profiles by calling GDCredentialsProfile_begin_enrolment. In the case of app-based profiles, setup is achieved by importing the credential using GDCredential_import. |
GDCredentialsProfileStateImportNow | Another application has requested credentials. This state arises when another application is requesting app-based 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 interface will have flipped to this application, which should initiate import of credentials for the profile straight away.
|
GDCredentialsProfileStateImported | All credentials have been setup. The application needn't take any action in this state. |
GDCredentialsProfileStateModified | The profile has been modified since credentials were setup. 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.
|
GDCredentialsProfileStateRenewalDue | Credentials will soon expire. If this state arrises the application should initiate renewal of credentials for the profile when it is convenient to do so. The application may initiate renewal of User Credential profiles by calling GDCredentialsProfile_begin_enrolment. In the case of app-based profiles, renewal is achieved by importing the new credential using GDCredential_import. If renewal isn't initiated, the credentials will expire and the profile will become due for setup. See the |
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.
|
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.
profileId
pointer isn't NULL
, or the credential
data is NULL
or zero length.After calling this function:
After finalization, the BlackBerry Dynamics runtime will:
profileId | Location 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. |
credential | GDData containing the PKCS #12 file to be imported. |
password | Null-terminated string containing the password of the PKCS #12 file. |
error | Location of a GDError instance to be overwritten if import fails. See the error descriptions, above. |
true
if import succeeded. false
otherwise. bool GDCredential_importPEM | ( | char ** | profileId, |
const struct GDData * | credential, | ||
const char * | password, | ||
struct GDError * | error | ||
) |
Call this function to import credentials from a PEM format container into the secure store.
This function behaves like and returns the same error codes as GDCredential_import(). The only difference is the credential input argument is expected in PEM format instead of PKCS #12.
After calling this function:
After finalization, the BlackBerry Dynamics runtime will:
profileId | Location 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. |
credential | GDData in PEM format containing the user certificate, optional intermediates, and private key to be imported. Inapplicable certificates are ignored. |
password | Null-terminated string containing the password of the encrypted key or null if not encrypted. |
error | Location of a GDError instance to be overwritten if import fails. See the error descriptions, above. |
true
if import succeeded. false
otherwise. void GDCredential_importDone | ( | void | ) |
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_undoImport | ( | const char * | profileId | ) |
Call this function to remove all credentials for a given User Credential Profile (UCP) after they have been imported or discovered. If successful, the state of the profile will change to GDCredentialsProfileStateImportDue.
If the credentials are stored in the device's keystore, they will still remain but will no longer be used by Dynamics applications.
profileId | Null-terminated string containing the identifier of the profile. |
true
if removal succeeded. false
otherwise. struct GDCredential* GDCredential_find | ( | const char * | issuer, |
const char * | serial | ||
) |
Call this function to find a user credential with the specified issuer and serial number. The issuer and serial number is case sensitive and must be the same format as returned in a previous GDX509Certificate object.
issuer | the full domain name of the issuer. |
serial | the certificate serial number. |
GDCredential
if found. NULL
otherwise. bool GDCredential_remove_credential | ( | const struct GDCredential * | credential | ) |
Call this function to remove an imported or device credential. If the credential is stored in the device's keystore it will still remain but will no longer be used by Dynamics applications.
credential | to remove. |
true
if removal succeeded. false
otherwise. bool GDCredential_remove | ( | const char * | issuer, |
const char * | serial | ||
) |
Call this function to remove an imported or device credential. If the credential is stored in the device's keystore it will still remain but will no longer be used by Dynamics applications.
issuer | the full domain name of the issuer. |
serial | the certificate serial number. |
true
if removal succeeded. false
otherwise. 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.
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.
profileId
is NULL
.profileId | Null-terminated string containing the identifier of the UCP. |
credentialCount | Location of a size_t that will be overwritten with the number of available credentials, which could be zero. |
credentials | Location 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. |
error | Location of a GDError instance to be overwritten if the function fails. See the error descriptions, above. |
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.
credentials | Buffer to release. |
credentialCount | size_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 app-based 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 app-based 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.
cb | GDCredentialsProfileEventCb implementation for the callback. |
appData | void* pointer to the application data for the callback. |
void GDCredentialsProfile_register_type | ( | GDCredentialsProfileType | type, |
GDCredentialsProfileEventCb | cb, | ||
void * | appData | ||
) |
Call this function to register a callback for notification of User Credential profile (UCP) state changes and to retrieve the UCP during the call to GDCredentialsProfile_list().
See the GDCredentialsProfileType reference documentation for descriptions of the different UCP types.
The application will be notified when any UCP of the same family (type) 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.
type | of UCPs to register. |
cb | GDCredentialsProfileEventCb implementation for the callback. |
appData | void* pointer to the application data for the callback. |
bool GDCredentialsProfile_is_type_registered | ( | GDCredentialsProfileType | type | ) |
Call this function to check if registered for a User Credential type.
See the GDCredentialsProfileType reference documentation for descriptions of the different UCP types.
type | of UCP to check. |
true
if the specified type of profile is registered. false
if not registered. bool GDCredentialsProfile_list | ( | size_t * | profileCount, |
struct GDCredentialsProfile ** | profiles, | ||
struct GDError * | error | ||
) |
This function returns a list of User Credential 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 Credential 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.
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.
profiles
is NULL
.profileCount | Location of a size_t that will be overwritten with the number of profiles, which could be zero. |
profiles | Location 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. |
error | Location of a GDError instance to be overwritten if the function fails. See the error descriptions, above. |
true
if a list was returned, or if there are no profiles assigned to the current end user. false
if an error was encountered. int GDCredentialsProfile_days_until_expiry | ( | const char * | profileId | ) |
Call this function to calculate the number of days until the next credential expires.
profileId | Null-terminated string containing the UCP ID. |
int
days remaining before expiry. If zero, all credentials have expired. int GDCredentialsProfile_days_until_renewal_due | ( | const char * | profileId | ) |
Call this function to calculate the number of days until a valid certificate within the profile is due for renewal.
profileId | Null-terminated string containing the UCP ID. |
int
days remaining before a certificate requires renewal. If zero, all credentials are overdue. void GDCredentialsProfile_begin_enrolment | ( | const char * | profileId | ) |
Call this funtion to initiate any steps that may be required to complete a pending enrolment for the given UCP. Other pending UCPs will not be processed. The UCP may require user interaction. UCP state will change to GDCredentialsProfileStateImported upon successful completion.
profileId | Null-terminated string containing the UCP ID. |
void GDCredentialsProfile_begin_enrolment_type | ( | GDCredentialsProfileType | type | ) |
Call this funtion to initiate any steps that may be required to complete pending enrolments for the given family of UCPs. Other pending UCPs types will not be processed. The UCPs may require user interaction. UCP state will change to GDCredentialsProfileStateImported upon successful completion.
type | of UCPs to initiate setup. |
bool GDCredentialsProfile_can_reset_type | ( | GDCredentialsProfileType | type | ) |
Call this funtion to determine whether a User Credential profile (UCP) of the same family can be reset. A credential is elegible for reset if it manages one or more credentials. This function is called by the Credential Manager UI when determining whether to enable the reset menu option.
type | of UCP to query. |
bool
true if elegible for reset. void GDCredentialsProfile_reset_type | ( | GDCredentialsProfileType | type | ) |
Call this funtion to reset all User Credential profiles (UCPs) of the same family. After reset, all credentials managed by the UCP family will be deleted and their state reset to GDCredentialsProfileStateImportDue .
type | of UCPs to reset. |
void GDCredentialsProfile_free | ( | struct GDCredentialsProfile * | profiles, |
size_t | profileCount | ||
) |
Call this function to release a profiles list buffer returned by the GDCredentialsProfile_list function.
profiles | Buffer to release. |
profileCount | size_t representation of the number of structures in the buffer. |
void GDCredentialsProfile_unregister | ( | void | ) |
Call this function to cancel notification of app-based User Credential profile (UCP) state changes. State changes that occur after cancellation may not be notified ever.
void GDCredentialsProfile_unregister_type | ( | GDCredentialsProfileType | type | ) |
Call this function to cancel notification of User Credential profile (UCP) state changes of the given type. State changes that occur after cancellation may not be notified ever.
type | of UCPs to unregister. |
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.