Secure storage

The AppFramework includes a Secure Storage QML plug-in, allowing AppStudio apps to store and access sensitive information such as credentials or tokens. With this plug-in, your data can be encrypted and stored in a system-provided location with the data only accessible by your app.

On Windows devices, these values are stored in the Credential Locker. On macOS and iOS, these values are stored in the system keychain. On Android, these values are stored in the Android Keystore. On Linux, these values are stored in a keychain.ini file in your system settings.

To use this functionality, you must first include the following import statement:

import ArcGIS.AppFramework.SecureStorage 1.0

For an example of this functionality, see the sample app available in ArcGIS AppStudio or in the AppStudio samples GitHub repository.

Store string value

The SecureStorage component in the plug-in is a singleton, meaning it doesn't need to be instantiated before use. This component consists of two methods, one that performs the storing of values and one that performs the retrieval of values, as well as an onError signal.

The setValue method saves a key-value pair to storage. The following code sample demonstrates the method's functionality, saving a username and password to storage for later use. The password field also hides provided input, unless an adjacent check box is checked.

TextField {
    id: username
    placeholderText: "Username"
}

TextField {
    id: password
    placeholderText: "Password"
    anchors.left: username.right
    echoMode: passwordVisible.checked === true ? TextInput.Normal : TextInput.PasswordEchoOnEdit
}

CheckBox {
    id: passwordVisible
    anchors.left: password.right
}

Button {
    id: secureButton
    text: qsTr("Store Combination")
    anchors.top: username.bottom
    onClicked: {
        SecureStorage.setValue(username.text,password.text)
    }
}

Consider the following behaviors of the setValue method when using it:

• The maximum length for a key or a value is based on your operating system. These can be checked with the maximumKeyLength and maximumValueLength properties. If the key or the value you intend to store, or a combination of the two, is greater than the maximum length, consider splitting them before storing them separately.
• The key cannot be null or empty.
• If you use the same key twice, the previous value associated with the key will be overwritten.
• Providing an empty value for a preexisting key will remove the key present in the keychain.
• Android users will encounter an exception if certain special characters, such as a slash (/), are used in keys.
• If the value or setValue method fails, the onError signal is triggered.

Retrieve string value

The value method in SecureStorage is the only means to access string data stored by your app. Replacing the username field in the previous code sample with the following modified version will use the value method to automatically fill the password field if the provided username is already stored.

TextField {
    id: username
    placeholderText: "Username"

    onEditingFinished: {
        password.text = SecureStorage.value(username.text)
    }
}