KeyManager API

The Key Manager API provides a secure repository for storing, retrieving and removing the sensitive data of users and their applications. Users can protect the data with passwords.

For more information on the Key Manager features, see Key Manager Guide.

Since: 2.4

Table of Contents

Summary of Interfaces and Methods

Interface Method
KeyManagerObject
KeyManager
void saveData (DOMString name, RawData rawData, optional DOMString? password, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void removeData (KeyManagerAlias dataAlias)
RawData getData (KeyManagerAlias dataAlias, optional DOMString? password)
void setPermission (KeyManagerAlias dataAlias, PackageId packageId, PermissionType permissionType, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
KeyManagerAlias

1. Type Definitions

1.1. RawData

Data to be stored or retrieved. 
  typedef DOMString RawData;

Since: 2.4

1.2. PermissionType

An enumerator to indicate permissions. 
  enum PermissionType { "NONE", "READ", "REMOVE", "READ_REMOVE" };

Since: 2.4

  • NONE - Clears or removes permissions
  • READ - Permission to read data
  • REMOVE - Permission to remove data
  • READ_REMOVE - Permission to read and remove data

2. Interfaces

2.1. KeyManagerObject

The KeyManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform. 
  [NoInterfaceObject] interface KeyManagerObject {
    readonly attribute KeyManager keymanager;
  };
  Tizen implements KeyManagerObject;

Since: 2.4

The tizen.keymanager object allows access to the functionality of the Key Manager API.

Attributes

  • readonly KeyManager keymanager
    Object representing a key manager.

    Since: 2.4

2.2. KeyManager

The KeyManager interface provides methods to store, retrieve and remove the sensitive data of users and their applications. 
  [NoInterfaceObject] interface KeyManager {
    void saveData(DOMString name, RawData rawData, optional DOMString? password, optional SuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);
    void removeData(KeyManagerAlias dataAlias) raises(WebAPIException);
    RawData getData(KeyManagerAlias dataAlias, optional DOMString? password) raises(WebAPIException);
    KeyManagerAlias[] getDataAliasList() raises(WebAPIException);
    void setPermission(KeyManagerAlias dataAlias, PackageId packageId, PermissionType permissionType,
                       optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

Since: 2.4

It provides access to the API functionalities through the tizen.keymanager interface.

Methods

saveData
Saves and stores data as a KeyManagerAlias inside the KeyManager. 
void saveData(DOMString name, RawData rawData, optional DOMString? password, optional SuccessCallback? successCallback,
              optional ErrorCallback? errorCallback);

Since: 2.4

On success, this method will add a KeyManagerAlias into the KeyManager. The name attribute of that KeyManagerAlias will be set to be the value of the name parameter which is used in this method call. The packageId attribute of that KeyManagerAlias will automatically be set to be the package ID of the application which calls this method.

The ErrorCallback is launched with these error types:

  • UnknownError - If the method cannot be completed because of an unknown error.

Warning: http://tizen.org/privilege/keymanager (public level privilege) MUST NOT be declared to use this API since 3.0.

Parameters:

  • name: Name to identify the data - this will be the name attribute of the KeyManagerAlias which this method adds, on success, into the KeyManager.
  • rawData: Raw data to be stored.
  • password [optional] [nullable]: Password to use for encrypting the data.
  • successCallback [optional] [nullable]: Callback function that is called when data is successfully saved.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

var data_name = "data1", raw_data = "my data";

function onSave()
{
  console.log("Successfully saved data");
}

tizen.keymanager.saveData(data_name, raw_data, null, onSave);
removeData
Removes data from the KeyManager. 
void removeData(KeyManagerAlias dataAlias);

Since: 2.4

To remove data, an application must have permission to remove that data. By default, an application which saved data into the KeyManager has permission to remove the data. An application can also use the setPermission method to allow another application to remove its data.

If an application calls this method to remove data which it saved into the KeyManager, the dataAlias parameter does not require the packageId attribute.

Warning: http://tizen.org/privilege/keymanager (public level privilege) MUST NOT be declared to use this API since 3.0.

Parameters:

  • dataAlias: Alias of the data to remove.

Exceptions:

  • WebAPIException

    • with error type NotFoundError, if the dataAlias cannot be found.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type UnknownError, if the method cannot be completed because of an unknown error

Code example:

var data_name = "data1", raw_data = "my data";

function onSave()
{
  /* Do something. */

  /* Dictionary does not require package ID because the */
  /* application which is calling removeData() saved "data1". */
  tizen.keymanager.removeData({"name": data_name});
}

tizen.keymanager.saveData(data_name, raw_data, null, onSave);

Code example:

var aliases = tizen.keymanager.getDataAliasList();

if (aliases.length != 0)
{
  /* Assuming the application calling removeData() has permission. */
  /* to remove aliases[0] */
  var app_data = tizen.keymanager.removeData(aliases[0]);
}
getData
Gets raw data from the KeyManager. 
RawData getData(KeyManagerAlias dataAlias, optional DOMString? password);

Since: 2.4

To get raw data, an application must have permission to get that raw data. By default, an application which saved raw data into the KeyManager has permission to get that raw data. An application can also use the setPermission method to allow another application to get and read its raw data.

If an application calls this method to retrieve raw data which it saved into the KeyManager, the dataAlias parameter does not require the packageId attribute.

Warning: http://tizen.org/privilege/keymanager (public level privilege) MUST NOT be declared to use this API since 3.0.

Parameters:

  • dataAlias: Alias of the data to get.
  • password [optional] [nullable]: Password which was used to encrypt the data.

Return value:

    RawData: Data.

Exceptions:

  • WebAPIException

    • with error type NotFoundError, if the dataAlias cannot be found.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type VerificationError, if the method cannot be completed because an incorrect password is used.

    • with error type UnknownError, if the method cannot be completed because of a database access failure or any other unknown error.

Code example:

var data_name = "data1", raw_data = "my data";

function onSave()
{
  /* Dictionary does not require package ID because the */
  /* application which is calling getData() saved "data1". */
  var app_data = tizen.keymanager.getData({"name": data_name});
  console.log("App data: " + app_data + " was retrieved");
}

tizen.keymanager.saveData(data_name, raw_data, null, onSave);

Code example:

var aliases = tizen.keymanager.getDataAliasList();

if (aliases.length != 0)
{
  /* Assuming the application calling getData() has permission to read. */
  /* aliases[0] */
  var app_data = tizen.keymanager.getData(aliases[0]);
  console.log("App data: " + app_data + " was retrieved");
}
getDataAliasList
Gets all the aliases which an application can access. 
KeyManagerAlias[] getDataAliasList();

Since: 2.4

Warning: http://tizen.org/privilege/keymanager (public level privilege) MUST NOT be declared to use this API since 3.0.

Return value:

    KeyManagerAlias[]: Array of aliases.

Exceptions:

  • WebAPIException

    • with error type UnknownError, if the method cannot be completed because of an unknown error.

Code example:

var aliases = tizen.keymanager.getDataAliasList();

console.log("Aliases: ");
for (var i = 0; i < aliases.length; i++)
{
  console.log("Package ID: " + aliases[i].packageId + ", Name: " + aliases[i].name);
}
setPermission
Sets permissions that another application has for accessing an application's data. 
void setPermission(KeyManagerAlias dataAlias, PackageId packageId, PermissionType permissionType,
                   optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 2.4

An application can only set permissions for data which it saved into the KeyManager. Therefore, the dataAlias parameter does not require the packageId attribute.

The ErrorCallback is launched with these error types:

  • NotFoundError - If the dataAlias cannot be found.
  • UnknownError - If the method cannot be completed because of an unknown error.

Warning: http://tizen.org/privilege/keymanager (public level privilege) MUST NOT be declared to use this API since 3.0.

Parameters:

  • dataAlias: Alias the data for which permission will be set.
  • packageId: Package ID of the accessor application.
  • permissionType: Permission to grant to the accessor application.
  • successCallback [optional] [nullable]: Callback function that is called when permission is successfully set.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example:

var data_name = "data1", raw_data = "my data";

function onPermissionSet()
{
  console.log("Successfully set permission");
}

function onSave()
{
  /* Dictionary does not require package ID because an */
  /* application can only set permission for data which it saved. */
  tizen.keymanager.setPermission({"name": data_name}, "9PdoiICQ4c", "READ_REMOVE", onPermissionSet);
}

tizen.keymanager.saveData(data_name, raw_data, null, onSave);

Code example:

var aliases = tizen.keymanager.getDataAliasList();

function onPermissionSet()
{
  console.log("Successfully set permission");
}

if (aliases.length != 0)
{
  /* Check that the application calling setPermission() saved aliases[0] into */
  /* the KeyManager. */
  if (aliases[0].packageId === tizen.package.getPackageInfo().id)
  {
    tizen.keymanager.setPermission(aliases[0], "9PdoiICQ4c", "READ_REMOVE", onPermissionSet);
  }
  else
  {
    console.log("This application did not save aliases[0] into the KeyManager");
  }
}

2.3. KeyManagerAlias

The KeyManagerAlias dictionary identifies items in the KeyManager. 
  dictionary KeyManagerAlias {
    PackageId packageId;
    DOMString name;
    boolean isProtected;
  };

Since: 2.4

Dictionary members

PackageId packageId
Package ID of the application which saved the item into the KeyManager.

Since: 2.4

DOMString name
Name which describes the item.

If this attribute contains any spaces, the spaces will be removed. Characters which are separated by spaces will be concatenated.

Since: 2.4

boolean isProtected
Flag indicating whether key is password-protected. This property is set only when returning object by getDataAliasList() method. In other methods which use this dictionary, the value is ignored.

Possible values:

  • true - data under the alias is password-protected,
  • false - data under the alias is not password-protected.

Since: 5.5

3. Full WebIDL

module KeyManager {
  typedef DOMString RawData;
  enum PermissionType { "NONE", "READ", "REMOVE", "READ_REMOVE" };
  dictionary KeyManagerAlias {
    PackageId packageId;
    DOMString name;
    boolean isProtected;
  };
  Tizen implements KeyManagerObject;
  [NoInterfaceObject] interface KeyManagerObject {
    readonly attribute KeyManager keymanager;
  };
  [NoInterfaceObject] interface KeyManager {
    void saveData(DOMString name, RawData rawData, optional DOMString? password, optional SuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);
    void removeData(KeyManagerAlias dataAlias) raises(WebAPIException);
    RawData getData(KeyManagerAlias dataAlias, optional DOMString? password) raises(WebAPIException);
    KeyManagerAlias[] getDataAliasList() raises(WebAPIException);
    void setPermission(KeyManagerAlias dataAlias, PackageId packageId, PermissionType permissionType,
                       optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
  };
};
Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License.