File System

C H A P T E R 9

File System

This chapter describes the optional file system supported on the Java Card Platform, Connected Edition, specifically:

File System Requirements

File System Object Identification

File Access Permissions

Atomicity and Transactional Behavior

Generic Connection Framework-based File Access

File Resource Event Notifications

Thread Safety

Platform Reset Behavior

9.1 File System Requirements

A Java Card Platform implementation MAY support one or several file systems. Each of these file systems MUST have the following characteristics:

It MUST be a hierarchical file system of directories and files.

For each file system object, generic read and write access permission attributes MUST be maintained, see Section 9.3, File Access Permissions.

It MUST be exclusively managed and accessible from the Java Card Platform. That is, the underlying data storage and the file system itself cannot be concurrently or alternatively accessed other than through the Java Card Platform.

It MUST provide an interface that can be exposed through the Generic Connection Framework as a javacardx.io.FileConnection, see Section 9.5, Generic Connection Framework-based File Access.

The underlying data storage MAY be partitioned and each partition MAY support a distinct physical file system, but the Java Card Platform MUST support all file system objects across all file systems to be uniformly accessed using file URIs, see Section 9.2, File System Object Identification.

9.2 File System Object Identification

To each valid file system path to a file system object (directory or file) MUST correspond a unique canonical file URI. The path name component of a file URI MUST follow the syntax of a URI path component, which uses the slash character ‘/’ as the path separator.

A canonical file URI MUST satisfy the following requirements:

it MUST have a file URI scheme,

it MUST have a normalized path with the following characteristics:

it MUST NOT contain any “.” or ”..” path name components

it MUST use the slash character ‘/’ as the path name component separator.

The path component of a file URI MAY correspond to a virtual path that the platform MUST map to a real path on the file system(s) it supports. In such a case, the platform MUST ensure that the constraints that apply to the file URIs are also enforced on the corresponding real paths. For example, dedicated application namespaces MUST NOT overlap, see Section 9.2.1, Application-private File System Objects, therefore the corresponding dedicated directories on the file system(s) MUST NOT overlap in any manner. Similarly, the Java Card Platform MUST ensure that the real paths to file system objects identified with URIs that use the aid registry-based authority do not overlap with any real path of file system objects identified with URIs that use the default registry-based authority.

9.2.1 Application-private File System Objects

Every application instance is named with a relative URI - its application URI. This application URI defines the root of a dedicated namespace within which all its resources, including files, MUST be named. The root of an application’s file namespace is of the form given in TABLE 9-1.

TABLE 9-1 Application-private File System Object Identification
Service Description	File URI
Application-private file namespace root	`file://`<app-path>: `file://`<context path> `file://aid/`<RID>`/`<PIX>
Application-private files and directories	`file://`<app-path>`/`<app-relative-path>: `file://`<context path>`/`<app-relative-path> `file://aid/`<RID>`/`<PIX>`/`<app-relative-path>

All files in an application’s namespace MUST only be accessible to that application. These files MUST be owned by that application. See Section 9.3, File Access Permissions.

Any attempt to access a file under another application’s namespace MUST result in a security exception.

Any attempt to access a file under the reserved file:///platform, file:///standard, file://aid/platform and file://aid/standard namespaces MUST result in a security exception.

9.3 File Access Permissions

On the Java Card Platform, a file system MUST implement restrictions to read and write operations on the actual file system objects. These restrictions are known as access permissions.

A file system MUST manage a generic set of read and write access permission attributes on every file system object. This set of attributes constitutes the object’s file permissions mode. The file permissions mode of a file system object MUST apply to all applications without distinctions.

Operations on a file system object that require read or write access to that file system object MUST fail if that file system object’s permissions mode does not grant the required permission.

TABLE 9-2 defines how a file system object’s permissions modes MUST be interpreted to grant read and write permissions for file system operations.

TABLE 9-2 Operations Granted By Read and Write Permissions on Files and Directories
Permission/File System Object	On a File	On a Directory
Read	Reading this file’s content and attributes.	Reading the names (but not other attributes) of files and subdirectories in this directory.
Write	Modifying (appending or overwriting) this file’s content. Deleting this file, only if write permission is also set on the containing directory.	Creating new files and subdirectories in this directory. Renaming existing files and subdirectories contained in this directory. Deleting subdirectories contained in this directory. Deleting existing files contained in this directory, only if write permission is also set on these files and subdirectories.

In addition to the file system access permissions, access to a file system object MUST be controlled by the permissions granted by the protection domain of the application attempting to access the object. These protection domain permissions are javacardx.io.ConnectorPermission objects with file URI target names. Permission checks MUST apply on the canonical forms of the file URI target names before translation to real file system paths that may apply. See Section 9.2, File System Object Identification.

9.4 Atomicity and Transactional Behavior

The Java Card Platform MUST ensure the atomicity of operations that affect the hierarchical structure of file systems, that is operations on directory entries:

creation of a new file or directory,

deletion of a file or directory,

renaming of a file or directory within the same physical file system,

change of file or directory attributes such as access permissions and last modification time.

All other operations on file content, such as read and write operations, are not transactional.

9.5 Generic Connection Framework-based File Access

The Java Card Platform MUST exclusively support access to file system objects through the Generic Connection Framework as follows:

using a javacardx.io.FileConnection object returned by a call to a javax.microedition.io.Connector open method with a file URL parameter,

using an input or output stream object returned by a call to a javax.microedition.io.Connector openXXXStream method with a file URL parameter.

If a Java Card Platform implementation does not support a file system, any attempt to open a file URL using the Generic Connection Framework MUST result in a javax.microedition.io.ConnectionNotFoundException being thrown.

9.6 File Resource Event Notifications

A developer may use the standard resource event URIs defined in the namespace rooted at event:///standard/rsrc to notify other applications of lifecycle events on file resources his/her application manages. See Section 7.4.1.1, Platform and Standard Events for more details about resource lifecycle events.

Note - The mechanism an application may use to share the content of a file with other applications that may have registered for such events are beyond the scope of this specification, but can be implemented by developers using the shareable interface and object ownership transfer mechanisms, see Section 7.3, Shareable Interface Object-based Services and Section 7.2, Object Ownership Transfer Mechanism.

9.7 Thread Safety

The atomic operations that affect the hierarchical structure of file systems, that is operation on directory entries, such as the creation, the deletion and the renaming of file or directories, MUST be thread safe.

All other operations on file system objects are not guaranteed to be thread safe. The application developer must properly account for thread safety and should handle synchronization explicitly.

9.8 Platform Reset Behavior

After a platform reset, the Java Card Platform MUST perform the following steps before any request or command can be dispatched to any application instance:

1. Any persistent GCF file connection objects, instances of classes implementing the javacardx.io.FileConnection interface, and associated input or output streams that are reachable from the persistence root MUST be placed in a "closed" state.

2. All files and directories for which a delete upon platform reset has been successfully requested through a call to the FileConnection.deleteOnReset MUST be deleted.

Refer to Chapter 5 for the other generic requirements that MUST be implemented by the Java Card Platform after a platform reset.