TJin-esristaff

Introduction to Secure Storage Plugin

Blog Post created by TJin-esristaff Employee on Dec 5, 2017

AppStudio 2.1 has introduced Secure Storage plugin (BETA) that provides a way to store and access sensitive information such as credentials, tokens etc. With Secure Storage, your data is now encrypted and store in the system provided keychain and can only be accessed by the app.  Let’s dive deeper to find out what is Secure Storage and how to use it.   

 

Note: This functionality is currently in BETA, which essentially means go ahead and use it but there might be slight modifications/enhancements made in the future releases based on usage and feedback. This also means that we are looking forward to your feedback. 

 

Overview

SecureStorage singleton is part of the SecureStorage module, it allows you to store and retrieve data directly with ease in a cross-platform wayIn its first implementation, you can store as key value pairs and retrieve data as a string format and each value is limited to 240 characters (technical limitation to provide cross-platform support). However, there is no limit on how many key/value pairs you can create. 

 

On a side note, when testing your app that uses SecureStorage inside of player make sure there are no collisions with key names since inside player both your app and the player app will be using the same keychains. You can easily make your key unique by adding a prefix such as your app name.

 

Supported Platforms

  • Android
  • iOS 
  • Mac OS
  • Linux
  • Windows

 

SecureStorage provides two methods and a signal (event):

 

Method:

  • Bool setValue (String key, String value) – Returns a boolean value indicating the data was stored encrypted in the system keychain. This method is also used to remove the existing keys from the keychain by providing a valid key name and empty string for the value.  

Note:

  • If you use the same key twice the previous one will be overwritten
  • Keys cannot be null or empty
  • If you enter a valid key with empty string, it will remove the key present in the keychain
  • String value(String key) – Returns string value which is the data associated with the key

 

Signal:

  • error(String errorMessage) - Emits when there is an unacceptable behavior when you try the above methods

 

How to use Secure Storage plugin  

This step - by - step tutorial will walk you through how to use Secure Storage plugin in your AppStudio apps.

 

Step 1

Import Secure Storage plugin statement 

 

import ArcGIS.AppFramework.SecureStorage 1.0

 

Step 2

Store data into system Keychain 

    TextField {
        id: key
        placeholderText: "Enter key"
    }

    TextField {
        id: value
        placeholderText: "Enter value"
        anchors.left: key.right
    }

    //Click on the button to store data into the keychain
    Button {
        id: secureButton
        text: qsTr("Secure Data")
        anchors.top: key.bottom
        onClicked: {
            SecureStorage.setValue(key.text,value.text)
        }
    }

 

Step 3 

Add a Retrieve button, click on the button to retrieve data from Keychain. 

    //Click on the button to retrieve data
    Button {
        id: retrieveButton
        text: qsTr("Retrieve Data")
        anchors.top:secureButton.bottom
        onClicked: {
            retrieveData.text = qsTr("Value: ") + SecureStorage.value(key.text)
        }
    }

    //Display retrieved data
    Text{
        id: retrieveData
        anchors.top: retrieveButton.bottom
    }

 

Step 4 

Display the error message while failing to store and retrieve data 

    Text {
        id: errorData
        anchors.top: retrieveData.bottom
    }

    Connections{
        target: SecureStorage
        onError: {
            errorData.text = errorMessage;
        }
    }

 

Secure Storage Sample 

We have provided a sample to help you learn how to use Secure Storage plugin.  It is available in AppStudio Desktop 2.1 via "New App" dialog:

 

  • Open AppStudio Desktop
  • Click on the New App button 
  • Search and select Secure Storage sample 
  • Click on the Create Button 

This sample is also available in the appstudio-samples GitHub repo

 

 

If you have any feedback or suggestions, let us know in the comments! 

 

To learn more about Secure Storage,  check out the API reference.  

Outcomes