Integration Hardening

See Installation Message Signing for setup and backend validation guidance.

Token Binding

Java

/**
 * 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
 */
public static final void setDataHashInToken(String data);

Objective-C

/**
 * 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;

Swift

/**
 * 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)

Install Attributes

Java

/**
 * Sets an install attributes token to be sent to the server and associated with this particular
 * app installation for future Approov token fetches. The token must be signed, within its
 * expiry time and bound to the correct device ID for it to be accepted by the server. This
 * provides a mechanism whereby attributes can become associated with an app installation when
 * certain actions are performed, in particular to allow the enforcement of additional frictions
 * for new app installations. Calling this method ensures that the next call to fetch an Approov
 * token will not use a cached version, so that this information can be transmitted to the server.
 *
 * @param installAttrs is the signed JWT holding the new install attributes
 */
public static final void setInstallAttrsInToken(String installAttrs);

Objective-C

/**
 * Sets an install attributes token to be sent to the server and associated with this particular
 * app installation for future Approov token fetches. The token must be signed, within its
 * expiry time and bound to the correct device ID for it to be accepted by the server. This
 * provides a mechanism whereby attributes can become associated with an app installation when
 * certain actions are performed, in particular to allow the enforcement of additional frictions
 * for new app installations. Calling this method ensures that the next call to fetch an Approov
 * token will not use a cached version, so that this information can be transmitted to the server.
 *
 * @param installAttrs is the signed JWT holding the new install attributes
 */
+ (void)setInstallAttrsInToken:(nonnull NSString *)installAttrs;

Swift

/**
 * Sets an install attributes token to be sent to the server and associated with this particular
 * app installation for future Approov token fetches. The token must be signed, within its
 * expiry time and bound to the correct device ID for it to be accepted by the server. This
 * provides a mechanism whereby attributes can become associated with an app installation when
 * certain actions are performed, in particular to allow the enforcement of additional frictions
 * for new app installations. Calling this method ensures that the next call to fetch an Approov
 * token will not use a cached version, so that this information can be transmitted to the server.
 *
 * @param installAttrs is the signed JWT holding the new install attributes
 */
class func setInstallAttrsInToken(_ installAttrs: String)

Integrity Measurement Proof

Java

/**
 * 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.
 *
 * @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
 */
public static final byte[] getIntegrityMeasurementProof(byte[] nonce, byte[] measurementConfig);

Objective-C

/**
 * 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

Swift

/**
 * 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?

Device Measurement Proof

Java

/**
 * 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.
 *
 * @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
 */
public static final byte[] getDeviceMeasurementProof(byte[] nonce, byte[] measurementConfig);

Objective-C

/**
 * 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

Swift

/**
 * 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?

Account Message Signing

Java

/**
 * Gets the account signature for the given message. When message signing is enabled for an account, this
 * method uses the message signing key that is transmitted to the SDK after each successful attestation
 * to generate the signature for the provided message. Note that if the attestation failed
 * then an invalid signing key is provided to the SDK so that the generated message signature will
 * be incorrect. An Approov token should always be included in the message being signed and must be
 * sent alongside this signature to enable the back end to correctly validate the signature.
 *
 * @param message is the message whose content is to be signed
 * @return base64 encoded signature of the message, or null if no signing key is available
 */
public static final String getAccountMessageSignature(String message);

Objective-C

/**
 * Gets the account signature for the given message. When message signing is enabled for an account, this
 * method uses the message signing key that is transmitted to the SDK after each successful attestation
 * to generate the signature for the provided message. Note that if the attestation failed
 * then an invalid signing key is provided to the SDK so that the generated message signature will
 * be incorrect. An Approov token should always be included in the message being signed and must be
 * sent alongside this signature to enable the back end to correctly validate the signature.
 *
 * @param message is the message whose content is to be signed
 * @return base64 encoded signature of the message, or null if no signing key is available
 */
+ (nullable NSString *)getAccountMessageSignature:(nonnull NSString *)message;

Swift

/**
 * Gets the account signature for the given message. When message signing is enabled for an account, this
 * method uses the message signing key that is transmitted to the SDK after each successful attestation
 * to generate the signature for the provided message. Note that if the attestation failed
 * then an invalid signing key is provided to the SDK so that the generated message signature will
 * be incorrect. An Approov token should always be included in the message being signed and must be
 * sent alongside this signature to enable the back end to correctly validate the signature.
 *
 * @param message is the message whose content is to be signed
 * @return base64 encoded signature of the message, or null if no signing key is available
 */
class func getAccountMessageSignature(_ message: String) -> String?

Installation Message Signing

Java

/**
 * Gets the installation signature for the given message. This uses a installation specific key pair for signing
 * where the private key is held securely on the device (and never leaves it) and the public key is included in
 * the Approov token for verification purposes. The signature is base64 DER encoded in ASN.1 format and is an
 * X962 signature of the SHA256 digest of the message UTF8 data provided. The key used is always ECDSA P-256.
 * Note that a valid installation signature does not mean that the device has been validly attested, and a
 * combination of a valid (and unexpired) Approov token and valid installation message signature are required to
 * verify a message. Moreover, the Approov token should always be included in the message being signed to prevent
 * replay attacks.
 *
 * @param message is the message whose content is to be installation signed
 * @return base64 encoded installation signature of the message, or null if no signing key is available
 */
public static final String getInstallMessageSignature(String message);

Objective-C

/**
 * Gets the installation signature for the given message. This uses a installation specific key pair for signing where
 * the private key is held securely on the device (and never leaves it) and the public key is included in
 * the Approov token for verification purposes. The signature is base64 DER encoded in ASN.1 format and is an
 * X962 signature of the SHA256 digest of the message UTF8 data provided. The key used is always ECDSA P-256.
 * Note that a valid installation signature does not mean that the device has been validly attested, and a combination
 * of a valid (and unexpired) Approov token and valid installation message signature are required to verify a message.
 * Moreover, the Approov token should always be included in the message being signed to prevent replay attacks.
 *
 * @param message is the message whose content is to be installation signed
 * @return base64 encoded installation signature of the message, or null if no signing key is available
 */
+ (nullable NSString *)getInstallMessageSignature:(nonnull NSString *)message;

Swift

/**
 * Gets the installation signature for the given message. This uses a installation specific key pair for signing where
 * the private key is held securely on the device (and never leaves it) and the public key is included in
 * the Approov token for verification purposes. The signature is base64 DER encoded in ASN.1 format and is an
 * X962 signature of the SHA256 digest of the message UTF8 data provided. The key used is always ECDSA P-256.
 * Note that a valid installation signature does not mean that the device has been validly attested, and a combination
 * of a valid (and unexpired) Approov token and valid installation message signature are required to verify a message.
 * Moreover, the Approov token should always be included in the message being signed to prevent replay attacks.
 *
 * @param message is the message whose content is to be installation signed
 * @return base64 encoded installation signature of the message, or null if no signing key is available
 */
class func getInstallMessageSignature(_ message: String) -> String?

Set User Property

Java

/**
 * 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 null
 */
public static final void setUserProperty(String property);

Objective-C

/**
 * 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;

Swift

/**
 * 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?)

Set Activity

Java

/**
 * Sets the information about a current activity. This may be set for an expected app
 * launch activity so that analysis can be performed to determine if the activity may have
 * been launched in an automatic way. A flag indicating this can then be included as an
 * annotation in the Approov token.
 *
 * @param activity is the current activity that is being run
 */
public static final void setActivity(Activity activity);