Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Contents


Symbian OS changes due to platform security –File Server (F32)

This document provides details of the API and functional changes from 7.0s to Symbian OS as a result of platform security for the File Server.

[Top]


1.1 File server (F32)

The file server, as part of the TCB, will have three ‘protected’ directories that form the trusted areas of the file system. Capabilities associated with the file server and its control over access to these trusted areas are

Tcb Super user capability to the file server

AllFiles Read and write access to the private directory, read access to /sys

DiskAdmin For functionality such as Formatting or disk checking

The \Sys\ directory hierarchy, in a similar way to the \System\ hierarchy in pre-security implementations of Symbian OS, contains system critical files such as installed binaries. Access to this directory in file or directory accessing APIs is restricted to processes with Tcb capability for write access and AllFiles capability for read access.

The \Private\ directory contains private directories for each process on the Symbian OS using the file server. To gain access to this directory, the process must either have AllFiles capability, or else be accessing its own subdirectory within \Private\. Other than these two cases, all other attempts to access these folders will return KErrAccessDenied.

The \Resource\ directory is read-only unless Tcb capability is held.

The rest of the drive is ‘public’ and the file server APIs will operate as usual here.

The main changes to the operation of the file server are that each process will have its own private directory and that to access certain areas of a drive requires correct capabilities. The result is that there are some changes to the File server API and how it is used.

Firstly the default path has been removed. Instead, when a connection to the file server is made the session path will automatically be set to the connecting process’s private directory.

The redundant functions RFs::DefaultPath() and RFs::SetDefaultPath() are also removed.

New functions added are: RFs::SetSessionToPrivate(TDrive aDrive), which sets the session path to the process’s private directory and RFs::PrivatePath(TDes & aPPath), which returns the private path for the process. No capabilities are required to use either of these new functions. Provisionally provided is the function, RFs::CreatePrivatePath(TDrive aDrive) to create the private directory for the calling process—though this is not strictly necessary as PrivatePath() can return the correct private path for a process and RFs::MkDirAll can be used to create it

The Files server’s main API is the RFs class, which is a sharable (for threads within a process) session to the file server. Sub-session APIs are RFile, RFormat, RDir and RRawDisk. Also provided are utility API classes such as TEntry which pose no threat to the file server. On top of the basic file server APIs are CFileMan and TFindFile classes, which remain the same: all checking will be done by the R classes.


1.1.1 RFs

TBool RFs::IsValidDrive(TInt aDrive)
TInt RFs::CharToDrive(TChar aChar,TInt& aDrive)
TInt RFs::DriveToChar(TInt aDrive,TChar& aChar)
TBool RFs::IsRomAddress(TAny* aPtr)
TInt RFs::Connect(TInt aMessageSlots)
TVersion RFs::Version() const

Most of these functions do not actually use a connection to the fileserver but are just related to the file server functionality.

Capabilities: Any

1.1.1.1 Loading and mounting

TInt RFs::AddFileSystem(const TDesC& aFileName) const
TInt RFs::RemoveFileSystem(const TDesC& aFileSystemName) const
TInt RFs::MountFileSystem(const TDesC& aFileSystemName, TInt aDrive) const
TInt RFs::DismountFileSystem(const TDesC& aFileSystemName, TInt aDrive) const

These are generally system level functions, not for any process.

Capabilities : DiskAdmin Tcb

TInt RFs::RemountDrive(TInt aDrive, const TDesC8* aMountInfo, TUint aFlags)
TInt RFs::FileSystemName(TDes& aName,TInt aDrive) const

Capability: Any

1.1.1.2 Notifiers

void RFs::NotifyChange(TNotifyType aType, TrequestStatus& aStat)
void RFs::NotifyChange(TNotifyType aType,TRequestStatus& aStat, const TDesC& aPathName)

Notification of changes to file system, write failure or space on a drive.

Capability: Global Any

“/Resource/” Any

“/Sys/” Tcb, AllFiles

“/Private/” Correct Process SID, AllFiles, Tcb

void RFs::NotifyDiskSpace(TInt64 aThreshold, TInt aDrive, TRequestStatus& aStat)
void RFs::NotifyDiskSpaceCancel(TRequestStatus& aStat)
void RFs::NotifyDiskSpaceCancel()
void RFs::NotifyChangeCancel(TRequestStatus& aStat)
void RFs::NotifyChangeCancel()

These functions concern global changes to a disk. The caller can not deduce where the change was made, just that a change occurred.

Capability: Any

TBool RFs::GetNotifyUser()
void RFs::SetNotifyUser(TBool aValue)

These functions set whether the user should be notified of file read or write failure. Although it could be dangerous to use the functions to not inform the user of a write failure, the risk is seen as low, and it would be more problematic to prevent processes without capabilities to call it.

Capabilities: Any

1.1.1.3 Drive and path

TInt RFs::SetSessionPathToPrivate(Tdrive aDrive) 
TInt RFs::PrivatePath(TDes & aPPath) const
TInt RFs::CreatePrivatePath(Tdrive aDrive)
TInt RFs::SessionPath(TDes& aPath) const
TInt RFs::DriveList(TDriveList& aList) const
TInt RFs::Drive(TDriveInfo& anInfo,TInt aDrive) const
TInt RFs::Volume(TVolumeInfo& aVol,TInt aDrive) const
TInt RFs::GetDriveName(TInt aDrive,TDes& aDriveName) const
TInt RFs::Subst(TDes& aPath,TInt aDrive) const 

Capabilities: Any

TInt RFs::SetDriveName(TInt aDrive,const TDesC& aDriveName)
TInt RFs::SetVolumeLabel(const TDesC& aName, TInt aDrive)

Capabilities: Tcb or DiskAdmin

TInt RFs::SetSubst(TDes& aPath,TInt aDrive)
TInt RFs::RealName(const TDesC& aName,TDes& aResult) const
TInt RFs::SetSessionPath(const TDesC& aPath)

Capabilities: “/Resource/” Any

“/Sys/” Tcb

“/Private/” Correct Process SID, AllFiles, Tcb

1.1.1.4 Directory operations

TInt RFs::MkDir(const TDesC& aPath)
TInt RFs::MkDirAll(const TDesC& aPath)
TInt RFs::RmDir(const TDesC& aPath)

Capabilities: “/Resource/” Tcb

“/Sys/” Tcb

“/Private/” Correct Process SID, AllFiles, Tcb

TInt RFs::GetDir(const TDesC& aName,const TUidType& aUidType,TUint aKey,CDir*& aFileList) const
TInt RFs::GetDir(const TDesC& aName,TUint anAttMask,TUint aKey,CDir*& aFileList) const
TInt RFs::GetDir(const TDesC& aName,TUint anAttMask,TUint aKey,CDir*& aFileList,CDir*& aDirList) const

Capabilities: “/Resource/” Any

“/Sys/” Tcb, AllFiles

“/Private/” Correct Process SID, AllFiles, Tcb

1.1.1.5 Parsing functions

TInt RFs::Parse(const TDesC& aName,TParse& aParse) const
TInt RFs::Parse(const TDesC& aName,const TDesC& aRelated,TParse& aParse) const

Capability: Any

1.1.1.6 File and directory operations

TInt RFs::Delete(const TDesC& aName)
TInt RFs::Rename(const TDesC& anOldName,const TDesC& aNewName)
TInt RFs::Replace(const TDesC& anOldName,const TDesC& aNewName)
TInt RFs::Modified(const TDesC& aName,TTime& aTime) const
TInt RFs::SetAtt(const TDesC& aName,TUint aSetAttMask,TUint aClearAttMask)
TInt RFs::SetModified(const TDesC& aName,const TTime& aTime)
TInt RFs::SetEntry(const TDesC& aName,const TTime& aTime,TUint aSetAttMask,TUint aClearAttMask)
TInt RFs::ReadFileSection(const TDesC& aName,TInt aPos,TDes8& aDes,TInt aLength) const

Capabilities: “/Resource/” Tcb

“/Sys/” Tcb

“/Private/” Correct Process SID, AllFiles, Tcb

TInt RFs::GetShortName(const TDesC& aLongName,TDes& aShortName) const
TInt RFs::GetLongName(const TDesC& aShortName,TDes& aLongName) const
TUint8* RFs::IsFileInRom(const TDesC& aFileName) const

Capabilities: “/Resource/” Any

“/Sys/” Tcb

“/Private/” Correct Process SID, AllFiles, Tcb

TInt RFs::Att(const TDesC& aName,TUint& aVal) const
TInt RFs::Entry(const TDesC& aName,TEntry& anEntry) const

Capabilities: “/Resource/” Any

“/Sys/” Tcb, AllFiles

“/Private/” Correct Process SID, AllFiles, Tcb

TBool RFs::IsValidName(const TDesC& aFileName,TText& aBadChar) const

Capability: Any

1.1.1.7 Error checking / utilities

TInt RFs::CheckDisk(const TDesC& aDrive) const
TInt RFs::ScanDrive(const TDesC& aDrive) const

Capabilities: DiskAdmin

1.1.1.8 Valid only on removable media

TInt RFs::LockDrive(TInt aDrv, const TMediaPassword &aOld, const TMediaPassword &aNew, TBool aStr)
TInt RFs::UnlockDrive(TInt aDrv, const TMediaPassword &aPswd, TBool aStr)
TInt RFs::ClearPassword(TInt aDrv, const TMediaPassword &aPswd)

Note that how to handle removable media is an open issue.

Capability: Tcb or DiskAdmin

1.1.1.9 Debug functions

TInt RFs::LoaderHeapFunction(TInt aFunction, TAny *aArg1, TAny *aArg2)
TInt RFs::SetErrorCondition(TInt anError,TInt aCount)
TInt RFs::SetDebugRegister(TInt aVal)
TInt RFs::SetAllocFailure(TInt aVal)
void RFs::DebugNotify(TInt aDrive,TUint aNotifyType,TRequestStatus& aStat)

These functions are used for debugging applications using the file server.

Capabilities: Any in debug builds

Tcb in release build

void RFs::ResourceCountMarkStart() const
void RFs::ResourceCountMarkEnd() const
TInt RFs::ResourceCount() const

Capabilities: Any

TInt RFs::ControlIO(TInt aDrive,TInt aCommand,TAny* aParam1,TAny* aParam2)

This function has uses other than debugging, and is currently an open issue.


1.1.2 RFile

TInt Create(RFs& aFs,const TDesC& aName,TUint aFileMode);
TInt Temp(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode);
TInt Rename(const TDesC& aNewName)
TInt Replace(RFs& aFs,const TDesC& aName,TUint aFileMode);

These create a sub-session of the fileserver session by either opening a file, creating a new unique file or a temporary file.

Capabilities: “/Resource/” Tcb

“/Sys/” Tcb

“/Private/” Correct Process SID, AllFiles, Tcb

TInt Open(RFs& aFs,const TDesC& aName,TUint aFileMode);

Capabilities: “/Resource/” Any for ReadOnly mode

“/Resource/” Tcb for all other modes

“/Sys/” Tcb

“/Private/” Correct Process SID, AllFiles, Tcb

TInt ChangeMode(TFileMode aNewMode)

Capabilities: “/Resource/” Tcb, only applicable for this folder

TInt SetAtt(TUint aSetAttMask,TUint aClearAttMask);
TInt SetModified(const TTime& aTime);
TInt Set(const TTime& aTime,TUint aSetAttMask,TUint aClearAttMask);
TInt SetSize(TInt aSize);
void Write(TInt aPos,const TDesC8& aDes,TInt aLength,TRequestStatus& aStatus);
TInt Lock(TInt aPos,TInt aLength) const;
TInt UnLock(TInt aPos,TInt aLength) const;
TInt Modified(TTime& aTime) const;
TInt Att(TUint& aAttValue) const;
TInt Size(TInt& aSize) const;
void Read(TInt aPos,TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const;
TInt Seek(TSeek aMode,TInt& aPos) const;
TInt Flush();
TInt Drive(TInt &aDriveNumber, TDriveInfo &aDriveInfo) const

These require an open file for use, so checking can be done then rather than when they are called. You can not change the mode of a file from read-only from once it has been opened.

Capabilities: Any


1.1.3 RDir

TInt Open(RFs& aFs,const TDesC& aMatchName,TUint anEntryAttMask)
TInt Open(RFs& aFs,const TDesC& aMatchName,const TUidType& aUidType)

Open directory for reading entries such as filename, UID and other attributes of files and directories.

Capabilities: “/Resource/” Any

“/Sys/” Tcb, AllFiles

“/Private/” Correct Process SID, AllFiles, Tcb

TInt Read(TEntryArray& anArray) const
void Read(TEntryArray& anArray,TRequestStatus& aStatus) const
void Read(TPckg<TEntry>& anEntry,TRequestStatus& aStatus) const

The given directory must be opened before use, so there is no need to check here.

Capabilities:Any


1.1.4 RFormat

TInt Open(RFs& aFs,const TDesC& aName,TUint aFormatMode,TInt& aCount)
TInt Next(TInt& aStep)
void Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus)

These can clear the entire contents of a disk.

Capability: DiskAdmin, Tcb


1.1.5 RRawDisk

TInt Open(RFs& aFs,TInt aDrive);
void Close();
TInt Read(TInt aPos,TDes8& aDes);
TInt Write(TInt aPos,TDesC8& aDes);

This API subverts the file system and has direct access to the media.

Capability: Tcb