org.simalliance.openmobileapi

Class SecureStorageProvider

java.lang.Object

org.simalliance.openmobileapi.Provider

org.simalliance.openmobileapi.SecureStorageProvider

public class SecureStorageProvider
extends Provider

This class provides an API to store and retrieve data on the SE which is protected in a secure environment. A default set of functionality that is always provided on every platform enable application developers to rely on this interface for secure data storage (e.g. credit cards numbers, private phone numbers, passwords, ...). The interface should encapsulate any SE specifics as it is intended for device application developers who might not be familiar with SE or APDU internals.

Version:

1.0

Field Summary

Fields

Modifier and Type	Field and Description
static byte	INS_CREATE_SS_ENTRY SIM Alliance Secure Storage CREATE SS ENTRY instruction value.
static byte	INS_DELETE_ALL_SS_ENTRIES SIM Alliance Secure Storage DELETE ALL SS ENTRIES instruction value.
static byte	INS_DELETE_SS_ENTRY SIM Alliance Secure Storage DELETE SS ENTRY instruction value.
static byte	INS_GET_SS_ENTRY_DATA SIM Alliance Secure Storage GET SS ENTRY DATA instruction value.
static byte	INS_GET_SS_ENTRY_ID SIM Alliance Secure Storage GET SS ENTRY ID instruction value.
static byte	INS_PING_SS_APPLET SIM Alliance Secure Storage PING SS APPLET instruction value.
static byte	INS_PUT_SS_ENTRY_DATA SIM Alliance Secure Storage PUT SS ENTRY DATA instruction value.
static byte	INS_SELECT_SS_ENTRY SIM Alliance Secure Storage SELECT SS ENTRY instruction value.
static int	MAX_TITLE_LENGTH Maximum length for a SS title.

Constructor Summary

Constructors

Constructor and Description
SecureStorageProvider(Channel channel) Creates a SecureStorageProvider instance which will be connected to the preselected SE Secure Storage Applet on defined channel.

Method Summary

Methods

Modifier and Type	Method and Description
void	create(java.lang.String title, byte[] data) This command creates a Secure Storage entry with the defined title and data.
boolean	delete(java.lang.String title) This command deletes the Secure Storage entry referenced by the title.
void	deleteAll() This command deletes all Secure Storage entry referenced.
boolean	exist(java.lang.String title) This command checks if the Secure Storage entry with the defined title exists.
java.lang.String[]	list() This command returns an entry list with all title-identifier.
byte[]	read(java.lang.String title) This command reads and returns the byte stream of a data entry stored in the Secure Element referenced by the title.
void	update(java.lang.String title, byte[] data) This command updates the data of the Secure Storage entry referenced by the defined title.

Methods inherited from class org.simalliance.openmobileapi.Provider

getChannel

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_TITLE_LENGTH

public static final int MAX_TITLE_LENGTH

Maximum length for a SS title.

See Also:

Constant Field Values

INS_PING_SS_APPLET

public static final byte INS_PING_SS_APPLET

SIM Alliance Secure Storage PING SS APPLET instruction value.

See Also:

Constant Field Values

INS_CREATE_SS_ENTRY

public static final byte INS_CREATE_SS_ENTRY

SIM Alliance Secure Storage CREATE SS ENTRY instruction value.

See Also:

Constant Field Values

INS_DELETE_ALL_SS_ENTRIES

public static final byte INS_DELETE_ALL_SS_ENTRIES

SIM Alliance Secure Storage DELETE ALL SS ENTRIES instruction value.

See Also:

Constant Field Values

INS_DELETE_SS_ENTRY

public static final byte INS_DELETE_SS_ENTRY

SIM Alliance Secure Storage DELETE SS ENTRY instruction value.

See Also:

Constant Field Values

INS_GET_SS_ENTRY_DATA

public static final byte INS_GET_SS_ENTRY_DATA

SIM Alliance Secure Storage GET SS ENTRY DATA instruction value.

See Also:

Constant Field Values

INS_GET_SS_ENTRY_ID

public static final byte INS_GET_SS_ENTRY_ID

SIM Alliance Secure Storage GET SS ENTRY ID instruction value.

See Also:

Constant Field Values

INS_SELECT_SS_ENTRY

public static final byte INS_SELECT_SS_ENTRY

SIM Alliance Secure Storage SELECT SS ENTRY instruction value.

See Also:

Constant Field Values

INS_PUT_SS_ENTRY_DATA

public static final byte INS_PUT_SS_ENTRY_DATA

SIM Alliance Secure Storage PUT SS ENTRY DATA instruction value.

See Also:

Constant Field Values

Constructor Detail

SecureStorageProvider

public SecureStorageProvider(Channel channel)
                      throws java.lang.IllegalStateException

Creates a SecureStorageProvider instance which will be connected to the preselected SE Secure Storage Applet on defined channel.

Parameters:

channel - the channel that shall be used by this Provider for operations on the Secure Storage.

Throws:

java.lang.IllegalStateException - if the defined channel is closed.

java.lang.IllegalStateException - if the defined channel is not connected to a Secure Storage applet.

Method Detail

create

public void create(java.lang.String title,
          byte[] data)
            throws java.lang.IllegalStateException,
                   java.lang.IllegalArgumentException,
                   java.lang.SecurityException,
                   java.io.IOException

This command creates a Secure Storage entry with the defined title and data. The data can contain an uninterpreted byte stream of an undefined max length (e.g. names,numbers,image,media data,...).

Parameters:

title - The title of the entry that shall be written. The max. title length is 60. All characters must be supported by UTF-8.

data - The data of the entry that shall be written. If data is empty or null then only the defined title will be assigned to the new entry.

Throws:

java.lang.SecurityException - if old PIN to access the Secure Storage Applet was not verified.

java.lang.IllegalStateException - if the used channel is closed.

java.lang.IllegalArgumentException - if the title already exists, if the data chain is too long or if the title has bad encoding or wrong length (empty or too long).

java.io.IOException - if the entry couldn't be created because of an incomplete write procedure.

update

public void update(java.lang.String title,
          byte[] data)
            throws java.lang.IllegalStateException,
                   java.lang.IllegalArgumentException,
                   java.lang.SecurityException,
                   java.io.IOException

This command updates the data of the Secure Storage entry referenced by the defined title. The data can contain an uninterpreted byte stream of an undefined max length (e.g. names, numbers, image, media data, ...).

Parameters:

title - the title of the entry that must already exist. The max. title length is 60. All characters must be supported by UTF-8.

data - the data of the entry that shall be written. If data is empty or null then the data of the existing entry (referenced by the title) will be deleted.

Throws:

java.lang.IllegalStateException - if the used channel is closed.

java.lang.IllegalArgumentException - if the title does not already exists.

java.lang.IllegalArgumentException - if the title is incorrect: bad encoding or wrong length (empty or too long).

java.lang.IllegalArgumentException - if the data chain is too long.

java.io.IOException - if the entry couldn’t be updated because of an incomplete write procedure.

java.lang.SecurityException - if the PIN to access the Secure Storage Applet was not verified.

read

public byte[] read(java.lang.String title)
            throws java.lang.IllegalStateException,
                   java.io.IOException,
                   java.lang.IllegalArgumentException,
                   java.lang.SecurityException

This command reads and returns the byte stream of a data entry stored in the Secure Element referenced by the title.

Parameters:

title - the title of the entry that must already exist. The max. title length is 60. All characters must be supported by UTF-8.

Returns:

the data contained in the file.

Throws:

java.lang.SecurityException - if the PIN to access the Secure Storage Applet was not verified.

java.lang.IllegalStateException - if the used channel is closed.

java.lang.IllegalArgumentException - if the title has bad encoding or wrong length (empty or too long).

java.io.IOException - if the entry couldn't be read because of an incomplete read procedure.

java.lang.IllegalArgumentException - when there are incorrect P1 or P2. TODO: should be an IllegalReferenceError

exist

public boolean exist(java.lang.String title)
              throws java.lang.IllegalStateException,
                     java.lang.IllegalArgumentException,
                     java.lang.SecurityException,
                     java.io.IOException

This command checks if the Secure Storage entry with the defined title exists.

Parameters:

title - the title of the entry that shall be checked. The max. title length is 60. All characters must be supported by UTF-8.

Returns:

True if the entry with the defined title exists. False if the entry does not exist.

Throws:

java.lang.IllegalStateException - if the used channel is closed.

java.lang.IllegalArgumentException - if the title is incorrect: bad encoding or wrong length (empty or too long).

java.lang.SecurityException - if the PIN to access the Secure Storage Applet was not verified.

java.io.IOException - lower-level API exception.

delete

public boolean delete(java.lang.String title)
               throws java.lang.IllegalStateException,
                      java.lang.IllegalArgumentException,
                      java.io.IOException,
                      java.lang.SecurityException

This command deletes the Secure Storage entry referenced by the title. If the entry does not exist nothing will be done.

Parameters:

title - The title of the entry that must already exist. The max. title length is 60. All characters must be supported by UTF-8.

Returns:

True if the entry with the defined title is deleted. False if the entry does not exist.

Throws:

java.lang.IllegalStateException - if the used channel is closed.

java.lang.IllegalArgumentException - if the title is incorrect: bad encoding or wrong length (empty or too long).

java.io.IOException - if there is an error in the transport layer.

java.lang.SecurityException - if old PIN to access the Secure Storage Applet was not verified.

deleteAll

public void deleteAll()
               throws java.lang.IllegalStateException,
                      java.lang.SecurityException,
                      java.io.IOException

This command deletes all Secure Storage entry referenced. If no entries exist, nothing will be done

Throws:

java.lang.SecurityException - if the PIN to access the Secure Storage Applet was not verified.

java.lang.IllegalStateException - if the used channel is closed.

java.io.IOException - if there is an error in the transport layer.

list

public java.lang.String[] list()
                        throws java.lang.IllegalStateException,
                               java.lang.SecurityException,
                               java.io.IOException

This command returns an entry list with all title-identifier. The title is intended for the users to identify and to reference the Secure Storage entries.

Returns:

a list of all entries located in Secure Storage. An empty list will be returned if no entries exist in the Secure Storage

Throws:

java.lang.SecurityException - if the PIN to access the Secure Storage Applet was not verified.

java.lang.IllegalStateException - if the used channel is closed.

java.io.IOException - if there is an error in the transport layer.