User identity credential certificate chain. More...

Description

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.

This class is used to represent user identity electronic certificate credentials that are stored in the BlackBerry Dynamics secure store.

A user identity credential:

Includes exactly one leaf certificate, also known as the user client certificate.
May include auxiliary intermediate certificates that represent the chain of trust from the leaf to a Certificate Authority (CA).

The auxiliary certificates don't include a certificate for the trusted root CA itself.

These credentials are part of the BlackBerry Dynamics app-based User Credentials Profile (UCP) configuration.

See also: com.good.gd.pki package reference for an introduction to the UCP feature.

Public Member Functions
Certificate	getUserCertificate ()
	Get the leaf certificate. More...

List< Certificate >	getAuxCertificates ()
	Get the Auxiliary intermediate certificates. More...

Static Public Member Functions
static String	importPKCS12 (byte[] pkcs12, String pkcs12Password) throws CredentialException
	Import electronic certificate credentials from a PKCS #12 file to an app-based UCP determined by BlackBerry Dynamics. More...

static void	importPKCS12 (byte[] pkcs12, String pkcs12Password, String profileId) throws CredentialException
	Import electronic certificate credentials from a PKCS #12 file to the specified app-based UCP. More...

static String	importPEM (byte[] pem, String keyPassword, String profileId) throws CredentialException
	Import an electronic certificate credential from PEM data to an app-based UCP. More...

static void	finalizeImport ()
	Finalize credential import. More...

static void	undoImport (String profileId) throws CredentialException
	Remove all credentials for a given User Credential profile. More...

static List< Credential >	getCredentials (String profileId)
	Return the credentials managed by a given User Credential profile. More...

static Credential	find (String issuer, String serial) throws CredentialException
	Find a credential. More...

static void	remove (String issuer, String serial) throws CredentialException
	Remove a credential. More...

Member Function Documentation

◆ getUserCertificate()

Certificate getUserCertificate ( )

Returns: Certificate instance for the leaf or user client certificate.

◆ getAuxCertificates()

List<Certificate> getAuxCertificates ( )

Returns: List<Certificate> for the auxiliary intermediate certificates, if present, or null otherwise.

◆ importPKCS12() [1/2]

static String importPKCS12	(	byte[]	pkcs12,
		String	pkcs12Password
	)		throws CredentialException

static

Call this method 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 method.

After calling this method:

Call it again, or call a different import method, if there are more credentials to import.
Call finalizeImport() to finalize.

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

pkcs12	`byte` array containing the PKCS #12 file to be imported.
pkcs12Password	`String` containing the password of the PKCS #12 file.

Returns: String containing the identifier of the UCP with which the credential was associated.

Exceptions

CredentialException if import fails.

◆ importPKCS12() [2/2]

static void importPKCS12	(	byte[]	pkcs12,
		String	pkcs12Password,
		String	profileId
	)		throws CredentialException

static

Call this method to import credentials from a PKCS #12 file into the secure store and specify the UCP with which the credentials are to be associated.

This method has similar semantics to the importPKCS12(byte[],String) method, above.

Parameters

pkcs12	`byte` array containing the PKCS #12 file to be imported.
pkcs12Password	`String` containing the password of the PKCS #12 file.
profileId	`String` containing the identifier of the UCP with which the imported credential is to be associated.

Exceptions

CredentialException if import fails.

◆ importPEM()

static String importPEM	(	byte[]	pem,
		String	keyPassword,
		String	profileId
	)		throws CredentialException

static

Call this method to import a credential from PEM data into the secure store and optionally specify the UCP with which the credential is to be associated. The PEM data must contain the end-user certificate and it's matching private key. It may optionally include intermediate certificates. The private key may or may not be encrypted.

Parameters

pem	`byte` array containing the PEM data to be imported.
keyPassword	`String` containing the password of the private key if encrypted, or null if not.
profileId	`String` containing the identifier of the UCP with which the imported credential is to be associated. If null, the credential will be associated with the best matching UCP.

Returns: String containing the identifier of the UCP with which the credential was associated.

Exceptions

CredentialException if import fails.

◆ finalizeImport()

static void finalizeImport ( )

static

Call this function to finalize import of credentials, for example after calling one of the import methods, above. Also call this method 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.

◆ undoImport()

static void undoImport ( String profileId ) throws CredentialException

static

Call this function to remove all credentials for a given User Credential Profile (UCP) after they have been imported. If successful, the state of the profile will change to GDCredentialsProfileStateImportDue.

Parameters

profileId String containing the identifier of the profile.

Exceptions

CredentialException if undo fails.

◆ getCredentials()

static List<Credential> getCredentials ( String profileId )

static

This method is an accessor for the credentials managed by the UCP. The list will include credentials that have been imported or are otherwise available. The list can be empty if no credentials are associated with the UCP.

Parameters

profileId String containing the identifier of the profile.

Returns: List<Credential> with an entry for each credential associated with the UCP.

◆ find()

static Credential find	(	String	issuer,
		String	serial
	)		throws CredentialException

static

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 Certificate object.

Parameters

issuer	the full domain name of the issuer.
serial	the certificate serial number.

Returns: Credential for the specified isser and serial number.

Exceptions

CredentialException if not found.

◆ remove()

static void remove	(	String	issuer,
		String	serial
	)		throws CredentialException

static

Call this function to remove a specific credential. A credential within the device keystore will not be deleted however it will no longer be used by any Dynamics application. A credentials within the Dynamics keystore will be deleted.

If no valid credentials remain the state of the profile will be reset to GDCredentialsProfileStateImportDue.

Parameters

issuer	the full domain name of the issuer.
serial	the certificate serial number.

Description

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ getUserCertificate()

◆ getAuxCertificates()

◆ importPKCS12() [1/2]

◆ importPKCS12() [2/2]

◆ importPEM()

◆ finalizeImport()

◆ undoImport()

◆ getCredentials()

◆ find()

◆ remove()