How To Clean Up Apple Developer Certificates And Provision

The previous two capacity took reward of Xcode'due south automatic lawmaking signing and provisioning feature. In those chapters, the goal was to submit your app for review every bit shortly as possible, so the automatic setting made sense. This feature does a lot of heavy lifting under the hood. You didn't have to pay much attention to certificates, entitlements, provisioning profiles or code signing.

Lawmaking signing and provisioning are amid the most difficult parts of app distribution — and it's where most developers run into bug. Even the nigh experienced developers routinely dabble around with settings until they get something working, without ever agreement how the system should work.

In this chapter, you'll learn how to do what Xcode did on your behalf so far. Automatic code signing is cracking, but more than advanced setups require manual configuration. If something goes wrong, you'll also want to know how the underlying system works so you lot can troubleshoot effectively.

A historical detour

Before diving into the underlying arrangement, you'll take a brief, historical detour to the 1970s. Apple's platforms are all based on a version of Unix, the operating organization famously developed at Bell Labs in the 1970s. Surprisingly, y'all can trace why code signing is a hurting back to Unix's original assumptions!

In Unix, a program has the same access and privileges every bit the user running information technology. This made sense back in the 1970s considering you had to code and load your own programs using punched cards. But in modern times, this is not a good assumption. Nowadays, the programs you run are typically 3rd-party apps that yous didn't write yourself.

For security reasons, your apps should not have the aforementioned access every bit you do. Third-political party apps shouldn't take free rein over your files, information and hardware. A malicious or compromised app that tin exercise everything you lot can could wreak havoc on your arrangement.

Consider how yous would handle this issue if you were Apple. What kind of system would yous build to protect users from the consequences of this decades-old assumption? Are you thinking of a system that separates a user'due south privileges from those of a third-party app? That kind of organization would enforce a strict separation between apps and the operating system'due south resources, requiring permission for everything.

If that'south what y'all were thinking, congratulations! That's what Apple tree ended upwardly doing. The resulting system is called App Sandbox. On iOS, iPadOS, watchOS and tvOS, apps have been sandboxed from day one. Apple later added sandboxing to macOS. In 2022, Apple announced that sandboxing would be required for all apps distributed on the macOS App Shop.

Introducing App Sandbox

The term "sandbox" helps you empathise the purpose of the organization. Y'all can retrieve of each app being in a restricted, safe space of its ain. Past default, a sandboxed app merely has admission to an app-specific section of the file system, plus the data the app itself creates and saves.

Exterior the sandbox, the host device has resource that the app might want to use, like the microphone or the photographic camera. However, for security reasons, the operating system closely guards these restricted resources. To utilise them, the app needs to validate its identity and request permission from the Os and, sometimes, the user.

Broadly speaking, the resources that crave permission fall into five categories:

Hardware: Photographic camera, microphone, sensors, etc.

Network access: Inbound and outbound traffic.

Information from other apps: Contacts, calendars, electronic mail, etc.

User files: Files from the file system or the Files app.

Special functionality: Push notifications, HomeKit access, etc.

Annotation: This is where terminology gets confusing. In technical documentation, you'll rarely see the word "permission", but you'll see "entitlements", "capabilities" and "resources". In a nutshell, developers request entitlements to add capabilities to their app and then information technology can access system resource.

The diagram below represents how the App Sandbox works. It's not based on the real architecture or implementation of the actual system, only it can assistance you identify and understand all the big pieces.

At a high level, there are resources outside the sandbox, components inside the sandbox and a runtime policy system in the middle that grants or blocks admission based on the app's entitlements. The following sections draw each in detail.

Outside the sandbox

The left-most column of boxes in the previous diagram represents system resources that require permission from the operating system and the user.

Most resources are things you can admission, like a user'south contacts. Other resource are restricted roles yous can take on in Apple tree's ecosystem, similar the ability to send push notifications or the ability to integrate with the Health app.

Runtime policy system

At runtime, a sandboxed app might effort a restricted functioning, similar getting location updates while the app isn't running. The policy system intercepts this operation and, based on a number of checks, allows or disallows the activity.

For example, in the example of background location updates, you lot need three things:

The user's explicit consent to start getting location data.

A description of why y'all're asking for location data in the app'south Info.plist.

The Background Modes location entitlement.

The runtime policy system checks that your app met all these requirements to determine if information technology can continue.

Apple, understandably, doesn't publish much documentation about its policy organisation on iOS and newer platforms. However, you can slice some things together by reading about how Apple rolled out App Sandbox to existing macOS developers.

For instance, spctl is the command-line tool — part of BSD Unix — that manages the security cess policy subsystem, including Gatekeeper on the Mac. For more information, read App Sandbox'due south Blueprint Guide: https://apple.co/2JMJF2u.

Inside App Sandbox

Finally, the right-manus rectangle represents App Sandbox. As mentioned before, each sandbox container has its own file organisation, which the sandboxed app tin can admission without restriction.

There's a "locked expanse" in the center of the sandbox that contains the app binary. Information technology's "locked" because Xcode digitally signed it using codesign. After code-signing something, it's incommunicable to alter anything about it without breaking the code seal, which is easy to check.

The curlicue icon next to the app icon represents the provisioning profile, a file embedded in the app's binary. You can remember of it as a public declaration that details who the app is, where it can run and what it wants to do.

Note: In that location's more than to lawmaking signing and codesign. This chapter aims to give you lot an intuitive understanding of what information technology does and why, merely if you want to learn about the nitty-gritty implementation details, refer to Apple'south Lawmaking Signing Guide: https://apple.co/36QwNBm.

Working astern

So far, you've read about App Sandbox and why Apple tree introduced it. This context is of import! If yous don't have the background context, information technology's easy to think of code signing and provisioning as a list of unrelated chores.

Just in one case you have a grasp of the organization behind information technology, you brainstorm to recollect in terms of providing the sandbox with a "plugin" that it can empathize and interact with.

To accomplish this, y'all might find it helpful to work backwards from an end goal. To properly interact with App Sandbox, your goal is to furnish a code-signed provisioning profile, represented below.

As previously discussed, App Sandbox makes several checks before letting an app consummate a restricted operation. The operating system asks questions and a code-signed provisioning contour answers them. Here are the basic questions the operating arrangement asks:

Who are you?: A provisioning contour includes an app's App ID, which in plow includes a squad ID. Chapter 3, "Submitting Your Offset App for Review", shows y'all how to create an App ID in App Shop Connect.

What would you like to do?: A provisioning contour also includes the list of entitlements for an app. This is a public declaration of your intentions. When your app starts doing something restricted, App Sandbox checks the app'southward requests against the intentions in the provisioning contour.

Can I trust you?: You answered who you are and what you intend to do, simply these answers are just written in manifestly files. A malicious actor could overwrite them. How can Apple tree know that you are who you say you are?

A provisioning profile also includes a programmer identity in the form of a document. The certificate includes the public fundamental, which Apple tree can utilize to verify that the digital signature was created with its corresponding private key.

Where tin you run?: Unlike rules govern different distribution types. For example, in ad hoc distribution — that is, distribution outside the App Shop — you may simply install your app on a maximum of 100 devices. If you're using ad hoc distribution, your provisioning profile will too include the list of device IDs that may apply the app.

Note: Thinking of a code-signed provisioning profile equally the "goal" is useful in practice. But in reality, you re-create your provisioning profile's contents to the digital signature. The real source of truth is the digital signature, not the provisioning contour.

Verifying your identity

I of the questions your code-signed provisioning contour needs to answer for the policy system is, "can I trust you lot?". To unambiguously identify the app and its developer, you need to embed a document in the provisioning profile.

Notation: Apple tree did not invent certificates. The certificates y'all use to identify yourself are based on the X.509 cryptographic standard. X.509 is also the basis for TLS/SSL and HTTPS.

https://en.wikipedia.org/wiki/X.509

Showtime, inspect the certificates you already have. There are two ways you can exercise this. The beginning is to use a built-in app called Keychain Access, which stores passwords, secrets and other sensitive data for the OS. Information technology likewise manages X.509 certificates.

Open up Keychain Access. Under Default Keychains in the left-manus sidebar, click login, then click My Certificates. Next, search Apple in the search bar to filter your certificates. Click the disclosure indicators to see the private keys.

At that place are two certificates from the previous two chapters: a development certificate and a distribution document.

The 2d way to discover your current certificates is by using the security control-line tool. Open Last and blazon the following command:

          security discover-identity -5 -p codesigning

The same two certificates you saw in Keychain Access now impress to the console. If you're function of multiple Apple Programmer teams, you lot might encounter more.

          1) 51CC49FC309619650FEC581586C7BB21B7467F86 "Apple Development: pasi@sweetpeamobile.com (PCQP3A43PK)" 2) C2B75ED2E049C4E8B13E2823A493132E0AE41756 "Apple tree Distribution: Sweetpea Mobile LLC (2DLBN8DKBU)"      2 valid identities constitute

Viewing your certificates

Now, go back to Keychain Access and double-click one of your certificates to open it.

The modal reveals important concepts related to certificates. You'll become over each in detail.

A certificate dominance problems and signs certificates: Something called "Apple Worldwide Programmer Relations Certificate Potency" issued the certificate you're looking at. A certificate authority is part of the X.509 standard. Its role is to tie an entity to a public key. In this case, Apple's WWDR certificate authority ties your Apple Developer Program team ID to your public key.

X.509 certificates rely on public-key cryptography: In public-fundamental cryptography, a public primal and a private central work together. Every bit the name implies, y'all can give your public key to others while keeping your private primal surreptitious.

In the context of app distribution, Xcode digitally signs your app using your private key. You then give your public key to Apple via the certificate and Apple uses it to verify that the digital signature came from y'all.

Code signing requires a valid certificate and its private primal: Certificates can become invalid for several reasons. Each certificate has a natural expiration engagement, usually one year from the time you got it. Separately, either y'all or Apple can revoke a certificate if information technology becomes compromised. To create a digital signature in Xcode, the certificate'south private fundamental needs to be installed in Keychain Admission.

At present that y'all have some background information on certificates and public-key cryptography, select and delete your old certificates in Keychain Access. Keychain Access will double-bank check that yous know what yous're doing.

Click Delete to confirm.

Side by side, you'll create new certificates from scratch.

Creating new certificates

Log into Apple Programmer Portal by opening https://developer.apple tree.com/ in your browser. Open Certificates, Identifiers & Profiles.

Select Certificates in the sidebar. Why are the certificates you only deleted here? The programmer portal is unaware of Keychain Access on your Mac. It doesn't know yous deleted your local re-create.

Because you besides deleted the private keys in the previous pace, you lot tin't utilise these certificates, even if you download them again. Click each document and revoke it.

Now, click the + button adjacent to the Certificates heading. Select Apple Distribution on the next screen.

You need a distribution certificate both to distribute apps in the App Store and for ad hoc distribution, which is covered in Chapter 5, "Internal Distribution". In contrast, y'all need a evolution certificate to install a build for your development device. You won't create a evolution certificate in this affiliate merely the process is essentially the same.

Click Go along to motility forward. The adjacent screen asks you to upload a Certificate Signing Request (CSR). This is also function of the X.509 standard and the official style to ask Apple to sign your certificate.

Request Apple to sign your certificate

Open Keychain Access. From the menu bar, select Keychain Access ▸ Document Assistant ▸ Request a Certificate from a Certificate Authorisation.

In the resulting modal, enter your email address in the User Electronic mail Address field. Side by side to Common Name, type Emitron Distribution Private Primal. Select Saved to disk.

Click Proceed. Salve the certificate signing asking somewhere easy to find in a file named CertificateSigningRequest.certSigningRequest.

Note: In the time information technology took to create a .certSigningRequest file, Keychain Access already created your public cardinal, private key and certificate. The CSR has all the data in your document, as well as your public primal.

You just demand Apple'due south cryptographic postage of blessing. That's why the next step is to upload the CSR to the developer portal.

Uploading the CSR

Return to Apple Developer Portal. Under the Upload a Certificate Signing Request section, click Choose File.

Select CertificateSigningRequest.certSigningRequest from your computer. Click Continue to upload your certificate signing request.

Next, click Download on the resulting screen to finally download the signed document.

Your browser downloads a file named distribution.cert. Double-click it to install it in Keychain Access.

Open Keychain Access. Filter by Apple tree certificates to see that your new document is there. The certificate expires exactly 1 yr from today.

The entry in Keychain Access might not look like much, merely it unambiguously identifies you as a developer on your Apple Programmer Plan team using state-of-the-art cryptographic standards.

Since Apple signed your certificate subsequently you uploaded the document signing request, the fact that you lot have that private primal in your possession means there'southward a direct concatenation of trust starting from Apple (the document authority) to your development squad (mentioned in your document) to the Mac sitting in front of you.

Once you see the certificate in Keychain Access, you can delete the .certSigningRequest file. Yous no longer need it.

Adding entitlements

To create a code-signed provisioning profile — the terminate goal! — the next slice of the puzzle is a list of entitlements. To epitomize, entitlements answer the question "what would you like to do?" on behalf of your app.

Viewing entitlements

Every sandboxed app uses entitlements, even the ones that Apple makes. Before moving forward, information technology'll be helpful for you to dig up some entitlements on your Mac to inspect their format.

Open Terminal. Enter the post-obit control to print the entitlements for a built-in app, like Keynote:

          codesign -d --entitlements - /Applications/Keynote.app

codesign is the command-line tool for digitally signing binaries that'due south built into every Mac. Xcode uses codesign backside the scenes when you archive a build. The command above volition give you a event like this:

          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://world wide web.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict>   <key>com.apple.security.automation.apple-events</fundamental>   <truthful/>   <key>com.apple.developer.icloud-container-identifiers</cardinal>   <assortment>     <string>com.apple.Keynote</string>   </array> ... </dict> </plist>%

That's the beginning of what codesign prints to the panel. At its core, an entitlement is a key-value pair.

You're looking at the text representation of the entitlements .plist, which stores reverse-DNS keys that represent different entitlements. The values can exist Booleans (true/false) or other information types, similar strings or arrays.

In the .plist in a higher place, you can come across that Keynote has the Mac-only entitlement for sending Apple Events to other apps, com.apple tree.security.automation.apple tree-events. Information technology too has the entitlement to salvage documents to iCloud, com.apple.developer.icloud-container-identifiers.

At present that you've seen how other apps utilise entitlements, it'southward time to add your ain.

Creating your own entitlement

Like certificates, entitlements also originate in Apple tree Developer Portal. Open Apple tree Programmer Portal. Click Certificates, Identifiers & Profiles followed past Identifiers. Then click the Raywenderlich Emitron App ID you created in Chapter 3, "Submitting Your First App for Review".

Technically, entitlements are part of an app's App ID. Nether Capabilities, select the Associated Domains checkbox. Click Relieve. Associated Domains permit y'all link an app with a website. The real raywenderlich.com iOS app doesn't use this, simply you lot'll add it here for the sake of practice.

Click Ostend to save the change. All provisioning profiles that use this App ID go invalid when yous change the ID's entitlements.

Annotation: Y'all're not technically "adding" an entitlement. All entitlements accept a default value at runtime, which is unremarkably fix to off. Adding an entitlement in Xcode or in Apple tree Programmer Portal merely overrides the default.

Not every entitlement has a checkbox in App Shop Connect or is represented in Xcode's Capabilities tab. Here'south a more than comprehensive listing of entitlements: https://apple.co/2VT5wrx.

I of the most popular entitlements is Push Notifications. Adding push notifications is also the betoken where many developers realize they don't understand code signing and provisioning as well as they demand to.

Information technology takes more than adding an entitlement to ship push notifications from a back-end server and display them in your app. If button notifications brought you to this chapter, or if you're by and large interested in them, check out Push Notifications by Tutorials by Scott Grosch and the raywenderlich.com team: http://flake.ly/3d47yyL.

Generating a provisioning profile

At this point, you have a distribution certificate and an updated App ID with a new entitlement. The side by side step is to necktie information technology all together in a provisioning profile. Like certificates, provisioning profiles are just files. On your Mac, Xcode stores all provisioning files in ~/Library/MobileDevices/Provisioning Profiles.

Open up Terminal. Execute the following command to expect at your provisioning profiles:

          open up ~/Library/MobileDevice/Provisioning\ Profiles

Final opens a Finder window that lists all the provisioning profiles Xcode has ever used.

Double-clicking on any row would open up Xcode. Instead, select the first row. Printing Infinite to preview with Quick Look.

Note: Quick Wait is a characteristic in Finder that opens up a preview window in Finder. This saves you lot from having to open up the file's designated app. Dissimilar file formats do dissimilar things with Quick Look previews.

The Quick Look preview for .mobileprovision gives yous a graphical representation of the provisioning profile. This is oftentimes useful for troubleshooting.

A provisioning contour is the combination of a scattering of things you've seen before:

App ID: The App ID uniquely identifies an app on Apple'southward platforms and ties the app to your development team.

Entitlements: Technically part of the App ID, but important enough to get their own section in the preview. Discover that in that location are entitlements that you lot didn't have to set manually, like keychain-access-groups and beta-reports-active.

Certificate: The certificate unambiguously identifies yous as the developer and certifies the chain of trust going from Apple to you. Call back that certificates are revokable and have an expiration date. If the certificate on a provisioning contour is invalid or expires, the entire provisioning profile is also invalid.

The listing of entitlements on the provisioning contour in a higher place doesn't include the Associated Domains entitlement you added earlier. That's considering you're looking at an old provisioning profile. It's fourth dimension to generate a new one.

Generating a new provisioning contour

Open Apple Developer Portal. Click Certificates, Identifiers & Profiles, then click Profiles.

Click the + button next to Profiles to add a new profile. On the adjacent screen, nether Distribution, select App Shop to register a new distribution provisioning profile.

On the side by side screen, select the App ID you created in Affiliate 3, "Submitting Your First App for Review". Click Continue.

Then, select the distribution certificate you created before in this chapter. Click Continue.

Equally a final step, App Store Connect asks you to name your provisioning contour. Enter Emitron Distribution Provisioning Profile. Click Generate.

On the next screen, click Download. Double-click the resulting .mobileprovision file to open it in Xcode. Xcode volition admit the file, and then motion it to /Library/MobileDevice/Provisioning Profiles.

Open this folder in Finder and audit the most recently added .mobileprovision with Quick Look to verify that this new provisioning contour does have the Associated Domains entitlement y'all added earlier.

Code signing and distribution

You at present take a valid distribution provisioning profile in your possession, along with its associated private key. You'll utilize these to generate another build, code-sign it and upload it to App Store Connect.

Open the starter project in Xcode. Navigate to the raywenderlich target.

Click the Signing & Capabilities tab, and then select the Release tab. Nether Signing, deselect Automatically manage signing.

Note: The Debug build configuration, which you lot typically use for evolution builds, withal uses automatic lawmaking signing. You tin alter Debug and Release configurations separately.

Yous don't need to know the ins and outs of build configurations to empathise code signing and provisioning. Chapter nine, "Build Customizations", covers this topic in item.

Don't worry that Xcode complains nigh a missing provisioning profile. You'll fix that adjacent.

Next to Provisioning Profile, click the Driblet-down button. Select Import Contour…. Navigate to and select the provisioning profile you lot downloaded in the previous section.

If you lot missed a step and see an fault, double-check your configurations by looking at build settings.

Nether the targets list, click raywenderlich. Click the Build Settings tab, then scroll down to the Signing section.

In that location are four build settings you demand to proceed in mind if you see whatsoever errors with code signing or provisioning: "Lawmaking Signing Identity", "Code Signing Manner", "Development Team", and "Provisioning Profile".

Code Signing Identity

Your app's lawmaking-signing identity sets the certificate that uniquely identifies you lot. Even if you choose to manage signing manually, this build setting has a manual option and an automated option. The values for the automated option are Apple tree Development, iOS Developer, Apple Distribution and iOS Distribution.

If you use one of the automatic options, Xcode tries to deduce the certificate from the provisioning contour selected below. Information technology can practise this because provisioning profiles include certificates. In this case, go out this value gear up to iOS Distribution.

Code Signing Mode

This is the same setting you changed earlier in the Signing & Capabilities tab. The possible values are Automatic and Manual. Here, you're managing signing automatically for Debug builds and manually for Release builds.

Development Team

When you lot log into Xcode with your Apple ID, your Apple Development Program teams get options you tin select. The team you select for this build setting must lucifer the team in your called certificate and provisioning profile.

Provisioning Contour

The provisioning profile build setting determines which provisioning profile y'all'll embed in the build. You can too change this setting in the Signing & Capabilities tab you lot saw before.

Uploading a manually signed build

Now that your settings look correct, it'south fourth dimension to generate another build to upload to App Store Connect using your manually created document and provisioning profile.

With the raywenderlich target selected, click the General tab and bump the Build number to 3. If you've uploaded more than builds in the meantime, your build number could be higher.

Set up Xcode's build destination to Whatsoever iOS Device (arm64). In the menu bar, click Product ▸ Annal. When Xcode finishes the build process, an Organizer window will open up automatically.

Click Distribute App. Get through the Organizer windows using the default values. Since you chose manual signing, Xcode now prompts you to select a distribution document and a provisioning contour.

Select Apple Distribution every bit the distribution certificate and Emitron Distribution Provisioning Profile as the provisioning profile, equally shown beneath.

Click Next to go along. Xcode then uses the certificate and provisioning profile you selected a moment agone to digitally sign the binary using codesign.

And so, click Upload to upload the generated IPA file to App Store Connect.

If all goes well, Xcode signs and uploads the binary and y'all'll see a success screen.

Congratulations! You've successfully uploaded a build where you managed lawmaking signing and provisioning manually. This is one of the thorniest things you lot tin can exercise every bit an Apple tree developer — and you came out the other end with flying colors.

Key points

Unix-like systems presume that third-political party apps should take the same access and privileges equally the user running them. Apple designed App Sandbox as a way to fix this supposition.

Sandboxed apps need to asking permission from the operating organization to admission hardware facilities, the network, data from other apps, user files and special functionality like push notifications.

App Sandbox and runtime policy infrastructure brand several checks when an app tries a protected operation. Yous must furnish a code-signed provisioning profile to answer them.

A provisioning profile comprises several parts: an App ID, entitlements, a certificate and (optionally) a list of device IDs.

Certificates are based on public-key cryptography and follow the X.509 standard. Certificates comprise information about your Apple Developer Program team and are associated with a public key and a private key.

Entitlements are cardinal-value pairs that describe what an app intends to exercise at runtime. They're stored in an app's App ID and code-signed with the residue of the binary.

When it comes to lawmaking signing and provisioning, the relevant build settings are Lawmaking Signing Identity, Lawmaking Signing Style, Development Team and Provisioning Profile.

five. Internal Distribution 3. Submitting Your First App for Review

Source: https://www.raywenderlich.com/books/ios-app-distribution-best-practices/v1.0/chapters/4-code-signing-provisioning

Posted by: medranogoomects.blogspot.com