Skip to main content

Storage and Encryption | Capacitor Document Scanner

The native Scanbot SDKs as well as the plugin itself use the internal and secure storage locations for all produced files (JPG, PNG, PDF, TIFF, etc) by default.

  • On Android all files will be stored in the internal files directory of your application. No permissions are required for your app to read or write files in this directory.

  • On iOS all files will be stored in the Application Support folder of your application.

Customize Storage Location

caution

It is strongly recommended to use the default storage location.

However, you can override the base storage directory on initialization of the SDK plugin. The initializeSDK method can take an optional parameter storageBaseDirectory to set a custom storage location.

import { ScanbotSDK, ScanbotSdkConfiguration } from 'capacitor-plugin-scanbot-sdk';
// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

const configuration: ScanbotSdkConfiguration = {
storageBaseDirectory: 'file:///some/custom/storage-dir/',
// ...
};
const result = await ScanbotSDK.initializeSDK(configuration);

The value of the storageBaseDirectory must be a file URL ('file:///...) pointing to a valid platform-specific file system path. If this directory does not exist yet, the plugin will try to create it.

caution

When overriding the default storage location, make sure

  • you have implemented a suitable storage permissions request handling on Android
  • you fully understand the consequences regarding the accessibility (security) of the produced document files.

👉 For more details about the storage locations on Android and iOS please also see:

Storage Cleanup

There is no automatic file clean mechanism in this plugin, because only your app can decide when is the perfect time to remove the document files produced by this plugin (images, PDFs, etc).

To avoid storage space issues caused by too many produced document files, it is strongly recommended implementing a suitable cleanup functionality based on the requirements of your app.

This Plugin provides the following helper methods to keep the storage clean:

  • ScanbotSDK.removePage(page) method to delete a certain Page object with all its files.\
  • ScanbotSDK.cleanup() method to remove all generated files by this plugin - scanned and imported images, document page files, barcode images, export files like PDF, TIFF, etc.

Storage Encryption

Scanbot SDK provides the ability to store the generated image and document files (JPG, PNG, PDF, TIFF) encrypted. This feature provides an additional level of security to the default secure storage locations of the native SDKs.

By default the file encryption is disabled. To enable it you have to pass the following config parameters on SDK initialization:

  • fileEncryptionPassword: A secure password or passphrase to derive the AES key for encryption/decryption.
  • fileEncryptionMode: Encryption mode, AES128 or AES256 (default and recommended).
import { ScanbotSDK, ScanbotSdkConfiguration } from 'capacitor-plugin-scanbot-sdk';
const config: ScanbotSdkConfiguration = {
fileEncryptionPassword: 'SomeSecretPa$$w0rdForFileEncryption',
fileEncryptionMode: 'AES256'
...
};
const result = await ScanbotSDK.initializeSDK(config);

By activating storage encryption the native Scanbot SDKs will use the built in AES 128 or AES 256 encryption. All generated image files (JPG, PNG) including the preview image files, as well as the exported PDF and TIFF files will be encrypted in memory and stored as encrypted data files on the flash storage of the device.

The Scanbot SDK derives the AES key from the given password, an internal salt value, and the internal number of iterations using the PBKDF2 function.

When applying image operations like cropping, rotation or image filters, the Scanbot SDK will decrypt the image file in memory, apply the changes, encrypt and store it again.

Display Encrypted Images

If file encryption is enabled you will not be able to display preview images via file URIs (e.g. page.documentPreviewImageFileUri). Instead, you have to load the decrypted data of a preview image and use it for displaying an image. In order to do this use the API function getImageData(imageFileUri: string):

import { ScanbotSDK } from 'capacitor-plugin-scanbot-sdk';
// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

// Use the low-res image file "documentPreviewImageFileUri" of a Page for the preview:
const result = await ScanbotSDK.getImageData({
imageFileUri: page.documentPreviewImageFileUri
});

const decryptedImageDataAsBase64 = `data:image/jpeg;base64,${result.base64ImageData}`;
<ion-img [src]="decryptedImageDataAsBase64" />

👉 For a full implementation see our example app.

Upload Encrypted Images

To upload an image you have the following options:

1) Use the encrypted image file to upload to your server and decrypt it in the back end. Please contact our team to get support on how to generate the corresponding AES key and decrypt images on your back end.

2) Alternatively, get the decrypted image data as Base64 on the mobile device by using the getImageData(imageFileUri: string) function and use this data for the upload process:

import { ScanbotSDK } from 'capacitor-plugin-scanbot-sdk';
// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

// use the final hi-res image file "documentImageFileUri" of a Page for the upload process:
const result = await ScanbotSDK.getImageData({
imageFileUri: page.documentImageFileUri
});

const decryptedImageDataAsBase64 = result.base64ImageData;
yourCustomUploadFunction(decryptedImageDataAsBase64);

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?