A Few Important App Directories

The OS X file system is organized in a way that groups related files and data together in specific places. Every file in the file system has its place and apps need to know where to put the files they create. This is especially important if you are distributing your app through the App Store, which expects you to put your app’s data files in specific directories.

Table 1-1 lists the directories with which apps commonly interact. Some of these directories are inside the home directory, which is either the user’s home directory or, if the app adopts App Sandbox, the app’s container directory as described in App Sandbox and XPC. Because the actual paths can differ based on these conditions, use the URLsForDirectory:inDomains: method of the NSFileManager class to retrieve the actual directory path. You can then add any custom directory and filename information to the returned URL object to complete the path.

Listing 1-1 shows an example of how to retrieve the base path to the Application Support directory and then append a custom app directory to it.

Listing 1-1  Getting the path to the Application Support directory

NSFileManager* fileManager = [NSFileManager defaultManager];

NSURL* appSupportDir = nil;

NSArray *urls = [fileManager URLsForDirectory:NSApplicationSupportDirectory inDomains:NSUserDomainMask];

if ([paths count] > 0) {

   appSupportDir = [[urls objectAtIndex:0] URLByAppendingPathComponent:@"com.example.MyApp"];

}

For more information about how to access files in well known system directories, see File System Programming Guide.

Coordinating File Access with Other Processes

In OS X, other processes may have access to the same files that your app does. Therefore, when working with files, you should use the file coordination interfaces introduced in OS X v10.7 to be notified when other processes (including the Finder) attempt to read or modify files your app is currently using. For example, coordinating file access is critical when your app adopts iCloud storage.

The file coordination APIs allow you to assert ownership over files and directories that your app cares about. Any time another process attempts to touch one of those items, your app is given a chance to respond. For example, when an app attempts to read the contents of a document your app is editing, you can write unsaved changes to disk before the other process is allowed to do its reading.

Using iCloud document storage, for example, you must incorporate file coordination because multiple apps can access your document files in iCloud. The simplest way to incorporate file coordination into your app is to use the NSDocument class, which handles all of the file-related management for you. See Document-Based App Programming Guide for Mac.

On the other hand, if you're writing a library-style (or “shoebox”) app, you must use the file coordination interfaces directly, as described in File System Programming Guide.

Interacting with the File System

Disks in Macintosh computers are formatted using the HFS+ file system by default. However, Macintosh computers can interact with disks that use other formats so you should never code specifically to any one file system. Table 1-2 lists some of the basic file system attributes you may need to consider in your app and how you should handle them.

File-System Usage Requirements for the Mac App Store

To promote a more consistent user experience, applications submitted to the Mac App Store must follow certain rules about where they write files. Users can be confused when applications cause unexpected side effects on the file system (for example, storing databases in the user’s Documents folder, storing files in the user’s Library folder that are not recognizably associated with your application, storing user data in the user’s Library folder, and so on).

Your application must adhere to the following requirements:

• You may use Apple frameworks such as User Defaults, Calendar Store, and Address Book that implicitly write to files in specific locations, including locations your application is not allowed to access directly.

• Your application may write to temporary paths that you acquire using the appropriate Apple programming interfaces, such as the NSTemporaryDirectory function.

• Your application may write to the following directories:

  • ~/Library/Application Support/<app-identifier>

  • ~/Library/<app-identifier>

  • ~/Library/Caches/<app-identifier>

  where <app-identifier> is your application's bundle identifier, its name, or your company’s name. This must exactly match what is in App Store Connect for the application.

  Always use Apple programming interfaces such as the URLsForDirectory:inDomains: function to locate these paths rather than hardcoding them. For more information, see File System Programming Guide.

• If your application manages libraries of pictures, music, or movies, the application may also write to the following directories:

  • ~/Pictures/<app-identifier>

  • ~/Music/<app-identifier>

  • ~/Movies/<app-identifier>

• If the user explicitly chooses to save data in an alternate location (using a Save As dialog), your application may write to the chosen location.

App Sandbox and XPC

You secure your app against attack from malware by following the practices recommended in Secure Coding Guide. But an attacker needs only to find a single hole in your defenses, or in any of the frameworks and libraries that you link against, to gain control of your app along with all of its privileges.

App Sandbox provides a last line of defense against stolen, corrupted, or deleted user data if malicious code exploits your app. App Sandbox also minimizes the damage from coding errors. Its strategy is twofold:

1. App Sandbox enables you to describe how your app interacts with the system. The system then grants your app the access it needs to get its job done, and no more. For your app to provide the highest level of damage containment, the best practice is to adopt the tightest sandbox possible.

2. App Sandbox allows the user to transparently grant your app additional access by way of Open and Save dialogs, drag and drop, and other familiar user interactions.

You describe your app’s interaction with the system by way of setting entitlements in Xcode. An entitlement is a key-value pair, defined in a property list file, that confers a specific capability or security permission to a target. For example, there are entitlement keys to indicate that your app needs access to the camera, the network, and user data such as the Address Book. For details on all the entitlements available in OS X, see Entitlement Key Reference.

When you adopt App Sandbox, the system provides a special directory for use by your app—and only by your app—called a container. Your app has unfettered read/write access to the container. All OS X path-finding APIs, above the POSIX layer, are relative to the container instead of to the user’s home directory. Other sandboxed apps have no access to your app’s container, as described further in Code Signing.

Your sandboxed app can access paths outside of its container in the following three ways:

• At the specific direction of the user

• By you configuring your app with entitlements for specific file-system locations, such as the Movies folder

• When a path is in any of certain directories that are world readable

The OS X security technology that interacts with the user to expand your sandbox is called Powerbox. Powerbox has no API. Your app uses Powerbox transparently when, for example, you use the NSOpenPanel and NSSavePanel classes, or when the user employs drag and drop with your app.

Some app operations are more likely to be targets of malicious exploitation. Examples are the parsing of data received over a network, and the decoding of video frames. By using XPC, you can improve the effectiveness of the damage containment offered by App Sandbox by separating such potentially dangerous activities into their own address spaces.

XPC is an OS X interprocess communication technology that complements App Sandbox by enabling privilege separation. Privilege separation, in turn, is a development strategy in which you divide an app into pieces according to the system resource access that each piece needs. The component pieces that you create are called XPC services. For details on adopting XPC, see Daemons and Services Programming Guide.

For a complete explanation of App Sandbox and how to use it, read App Sandbox Design Guide.

Code Signing

OS X employs the security technology known as code signing to allow you to certify that your app was indeed created by you. After an app is code signed, the system can detect any change to the app—whether the change is introduced accidentally or by malicious code. Various security technologies, including App Sandbox and parental controls, depend on code signing.

In most cases, you can rely on Xcode’s automatic code signing, which requires only that you specify a code signing identity in the build settings for your project. The steps to take are described in Code Signing Your App in Tools Workflow Guide for Mac. If you need to incorporate code signing into an automated build system, or if you link your app against third-party frameworks, refer to the procedures described in Code Signing Guide.

When you adopt App Sandbox, you must code sign your app. This is because entitlements (including the special entitlement that enables App Sandbox) are built into an app’s code signature.

OS X enforces a tie between an app’s container and the app’s code signature. This important security feature ensures that no other sandboxed app can access your container. The mechanism works as follows: After the system creates a container for an app, each time an app with the same bundle ID launches, the system checks that the app’s code signature matches a code signature expected by the container. If the system detects a mismatch, it prevents the app from launching.

For a complete explanation of code signing in the context of App Sandbox, read App Sandbox in Depth in App Sandbox Design Guide.

The Keychain

A keychain is a secure, encrypted container for storing a user’s passwords and other secrets. It is designed to help a user manage their multiple logins, each with its own ID and password. You should always use keychain to store sensitive credentials for your app.

For more on the keychain, see Keychain Services Concepts in Keychain Services Programming Guide.