The biidCoreSDK can be installed into an Xcode project using CocoaPods.

Cocoapods can be installed on your machine via the terminal:

$ gem install cocoapods

CocoaPods 1.3.0+ is required to build the biidCoreSDK.

Full details on how to install cocoapods can be found here.

To integrate biidCoreSDK into your Xcode project using CocoaPods, specify it in your Podfile as follows:

source ''
platform :ios, '9.0'

target '<Your Target Name>' do
    pod 'biidCoreSDK', '3.0.181'

Then, run the following command to install the SDK and any other dependencies:

$ pod install

Manifest File

A manifest file is required to successfully initialize the biidCoreSDK. The manifest file contains metadata data such as an app key and URL endpoints, public key information and details of backoffice modifiable settings.

the Manifest file for an app can be generated and downloaded directly from the back office environment.

The manifest file should added to a build target so that it is available from within the bundle of the built app.

On initialization the SDK will check for the presence of a valid manifest file and load the settings accordingly.

Example of a manifest file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">
    <string>Company App Name</string>
    <string>-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----</string>

Modifiable Keys

The following manifest keys are modifiable in the backoffice:

  • AppName - The name of the app.

  • BundleID - The bundleID of the app.

    On initialising the SDK, the bundleID specified in the manifest and the bundleID of the app are checked. If they do not match a ClientException.appAndManifestBundleIDsDoNotMatch error is thrown.

  • AllowMultipleEntities - if true the SDK will allow certain entity specific APIs such as requestEntity, checkEntity etc. to be called. Attempting to call these APIs when this setting is set to false will result in a Client Exception.

    For further information see the Multiple Entities documentation.

  • RequiresSecureEnclave - if set to true, the SDK can only be initialised on a device that includes a Secure Enclave. On such devices the creation and storage of the private key (see certification process), and subsequent operations with it, all take place within the secureEnclave. If set to true and the device does not have a secureEnclave, a Client Exception is returned when initializing the SDK.


    Keys generated and stored in the secureEnclave are ECC (Elliptic Curve Cryptography) keys of 256 bits (equivalent to an RSA key of 3072 bits). Keys generated outside the secureEnclave are RSA keys of 2048 bits

    Use of ECC keys require a CA provider that is able to handle ECC signed Certificate Signing Requests.

    Further information about the Secure Enclave can be found in Apple’s Security Guide.

  • TouchIDRequiredForKeyAccess - if true, then any API that needs to access the generated private key (generated and stored on the device as part of the certification process) such as transaction confirmation or document signing will present an authentication dialog (second factor authentication). For further information and details on how to manage the authentication process see the TouchID Authentication section.

Non Modifiable Keys

The following appear in the manifest but are populated in the manifest automatically and therefore are can not be modified.

  • EndPoint - The end point of the API. This is used by the SDK for all Client requests.

  • PublicKey - The public key associated with this app & entity. Used in the SDK for encrypting certain request parameters.

  • PublicKeyExponent - used in the SDK for encryption.

  • PublicKeyModulus - used in the SDK for encryption.

Manifest Error handling

The following manifest related errors can be returned when loading the manifest whilst Initializing the SDK.

  • BiidManifestException.manifestNotFoundInBundle - Manifest file not found in app bundle

  • BiidManifestException.failedToLoadManifest - Manifest file could not be loaded

  • BiidManifestException.invalidChecksum - Manifest checksum failed

  • BiidManifestException.manifestKeyMissing - A required manifest key is missing from the manifest

NB The above errors are returned wrapped in a ClientException.manifestException

In addition the following client exception can be returned during initialization:

Certificate Pinning

The biid SDK implements an additional level of security through the use of Certificate Pinning (SSL Pinning). Certificate pinning ensures that the SSL certificate returned from an SSL connection exactly matches a copy of the certificate stored locally within the app.

To implement certificate pinning, a copy of the SSL certificate, for the endpoint defined in the manifest file, needs be placed in the bundle of the app.

NB The certificate can be downloaded directly from the back office environment.

During initialization, the SDK will look through the app bundle and load any certificates it finds. All subsequent network requests then check for the matching certificate and if one isn’t found, a onNoConnection error is returned (see Error Handling for further details).


It is highly recommended that certificate used for pinning is a non wild card leaf certificate for the endpoint

It is possible to include multiple certificates for the same endpoint.

Certificates should be in DER format, can have any name, but should have one of the following file extensions : .cer, .CER, .crt, .CRT, .der, .DER.

Thread safety

The biid Core SDK is completely thread safe. All SDK API calls should be executed on the main thread, leaving the SDK to manage any required asynchronous requests, threading as necessary.

All API responses are guaranteed to be returned on the main thread.

Referencing the biid Client

The biid client, and it’s APIs and properties, is accessible through the SDK’s getClient() function.

Assigning the biid client to a var can be done as follows:


    var biidClient = SDK.getClient


    id<Client>biidClient = [biidCoreSDK getClient];

    id<Client>biidClient = biidCoreSDK.getClient;

Alternatively the getClient function can be called inline if preferred:




    [biidCoreSDK.getClient xxxxxx];

NB Calling the getClient method more than once will always return the same instance.


Initializing the SDK

The SDK can be initialized as follows:


    do {
        try SDK.getClient.initialize()
    catch (let exception) {
        // Handle exception


    NSError *error;
    [biidCoreSDK.getClient initialize:&error];
    if (error) {
        // Handle error


Device InstallationID

A unique installationID for a device is required and is automatically generated for each new app installation. The current installationID can be returned as follows:


    do {
        let language = try SDK.getClient.getLanguage()
    catch (let exception) {
        // handle exception


    NSError *error;
    NSString *installationID = [biidCoreSDK.getClient getInstallationID:&error];

    if (error) {
        // handle error


On occasions it may be appropriate for the installationID to be set to a required value. This can be done as follows:


    do {
        try SDK.getClient.setInstallationID (installationID: installationID)
    catch (let exception) {
        // handle exception


    NSError *error;
    [biidCoreSDK.getClient setInstallationID:installationID error:&error];

    if (error) {
        // handle error


TouchID Authentication

If the TouchIDRequiredForKeyAccess setting is set to true in the manifest file then calling any API that accesses the private key (i.e. user certification, document signing, authentication confirmation) will result in an authentication dialog being presented to the user before the request can continue.

Internally Authentication is managed by way of a class named LAContext. A LAContext instance has a number of inherent properties, the two most important being those used for Authentication reuse and Authentication reason.

NB On devices that do not support TouchID, a Device Password dialog will be displayed instead.

Authentication Reuse

In order to provide a more user friendly user experience and to reduce the number of times a user is asked to authenticate, the SDK sets a reuse period during which authentication automatically succeeds, without prompting the user to authenticate again.

If there is a requirement to override this behaviour, that is to force the display of an authentication dialog when the private key is next accessed, this can be achieved by calling forceAuthenticationOnNextKeyAccess(:) sometime prior to the any call that may require authentication such as document signing, authentication confirmation or user certification.


    SDK.getClient.forceAuthenticationOnNextKeyAccess(withReason:"Authentication required")

    SDK.getClient.forceAuthenticationOnNextKeyAccess() // use default reason


    [biidCoreSDK.getClient forceAuthenticationOnNextKeyAccessWithReason:"Authentication required"];

    [biidCoreSDK.getClient forceAuthenticationOnNextKeyAccessWithReason:@""]; // use default reason


Authentication Reason

An authentication dialog includes text detailing the reason why authentication is required. The SDK considers this text to be a localizable string and so it is possible to localize it by creating a Localizable.strings file for each language that needs to be supported and setting the authentication-required key value accordingly:

For en localized.strings file:

"authentication-required" = "Please authenticate";

For es localized.strings file:

"authentication-required" = "Por favor autentíquese";

In addition, in iOS 11 and above, it is also possible to set the reason as an argument to the forceAuthenticationOnNextKeyAccess(:) method or directly as follows:


    let reason = NSLocalizedString("signing-authentication-reason", comment: "")
    SDK.getClient.setAuthenticationReason(to: reason)


    NSString *reason = NSLocalizedString(@"signing-authentication-reason", comment: "");
    [biidCoreSDK.getClient setAuthenticationReason:reason];


The reason set will remain until either the app is terminated or forceAuthenticationOnNextKeyAccess(:) is called resulting in the reason being reset to it’s default value.

If the authentication reuse period is still valid, no dialog will be presented regardless of setting the reason


When setting a reason, considering the following advice from Apple:

The string you present to the user should provide a clear reason for why you are requesting they authenticate themselves, and what action you will be taking based on that authentication. This string should be provided in the user’s current language and should be short and clear. It should not contain the app name, because that appears elsewhere in the authentication dialog

Language Settings

See localization for details on how to return and set the language code used for localised content.