A deep dive into what the TCC database contains and the meaning of the various fields present in it.

What is TCC?

TCC (Transparency, Consent, and Control) is a mechanism in macOS to limit and control application access to certain features, usually from a privacy perspective. This can include things such as location services, contacts, photos, microphone, camera, accessibility, full disk access, and a bunch more. TCC was introduced with OSX Mavericks and has gone through a number of changes since to expand what it has control over. TCC also appears to exist and provide the same functionality on iOS, but in this post we’ll only be looking at TCC on macOS.

Why write this?

TCC is an end-user protection feature, and tends to get in the way when you’re trying to provision machines in an automatic manner without user interaction. Part of the RainforestQA service is that we run all tests in fresh VMs that we keep up-to-date, and to do this we want to automate as much of the VM build process as possible and we don’t want to babysit the build process to click “allow” when dialogs pop up. Instead we would rather have a reliable way of manipulating TCC to grant access programatically with zero human interaction. TCC is not very well documented and the information you can find on it is scattered about the web with various levels of completeness.

TCC for the User

From a user’s perspective, they see TCC in action when an application wants access to one of the features protected by TCC. When this happens the user is prompted with a dialog asking them whether they want to allow access or not. This response is then stored in the TCC database.

An example of a TCC prompt

Users can also use the System Preferences to manipulate TCC.

System Preferences -> Security and Privacy -> Privacy

The TCC Database(s)

The TCC database is just a sqlite3 database, which makes the task of investigating it much simpler. There are two different databases, a global one in /Library/Application Support/com.apple.TCC/TCC.db and a per-user one located in /Users/<username>/Library/Application Support/com.apple.TCC/TCC.db. These databases are protected from editing with SIP(System Integrity Protection), but you can read them by granting terminal(or your editor) full disk access.

TCC Database Schema

As TCC has evolved over the years the database schema has changed as well. The database contains a few tables but the one we’re most interested in is the access table. Dumping the schema with sqlite gives us the following:

CREATE TABLE access (
    service TEXT NOT NULL,
    client TEXT NOT NULL,
    client_type INTEGER NOT NULL,

--  allowed INTEGER NOT NULL,       -- Removed in Big Sur
--  prompt_count INTEGER NOT NULL,  -- Removed in Big Sur

    auth_value INTEGER NOT NULL,    -- Added in Big Sur
    auth_reason INTEGER NOT NULL,   -- Added in Big Sur
    auth_version INTEGER NOT NULL,  -- Added in Big Sur

    csreq BLOB,
    policy_id INTEGER,

    -- Added in Mojave
    indirect_object_identifier_type INTEGER,
    indirect_object_identifier TEXT NOT NULL DEFAULT "UNUSED",
    indirect_object_code_identity BLOB,

    flags INTEGER,
    last_modified INTEGER NOT NULL DEFAULT (CAST(strftime('%s','now') AS INTEGER))
)

Lets take a look at these fields and what they actually mean:

  • service – What service access is being restricted to. E.g. kTCCServiceMicrophone. See below for a full list of services.
  • clientBundle Identifier or absolute path to the program that wants to use service (e.g. com.apple.finder or /usr/libexec/sshd-keygen-wrapper)
  • client_type – For the previous value, whether it’s a Bundle Identifier(0) or an absolute path(1)
  • allowed – (Prior to big sur) Whether to allow access(1) to this service or deny it(0)
  • prompt_count – (Prior to big sur) How many times the user has been prompted about this access. Programs can repeatedly prompt if they are not granted access the first time so this can be used to track if that’s happening.
  • auth_value – Whether the access is denied(0), unknown(1), allowed(2), or limited(3). An example for limited access: an application might be allowed ask the user to select some photos, but without being granted access to the User’s entire Photo library. It’s unclear if this is actually implemented in macOS or if this is a carryover from iOS.
  • auth_reason – A code indicating how this auth_value was set. A common value is 3 which means “User Set”. See below for full list of values and their meaning.
  • auth_version – Always 1. Since these auth_* fields are new with macOS Big Sur, this seems expected. Presumably this will change with future macOS releases.
  • csreq – Binary code signing requirement blob that the client must satisfy in order for access to be granted. This is used to prevent spoofing/impersonation if another program uses the same bundle identifier. There’s an excellent stack overflow answer(written by yours truly) that covers how this field can be decoded(or generated).
  • policy_id – I believe this is related to MDM(Mobile Device Management) policies, which can be used by organizations to allow TCC access for some applications at a global level. Policies are not able to automatically grant camera or microphone access however. One tool that can generate these profiles is github.com/carlashley/tccprofile.
  • indirect_object_identifier – For some services (kTCCServiceAppleEvents) this is what the client is asking to interact with. It’s an absolute path or bundle identifier just like client. This will be set to UNUSED in cases where it doesn’t make sense.
  • indirect_object_identifier_type – For the previous value, whether it’s a Bundle Identifier(0) or an absolute path(1)
  • indirect_object_code_identity – Same as csreq, but for the indirect_object_identifier instead of client.
  • flags – I wasn’t able to find any documentation on this, and it always seems to be 0. I believe it is likely used along with the MDM policies.
  • last_modified – The last time this entry was modified(seconds since the start of the unix epoch)

Simple summary of the above

Each row in the table basically says:

The program client identified by csreq is allowed/disallowed/limited/unknown [set by auth_value] to use service [with a target of indirect_object_identifier identified by indirect_object_code_identity]

An example entry

This is what you might find in the database if you granted Terminal “Full Disk Access”:

INSERT INTO access VALUES(
  'kTCCServiceSystemPolicyAllFiles',  -- service
  'com.apple.Terminal',               -- client
  0,    -- client_type (0 - bundle id)
  2,    -- auth_value  (2 - allowed)
  3,    -- auth_reason (3 - "User Set")
  1,    -- auth_version
  -- csreq
  X'fade0c000000003000000001000000060000000200000012636f6d2e6170706c652e5465726d696e616c000000000003',
  NULL,        -- policy_id
  NULL,        -- indirect_object_identifier_type
  'UNUSED',    -- indirect_object_identifier
  NULL,        -- indirect_object_code_identity
  0,           -- flags
  1612407199   -- last_updated
);

com.apple.terminal is allowed (2) access to kTCCServiceSystemPolicyAllFiles(Full Disk Access) because “User Set”(3).

The fade0c… represents the csreq blob, and decoded it would read: identifier “com.apple.Terminal” and anchor apple (Refer to this stack overflow answer for how to decode this). This means that the application needs to have the bundle identifier com.apple.Terminal and it needs to be signed by Apple. This prevents anyone from creating their own application with that bundle identifier and gaining access to everything the user has granted to terminal.

Final Thoughts

Understanding the TCC database allows numerous possibilities. It becomes trivial to audit what access has been granted. It also allows one to manipulate the database to authorize permissions without requiring user interaction(e.g. during testing).

At RainforestQA, we use this functionality when configuring our macOS machines to authorize access for our command and control scripts. This allows us to completely automate the installation and maintenance of our macOS fleet, saving us countless hours and making upgrades and maintenance a simple task.

Appendix

The following is a complete list of possible values for auth_reason and service.

auth_reason

I was unable to find any documentation around auth_value or auth_reason. Using the demo version of Hopper Dissassembler I loaded up /System/Library/PrivateFrameworks/TCC.framework/Versions/A/Resources/tccd and found some references to these fields that gave me clues as to what the possible values are.

auth_reason can take the following values:
1 – Error
2 – User Consent
3 – User Set
4 – System Set
5 – Service Policy
6 – MDM Policy
7 – Override Policy
8 – Missing usage string
9 – Prompt Timeout
10 – Preflight Unknown
11 – Entitled
12 – App Type Policy

service

It is possible to inspect the localizable strings for the tcc framework to determine what (some) of the valid services are. Using this command:

plutil -p /System/Library/PrivateFrameworks/TCC.framework/Resources/en.lproj/Localizable.strings

…gives us the following list of services along with what the user will be prompted with when access is requested.

  • kTCCServiceAddressBookclient would like to access your contacts.
  • kTCCServiceAppleEventsclient wants access to control indirect_object. Allowing control will provide access to documents and data in indirect_object, and to perform actions within that app.
  • kTCCServiceBluetoothAlwaysclient would like to use Bluetooth.
  • kTCCServiceCalendarclient would like to access your calendar.
  • kTCCServiceCameraclient would like to access the camera.
  • kTCCServiceContactsFullclient would like to access all of your contacts information.
  • kTCCServiceContactsLimitedclient would like to access your contacts basic information.
  • kTCCServiceFileProviderDomainclient wants to access files managed by indirect_object.
  • kTCCServiceFileProviderPresence – Do you want to allow client to see when you are using files managed by it? It will see which applications are used to access files and whether you are actively using them. It will not see when files that are not managed by it are accessed.
  • kTCCServiceLocationclient would like to use your current location.
  • kTCCServiceMediaLibraryclient would like to access Apple Music, your music and video activity, and your media library.
  • kTCCServiceMicrophoneclient would like to access the microphone.
  • kTCCServiceMotionclient Would Like to Access Your Motion & Fitness Activity.
  • kTCCServicePhotosclient Would Like to Access Your Photos
  • kTCCServicePhotosAddclient Would Like to Add to your Photos
  • kTCCServicePrototype3Rightsclient Would Like Authorization to Test Service Proto3Right.
  • kTCCServicePrototype4Rightsclient Would Like Authorization to Test Service Proto4Right.
  • kTCCServiceRemindersclient would like to access your reminders.
  • kTCCServiceScreenCaptureclient would like to capture the contents of the system display.
  • kTCCServiceSiri – Would You Like to Use client with Siri?
  • kTCCServiceSpeechRecognitionclient Would Like to Access Speech Recognition.
  • kTCCServiceSystemPolicyDesktopFolderclient would like to access files in your Desktop folder.
  • kTCCServiceSystemPolicyDeveloperFilesclient would like to access a file used in Software Development.
  • kTCCServiceSystemPolicyDocumentsFolderclient would like to access files in your Documents folder.
  • kTCCServiceSystemPolicyDownloadsFolderclient would like to access files in your Downloads folder.
  • kTCCServiceSystemPolicyNetworkVolumesclient would like to access files on a network volume.
  • kTCCServiceSystemPolicyRemovableVolumesclient would like to access files on a removable volume.
  • kTCCServiceSystemPolicySysAdminFilesclient would like to administer your computer. Administration can include modifying passwords, networking, and system settings.
  • kTCCServiceWillowclient would like to access your Home data.

Some other values(from running strings on tccd binary, observation, and other places online):

  • kTCCServiceSystemPolicyAllFiles – Full Disk Access
  • kTCCServiceAccessibility – Allows app to control your computer
  • kTCCServicePostEvent – Allows to send keystrokes
  • kTCCServiceListenEvent – Input Monitoring; to monitor input from your keyboard
  • kTCCServiceDeveloperTool – Allows app to run software locally that do not meet the system’s security policy

These seem to be carry-overs from iOS, and may not apply on macOS:

  • kTCCServiceLiverpool – Related to location services
  • kTCCServiceUbiquity – Related to iCloud
  • kTCCServiceShareKit – Related to the share feature(presumably from iOS)(ShareKit)

There’s also some for specific social networks; again I suspect this is a carry-over from iOS.

  • kTCCServiceLinkedIn – LinkedIn
  • kTCCServiceTwitter – Twitter
  • kTCCServiceFacebook – Facebook
  • kTCCServiceSinaWeibo – Sina Weibo
  • kTCCServiceTencentWeibo – Tencent Weibo