Skip to main content

SDK Configuration

The overall SDK interfaces may be accessed as follows:

import com.criticalblue.approovsdk.Approov;

Note that the iOS SDK is actually written in Objective-C and the method references are described in this way. Other code examples in the documentation are in Swift, using the automatically generated bindings to the SDK methods.

Initialization​

/**
 * Initialize the Approov SDK. This must be called prior to any other methods on the Approov
 * SDK. The SDK is initialized with an application context, an initial configuration, an optional
 * update configuration, and a comment. The initial configuration is either a short initialization
 * string or a signed JWT token string that is obtained from the Approov CLI tool and contains all
 * the necessary parameters to initialize the SDK. An updated configuration may be transmitted
 * while the SDK is in use and this must be stored in the local storage of the app. If the string
 * "auto" is provided as the update configuration parameter then the SDK will manage its own update
 * configuration storage. If the comment parameter starts with "options:" then options can be
 * provided to the initialization. Typically the SDK can only be initialized once, although
 * subsequent calls with exactly the same parameters are ignored (with a return value of false
 * indicating that no change was made). If the comment starts with "reinit" then this allows the
 * SDK to be reinitialized with a different account.
 *
 * Calling this method may cause an asynchronous background fetch to be initiated. If the app
 * has been previously launched then this may perform a full resumption to fetch Approov tokens and
 * secure strings to minimize the latency when an explicit fetch is subsequently made. Otherwise
 * a fetch is only made if the InitFetch SDK configuration option has been enabled for the account.
 *
 * @param appContext is the application context to use
 * @param initialConfig is the initial configuration short init string or JWT and must be present
 * @param updateConfig is any update configuration JWT, "auto" or null if there is none
 * @param comment is an optional comment that may provide initialization/reinitialization options,
 *     or null otherwise
 * @return true if the SDK was initialized, false if it didn't need to be because it was already
 *     initialized with the same parameters
 * @throws IllegalArgumentException if provided configuration is not valid
 */
public static boolean initialize(Context appContext, String initialConfig, String updateConfig, String comment) throws IllegalArgumentException;

Configuration Fetching​

/**
  * Fetches the current configuration for the SDK. This may be the initial configuration or may
  * be a new updated configuration returned from the Approov cloud service. Such updates of the
  * configuration allow new sets of certificate pins and other configuration to be passed to
  * an app instance that is running in the field.
  *
  * Normally this method returns immediately with the latest configuration that is cached in the
  * SDK. However, if the configuration has not been refreshed at all from the Approov server since
  * the app started, then there will be a short blocking delay as an attempt will be made to fetch
  * the latest configuration from the Approov servers.
  *
  * Note that the returned configuration should generally be kept in local storage for the app
  * so that it can be made available on initialization of the Approov SDK next time the app
  * is started.
  *
  * It is possible to see if a new configuration becomes available from the isConfigChanged()
  * method of the TokenFetchResult. This changed flag is only cleared for future token fetches
  * if a call to this method is made.
  *
  * @return String representation of the configuration
  */
public static final String fetchConfig();

Pins Extraction​

/**
 * Fetches the pins from the current configuration of the SDK. This is returned as
 * as map from URL domain (hostname only) to the possible pins for that domain. If there is
 * no map entry for a domain then that indicates that the connection is not specifically
 * pinned. The type of pin requested determines the data in each of the pins. This is typically
 * the base64 encoding of the hash of some aspect of the certificate. A connection is considered
 * to be valid if any certificate in the chain presented is one with the same hash as one in
 * the array of hashes. Note that if the isForceApplyPins flag was set on the last Approov
 * token fetch then this clears the flag for future fetches as it indicates that the latest
 * pin information has been read. Pins may be returned with "*" as the domain as these represent
 * the trusted root pins of all the acceptable certificate authorities.
 * 
 * Normally this method returns immediately with the latest pins that are cached in the
 * SDK. However, if no pins are available at all then there will be a short blocking delay as an
 * attempt will be made to fetch them from the Approov servers.
 *
 * @param pinType is the type of pinning information that is required
 * @return Map from domain to the list of strings providing the pins
 */
public static final Map<String, List<String>> getPins(String pinType);

Pins JSON Extraction​

/**
 * Fetches the pins from the current configuration of the SDK. This is returned as
 * JSON which defines a map from URL domain (hostname only) to the possible pins for
 * that domain. If there is no map entry for a domain then that indicates that the connection
 * is not specifically pinned. The type of pin requested determines the data in each of the
 * pins. This is typically the base64 encoding of a hash of some aspect of the certificate.
 * A connection is considered to be valid if any certificate in the presented chain has a hash
 * that matches one in the array of hashes for the domain. Note that if the isForceApplyPins flag
 * was set on the last Approov token fetch then this clears the flag for future fetches as it
 * indicates that the latest pin information has been read. The special domain "*" may be present
 * to provide the full list of trusted root pins for all accepted certificate authorities.
 * 
 * Normally this method returns immediately with the latest pins that are cached in the
 * SDK. However, if no pins are available at all then there will be a short blocking delay as an
 * attempt will be made to fetch them from the Approov servers.
 *
 * @param pinType is the type of pinning information that is required
 * @return JSON representation of the pins
 */
public static final String getPinsJSON(String pinType);

Getting the Device ID​

/**
 * Gets the device ID used by Approov to identify the particular app installation that the SDK is running
 * in. Different Approov apps on the same device will return a different ID. The ID may be changed by an
 * uninstall and reinstall of the app.
 *
 * @return String representation of the deviceID.
 */
public static final String getDeviceID();

Getting the Installation Public Key​

/**
 * Gets the installation public key created when the app is run for the first time. The private key is used
 * to sign getInstallMessageSignature() messages and the public key may also be included in Approov
 * tokens. The key is provided base64 DER encoded in an ASN.1 format. The key is always EC using the
 * P-256 curve.
 *
 * @return installation public key has base64 DER encoded ASN.1 string
 */
public static final String getInstallPublicKey();

Development Key​

/**
 * Sets a development key on the SDK. This may provide a key indicating that
 * the app is a development version and it should pass attestation even
 * if the app is not registered or it is running on an emulator. The development
 * key value can be rotated at any point in the account if a version of the app
 * containing the development key is accidentally released. This is primarily
 * used for situations where the app package must be modified or resigned in
 * some way as part of the testing process.
 *
 * @param key is the development key value to be set, which may be null
 */
public static final void setDevKey(String key);