KeyManager API

The KeyManager 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.

Since: 2.4

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)

KeyManagerAlias[] getDataAliasList ()

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 KeyManager API.

2.2. 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);
      };

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 permssion");
     }
    
     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 permssion");
     }
    
     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;
      };

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

3. Full WebIDL

    module KeyManager {
      typedef DOMString RawData;
    
      enum PermissionType{
          "NONE",
          "READ",
          "REMOVE",
          "READ_REMOVE"
      };
    
      [NoInterfaceObject] interface KeyManagerObject {
          readonly attribute KeyManager keymanager;
      };
      Tizen implements KeyManagerObject;
    
      [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);
      };
    
      dictionary KeyManagerAlias {
        PackageId packageId;
    
        DOMString name;
      };
    }