Package | flash.data |
Class | public class EncryptedLocalStore |
Inheritance | EncryptedLocalStore Object |
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
ELS data cannot be shared between applications. The intent of ELS is to allow an application to store easily recreated items such as login credentials and other private information. ELS data should not be considered as permanent; see "Limitations of the encrypted local store" and "Best practices for using ELS." below.
AIR profile support: This feature is not supported on AIR for TV devices. You can test
for support at run time using the EncryptedLocalStore.isSupported
property. See
AIR Profile Support for more information regarding API support across multiple profiles.
AIR provides an encrypted local store (ELS) for each AIR application installed on a user's computer or device. This lets you save and retrieve data that is stored on the user’s local hard drive in an encrypted format that cannot easily be deciphered by other users. A separate encrypted local store is used for each AIR application, and each AIR application uses a separate encrypted local store for each user account on the computer.
Use the encrypted local store to cache information that must be secured, such as login credentials for web services. The ELS is appropriate for storing information that must be kept private from other users. It does not, however, protect the data from other processes run under the same user account. It is thus not appropriate for protecting secret application data, such as DRM or encryption keys.
AIR uses DPAPI on Windows, KeyChain on Mac OS and iOS, and KeyRing or KWallet on Linux to associate the encrypted local store to each application and user. The encrypted local store uses AES-CBC 128-bit encryption.
On Android, the data stored by the EncryptedLocalStorage class are not encrypted. Instead the data is protected by the user-level security provided by the operating system. The Android operating system assigns every application a separate user ID. Applications can only access their own files and files created in public locations (such as the removable storage card). Note that on rooted Android devices, applications running with root privileges can access the files of other applications. Thus on a rooted device, the encrypted local store does not provide as high a level of data protection as it does on on a non-rooted device.
Information in the encrypted local store is only available to AIR application content in the application security sandbox.
If you update an AIR application, the updated version retains access to any existing data in the encrypted local store unless:
- The items were added with the
stronglyBound
parameter set totrue
- You have upgraded from the AIR 3.2 namespace to AIR 3.3 (the physical location of the encrypted local store changed between AIR 3.2 and AIR 3.3 for both Mac OS and Windows)
- The existing and update versions are both published prior to AIR 1.5.3 and the update is signed with a migration signature
Limitations of the encrypted local store
The data in the encrypted local store is protected by the user’s operating system account credentials. Other entities cannot access the data in the store unless they can login as that user. However, the data is not secure against access by other applications run by an authenticated user. Thus, data that your application may want to keep secret from users, such as keys used for licensing or digital rights management, is not secure. The ELS is not an appropriate location for storing such information. It is only an appropriate place for storing a user’s private data, such as passwords.
Data in the ELS can be lost for a variety of reasons. For example, the user could uninstall the application and delete the encrypted file. Or, the publisher ID could be changed as a result of an update. Thus the ELS should be treated as a private cache, not permanent data storage.
The stronglyBound
parameter
is deprecated and should not be set to true
. Setting
the parameter to true
does not provide any additional
protection for data. At the same time, access to the data is lost
whenever the application is updated — even if the publisher ID stays
the same.
The encrypted local store may perform more slowly if the stored data exceeds 10MB.
When you uninstall an AIR application, the uninstaller does not delete data stored in the encrypted local store.
Best practices for using ELS
The best practices for using the ELS include:
- Use the ELS to store sensitive user data
such as passwords (setting
stronglyBound
tofalse
) - Do not use the ELS to store applications secrets such as DRM keys or licensing tokens
- Provide a way for your application to recreate the data stored in the ELS if the ELS data is lost. For example, by prompting the user to re-enter their account credentials when necessary.
- Do not use the
stronglyBound
parameter. - If you do set
stronglyBound
totrue
, do not migrate stored items during an update. Recreate the data after the update instead. - Only store relatively small amounts of data. For large amounts of data, use an AIR SQL database with encryption.
Items in the encrypted local store are identified with a string. All items are stored as byte array data.
More examples
Property | Defined By | ||
---|---|---|---|
constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | ||
isSupported : Boolean [static] [read-only]
The isSupported property is set to true if the
EncryptedLocalStore class is supported on the current platform, otherwise it is
set to false. | EncryptedLocalStore |
Method | Defined By | ||
---|---|---|---|
[static]
The data corresponding to the specified name. | EncryptedLocalStore | ||
Indicates whether an object has a specified property defined. | Object | ||
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
[static]
Removes the item with the given name from the encrypted local store. | EncryptedLocalStore | ||
[static]
Clears the entire encrypted local store, deleting all data. | EncryptedLocalStore | ||
[static]
Stores a ByteArray object under the specified name. | EncryptedLocalStore | ||
Sets the availability of a dynamic property for loop operations. | Object | ||
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
Returns the string representation of the specified object. | Object | ||
Returns the primitive value of the specified object. | Object |
isSupported | property |
getItem | () | method |
public static function getItem(name:String):ByteArray
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
The data corresponding to the specified name.
If an item does not exist by the specified name, this method returns null
.
Parameters
name:String — The name of the item in the encrypted local store.
|
ByteArray — The ByteArray data. If there is no data for the provided name ,
the method returns null .
|
Throws
ArgumentError — The name value is null or an empty string.
|
removeItem | () | method |
public static function removeItem(name:String):void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Removes the item with the given name from the encrypted local store.
Parameters
name:String — The name of the item in the encrypted local store.
|
Throws
ArgumentError — The name value is null or an empty string.
|
reset | () | method |
public static function reset():void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Clears the entire encrypted local store, deleting all data.
setItem | () | method |
public static function setItem(name:String, data:ByteArray, stronglyBound:Boolean = false):void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
Stores a ByteArray object under the specified name.
Parameters
name:String — The name of the item in the encrypted local store.
| |
data:ByteArray — The data.
| |
stronglyBound:Boolean (default = false ) — (deprecated) The stronglyBound parameter should
be set to false (the default value). If set to true , the stored item
cannot be retrieved if any application files are altered. For example,if a user installs an
update of your application, the updated application cannot read any strongly bound data that
was previously written to the encrypted local store.
|
Throws
ArgumentError — The name value is null or an empty string.
| |
ArgumentError — The data value is null .
|
var str:String = "Bob"; var bytes:ByteArray = new ByteArray(); bytes.writeUTFBytes(str); EncryptedLocalStore.setItem("firstName", bytes); var storedValue:ByteArray = EncryptedLocalStore.getItem("firstName"); trace(storedValue.readUTFBytes(storedValue.length)); // "Bob" EncryptedLocalStore.removeItem("firstName");
Wed Nov 21 2018, 06:34 AM -08:00