Mac Os Library Containers

admin 10.04.2020

The specific steps you take to adopt App Sandbox are unique to your app, but the access control mechanisms used by App Sandbox to protect user data remain consistent:

Mac Os Library Containers 2017
Mac Os Group Containers Folder

Some troubleshooting procedures require you to navigate to and view a hidden folder on Mac. You can access the Library folder with the Go To Folder command or from the Terminal app. Access the Library folder in Finder: In Finder, choose Go Go To Folder In the Go To The Folder field, enter /library/ Click Go. Some troubleshooting procedures require you to navigate to and view a hidden folder on Mac. You can access the Library folder with the Go To Folder command or from the Terminal app. Access the Library folder in Finder: In Finder, choose Go Go To Folder In the Go To The Folder field, enter /library/ Click Go. Access the Library folder directly through the Terminal: Click the Spotlight Search. How To: Disable Mac Mail Connection Logging. Mac OS Mail offers the ability to enable connection logging to help troubleshoot email server issues. In addition, the logs will monitor all email sent and received by any email addresses you have added to your Mac OS Mail client. Mar 29, 2019 How to Find the Library Folder on a Mac. This wikiHow teaches you how to force your Mac's user 'Library' folder to show up in the Finder window. While the 'Library' folder is hidden by default, you can prompt it to appear both temporarily.

Entitlements. Communicate to macOS the specific system resources your app needs to get its job done, and no more.
Containers. Access only the files and directories considered safe for your app.
Persistent Resource Access. Retain security-scoped bookmarks across launches of your app to any additional files to which the user has specifically granted your app access.
Code Signing. Unambiguously identify your app to the system so another app cannot masquerade as yours.
Privilege Separation. Split your app into smaller parts, each with its own resource privileges, minimizing the damage if any one part becomes compromised.

The Need for a Last Line of Defense

You secure your app against attack from malware by following the practices recommended in Secure Coding Guide. But despite your best efforts to build an invulnerable barrier—by avoiding buffer overflows and other memory corruptions, preventing exposure of user data, and eliminating other vulnerabilities—your app can be exploited by malicious code. 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’s interactions with the system.

App Sandbox is designed to confront this scenario head on by letting you describe your app’s intended interactions with the system. The system then grants your app only the access your app needs to get its job done. If malicious code gains control of a properly sandboxed app, it is left with access to only the files and resources in the app’s sandbox.

To successfully adopt App Sandbox, use a different mindset than you might be accustomed to, as suggested in Table 2-1.

**Table 2-1** The App Sandbox mindset
When developing…	When adopting App Sandbox…
Add features	Minimize system resource use
Take advantage of access throughout your app	Partition functionality, then distrust each part
Use the most convenient API	Use the most secure API In Mac OS X 10.7 (Lion) and later the Library folder is hidden. To learn how to open the folder, see the guide in the block below. Send a request to Kaspersky Lab Technical Support via the My Kaspersky portal, and include a detailed description of the issue. Sep 02, 2009 Tutorial: An introduction to reading Mac OS X crash reports. Tutorial: An introduction to reading Mac OS X crash reports. Unfortunately, deciphering the logs generated by CrashReporter. To find the crash files, you can run Console app which will display all the system messages. If any specific application crashed, look in User Reports. If it's system crash, check in System Reports. Once you have found the crash file, you can Reveal in Finder (usually located in /Library/Logs/DiagnosticReports).
View restrictions as limitations	View restrictions as safeguards

Entitlements and System Resource Access

An app that is not sandboxed has access to all user-accessible system resources—including the built-in camera and microphone, network sockets, printing, and most of the file system. If successfully attacked by malicious code, such an app can behave as a hostile agent with wide-ranging potential to inflict harm.

When you enable App Sandbox for your app, you remove all but a minimal set of privileges and then deliberately restore them, one-by-one, using entitlements. An entitlement is a key-value pair that identifies a specific capability, such as the capability to open an outbound network socket.

One special entitlement—Enable App Sandboxing—turns on App Sandbox. When you enable sandboxing, Xcode creates a .entitlementsproperty list file and shows it in the project navigator.

If your app requires a capability, request it by adding the corresponding entitlement to your Xcode project using the Summary tab of the target editor. If you don’t require a capability, take care to not include the corresponding entitlement.

You request entitlements on a target-by-target basis. If your app has a single target—the main application—you request entitlements only for that target. If you design your app to use a main application along with helpers (in the form of XPC services), you request entitlements individually, and as appropriate, for each target. You learn more about this in External Tools, XPC Services, and Privilege Separation.

You may require finer-grained control over your app’s entitlements than is available in the Xcode target editor. For example, you might request a temporary exception entitlement because App Sandbox does not support a capability your app needs, such as the ability to send an Apple event to an app that does not yet provide any scripting access groups. To work with temporary exception entitlements, use the Xcode property list editor to edit a target’s .entitlements property list file directly.

Note: If you request a temporary exception entitlement, be sure to follow the guidance regarding entitlements provided on the iTunes Connect website. In particular, file a bug asking for the functionality that you need, and use the Review Notes field in iTunes Connect to explain why your app needs the temporary exception. Be sure to provide the bug number.

macOS App Sandbox entitlements are described in Enabling App Sandbox in Entitlement Key Reference. For a walk-through of requesting an entitlement for a target in an Xcode project, see App Sandbox Quick Start.

Container Directories and File System Access

When you adopt App Sandbox, your application has access to the following locations:

The app container directory. Upon first launch, the operating system creates a special directory for use by your app—and only by your app—called a container. Each user on a system gets an individual container for your app, within their home directory; your app has unfettered read/write access to the container for the user who ran it.
App group container directories. A sandboxed app can specify an entitlement that gives it access to one or more app group container directories, each of which is shared among all apps with that entitlement.
User-specified files. A sandboxed app (with an appropriate entitlement) automatically obtains access to files in arbitrary locations when those files are explicitly opened by the user or are dragged and dropped onto the application by the user.
Related items. With the appropriate entitlement, your app can access a file with the same name as a user-specified file, but a different extension. This can be used for accessing files that are functionally related (such as a subtitle file associated with a movie) or for saving modified files in a different format (such as re-saving an RTF flat file as an RTFD container after the user added a picture).
Temporary directories, command-line tool directories, and specific world-readable locations. A sandboxed app has varying degrees of access to files in certain other well-defined locations.

These policies are detailed further in the sections that follow.

The App Sandbox Container Directory

The app sandbox container directory has the following characteristics:

It is located at a system-defined path, within the user’s home directory. In a sandboxed app, this path is returned when your app calls the NSHomeDirectory function.
Your app has unrestricted read/write access to the container and its subdirectories.
macOS path-finding APIs (above the POSIX layer) refer to locations that are specific to your app.
Most of these path-finding APIs refer to locations relative to your app’s container. For example, the container includes an individual Library directory (specified by the NSLibraryDirectory search path constant) for use only by your app, with individual Application Support and Preferences subdirectories.
Using your container for support files requires no code change (from the pre-sandbox version of your app) but may require one-time migration, as explained in Migrating an App to a Sandbox.
Some path-finding APIs (above the POSIX layer) refer to app-specific locations outside of the user’s home directory. In a sandboxed app, for example, the NSTemporaryDirectory function provides a path to a directory that is outside of the user’s home directory but specific to your app and within your sandbox; you have unrestricted read/write access to it for the current user. The behavior of these path-finding APIs is suitably adjusted for App Sandbox and no code change is needed.
macOS establishes and enforces the connection between your app and its container by way of your app’s code signature.
The container is in a hidden location, and so users do not interact with it directly. Specifically, the container is not for user documents. It is for files that your app uses, along with databases, caches, and other app-specific data.
For a shoebox-style app, in which you provide the only user interface to the user’s content, that content goes in the container and your app has full access to it.
iOS Note: Because it is not for user documents, a macOS container differs from an iOS container. In addition, unlike in macOS, an iOS container contains the app itself.
iCloud Note: Apple’s iCloud technology, as described in iCloud Design Guide, uses the name “container” as well. There is no functional connection between an iCloud container and an App Sandbox container.

Thanks to code signing, no other sandboxed app can gain access to your container, even if it attempts to masquerade as your app by using your bundle identifier. Future versions of your app, however—provided that you use the same code signature and bundle identifier—do reuse your app’s container.

For each user, a sandboxed app’s container directory is created automatically when that user first runs the app. Because a container is within a user’s home directory, each user on a system gets their own container for your app.

The Application Group Container Directory

In addition to per-app containers, in macOS 10.7.5 and 10.8.3 and later, an app can use the com.apple.security.application-groups entitlement to request access to one or more shared containers common to multiple apps produced by the same development team. The entitlement is an array of group identifier strings, each of which names a different group to which the app belongs. Group containers are intended for content that is not user-facing, such as shared caches or databases.

Note: Apps that are members of an application group also gain the ability to share Mach and POSIX semaphores and to use certain other IPC mechanisms in conjunction with other group members. See IPC and POSIX Semaphores and Shared Memory for more details.

An app’s sandbox is automatically enlarged to include all of the app’s group containers. The containers themselves are stored in ~/Library/Group Containers/<application-group-id>, where <application-group-id> is the name of a group, as specified in one of the entitlement’s group identifier strings. Group identifiers must begin with your development team ID, followed by a period.

Beginning in macOS 10.8.3, your app can obtain the path to a group container by calling the containerURLForSecurityApplicationGroupIdentifier: method of NSFileManager with a valid group identifier.

Note: In macOS 10.9, calling this method creates the group container directory automatically, along with Library/Preferences, Library/Caches, and Library/Application Support folders within that group container directory.

In previous versions, although the group container directory is part of your sandbox, the directory itself is not created automatically. Your app must create this directory as shown in Listing 2-1:

Listing 2-1 Creating an app group container directory

You should organize the contents of this directory in the same way that any other Library folder is organized, using standard folder names—Preferences, Application Support, and so on—as needed.

For more details, see Adding an Application to an Application Group in Entitlement Key Reference.

Powerbox and File System Access Outside of Your Container

Your sandboxed app can access file system locations outside of its container in the following three ways:

At the specific direction of the user
By using entitlements for specific file-system locations (described in Entitlements and System Resource Access)
When the file system location is in certain directories that are world readable

The macOS security technology that interacts with the user to expand your sandbox is called Powerbox. Powerbox has no API. Your app uses Powerbox transparently when you use the NSOpenPanel and NSSavePanel classes. You enable Powerbox by setting an entitlement using Xcode, as described in Enabling User-Selected File Access in Entitlement Key Reference.

When you invoke an Open or Save dialog from your sandboxed app, the window that appears is presented not by AppKit but by Powerbox. Using Powerbox is automatic when you adopt App Sandbox—it requires no code change from the pre-sandbox version of your app. Accessory panels that you’ve implemented for opening or saving are faithfully rendered and used.

Note: When you adopt App Sandbox, there are some important behavioral differences for the NSOpenPanel and NSSavePanel classes, described in Open and Save Dialog Behavior with App Sandbox.

The security benefit provided by Powerbox is that it cannot be manipulated programmatically—specifically, there is no mechanism for hostile code to use Powerbox for accessing the file system. Only a user, by interacting with Open and Save dialogs via Powerbox, can use those dialogs to reach portions of the file system outside of your previously established sandbox. For example, if a user saves a new document, Powerbox expands your sandbox to give your app read/write access to the document.

When a user of your app specifies they want to use a file or a folder, the system adds the associated path to your app’s sandbox. Say, for example, a user drags the ~/Documents folder onto your app’s Dock tile (or onto your app’s Finder icon, or into an open window of your app), thereby indicating they want to use that folder. In response, the system makes the ~/Documents folder, its contents, and its subfolders available to your app.

If a user instead opens a specific file, or saves to a new file, the system makes the specified file, and that file alone, available to your app.

In addition, the system automatically permits a sandboxed app to:

Connect to system input methods
Invoke services chosen by the user from the Services menu.
Some services are not sandbox safe. For example, the Finder app’s Open service might enable a compromised app to programmatically open an arbitrary file anywhere on the system, thus escaping its sandbox. Service providers are encouraged to mark these kinds of services as restricted (services are not restricted by default), in which case the service is still available to sandboxed apps, but only after the user is warned and gives explicit permission to continue. See the Services Implementation Guide for more information.
Open files chosen by the user from the Open Recent menu
Participate with other apps by way of user-invoked copy and paste
Read files that are world readable, in certain directories, including the following directories:
- /bin
- /sbin
- /usr/bin
- /usr/lib
- /usr/sbin
- /usr/share
- /System
Read and write files in directories created by calling NSTemporaryDirectory.
Note: The /tmp directory is not accessible from sandboxed apps. Use the NSTemporaryDirectory function to obtain a temporary location for your app’s temporary files.

After a user has specified a file they want to use, that file is within your app’s sandbox. The file is then vulnerable to attack if your app is exploited by malicious code: App Sandbox provides no protection. To provide protection for the files within your sandbox, follow the recommendations in Secure Coding Guide.

By default, files opened or saved by the user remain within your sandbox until your app terminates, except for files that were open at the time that your app terminates. Such files reopen automatically by way of the macOS Resume feature the next time your app launches, and are automatically added back to your app’s sandbox.

To provide persistent access to resources located outside of your container, in a way that doesn’t depend on Resume, use security-scoped bookmarks as explained in Security-Scoped Bookmarks and Persistent Resource Access.

Related Items

The related items feature of App Sandbox lets your app access files that have the same name as a user-chosen file, but a different extension. This feature consists of two parts: a list of related extensions in the application’s Info.plist file and code to tell the sandbox what you’re doing.

There are two common scenarios where this makes sense:

Scenario 1:
Your app needs to be able to save a file with a different extension than that of the original file. For example, when you paste an image into an RTF file in TextEdit and save it, TextEdit changes the file’s extension from .rtf to .rtfd (and it becomes a directory).
To handle this situation, you must use an NSFileCoordinator object to coordinate access to the file. Before you rename the file, call the itemAtURL:willMoveToURL: method. After you rename the file, call the itemAtURL:didMoveToURL: method.
Scenario 2:
Your app needs to be able to open or save multiple related files with the same name and different extensions (for example, to automatically open a subtitle file with the same name as a movie file, or to allow for a SQLite journal file).
To gain access to that secondary file, create a class that conforms to the NSFilePresenter protocol. This object should provide the main file’s URL as its primaryPresentedItemURL property, and should provide the secondary file’s URL as its presentedItemURL property.
After the user opens the main file, your file presenter object should call the addFilePresenter: class method on the NSFileCoordinator class to register itself.
Note: In the case of a SQLite journal file, beginning in 10.8.2, journal files, write-ahead logging files, and shared memory files are automatically added to the related items list if you open a SQLite database, so this step is unnecessary.

In both scenarios, you must make a small change to the application’s Info.plist file. Your app should already declare a Document Types (CFBundleDocumentTypes) array that declares the file types your app can open.

For each file type dictionary in that array, if that file type should be treated as a potentially related type for open and save purposes, add the key NSIsRelatedItemType with a boolean value of YES.

To learn more about file presenters and file coordinators, read File System Programming Guide.

Open and Save Dialog Behavior with App Sandbox

Certain NSOpenPanel and NSSavePanel methods behave differently when App Sandbox is enabled for your app:

You cannot invoke the OK button using the ok: method.
You cannot rewrite the user’s selection using the panel:userEnteredFilename:confirmed: method from the NSOpenSavePanelDelegate protocol.

In addition, the effective, runtime inheritance path for the NSOpenPanel and NSSavePanel classes is different with App Sandbox, as illustrated in Table 2-2.

**Table 2-2** Open and Save class inheritance with App Sandbox
Without App Sandbox	NSOpenPanel : NSSavePanel : NSPanel : NSWindow : NSResponder : NSObject
With App Sandbox	NSOpenPanel : NSSavePanel : NSObject

Because of this runtime difference, an NSOpenPanel or NSSavePanel object inherits fewer methods with App Sandbox. If you attempt to send a message to an NSOpenPanel or NSSavePanel object, and that method is defined in the NSPanel, NSWindow, or NSResponder classes, the system raises an exception. The Xcode compiler does not issue a warning or error to alert you to this runtime behavior.

Security-Scoped Bookmarks and Persistent Resource Access

Your app’s access to file-system locations outside of its container—as granted to your app by way of user intent, such as through Powerbox—does not automatically persist across app launches or system restarts. When your app reopens, you have to start over. (The one exception to this is for files open at the time that your app terminates, which remain in your sandbox thanks to the macOS Resume feature).

Starting in macOS 10.7.3, you can retain access to file-system resources by employing a security mechanism, known as security-scoped bookmarks, that preserves user intent. Here are a few examples of app features that can benefit from this:

A user-selected download, processing, or output folder
An image browser library file, which points to user-specified images at arbitrary locations
A complex document format that supports embedded media stored in other locations

Two Distinct Types of Security-Scoped Bookmark

Security-scoped bookmarks, available starting in macOS 10.7.3, support two distinct use cases:

An app-scoped bookmark provides your sandboxed app with persistent access to a user-specified file or folder.
For example, if your app employs a download or processing folder that is outside of the app container, obtain initial access by presenting an NSOpenPanel dialog to obtain the user’s intent to use a specific folder. Then, create an app-scoped bookmark for that folder and store it as part of the app’s configuration (perhaps in a property list file or using the NSUserDefaults class). With the app-scoped bookmark, your app can obtain future access to the folder.
A document-scoped bookmark provides a specific document with persistent access to a file.
For example, a video editing app typically supports the notion of a project document that refers to other files and needs persistent access to those files. Such a project document can store security-scoped bookmarks to the files it refers to.
Obtain initial access to a referred item by asking for user intent to use that item. Then, create a document-scoped bookmark for the item and store the bookmark as part of the document’s data.
A document-scoped bookmark can be resolved by any app that has access to the bookmark data itself and to the document that owns the bookmark. This supports portability, allowing a user, for example, to send a document to another user; the document’s secure bookmarks remain usable for the recipient. The document can be a single flat file or a package containing multiple files.
A document-scoped bookmark can point only to a file, not a folder, and only to a file that is not in a location used by the system (such as /private or /Library).

Using Security-Scoped Bookmarks

To use either type of security-scoped bookmark requires you to perform five steps:

Set the appropriate entitlement in the target that needs to use security-scoped bookmarks.
Do this once per target as part of configuring your Xcode project.
Create a security-scoped bookmark.
Do this when a user has indicated intent (such as via Powerbox) to use a file-system resource outside of your app’s container, and you want to preserve your app’s ability to access the resource.
Resolve the security-scoped bookmark.
Do this when your app later (for example, after app relaunch) needs access to a resource you bookmarked in step 2. The result of this step is a security-scoped URL.
Explicitly indicate that you want to use the file-system resource whose URL you obtained in step 3.
Do this immediately after obtaining the security-scoped URL (or, when you later want to regain access to the resource after having relinquished your access to it).
When done using the resource, explicitly indicate that you want to stop using it.
Do this as soon as you know that you no longer need access to the resource (typically, after you close it).
After you relinquish access to a file-system resource, to use that resource again you must return to step 4 (to again indicate you want to use the resource).
If your app is relaunched, you must return to step 3 (to resolve the security-scoped bookmark).

The first step in the preceding list, requesting entitlements, is the prerequisite for using either type of security-scoped bookmark. Perform this step as follows:

To use app-scoped bookmarks in a target, set the com.apple.security.files.bookmarks.app-scope entitlement value to true.
To use document-scoped bookmarks in a target, set the com.apple.security.files.bookmarks.document-scope entitlement value to true.

You can request either or both of these entitlements in a target, as needed. These entitlements are available starting in macOS 10.7.3 and are described in Enabling Security-Scoped Bookmark and URL Access.

With the appropriate entitlements, you can create a security-scoped bookmark by calling the bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: method of the NSURL class.

When you later need access to a bookmarked resource, resolve its security-scoped bookmark by calling the the URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error: method of the NSURL class.

In a sandboxed app, you cannot access the file-system resource that a security-scoped URL points to until you call the startAccessingSecurityScopedResource method on the URL.

When you no longer need access to a resource that you obtained using security scope (typically, after you close the resource) you must call the stopAccessingSecurityScopedResource method on the resource’s URL.

Calls to start and stop access are not nested. When you call the stopAccessingSecurityScopedResource method, you immediately lose access to the resource. If you call this method on a URL whose referenced resource you do not have access to, nothing happens.

Warning: If you fail to relinquish your access to file-system resources when you no longer need them, your app leaks kernel resources. If sufficient kernel resources are leaked, your app loses its ability to add file-system locations to its sandbox, such as via Powerbox or security-scoped bookmarks, until relaunched.

For detailed descriptions of the methods, constants, and entitlements to use for implementing security-scoped bookmarks in your app, read NSURL Class Reference, and read Enabling Security-Scoped Bookmark and URL Access in Entitlement Key Reference.

Note: The Core Foundation framework also provides equivalent C functions for working with security-scoped bookmarks. For details, see the documentation for CFURLCreateBookmarkData, CFURLCreateByResolvingBookmarkData,CFURLStartAccessingSecurityScopedResource, and CFURLStopAccessingSecurityScopedResource in CFURL Reference.

App Sandbox and Code Signing

In order to adopt App Sandbox, you also adopt code signing. Without a code signature, many of the features of App Sandbox, such as restricting your app to its own file system container, make little sense, because the system cannot unambiguously identify your app. More fundamentally, entitlements, including the one that activates App Sandbox in the first place, are physically stored in an app’s code signature. An app that is not code signed has no way to even ask to be put into a sandbox. Put simply, unsigned code is not sandboxed, regardless of what entitlements you request in the target build settings.

Modern Xcode makes it easy to adopt code signing for your app. You provide your developer program credentials, and Xcode handles most of the rest automatically. For more about code signing, including descriptions of both how it works and how you use it, read Code Signing Guide.

macOS 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:

When the system creates a container for an app, it sets an access control list (ACL) on that container. The initial access control entry in that list contains the app’s Designated Requirement (DR), which is part of the app’s signature that describes how future versions of the app can be recognized. See Code Requirements in Code Signing Guide for a description of the DR.
Each time an app with the same bundle ID launches, the system checks that the app’s code signature matches the designated requirements specified in one of the entries in the container’s ACL. If the system does not find a match, it prevents the app from launching.

macOS’s enforcement of container integrity impacts your development and distribution cycle. This is because, in the course of creating and distributing an app, the app is code signed using various signatures. Here’s how the process works:

Before you create a project, you obtain three code signing certificates from Apple: a development certificate, a distribution certificate, and (optionally) a Developer ID certificate.
When used in conjunction with the corresponding private keys from your keychain, these certificates form three separate digital identities. For development and testing, you sign your app with your development identity. When you submit a version to the app store, you use your distribution identity. If you are distributing a version outside the app store, you use your Developer ID identity.
When the Mac App Store distributes your app, it is signed with an Apple code signature.

Mac Os Library Containers 2017

For testing and debugging, you may want to run both versions of your app: the version you sign and the version Apple signs. But macOS sees the Apple-signed version of your app as an intruder and won’t allow it to launch: Its code signature does not match the one expected by your app’s existing container.

If you try to run the Apple-signed version of your app, you get a crash report containing a statement similar to this:

The solution is to adjust the access control list (ACL) on your app’s container to recognize the Apple-signed version of your app. Specifically, you add the designated code requirement of the Apple-signed version of your app to the app container’s ACL.

To adjust an ACL to recognize an Apple-signed version of your app

Open a Finder window that contains the Apple-signed version of your app.
In place of the <path/to/app> placeholder, substitute the path to the Apple-signed version of your app. Instead of manually typing the path, you can drag the app’s Finder icon to the Terminal window.

The container’s ACL now includes the designated code requirements for both versions of your app. macOS then allows you to run either version of your app.

You can use this same technique to share a container between (1) a version of an app that you initially signed with a development identity, such as the one you used in App Sandbox Quick Start, and (2) a released version downloaded from the Mac App Store.

You can view the list of code requirements in a container’s ACL. For example, after adding the designated code requirement for the Apple-signed version of your app, you can confirm that the container’s ACL lists two permissible code requirements.

To display the list of code requirements in a container’s ACL

In Terminal, enter the following command:
In place of the <container name> placeholder, substitute the name of your app’s container directory. (The name of your app’s container directory is typically the same as your app’s bundle identifier.)

For more information about working with App Sandbox container access control lists and their code requirements, read the man page for the asctl (App Sandbox control) tool.

External Tools, XPC Services, and Privilege Separation

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.

Your app can also launch existing helper apps using Launch Services, but only if certain conditions are met.

Important: While a child process spawned by an app (using fork, for example) simply inherits its parent’s sandbox, helper apps do not. Therefore, if you are submitting your app to the Mac App Store, verify that any embedded helper apps are also individually sandboxed.

To do this, run the following command on each embedded executable in your app bundle and confirm that each one has an App Sandbox entitlement:

where <executable-path> is the complete path to an executable binary in your app bundle.

The sections below explain these concepts in more detail.

XPC Services

XPC is an macOS 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.

You create an XPC service as an individual target in your Xcode project. Typically, each service gets its own sandbox—specifically, it gets its own container and its own set of entitlements. In fact, if you are distributing your app in the Mac App Store, XPC services must be sandboxed. For apps distributed elsewhere, for example using Developer ID, sandboxing XPC services is optional, but strongly recommended.

Note: In rare cases, your app might have a small piece of functionality that cannot be sandboxed. Rather than abandon App Sandbox altogether, you might relegate the ineligible code to an XPC service that is not sandboxed. It is easier to secure a smaller piece of code than a larger one, and in this way, the bulk of your app enjoys the benefits of App Sandbox.

In addition, an XPC service that you include with your app is accessible only by your app. These advantages add up to making XPC the best technology for implementing privilege separation in an macOS app.

By contrast, a child process created by using the posix_spawn function, by calling fork and exec (discouraged), or by using the NSTask class simply inherits the sandbox of the process that created it. You cannot configure a child process’s entitlements. For these reasons, child processes do not provide effective privilege separation.

To use XPC with App Sandbox:

Confer minimal privileges to each XPC service, according to its needs.
Design the data transfers between the main app and each XPC service to be secure.
Structure your app’s bundle appropriately.

The life cycle of an XPC service, and its integration with Grand Central Dispatch (GCD), is managed entirely by the system. To obtain this support, you need only to structure your app’s bundle correctly.

For more on XPC, see Creating XPC Services in Daemons and Services Programming Guide.

Launching Helpers with Launch Services

A sandboxed app is allowed to launch a helper using Launch Services if at least one of these conditions has been met:

Both the app and helper pass the Gatekeeper assessment. By default that means both are signed by the Mac App Store or with Developer ID.
Note: This does not include your development ('Mac Developer') or distribution ('3rd Party Mac Developer Application') signing identities.
The app is installed in /Applications and the app bundle and all contents are owned by root.
The helper has been (manually) run at least once by the user.

If none of these conditions have been met, you'll see errors like the following:

'Not allowing process 19920 to launch '/Applications/Main.app/Contents/Resources/Helper.app' because the security assessment verdict was denied.'
This message means that the Gatekeeper assessment was denied. You can confirm that with the spctl tool as follows:
'The application “Helper” could not be launched because it is corrupt.'
'The operation couldn’t be completed. (OSStatus error -10827.)'
This is the typical error if none of the above conditions have been fulfilled.

The results are the same whether you use Launch Services directly (by calling LSOpenCFURLRef, for example) or indirectly (by calling the launchApplicationAtURL:options:configuration:error: method in NSWorkspace, for example).

In addition, upon failure, in OS X 10.7.5 and earlier, you will also see a bogus deny file-write-data /Applications/Main.app/Contents/Resources/Helper.app sandbox violation. This error has no functional impact and can be ignored.

IPC and POSIX Semaphores and Shared Memory

Normally, sandboxed apps cannot use Mach IPC, POSIX semaphores and shared memory, or UNIX domain sockets (usefully). However, by specifying an entitlement that requests membership in an application group, an app can use these technologies to communicate with other members of that application group.

Note: System V semaphores are not supported in sandboxed apps.

UNIX domain sockets are straightforward; they work just like any other file.

Any semaphore or Mach port that you wish to access within a sandboxed app must be named according to a special convention:

POSIX semaphores and shared memory names must begin with the application group identifier, followed by a slash (/), followed by a name of your choosing.
Mach port names must begin with the application group identifier, followed by a period (.), followed by a name of your choosing.

For example, if your application group’s name is Z123456789.com.example.app-group, you might create two semaphores named Z123456789.myappgroup/rdyllwflg and Z123456789.myappgroup/bluwhtflg. You might create a Mach port named Z123456789.com.example.app-group.Port_of_Kobe.

Note: The maximum length of a POSIX semaphore name is only 31 bytes, so if you need to use POSIX semaphores, you should keep your app group names short.

To learn more about application groups, read The Application Group Container Directory, then read Adding an Application to an Application Group in Entitlement Key Reference.

Estimated reading time: 17 minutes

Welcome to Docker Desktop!

The Docker Desktop for Mac section contains information about the Docker Desktop Community Stable release. For information about features available in Edge releases, see the Edge release notes. For information about Docker Desktop Enterprise (DDE) releases, see Docker Desktop Enterprise.

Docker is a full development platform to build, run, and share containerized applications. Docker Desktop is the best way to get started with Docker on Mac.

See Install Docker Desktop for download information, system requirements, and installation instructions.

Check versions

Ensure your versions of docker and docker-compose areup-to-date and compatible with Docker.app. Your output may differ if you arerunning different versions.

Explore the application

Open a command-line terminal and test that your installation works byrunning the simple Docker image,hello-world:
Start a Dockerized web server. Like the hello-world image above, if theimage is not found locally, Docker pulls it from Docker Hub.
In a web browser, go to http://localhost/ to view the nginx homepage.Because we specified the default HTTP port, it isn’t necessary to append:80 at the end of the URL.
Early beta releases used docker as the hostname to build the URL. Now,ports are exposed on the private IP addresses of the VM and forwarded tolocalhost with no other host name set.
View the details on the container while your web server is running (withdocker container ls or docker ps):
Stop and remove containers and images with the following commands. Use the“all” flag (--all or -a) to view stopped containers.

Preferences

Choose the Docker menu > Preferences from themenu bar and configure the runtime options described below.

General

On the General tab, you can configure when to start and update Docker:

Start Docker Desktop when you log in: Automatically starts Docker Desktop when you open your session.
Automatically check for updates: By default, Docker Desktop automatically checks for updates and notifies you when an update is available. You can manually check for updates anytime by choosing Check for Updates from the main Docker menu.
Include VM in Time Machine backups: Select this option to back up the Docker Desktop virtual machine. This option is disabled by default.
Securely store Docker logins in macOS keychain: Docker Desktop stores your Docker login credentials in macOS keychain by default.
Send usage statistics: Docker Desktop sends diagnostics, crash reports, and usage data. This information helps Docker improve and troubleshoot the application. Clear the check box to opt out.

Resources

The Resources tab allows you to configure CPU, memory, disk, proxies, network, and other resources.

Advanced

On the Advanced tab, you can limit resources available to Docker.

Advanced settings are:

CPUs: By default, Docker Desktop is set to use half the number of processorsavailable on the host machine. To increase processing power, set this to ahigher number; to decrease, lower the number.

Memory: By default, Docker Desktop is set to use 2 GB runtime memory,allocated from the total available memory on your Mac. To increase the RAM, set this to a higher number. To decrease it, lower the number.

Swap: Configure swap file size as needed. The default is 1 GB.

Disk image size: Specify the size of the disk image.

Disk image location: Specify the location of the Linux volume where containers and images are stored.

You can also move the disk image to a different location. If you attempt to move a disk image to a location that already has one, you get a prompt asking if you want to use the existing image or replace it.

File sharing

Use File sharing to allow local directories on the Mac to be shared with Linux containers.This is especially useful forediting source code in an IDE on the host while running and testing the code in a container.By default the /Users, /Volume, /private, /tmp and /var/folders directory are shared. If your project is outside this directory then it must be addedto the list. Otherwise you may get Mounts denied or cannot start service errors at runtime.

File share settings are:

Add a Directory: Click + and navigate to the directory you want to add.
Apply & Restart makes the directory available to containers using Docker’sbind mount (-v) feature.
There are some limitations on the directories that can be shared:
- The directory must not exist inside of Docker.

For more information, see:

Namespaces in the topic onosxfs file system sharing.
Volume mounting requires file sharing for any project directories outside of /Users.)

Proxies

Docker Desktop detects HTTP/HTTPS Proxy Settings from macOS and automaticallypropagates these to Docker and to your containers. For example, if you set yourproxy settings to http://proxy.example.com, Docker uses this proxy whenpulling containers.

When you start a container, your proxy settings propagate into the containers.For example:

You can see from the above output that the HTTP_PROXY, http_proxy, andno_proxy environment variables are set. When your proxy configuration changes,Docker restarts automatically to pick up the new settings. If you have anycontainers that you would like to keep running across restarts, you should consider using restart policies.

Network

You can configure Docker Desktop networking to work on a virtual private network (VPN). Specify a network address translation (NAT) prefix and subnet mask to enable Internet connectivity.

Docker Engine

The Docker Engine page allows you to configure the Docker daemon to determine how your containers run.

Type a JSON configuration file in the box to configure the daemon settings. For a full list of options, see the Docker Enginedockerd commandline reference.

Mac Os Group Containers Folder

Click Apply & Restart to save your settings and restart Docker Desktop.

Command Line

On the Command Line page, you can specify whether or not to enable experimental features.

Experimental features provide early access to future product functionality.These features are intended for testing and feedback only as they may changebetween releases without warning or can be removed entirely from a futurerelease. Experimental features must not be used in production environments.Docker does not offer support for experimental features.

To enable experimental features in the Docker CLI, edit the config.jsonfile and set experimental to enabled.

To enable experimental features from the Docker Desktop menu, clickSettings (Preferences on macOS) > Command Line and then turn onthe Enable experimental features toggle. Click Apply & Restart.

On both Docker Desktop Edge and Stable releases, you can toggle the experimental features on and off. If you toggle the experimental features off, Docker Desktop uses the current generally available release of Docker Engine.

You can see whether you are running experimental mode at the command line. IfExperimental is true, then Docker is running in experimental mode, as shownhere. (If false, Experimental mode is off.)

Kubernetes

Docker Desktop includes a standalone Kubernetes server that runs on your Mac, sothat you can test deploying your Docker workloads on Kubernetes.

The Kubernetes client command, kubectl, is included and configured to connectto the local Kubernetes server. If you have kubectl already installed andpointing to some other environment, such as minikube or a GKE cluster, be sureto change context so that kubectl is pointing to docker-desktop:

If you installed kubectl with Homebrew, or by some other method, andexperience conflicts, remove /usr/local/bin/kubectl.

To enable Kubernetes support and install a standalone instance of Kubernetesrunning as a Docker container, select Enable Kubernetes. To set Kubernetes as thedefault orchestrator, select Deploy Docker Stacks to Kubernetes by default.
Click Apply & Restart to save the settings. This instantiates images required to run the Kubernetes server as containers, and installs the/usr/local/bin/kubectl command on your Mac.
When Kubernetes is enabled and running, an additional status bar item displaysat the bottom right of the Docker Desktop Settings dialog.
The status of Kubernetes shows in the Docker menu and the context points todocker-desktop.
By default, Kubernetes containers are hidden from commands like dockerservice ls, because managing them manually is not supported. To make themvisible, select Show system containers (advanced) and click Apply andRestart. Most users do not need this option.
To disable Kubernetes support at any time, clear the Enable Kubernetes check box. TheKubernetes containers are stopped and removed, and the/usr/local/bin/kubectl command is removed.
For more about using the Kubernetes integration with Docker Desktop, seeDeploy on Kubernetes.

Reset

Reset and Restart options

On Docker Desktop Mac, the Restart Docker Desktop, Reset to factory defaults, and other reset options are available from the Troubleshoot menu.

For information about the reset options, see Logs and Troubleshooting.

Dashboard

The Docker Desktop Dashboard enables you to interact with containers and applications and manage the lifecycle of your applications directly from your machine. The Dashboard UI shows all running, stopped, and started containers with their state. It provides an intuitive interface to perform common actions to inspect and manage containers and existing Docker Compose applications. For more information, see Docker Desktop Dashboard.

Add TLS certificates

You can add trusted Certificate Authorities (CAs) (used to verify registryserver certificates) and client certificates (used to authenticate toregistries) to your Docker daemon.

Add custom CA certificates (server side)

All trusted CAs (root or intermediate) are supported. Docker Desktop creates acertificate bundle of all user-trusted CAs based on the Mac Keychain, andappends it to Moby trusted certificates. So if an enterprise SSL certificate istrusted by the user on the host, it is trusted by Docker Desktop.

To manually add a custom, self-signed certificate, start by adding thecertificate to the macOS keychain, which is picked up by Docker Desktop. Here isan example:

Or, if you prefer to add the certificate to your own local keychain only (ratherthan for all users), run this command instead:

See also, Directory structures forcertificates.

Note: You need to restart Docker Desktop after making any changes to thekeychain or to the ~/.docker/certs.d directory in order for the changes totake effect.

For a complete explanation of how to do this, see the blog post AddingSelf-signed Registry Certs to Docker & Docker Desktop forMac.

Add client certificates

You can put your client certificates in~/.docker/certs.d/<MyRegistry>:<Port>/client.cert and~/.docker/certs.d/<MyRegistry>:<Port>/client.key.

When the Docker Desktop application starts, it copies the ~/.docker/certs.dfolder on your Mac to the /etc/docker/certs.d directory on Moby (the DockerDesktop xhyve virtual machine).

You need to restart Docker Desktop after making any changes to the keychainor to the ~/.docker/certs.d directory in order for the changes to takeeffect.
The registry cannot be listed as an insecure registry (see DockerEngine. Docker Desktop ignores certificates listedunder insecure registries, and does not send client certificates. Commandslike docker run that attempt to pull from the registry produce errormessages on the command line, as well as on the registry.

Directory structures for certificates

If you have this directory structure, you do not need to manually add the CAcertificate to your Mac OS system login:

The following further illustrates and explains a configuration with customcertificates:

You can also have this directory structure, as long as the CA certificate isalso in your keychain.

To learn more about how to install a CA root certificate for the registry andhow to set the client TLS certificate for verification, seeVerify repository client with certificatesin the Docker Engine topics.

Install shell completion

Docker Desktop comes with scripts to enable completion for the docker and docker-compose commands. The completion scripts may befound inside Docker.app, in the Contents/Resources/etc/ directory and can beinstalled both in Bash and Zsh.

Bash

Bash has built-in support forcompletion To activate completion for Docker commands, these files need to becopied or symlinked to your bash_completion.d/ directory. For example, if youinstalled bash via Homebrew:

Add the following to your ~/.bash_profile:

Zsh

In Zsh, the completionsystem takes care of things. To activate completion for Docker commands,these files need to be copied or symlinked to your Zsh site-functions/directory. For example, if you installed Zsh via Homebrew:

Give feedback and get help

To get help from the community, review current user topics, join or start adiscussion, log on to our Docker Desktop for Macforum.

To report bugs or problems, log on to Docker Desktop for Mac issues onGitHub,where you can review community reported issues, and file new ones. SeeLogs and Troubleshooting for more details.

For information about providing feedback on the documentation or update it yourself, see Contribute to documentation.

Docker Hub

Select Sign in /Create Docker ID from the Docker Desktop menu to access your Docker Hub account. Once logged in, you can access your Docker Hub repositories and organizations directly from the Docker Desktop menu.

For more information, refer to the following Docker Hub topics:

Two-factor authentication

Docker Desktop enables you to sign into Docker Hub using two-factor authentication. Two-factor authentication provides an extra layer of security when accessing your Docker Hub account.

You must enable two-factor authentication in Docker Hub before signing into your Docker Hub account through Docker Desktop. For instructions, see Enable two-factor authentication for Docker Hub.

After you have enabled two-factor authentication:

Go to the Docker Desktop menu and then select Sign in / Create Docker ID.
Enter your Docker ID and password and click Sign in.
After you have successfully signed in, Docker Desktop prompts you to enter the authentication code. Enter the six-digit code from your phone and then click Verify.

After you have successfully authenticated, you can access your organizations and repositories directly from the Docker Desktop menu.

Where to go next

Try out the walkthrough at Get Started.
Dig in deeper with Docker Labs examplewalkthroughs and source code.
For a summary of Docker command line interface (CLI) commands, seeDocker CLI Reference Guide.
Check out the blog post, What’s New in Docker 17.06 Community Edition(CE).

mac, tutorial, run, docker, local, machine