Variables

TalsecConfig

Specifies configuration for your app. See the table below for detailed description of the attributes.

AndroidConfig

Specifies configuration for instances of the app running on Android devices. See the table below for detailed description of the attributes.

IOSConfig

Specifies configuration for instances of the app running on Android devices. See the table below for detailed description of the attributes.

Methods

Future<void> start(TalsecConfig config)

Starts freeRASP with configuration provided in config.

void attachListener(ThreatCallback callback)

Attaches instance of ThreatCallback to freeRASP. If ThreatCallback is already attached, current one will be detached and replaced with callback. When threat is detected, respective callback of ThreatCallback is invoked.

Classes

ThreatCallback

Methods

The most frequent issues occurring during integration:

General

Android Devices

iOS Devices

This page provides you with all the necessary information about freeRASP integration for FlutterFlow. Please read it carefully. If you have a question, don't hesitate to open an issue.

📦 Install the plugin

In this section, you will implement the imported freeRASP Action.

1. On your app's initial page, navigate to the UI Builder.

2. On the right panel, click on Actions.

3. In the Action Flow Editor box, click Open.

4. In the newly opened window, click on On Page Load at the top.

5. Click Add Action (or + and then Add Action, if you already have an Action).

6. On the right panel, search for the runRASP Custom Action.

7. Select the runRASP Action.

⚙️ Setup the Configuration for your App

The freeRASP Action requires several arguments to be filled to function. Some data are related to specific platforms.

If you are developing the application exclusively for one platform, you can omit the configuration part related to the other platform. If you don't want to provide configuration to an unrelated platform, provide an empty string:

1. Click the orange variable icon next to the Value label

2. Scroll down to Constants

3. Click Constant to expand the dropdown menu

4. Select Empty String

Configuration parameters

watcherMail

watcherMail is an email address designated for receiving security reports. Ensure that the email address follows the strict name@domain.com format.

isProd

isProd is a boolean flag that determines whether the freeRASP integration is in the Dev or Release version.

The Dev version of freeRASP is intended for usage during the development phase. It serves the purpose of segregating development and production data, as well as disabling certain checks that are not applicable during the development process. These checks include:

• Emulator usage (onSimulator)

• Debugging (onDebug)

• Signing (onAppIntegrity)

• Unofficial store (onUnofficialStore)

• Obfuscation issues (onObfuscationIssues)

• Developer mode (onDevMode)

• ADB Enabled (onADBEnabled)

[Android] packageName

packageName is a unique identifier for your Android application.

You can find the packageName value for your application in FlutterFlow settings:

1. Navigate to Settings and Integrations.

2. Locate and select App Details.

3. In the textbox labelled Package Name, you will find the package name associated with your application.

[Android] signingCertHash

signingCertHash is a hash of the certificate of the key which was used to sign the application. The value of the hash must be encoded in Base64 form.

More about signing hash and how to obtain it in Getting Signing Certificate Hash.

[Android] supportedStore (optional)

supportedStore is a third-party app store to which your application is uploaded. By including this store, freeRASP considers it as trusted source.

To add a store, add the package name of the store to the supportedStore list.

[iOS] bundleId

bundleId is a unique identifier for your iOS application.

More about bundle ID and how to obtain one: FlutterFlow Documentation | App Deployment.

[iOS] teamId

teamId is a unique identifier assigned to a development team enrolled in the Apple Developer Program.

You can find your teamId on the Apple Developer portal:

1. Go to the website: https://developer.apple.com/account.

2. Log in using the account that is used to sign and release your app.

3. Scroll down to the Membership details section.

4. Look for the line labelled "Team ID" - the value of your team will be displayed there.

👷 Handle detected threats

The freeRASP Action offers multiple callbacks for handling threats. A callback is an Action that gets triggered when a threat is detected.

To implement callback:

1. Open Action Flow Editor with runRASP action.

2. Open one of the dropdown menus labelled "onX" on the right panel (X for a given type of reaction, for example, onAppIntegrity)

3. In the Action Flow Editor box, click on Open.

4. Implement your reaction.

Visit Threat detection to learn more details about the performed checks and their importance for app security.

Limitations

Limited configuration

freeRASP for Flutter allows you to define multiple values for:

• Signing certificate hash

• Supported app store

• Bundle ID

Due to FlutterFlow's limitations, the current implementation of freeRASP for FlutterFlow only allows you to specify a single value for each of these attributes. If want to provide more values, you can download the code and adjust those parameters manually (see Flutter)

Mobile support only

Currently, freeRASP supports only Android and iOS. When running the application in the FlutterFlow web client, freeRASP will not be initialized.

[Android] Minimal SDK level

The minimum required Android SDK level for freeRASP is 23. FlutterFlow applications have a minimum SDK level of 21 by default.

This creates some restrictions:

• Deploying the application from the FlutterFlow web client is not possible.

• Downloading the APK from the FlutterFlow web client is not supported.

To overcome these limitations, we recommend following these steps:

1. Download the code.

2. Manually raise the SDK level in the build.gradle file to 23.

3. Deploy the application using Google Play Console.

Raising SDK version

1. From the root of your project, go to android > app > build.gradle

2. In defaultConfig update minSdkVersion to at least 23 (Android 6.0) or higher

android {
...
defaultConfig {
    ...
    minSdkVersion 23
    ...
    }
...
}

📝 Prerequisites

The freeRASP has the following prerequisites that must be met before starting.

Android

freeRASP requires a minimum SDK level of 23. Some versions of Flutter projects, by default, support even lower levels of minimum SDK. This creates an inconsistency we must solve by updating the minimum SDK level of the application:

• From the root of your project, go to android > app > build.gradle.

• In defaultConfig, update minSdkVersion property to at least 23 (Android 6.0) or higher.

android {
    defaultConfig {
        minSdkVersion 23
    }
}

iOS

Xcode 15 is required to be able to build the application

📦 Install the plugin

Run the following command inside the project directory to add the freeRASP dependency:

flutter pub add freerasp

⚙️ Setup the Configuration for your App

To ensure freeRASP functions correctly, you need to provide the necessary configuration and initialize it. All required values must be filled in for the plugin to operate properly. Detailed descriptions of the configuration options are provided on the API page.

For Android apps, you must get your expected signing certificate hashes in Base64 form. You can go through this manual to learn how to sign your app in more detail, including manual signing and using Google's Play app signing.

In the entry point to your app, import freeRASP and add the following code:

import 'package:freerasp/freerasp.dart';

void main() {

  // This line is important!
  WidgetsFlutterBinding.ensureInitialized();

  // create a configuration for freeRASP
  final config = TalsecConfig(
    /// For Android
    androidConfig: AndroidConfig(
      packageName: 'your.package.name',
      signingCertHashes: [
        'AKoRu...'
      ],
      supportedStores: ['com.sec.android.app.samsungapps'],
    ),

    /// For iOS
    iosConfig: IOSConfig(
      bundleIds: ['YOUR_APP_BUNDLE_ID'],
      teamId: 'M8AK35...',
    ),
    watcherMail: 'your_mail@example.com',
    isProd: true,
  );
}

👷 Handle detected threats

freeRASP executes periodical checks when the application is running. You can handle the detected threats using listeners. For example, you can log the event, show a window to the user or kill the application. See the Threat detection in the wiki to learn more details about the performed checks and their importance for app security.

freeRASP reacts to threats using ThreatCallback. Internally, each threat has its own callback (of VoidCallback type), which is called when a threat is detected.

import 'package:freerasp/freerasp.dart';

void main() {

  // Setting up callbacks
  final callback = ThreatCallback(
      onAppIntegrity: () => print("App integrity"),
      onObfuscationIssues: () => print("Obfuscation issues"),
      onDebug: () => print("Debugging"),
      onDeviceBinding: () => print("Device binding"),
      onDeviceID: () => print("Device ID"),
      onHooks: () => print("Hooks"),
      onPasscode: () => print("Passcode not set"),
      onPrivilegedAccess: () => print("Privileged access"),
      onSecureHardwareNotAvailable: () => print("Secure hardware not available"),
      onSimulator: () => print("Simulator"),
      onSystemVPN: () => print("System VPN"),
      onDevMode: () => print("Developer mode"),
      onADBEnabled: () => print("USB debugging enabled"),
      onUnofficialStore: () => print("Unofficial store")
  );

  // Attaching listener
  Talsec.instance.attachListener(callback);
}

🛡️ Start freeRASP

Start freeRASP to detect threats just by adding this line below the created config and the callback handler:

void main() async {

  // start freeRASP
  await Talsec.instance.start(config);
}

🌁 Enable source code obfuscation

In order to provide as much protection as possible, freeRASP enhances security measures by implementing ProGuard consumer rules, which obfuscate specific sections of the SDK. However, these rules are applied to your Android app code as well due to inheritance.

In certain cases, you may prefer to exclude this rule.

To remove the rule, you need to find freerasp in your cache folder. More about where to find the cache folder here. Then navigate to the freerasp-X.Y.Z/android/build.gradle file and delete the line:

consumerProguardFiles 'consumer-rules.pro'

Read more about why obfuscation is important in the wiki.

☢️ (Optionally) Integrate freeMalwareDetection

freeMalwareDetection is a powerful feature designed to enhance the security of your Android application by quickly and efficiently scanning for malicious or suspicious applications (e.g. Android malware) based on various blacklists and security policies.

It helps to detect apps with suspicious package names, hashes, or potentially dangerous permissions.

Visit the freeMalwareDetection repository to learn more about this feature! For the integration, refer to the integration guide for the Flutter platform.