Security best practices

To maintain compliance with PSD2 (Payment Services Directive 2) and ensure robust application security, it is important that you properly manage how sensitive data is handled in memory.

On this page, you can learn about:

• The different types of data handled by the SDK.
• The classification of data handled by the SDK.
• How you should manage data in your application's memory lifecycle.

How does it work?

When handling authentication and user verification, sensitive data is temporarily loaded into the mobile device's memory.

To prevent this data from being exposed in the event of a memory dump or a device-level compromise, we recommend that you overwrite secrets as early as possible after use, so that they are completely erased from memory.

Classification definitions

To learn about the different data classifications, see the table below:

Classification	Description
SECRET	This data is highly sensitive. You should overwrite it in memory immediately after it is no longer required.
NOT SECRET	This data is not considered highly sensitive. You do not need to overwrite it after use, although doing so is safe and acceptable.

Data classification and handling

You can learn about the specific data types, their security classification, and the reasoning behind their memory management requirements in the table below:

Data type	Classification	Memory management
PIN	SECRET	The end-user's PIN must not be stored anywhere. It should be overwritten immediately after it is sent to the controller and no longer needed.
Activation code	SECRET	This is a one-time code that could potentially be copied and used as long as the session remains valid (typically a maximum of 5 minutes). It must be erased from memory right after the activation is triggered.
Recovery code	SECRET	The recovery code is similar to a PIN in terms of its validity lifecycle. It must be overwritten as soon as the recovery process is successfully initiated or rejected.
Token ID	NOT SECRET	The token ID is a hash that is only valid for the specific application on the device during recovery operations. Because the authorisation token cannot be utilised outside of this specific context, it does not strictly need to be overwritten.

Want to learn more?

To learn how the authorisation token is used for recovery operations, see the Android Account recovery feature documentation.

Memory management in Java and Kotlin

When handling SECRET data in Java or Kotlin, you should not store the values as String objects. This is because strings are immutable in the JVM, which leaves the sensitive data vulnerable to memory dumping and analysis.

What does this mean?

Once a String is created, its value cannot be modified or overwritten; it remains in memory until the Garbage Collector unpredictably decides to clean it up.

Instead of strings, you should always use mutable data structures to store sensitive information. For example:

• CharArray
• ByteArray

This allows you to explicitly shred/overwrite the data with zeros or null characters the exact moment after sending the sensitive data to the Encap SDK.

How to shred arrays

Once the secret has been used, you should immediately clear the array contents. It is best practice to wrap your logic in a try-finally block to ensure that the memory is shredded, even if an exception occurs during processing.

Example of overwriting a CharArray

Kotlin

Example: Overwriting a CharArray

fun processPin(pin: CharArray) {
    try {
        // 1. Process the sensitive data
        verifyPin(pin)
    } finally {
        // 2. Shred the data by overwriting it with zeros
        pin.fill('\u0000')
    }
}

Java

Example: Overwriting a CharArray

import java.util.Arrays;

void processPin(char[] pin) {
    try {
        // 1. Process the sensitive data
        verifyPin(pin);
    } finally {
        // 2. Shred the data by overwriting it with zeros
        Arrays.fill(pin, '\u0000');
    }
}

Example of overwriting a ByteArray

Kotlin

Example: Overwriting a ByteArray

fun processSecret(secret: ByteArray) {
    try {
        // 1. Use the sensitive byte array
        processSecret(secret)
    } finally {
        // 2. Shred the data by overwriting it with zeros
        secret.fill(0)
    }
}

Java

Example: Overwriting a ByteArray

import java.util.Arrays;

void processSecret(byte[] secret) {
    try {
        // 1. Use the sensitive byte array
        processSecret(secret);
    } finally {
        // 2. Shred the data by overwriting it with zeros
        Arrays.fill(secret, (byte) 0);
    }
}