Approov Direct SDK Integration

import <Approov/Approov.h>

do {
    try Approov.initialize(initialConfig!, updateConfig:"auto", comment: nil)
} catch {
    NSLog("Approov initialization failed: \(error.localizedDescription)")
}

do {
    try Approov.initialize(initialConfig, updateConfig:"auto", comment:"reinit")
} catch {
    NSLog("Approov reinitialization failed: \(error.localizedDescription)")
}

let status = approovResult.status

let approovResult = Approov.fetchTokenAndWait("api.myservice.io")

if (approovResult.status == ApproovTokenFetchStatus.success) {
    let token = approovResult.token
    // proceed with the API request, adding the Approov token to the request
} else if (approovResult.status == ApproovTokenFetchStatus.unprotectedURL) ||
          (approovResult.status == ApproovTokenFetchStatus.unknownURL) ||
          (approovResult.status == ApproovTokenFetchStatus.noApproovService) {
    // proceed with the API request, but without adding an Approov token to the request
} else if (approovResult.status == ApproovTokenFetchStatus.noNetwork) ||
          (approovResult.status == ApproovTokenFetchStatus.poorNetwork) ||
          (approovResult.status == ApproovTokenFetchStatus.mitmDetected) {
    // network conditions do not allow the token fetch so allow a user initiated retry
} else {
   // unexpected error handling
}

Approov.fetchToken({ (approovResult: ApproovTokenFetchResult) in
    switch approovResult.status {
    case ApproovTokenFetchStatus.success:
         let token = approovResult.token
          // proceed with the API request, adding the Approov token to the request
    case ApproovTokenFetchStatus.unprotectedURL,
         ApproovTokenFetchStatus.unknownURL,
         ApproovTokenFetchStatus.noApproovService:
         // proceed with the API request, but without adding an Approov token to the request
    case ApproovTokenFetchStatus.noNetwork,
         ApproovTokenFetchStatus.poorNetwork,
         ApproovTokenFetchStatus.mitmDetected:
         // network conditions do not allow the token fetch so allow a user initiated retry
    default:
         // unexpected error handling
    }
}, "api.myservice.io")

let arc = approovResult.ARC

let reasons = approovResult.rejectionReasons

#import <Approov/Approov.h>

import Approov

/**
 * Initialize the Approov SDK. This must be called prior to any other methods on the Approov
 * SDK. The SDK is initialized with an initial configuration and an optional update configuration
 * and comment. The initial configuration is either a short init string or a signed JWT token
 * that is obtained from the Approov CLI tool and contains all 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 "auto" is provided as the update configuration then the SDK will manage
 * its own configuration update storage. If "auto" is used then on the very first initialization
 * a short network fetch will be attempted to get the latest update configuration if possible. If
 * "reinit" is provided for the comment then it allows the SDK to be reinitialized to change Approov
 * accounts.
 *
 * @param initialConfig is the initial configuration which is either a short init string or full JWT and must be present
 * @param updateConfig is any update configuration JWT, "auto" or nil if there is none
 * @param comment is an optional comment that may be "reinit" to force SDK reinitialization, or nil otherwise
 * @param error the reference to an error object which will be set if an error occurred
 * @return YES if the Approov framework was successfully initialized or NO otherwise
 */
+ (BOOL)initialize:(nonnull NSString *)initialConfig updateConfig:(nullable NSString *)updateConfig
    comment:(nullable NSString * )comment error:(NSError *_Nullable *_Nullable)error;

/**
 * Initialize the Approov SDK. This must be called prior to any other methods on the Approov
 * SDK. The SDK is initialized with an initial configuration and an optional update configuration
 * and comment. The initial configuration is either a short init string or a signed JWT token
 * that is obtained from the Approov CLI tool and contains all 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 "auto" is provided as the update configuration then the SDK will manage
 * its own configuration update storage. If "auto" is used then on the very first initialization
 * a short network fetch will be attempted to get the latest update configuration if possible. If
 * "reinit" is provided for the comment then it allows the SDK to be reinitialized to change Approov
 * accounts.
 *
 * @param initialConfig is the initial configuration which is either a short init string or full JWT and must be present
 * @param updateConfig is any update configuration JWT, "auto" or nil if there is none
 * @param comment is an optional comment that may be "reinit" to force SDK reinitialization, or nil otherwise
 * @param error the reference to an error object which will be set if an error occurred
 * @return YES if the Approov framework was successfully initialized or NO otherwise
 */
class func initialize(_ initialConfig: String, updateConfig: String?, comment: String?) throws

/**
 * 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 the latest configuration that is available and is cached in the
 * SDK. Thus the method will return quickly. However, if this method is called when there has
 * been no prior call to fetch an Approov token then a network request to the Approov cloud
 * service will be made to obtain any latest configuration update. The maximum timeout period
 * is set to be quite short but the caller must be aware that this delay may occur.
 *
 * 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
 * property 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 or nil if SDK not initialized
 */
+ (nullable NSString *)fetchConfig;

/**
 * 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 the latest configuration that is available and is cached in the
 * SDK. Thus the method will return quickly. However, if this method is called when there has
 * been no prior call to fetch an Approov token then a network request to the Approov cloud
 * service will be made to obtain any latest configuration update. The maximum timeout period
 * is set to be quite short but the caller must be aware that this delay may occur.
 *
 * 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
 * property 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 or nil if SDK not initialized
 */
class func fetchConfig() -> String?

/**
 * Gets the device ID used by Approov to identify the particular device that the SDK is running on. Note
 * that different Approov apps on the same device will return a different ID. Moreover, the ID may be
 * changed by an uninstall and reinstall of the app.
 *
 * @return String of device ID or nil if SDK not initialized.
 */
+ (nullable NSString *)getDeviceID;

/**
 * Gets the device ID used by Approov to identify the particular device that the SDK is running on. Note
 * that different Approov apps on the same device will return a different ID. Moreover, the ID may be
 * changed by an uninstall and reinstall of the app.
 *
 * @return String of device ID or nil if SDK not initialized.
 */
class func getDeviceID() -> String?

/**
 * Provide access to the API-Pins information held in the current app configuration. This is a helper method that avoids
 * the need for the app to access the configuration directly. Pins of a particular type are retrieved. If the
 * SDK has not be initialized then nil is returned. A connection is considered to be valid if any certificate
 * in the chain presented has the same hash as one in the list 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. Pins may be returned with "*" as the domain as these represent the trusted
 * root pins of all the acceptable certificate authorities.
 *
 * @param pinType is the format of the pins that should be retrieved
 * @result NSDictionary mapping from domain names to a list of pins in base64 format for that domain
*/
+ (nullable NSDictionary<NSString *, NSArray<NSString *> *> *)getPins:(nonnull NSString *)pinType;

/**
 * Provide access to the API-Pins information held in the current app configuration. This is a helper method that avoids
 * the need for the app to access the configuration directly. Pins of a particular type are retrieved. If the
 * SDK has not be initialized then nil is returned. A connection is considered to be valid if any certificate
 * in the chain presented has the same hash as one in the list 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. Pins may be returned with "*" as the domain as these represent the trusted
 * root pins of all the acceptable certificate authorities.
 *
 * @param pinType is the format of the pins that should be retrieved
 * @result NSDictionary mapping from domain names to a list of pins in base64 format for that domain
*/
class func getPins(_ pinType: String) -> [String : [String]]?

/**
 * Provide access to the API pin information held in the current app configuration. This method provides the information in
 * marsahlled JSON form. Pins of a particular type are retrieved. If the SDK has not be initialized then nil is returned. 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.
 *
 * @param pinType is the format of the pins that should be retrieved
 * @result String representation of the JSON representing the pins, or nil if the SDK has not been initialized
 */
+ (nullable NSString *)getPinsJSON:(nonnull NSString *)pinType;

/**
 * Provide access to the API pin information held in the current app configuration. This method provides the information in
 * marsahlled JSON form.Pins of a particular type are retrieved. If the SDK has not be initialized then nil is returned. 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.
 *
 * @param pinType is the format of the pins that should be retrieved
 * @result String representation of the JSON representing the pins, or nil if the SDK has not been initialized
 */
class func getPinsJSON(_ pinType: String) -> String?

/*
 * Enumeration of results that may be generated as a result of an Approov fetch operation.
 */
typedef NS_ENUM(NSUInteger, ApproovTokenFetchStatus)
{
    // Indicates that a fetch successfully completed.
    ApproovTokenFetchStatusSuccess,

    // Indicates that the fetch failed because there is currently no network connectivity.
    ApproovTokenFetchStatusNoNetwork,

    // Indicates that the fetch failed because the certificate presented on the Approov endpoint was not one
    // that was expected. This might indicate the device is running on a network with a firewall that terminates TLS.
    ApproovTokenFetchStatusMITMDetected,

    // Indicates that the fetch failed due to poor network connectivity.
    ApproovTokenFetchStatusPoorNetwork,

     // Indicates that the fetch failed, perhaps because Approov services (primary and failover) are down.
    ApproovTokenFetchStatusNoApproovService,

    // Indicates that the provided domain is not in the correct format or is not of the https scheme.
    ApproovTokenFetchStatusBadURL,

    // Indicates that the URL provided is a for a domain that has not be specified in the Approov administration portal.
    // This may be an incorrect URL or may indicate that no Approov token is required for protecting this endpoint.
    ApproovTokenFetchStatusUnknownURL,

    // Indicates that no Approov token is needed for the domain. This is returned as a result of a configuration
    // that is set server side, indicating that the domain is pinned but no Approov token is required.
    ApproovTokenFetchStatusUnprotectedURL,

    // Indicates that the Approov SDK has not been initialized.
    ApproovTokenFetchStatusNotInitialized,

    // Indicates a custom JWT or secure string fetch has been rejected because Approov attestation fails.
    ApproovTokenFetchStatusRejected,

    // Indicates that a custom JWT or secure string fetch fails because the feature is not enabled.
    ApproovTokenFetchStatusDisabled,

    // Indicates an attempt to fetch a secure string that has not been defined.
    ApproovTokenFetchStatusUnknownKey,

    // Indicates an attempt to fetch a secure string with a bad key.
    ApproovTokenFetchStatusBadKey,

    // Indicates an attempt to fetch a custom JWT with a bad payload.
    ApproovTokenFetchStatusBadPayload,

    // Indicates an internal SDK error.
    ApproovTokenFetchStatusInternalError
};

/**
 * This interface is used for the result value of the fetch methods.
 */
__attribute__((visibility("default"))) @interface ApproovTokenFetchResult: NSObject

// The result code generated by a fetch operation
@property (readonly) ApproovTokenFetchStatus status;

// The last fetched token as a string which should not be cached by the app client code. This is the empty string if
// no token could be obtained.
@property (readonly, nonnull) NSString *token;

// The secure string of the last secure string fetch. This value should not be cached by the app client code. This
// may be nil if the string is not available.
@property (readonly, nullable) NSString *secureString;

// Any Attestation Response Code (ARC) providing details of the device properties. This is the empty string if
// no ARC was obtained.
@property (readonly, nonnull) NSString *ARC;

// Any rejection reasons describing why Approov attestation has failed. This is a comma separated list of
// device properties, or an empty string for a pass or if the feature is not enabled.
@property (readonly, nonnull) NSString *rejectionReasons;

// Provides a flag indicating if a new updated configuration JWT has been obtained from the server. Once set this
// remains true for subsequent token fetches until a fetchConfig() call is made.
@property (readonly) BOOL isConfigChanged;

// Provides a flag indicating if current user APIs must be updated to reflect a new version
// available from getPins(). Calling getPins() will clear this flag for the
// next Approov token fetch.
@property (readonly) BOOL isForceApplyPins;

// The measurement configuration is only provided if the last fetch operation for the domain initiated an integrity
// measurement, and the fetch was successful. This provides a binary buffer that must be provided to the
// getIntegrityMeasurementProof() or getDeviceMeasurementProof() to obtain a new proof.
@property (readonly, nullable) NSData *measurementConfig;

// ApproovTokenFetchCallback type definition
typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Gets a loggable version of the result Approov token. This provides the decoded JSON payload along with the first six
 * characters of the base64 encoded signature as an additional "sip" claim. This can be safely logged as it cannot be
 * transformed into a valid token since the full signature is not provided, but it can be subsequently checked for
 * validity if the shared secret is known, with a very high probability. The loggable token is always valid JSON. If
 * there is an error then the type is given with the key "error".
 * Note that this is not applicable to JWE tokens.
 *
 * @return Loggable Approov token string
 */
- (nonnull NSString *)loggableToken;

@end

/**
 * Gets a human readable string from an Approov token fetch status.
 *
 * @param approovTokenFetchStatus is the ApproovTokenFetchStatus
 * @return the string for the ApproovTokenFetchStatusq
 */
+ (nonnull NSString *)stringFromApproovTokenFetchStatus:(ApproovTokenFetchStatus)approovTokenFetchStatus;

/*
 * // Enumeration of results that may be generated as a result of an Approov fetch operation.
 */  
enum ApproovTokenFetchStatus {
    // Indicates that a fetch successfully completed.
    case success  

    // Indicates that the fetch failed because there is currently no network connectivity.
    case noNetwork

    // Indicates that the fetch failed because the certificate presented on the Approov endpoint was not one
    // that was expected. This might indicate the device is running on a network with a firewall that terminates TLS.
    case mitmDetected

    // Indicates that no token could be obtained due to poor network connectivity
    case poorNetwork

    // Indicates that the fetch failed, perhaps because Approov services (primary and failover) are down.
    case noApproovService

    // Indicates that the provided domain is not in the correct format or is not of the https scheme.
    case badURL

    // Indicates that the URL provided is a for a domain that has not be specified in the Approov administration portal.
    // This may be an incorrect URL or may indicate that no Approov token is required for protecting this endpoint.
    case unknownURL

    // Indicates that no Approov token is needed for the domain. This is returned as a result of a configuration
    // that is set server side, indicating that the domain is pinned but no Approov token is required.
    case unprotectedURL

    // Indicates that the Approov SDK has not been initialized.
    case notInitialized

    // Indicates a custom JWT or secure string fetch has been rejected because Approov attestation fails.
    case rejected

    // Indicates that a custom JWT or secure string fetch fails because the feature is not enabled.
    case disabled

    // Indicates an attempt to fetch a secure string that has not been defined.
    case unknownKey

    // Indicates an attempt to fetch a secure string with a bad key.
    case badKey

    // Indicates an attempt to fetch a custom JWT with a bad payload.
    case badPayload

    // Indicates an internal SDK error.
    case InternalError
}

/**
 * This interface is used for the result value of the fetch methods.
 */
class ApproovTokenFetchResult: NSObject {

    // The result code generated by a fetch operation
    private(set) var status: ApproovTokenFetchStatus?

    // The last fetched token as a string which should not be cached by the app client code. This is the empty string if
    // no token could be obtained.
    private(set) var token = ""

    // The secure string of the last secure string fetch.  This value should not be cached by the app client code. This may
    // be nil if the string is not available.
    private(set) var secureString: String?

    // Any Attestation Response Code (ARC) provided details of the device properties. This is the empty string if
    // no ARC was obtained.
    private(set) var arc = ""

    // Any rejection reasons describing why Approov attestation has failed. This is a comma separated list of
    // device properties, or an empty string for a pass or if the feature is not enabled.
    private(set) var rejectionReasons = ""

    // Provides a flag indicating if a new updated configuration JWT has been obtained from the server. Once set this
    // remains true for subsequent token fetches until a fetchConfig() call is made.
    private(set) var isConfigChanged = false

    // Provides a flag indicating if current user APIs must be updated to reflect a new version
    // available from getPins() or getPinsJSON(). Calling getPins() or getPinsJSON() will clear this flag for the
    // next Approov token fetch.
    private(set) var isForceApplyPins = false

    // The measurement configuration is only provided if the last fetch operation for the domain initiated an integrity
    // measurement, and was successful. This provides a binary buffer that must be provided to the
    // getIntegrityMeasurementProof() or getDeviceMeasurementProof() to obtain a new proof.
    private(set) var measurementConfig: Data?

    /**
     * Gets a loggable version of the result Approov token. This provides the decoded JSON payload along with the first six
     * characters of the base64 encoded signature as an additional "sip" claim. This can be safely logged as it cannot be
     * transformed into a valid token since the full signature is not provided, but it can be subsequently checked for
     * validity if the shared secret is known, with a very high probability. The loggable token is always valid JSON. If
     * there is an error then the type is given with the key "error".
     * Note that this is not applicable to JWE tokens.
     *
     * @return Loggable Approov token string
     */
    func loggableToken() -> String
}

/**
 * Gets a human readable string from an Approov token fetch status.
 *
 * @param approovTokenFetchStatus is the ApproovTokenFetchStatus
 * @return the string for the ApproovTokenFetchStatus
 */
class func string(from approovTokenFetchStatus: ApproovTokenFetchStatus) -> String

/**
 * Initiates a synchronous request to obtain an Approov token and other results. If an Approov token fetch
 * has been completed previously and the tokens are unexpired then this may return the same one
 * without a need to perform a network transaction. Note though that the caller should never cache the
 * Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. Thus this method may take up to several seconds to
 * return and should not be called from a UI thread. There is also a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the high level domain of the API to which the Approov
 * token is going to be sent. Different API domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the admin portal then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param url provides the top level domain URL for which a token is being fetched
 * @return results of fetching a token
 */
+ (nonnull ApproovTokenFetchResult *)fetchApproovTokenAndWait:(nonnull NSString *)url;

/**
 * Initiates a synchronous request to obtain an Approov token and other results. If an Approov token fetch
 * has been completed previously and the tokens are unexpired then this may return the same one
 * without a need to perform a network transaction. Note though that the caller should never cache the
 * Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. Thus this method may take up to several seconds to
 * return and should not be called from a UI thread. There is also a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a URL which provides the high level domain of the API to which the Approov
 * token is going to be sent. Different API domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the admin portal then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param url provides the top level domain URL for which a token is being fetched
 * @return results of fetching a token
 */
class func fetchTokenAndWait(_ url: String) -> ApproovTokenFetchResult

typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Initiates an asynchronous request to obtain an Approov token and other results. The call returns
 * immediately and when the token is fetched (or if the request times out due to an error) then
 * a callback function is called with the result. This callback is made on a different thread. If
 * an Approov token fetch has been completed previously and the token are unexpired then this callback
 * may be very rapid without a need to perform a network transaction. Note though that the caller
 * should never cache the Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. There is a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a url which provides the high level domain of the API to which the Approov
 * token is going to be sent. Different API domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the admin portal then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param url provides the top level domain url for which a token is being fetched
 */
+ (void)fetchApproovToken:(nonnull ApproovTokenFetchCallback)callbackHandler :(nonnull NSString *)url;

typealias ApproovTokenFetchCallback = (ApproovTokenFetchResult) -> Void

/**
 * Initiates an asynchronous request to obtain an Approov token and other results. The call returns
 * immediately and when the token is fetched (or if the request times out due to an error) then
 * a callback function is called with the result. This callback is made on a different thread. If
 * an Approov token fetch has been completed previously and the token are unexpired then this callback
 * may be very rapid without a need to perform a network transaction. Note though that the caller
 * should never cache the Approov token as it may become invalidated at any point.
 *
 * If a new Approov token is required then a more extensive app measurement is performed that involves
 * communicating with the Approov cloud service. There is a chance that due to poor network
 * connectivity or other factors an Approov token cannot be obtained, and this is reflected in the
 * returned status.
 *
 * All calls must provide a url which provides the high level domain of the API to which the Approov
 * token is going to be sent. Different API domains will have different Approov tokens associated with
 * them so it is important that the Approov token is only sent to requests for that domain. If the
 * domain has not been configured in the admin portal then an error is obtained. Note that the provided
 * URL may be suffixed by "?measurement" to initiate a measurement process for use with integrity and
 * device proofs.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param url provides the top level domain url for which a token is being fetched
 */
class func fetchToken(_ callbackHandler: ApproovTokenFetchCallback, _ url: String)

/**
 * Initiates a synchronous request to obtain, or update, a string held securely by the SDK. The
 * call only returns when the secure string has been obtained (or if the request times out due to
 * an error, or if the request is rejected). This provides the secure string value. It is also
 * possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the
 * string entry. Note that after an initial fetch secure strings will be available for some period
 * until they expire, with no latency for a network operation. If the string is not defined then
 * the UnknownKey error status is returned. If the attestation process fails then the error status
 * Rejected is returned. If the provided key is invalid then a BadKey status is returned. Finally,
 * if the feature is not enabled then the Disabled status is returned.
 *
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 * @return results of fetching the secure string
 */
+ (nonnull ApproovTokenFetchResult *)fetchSecureStringAndWait:(nonnull NSString *)key :(nullable NSString *)newDef;

/**
 * Initiates a synchronous request to obtain, or update, a string held securely by the SDK. The
 * call only returns when the secure string has been obtained (or if the request times out due to
 * an error, or if the request is rejected). This provides the secure string value. It is also
 * possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the
 * string entry. Note that after an initial fetch secure strings will be available for some period
 * until they expire, with no latency for a network operation. If the string is not defined then
 * the UnknownKey error status is returned. If the attestation process fails then the error status
 * Rejected is returned. If the provided key is invalid then a BadKey status is returned. Finally,
 * if the feature is not enabled then the Disabled status is returned.
 *
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 * @return results of fetching the secure string
 */
class func fetchSecureStringAndWait(_ key: String, _ newDef: string) -> ApproovTokenFetchResult

typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Initiates an asynchronous request to obtain, or update, a string held securely by the SDK. The call
 * returns immediately. After the secure string is fetched (or if the request times out due to an
 * error, or if the request is rejected), then a callback method is called on the supplied interface
 * instance object. This callback is made on a different thread. This provides the secure string value.
 * It is also possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the string entry.
 * Note that after an initial fetch secure strings will be available for some period until they expire, with
 * no latency for a network operation. If the string is not defined then the UnknownKey error status
 * is returned. If the attestation process fails then the error status Rejected is returned. If the provided
 * key is invalid then a BadKey status is returned. Finally, if the feature is not enabled then the Disabled
 * status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 */
+ (void)fetchSecureString:(nonnull ApproovTokenFetchCallback)callbackHandler :(nonnull NSString *)key :(nullable NSString *)newDef;

typealias ApproovTokenFetchCallback = (ApproovTokenFetchResult) -> Void

/**
 * Initiates an asynchronous request to obtain, or update, a string held securely by the SDK. The call
 * returns immediately. After the secure string is fetched (or if the request times out due to an
 * error, or if the request is rejected), then a callback method is called on the supplied interface
 * instance object. This callback is made on a different thread. This provides the secure string value.
 * It is also possible to update the secure string value by providing a new definition. In this case the
 * new value is returned as the secure string. Use of an empty string for newDef removes the string entry.
 * Note that after an initial fetch secure strings will be available for some period until they expire, with
 * no latency for a network operation. If the string is not defined then the UnknownKey error status
 * is returned. If the attestation process fails then the error status Rejected is returned. If the provided
 * key is invalid then a BadKey status is returned. Finally, if the feature is not enabled then the Disabled
 * status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param key is the name of the key (max 64 characters) that the secure string is held against
 * @param newDef is any new definition for the secure string, or nil otherwise
 */
class func fetchSecureString(_ callbackHandler: ApproovTokenFetchCallback, _ key: String, _ newDef: String)

/**
 * Initiates a synchronous request to obtain a custom JWT with the given payload. The call only
 * returns when the custom JWT has been obtained (or if the request times out due to an error, or
 * if the request is rejected). The payload must be valid JSON or else a BadPayload error status
 * is returned. If the attestation process fails then the error status Rejected is returned.
 * Finally, if the feature is not enabled then the Disabled status is returned.
 *
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 * @return results of fetching a token
 */
+ (nonnull ApproovTokenFetchResult *)fetchCustomJWTAndWait:(nonnull NSString *)payload;

/**
 * Initiates a synchronous request to obtain a custom JWT with the given payload. The call only
 * returns when the custom JWT has been obtained (or if the request times out due to an error, or
 * if the request is rejected). The payload must be valid JSON or else a BadPayload error status
 * is returned. If the attestation process fails then the error status Rejected is returned. Finally,
 * if the feature is not enabled then the Disabled status is returned.
 *
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 * @return results of fetching a token
 */
class func fetchCustomJWTAndWait(_ payload: String) -> ApproovTokenFetchResult

typedef void (^ApproovTokenFetchCallback)(ApproovTokenFetchResult *_Nonnull result);

/**
 * Initiates an asynchronous request to obtain a custom JWT with the given payload. The call returns
 * immediately. After the token is fetched (or if the request times out due to an error, or if the
 * request is rejected) then a callback method is called on the supplied interface instance object.
 * This callback is made on a different thread. The payload must be valid JSON or else a BadPayload
 * error status is returned. If the attestation process fails then the error status Rejected is
 * returned. Finally, if the feature is not enabled then the Disabled status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 */
+ (void)fetchCustomJWT:(nonnull ApproovTokenFetchCallback)callbackHandler :(nonnull NSString *)payload;

typealias ApproovTokenFetchCallback = (ApproovTokenFetchResult) -> Void

/**
 * Initiates an asynchronous request to obtain a custom JWT with the given payload. The call returns
 * immediately. After the token is fetched (or if the request times out due to an error, or if the
 * request is rejected) then a callback method is called on the supplied interface instance object.
 * This callback is made on a different thread. The payload must be valid JSON or else a BadPayload
 * error status is returned. If the attestation process fails then the error status Rejected is
 * returned. Finally, if the feature is not enabled then the Disabled status is returned.
 *
 * @param callbackHandler is a function that takes an ApproovTokenFetchResult when the token is obtained
 * @param payload provide marshaled JSON to be included in the custom JWT to be fetched
 */
class func fetchCustomJWT(_ callbackHandler: ApproovTokenFetchCallback, _ payload: String)

/**
 * Sets a development key on the SDK. This may be used to force a build of the app
 * to always pass attestation, even if the app itself is not registered or it is
 * being run on a simulator. This is to allow testing when the app might have to
 * be resigned to run on a particular test environment and the signing certificate
 * is either not known or not easily accessible. The development key is defined at
 * the account level and can be changed at any point.
 *
 * @param key is the development key to be set, which may be nil
 */
+ (void)setDevKey:(nullable NSString *)key;

/**
 * Sets a development key on the SDK. This may be used to force a build of the app
 * to always pass attestation, even if the app itself is not registered or it is
 * being run on a simulator. This is to allow testing when the app might have to
 * be resigned to run on a particular test environment and the signing certificate
 * is either not known or not easily accessible. The development key is defined at
 * the account level and can be changed at any point.
 *
 * @param key is the development key to be set, which may be nil
 */
class func setDevKey(_ key: String)

/**
 * Sets a hash of the given data value in the 'pay' claim of any subsequent Approov token
 * fetch. If the data value is also transmitted to your API backend, along with the Approov
 * token, then this allows the backend to check that the data value was indeed known to the
 * app at the time of the token fetch and hasn't been spoofed. If the provided data is the
 * same as the one from the previous call to this method, then the current tokens held by
 * the SDK do not need to be updated. Otherwise the next token fetch call will cause a new
 * attestation to fetch a new token. Note that this should not be done frequently due to
 * the additional latency on token fetching that will be caused. The hash appears in the
 * 'pay' claim of the Approov token as a base64 encoded string of the SHA256 hash of the
 * data. Note that the data is hashed locally and never sent to the Approov cloud service.
 *
 * @param data is the data whose SHA256 hash is to be included in future Approov tokens
 */
+ (void)setDataHashInToken:(nonnull NSString *)data;

/**
 * Sets a hash of the given data value in the 'pay' claim of any subsequent Approov token
 * fetch. If the data value is also transmitted to your API backend, along with the Approov
 * token, then this allows the backend to check that the data value was indeed known to the
 * app at the time of the token fetch and hasn't been spoofed. If the provided data is the
 * same as the one from the previous call to this method, then the current tokens held by
 * the SDK do not need to be updated. Otherwise the next token fetch call will cause a new
 * attestation to fetch a new token. Note that this should not be done frequently due to
 * the additional latency on token fetching that will be caused. The hash appears in the
 * 'pay' claim of the Approov token as a base64 encoded string of the SHA256 hash of the
 * data. Note that the data is hashed locally and never sent to the Approov cloud service.
 *
 * @param data is the data whose SHA256 hash is to be included in future Approov tokens
 */
class func setDataHashInToken(_ data: String)

/**
 * Obtains an integrity measurement proof that is used to show that the app and its
 * environment have not changed since the time of the original integrity measurement.
 * The proof does an HMAC calculation over the secret integrity measurement value which
 * is salted by a provided nonce. This proves that the SDK is able to reproduce the
 * integrity measurement value. This may return nil if the SDK has not been initialized
 * or if the parameters are in invalid.
 *
 * @param nonce is a 16-byte (128-bit) nonce value used to salt the proof HMAC
 * @param measurementConfig is the measurement configuration obtained from a previous token fetch results
 * @return 32-byte (256-bit) measurement proof value or nil if there was an error
 */
+ (nullable NSData *)getIntegrityMeasurementProof:(nonnull NSData *)nonce :(nonnull NSData *)measurementConfig

/**
 * Obtains an integrity measurement proof that is used to show that the app and its
 * environment have not changed since the time of the original integrity measurement.
 * The proof does an HMAC calculation over the secret integrity measurement value which
 * is salted by a provided nonce. This proves that the SDK is able to reproduce the
 * integrity measurement value. This may return nil if the SDK has not been initialized
 * or if the parameters are in invalid.
 *
 * @param nonce is a 16-byte (128-bit) nonce value used to salt the proof HMAC
 * @param measurementConfig is the measurement configuration obtained from a previous token fetch results
 * @return 32-byte (256-bit) measurement proof value or nil if there was an error
 */
class func getIntegrityMeasurementProof(_ nonce: Data, _ measurementConfig: Data) -> Data?

/**
 * Obtains a device measurement proof that is used to show that the device environment
 * has not changed since the time of the original integrity measurement. This allows the
 * app version, including the Approov SDK, to be updated while preserving the device
 * measurement. The proof does an HMAC calculation over the secret device measurement
 * value which is salted by a provided nonce. This proves that the SDK is able to reproduce
 * the device measurement value. This may return nil if the SDK has not been initialized
 * or if the parameters are in invalid.
 *
 * @param nonce is a 16-byte (128-bit) nonce value used to salt the proof HMAC
 * @param measurementConfig is the measurement configuration obtained from a previous token fetch results
 * @return 32-byte (256-bit) measurement proof value or nil if there was an error
 */
+ (nullable NSData *)getDeviceMeasurementProof:(nonnull NSData *)nonce :(nonnull NSData *)measurementConfig

/**
 * Obtains a device measurement proof that is used to show that the device environment
 * has not changed since the time of the original integrity measurement. This allows the
 * app version, including the Approov SDK, to be updated while preserving the device
 * measurement. The proof does an HMAC calculation over the secret device measurement
 * value which is salted by a provided nonce. This proves that the SDK is able to reproduce
 * the device measurement value. This may return nil if the SDK has not been initialized
 * or if the parameters are in invalid.
 *
 * @param nonce is a 16-byte (128-bit) nonce value used to salt the proof HMAC
 * @param measurementConfig is the measurement configuration obtained from a previous token fetch results
 * @return 32-byte (256-bit) measurement proof value or nil if there was an error
 */
class func getDeviceMeasurementProof(_ nonce: Data, _ measurementConfig: Data) -> Data?

/**
 * Gets the signature for the given message. This uses an account specific message signing key that is
 * transmitted to the SDK after a successful token fetch if the facility is enabled for the account. Note
 * that if the attestation failed then the signing key provided is actually random so that the
 * signature will be incorrect. An Approov token should always be included in the message
 * being signed and sent alongside this signature to prevent replay attacks.
 *
 * @param message is the message whose content is to be signed
 * @return base64 encoded signature of the message, or nil if no signing key is available
 */
+ (nullable NSString *)getMessageSignature:(nonnull NSString *)message;

/**
 * Gets the signature for the given message. This uses an account specific message signing key that is
 * transmitted to the SDK after a successful token fetch if the facility is enabled for the account. Note
 * that if the attestation failed then the signing key provided is actually random so that the
 * signature will be incorrect. An Approov token should always be included in the message
 * being signed and sent alongside this signature to prevent replay attacks.
 *
 * @param message is the message whose content is to be signed
 * @return base64 encoded signature of the message, or nil if no signing key is available
 */
class func getMessageSignature(_ message: String) -> String?

/**
 * Sets a user defined property on the SDK. This may provide information about the
 * app state or aspects of the environment it is running in. This has no direct
 * impact on Approov except it is visible as a property on attesting devices and
 * can be analyzed using device filters. Note that properties longer than 128
 * characters are ignored and all non ASCII characters are removed. The special
 * value "$error" may be used to mark an error condition for offline measurement
 * mismatches.
 *
 * @param property to be set, which may be nil
 */
+ (void)setUserProperty:(nullable NSString *)property;

/**
 * Sets a user defined property on the SDK. This may provide information about the
 * app state or aspects of the environment it is running in. This has no direct
 * impact on Approov except it is visible as a property on attesting devices and
 * can be analyzed using device filters. Note that properties longer than 128
 * characters are ignored and all non ASCII characters are removed. The special
 * value "$error" may be used to mark an error condition for offline measurement
 * mismatches.
 *
 * @param property to be set, which may be nil
 */
class func setUserProperty(_ property: String?)

let approovResult = Approov.fetchTokenAndWait("api.myservice.io?measurement");

if approovResult.status == ApproovTokenFetchStatus.success {
    // check that we obtained a configuration measurement (this should always be the case
    // but we check in case there has been an error)
    if approovResult.measurementConfig == nil {
        // error handling
    }

    // save the measurement configuration to local storage
    let URLs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)
    let measurementConfigURL = URLs[0].appendingPathComponent("measurement_config.bin")
    do {
        try approovResult.measurementConfig!.write(to: measurementConfigURL)
    } catch {
        // error handling
    }
}

let URLs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)
let measurementConfigURL = URLs[0].appendingPathComponent("measurement_config.bin")
var measurementConfig : Data? = nil;
do {
    measurementConfig = try Data.init(contentsOf: measurementConfigURL)
} catch {
    // error handling
}

let integrityProof = Approov.getIntegrityMeasurementProof(proofNonce, measurementConfig!)
if integrityProof == nil {
    // error handling
}