Credential Manager Library

The Credential Management API provides an interface to use the Credential Manager service, which supports password-based and certificate-based credentials.

The Credential Manager improves the user experience by:
  • Providing a consistent and informative UI for credential dialogs
  • Reducing the frequency of login prompts
The Credential Manager improves app security by:
  • Providing app developers with tools to integrate strong authentication
  • Enforcing secure management of credentials
The Credential Management API includes:
  • Store API, used for finding and saving credentials
  • Authentication API, used for defining credential authentication scopes and reporting authentication status
  • Password Credential API, used for managing password-based credentials
  • Certificate Credential API, used for managing certificate-based credentials
  • Kerberos API, used for managing Kerberos-based tickets

Terminology

The following terms are used throughout the Credential Management API:

Credentials – Credentials are used as proof of identity for a user or an app. The Credential Management API supports password-based and certificate-based credentials.

Credential Store – A credential store is a management container for credentials. A separate credential store is maintained for each BlackBerry Balance perimeter.

Authentication Scope – An authentication scope is a description of service endpoints where a particular credential can be used. Two examples of service endpoints are the URL of a login page for a website, and the hostname of a network server.

Creating credentials

You can use the Store API to create credentials either implicitly or explicitly.

Implicitly

Use a credentials query to implicitly create credentials when your app doesn't need to import existing credentials. You can configure a query to create new credentials if no existing credentials match the query. If necessary, the user will be prompted to enter the new credentials. The new credentials are automatically associated with the authentication scope that was used to create the credential query. See "Searching for credentials" section below for more information.

Explictly

Alternatively, you can use the Store API to explicitly create credentials when your app has existing credentials it needs to migrate or has its own credentials UI. You can use the Store API to create a new credential and associate it with any number of authentication scopes.

Note: Currently, only password-based credentials can be created using the Store API.
  1. Create a structure representing the credential using credential_pwd_create()
  2. Create an authentication scope using credential_net_auth_scope_create_from_server() or credential_net_auth_scope_create_from_url()
    • If required, call credential_net_auth_scope_add_server() to add more services to the authentication scope
  3. Associate the authentication scope with the credential using credential_add_auth_scope()

Searching for credentials

The following steps illustrate the steps taken when you execute a credentials query:

  1. Create an authentication scope that represents the service that initiated the authentication challenge. The scope can be created using credential_net_auth_scope_create_from_server() or credential_net_auth_scope_create_from_url().

    Note that:
    • You should not use the ANY flag or set multiple flags when specifying the network protocol, authentication scheme, or host type.
    • You should not add any additional services to the authentication scope using credential_net_auth_scope_add_server()
  2. Create a credential query from the authentication scope by calling credential_query_create_from_auth_scope().
  3. Set any additional query parameters. By default:
    • The query includes all credential types. Use credential_query_set_cred_type() to limit the query to a specific credential type (for example, CREDENTIAL_TYPE_PASSWORD_CRED for password-based credentials).
    • The query includes credentials with any owner type. Use credential_query_set_owner_type() to limit the query to a specific owner type (for example, CREDENTIAL_OWNER_TYPE_ENTERPRISE for enterprise-provisioned credentials).
    • The query disables all user prompts and returns all the credentials found. You can enable specific user prompts by calling credential_query_set_user_prompt_policy() and setting the prompt policy mask.

      For example:

      • Include the CREDENTIAL_USER_PROMPT_POLICY_ALLOW_RESOLVE flag to limit the query result to the best match.
      • Include the CREDENTIAL_USER_PROMPT_POLICY_ALLOW_SOLICIT flag to prompt the user for new credentials when no existing credentials are found.
      • Include the CREDENTIAL_USER_PROMPT_POLICY_ALLOW_VERIFY flag to be prompt the user to re-enter credentials when existing credentials failed the previous authentication attempt. This logic is only triggered when the query finds exactly one set of matching credentials. It is recommended that you use this flag in conjunction with CREDENTIAL_USER_PROMPT_POLICY_ALLOW_RESOLVE.
  4. Execute the credential query by calling credential_find().
  5. Retrieve the status of the query by calling credential_query_result_get_status(). A status of CREDENTIAL_QUERY_STATUS_OK indicates that the credential query completed. Otherwise, the query was either canceled by the user from a credential prompt or it was canceled by the Credential Manager based on user preferences.
  6. Access the returned credentials. You can do this in one of two ways:
    1. If you expect at most one credential, use credential_query_result_get_first(). Note, this function will return a NULL item if no results were found.
    2. If you expect more than one credential, use credential_query_result_get_iterator() to retrieve an iterator for the credentials.
    Note: You should use not call credential_release() to release the memory for credentials as both credential_query_result_get_first() and credential_query_result_get_iterator() functions use memory allocated for query result.

Integration with the protocol stack

The Credential Manager service integrates with the cURL and GSSAPI protocol APIs.

cURL

To configure cURL to use a credential from the Credential Manager service:
  1. Convert the credential to an opaque handle by calling credential_to_handle_string()
  2. Set the handle as a security credential in cURL using curl_easy_setopt()
    • To set a credential for authentication with a server, use the CURLOPT_QNX_CREDMGR_HANDLE option flag.
    • To set a credential for authentication with a proxy, use the CURLOPT_QNX_PROXY_CREDMGR_HANDLE option flag.
  3. Call credential_util_free() to release the memory for the handle when you are done.

GSSAPI

To convert a credential from the Credential Manager service into a GSSAPI representation:
  1. Convert the credential to an opaque handle by calling credential_to_handle_string()
  2. Call gss_import_name() to convert the credential handle into a GSSAPI name. Set the input name type OID to GSS_C_NT_QNX_CREDMGR_HANDLE.
  3. Call gss_acquire_cred() to create a GSS credential using the handle name imported in the previous step.
  4. Call credential_util_free() to release the memory for the handle when you are done.